docs: federation request guide, Lola URL migration, and MCP validation summary

.claude/skills/agentic-contribution-skill/SKILL.md

@@ -411,7 +411,7 @@ See [Prerequisites](#prerequisites) section for required system tools (git, uv,
 **External**:
 - [agentskills.io Specification](https://agentskills.io/specification) - Base skill standard
 - [Conventional Commits](https://www.conventionalcommits.org/) - Commit message format
-- [Lola Package Manager](https://github.com/RedHatProductSecurity/lola) - AI skills package manager
+- [Lola Package Manager](https://github.com/LobsterTrap/lola) - AI skills package manager
 
 ## Critical: Human-in-the-Loop Requirements
 

.claude/skills/federation-request/SKILL.md

@@ -23,6 +23,10 @@ allowed-tools: Read Edit Write Bash Glob Grep Skill
 
 Guide users through creating a complete federation PR — from discovering pack metadata in an external repo to opening the pull request with the `federation` label. Only repository URL and pack path are asked upfront; other fields are inferred and confirmed before any writes.
 
+**Install scope:** Federated modules are full Lola packs. `lola install -f <name>` installs **every skill** in the pack, the same as in-repo modules (`rh-sre`, `rh-developer`, etc.). There is no marketplace field to install a subset.
+
+**`ref` pinning:** Marketplace `ref` is required for CI/catalog in this repo but **ignored by Lola at install** until [lola#180](https://github.com/LobsterTrap/lola/issues/180).
+
 ## Prerequisites
 
 **Required Tools**:
@@ -154,7 +158,7 @@ Keep the temporary clone at `$TMP` through Phase 2 if no corrections require re-
     description: "<description>"
     version: "<version>"
     repository: "<repository>"
-    ref: "<commit-sha>"         # required project extension: 40-character commit SHA
+    ref: "<commit-sha>"         # required project extension: 40-character commit SHA (Lola ignores until lola#180)
     path: "<path>"
     tags:
       - "<tag1>"
@@ -333,6 +337,7 @@ None — no MCP tools are invoked.
 ### Reference Documentation
 
 **Internal:**
+- [Federation Request Guide](../../../FEDERATION_REQUEST_GUIDE.md) — contributor guide for federation requests
 - [Federation Review Guide](../../../FEDERATION_REVIEW_GUIDE.md) — evaluation criteria for federated packs
 - [COLLECTION_SPEC.md](../../../COLLECTION_SPEC.md) — collection catalog specification
 - [CONTRIBUTING.md](../../../CONTRIBUTING.md) — contribution paths overview

.claude/skills/federation-review/SKILL.md

@@ -22,6 +22,10 @@ metadata:
 
 Validate an external agentic pack proposed for federation in a PR. Checks license compatibility, runs automated validation, and verifies the module is loadable by Lola.
 
+Federated modules install as **complete Lola packs** — all skills under the declared `path`, same as in-repo marketplace modules. There is no per-skill marketplace filter.
+
+Federated modules install as **complete Lola packs** — all skills under the declared `path`, same as in-repo marketplace modules. There is no per-skill marketplace filter.
+
 ## Prerequisites
 
 - Access to the agentic-collections repository
@@ -116,7 +120,8 @@ lola market rm "$MARKET"
 ```
 
 2. **Check:** The federated module appears in the module list with correct name, version, and description.
-3. **Output to user:** Lola verification result (visible or not, with details).
+3. **Note:** Lola does not yet honor marketplace `ref` at install time ([lola#180](https://github.com/LobsterTrap/lola/issues/180)); verify listing only, not revision pinning.
+4. **Output to user:** Lola verification result (visible or not, with details).
 
 ### Phase 5: Summary
 

.github/workflows/federation-validation.yml

@@ -99,7 +99,6 @@ jobs:
               repo = mod.get('repository', '')
               ref = mod.get('ref', '')
               pack_path = mod.get('path', '.')
-              skills = mod.get('skills')
               name = mod.get('name', 'unknown')
 
               print(f'\n--- Validating: {name} ---')
@@ -111,8 +110,6 @@ jobs:
 
               cmd = [sys.executable, 'scripts/validate_federation.py', repo, '--ref', ref, '--pack-path', pack_path, '--json',
                      '--module-json', json.dumps(mod)]
-              if skills:
-                  cmd.extend(['--skills'] + skills)
 
               result = subprocess.run(cmd, capture_output=True, text=True)
               print(result.stdout)

CLAUDE.md

@@ -18,7 +18,7 @@ agentic-collections/
 
 ### Agentic Pack Architecture
 
-Packs follow the [Lola](https://github.com/RedHatProductSecurity/lola) package manager format. Install via `lola install -f <pack-name>` from the marketplace.
+Packs follow the [Lola](https://github.com/LobsterTrap/lola) package manager format. Install via `lola install -f <pack-name>` from the marketplace.
 
 Each pack follows this structure:
 ```
@@ -44,7 +44,7 @@ There are two ways to add skills to this project:
 
 **Direct Contribution** — Skills are added directly to this repository, inside an existing pack. The contributor opens a PR, skills are reviewed and merged, and maintainers own them from that point. Use `/agentic-contribution-skill` in Claude Code or follow [CONTRIBUTING.md](CONTRIBUTING.md).
 
-**Federation** — An external repository containing a complete, independent Lola pack is referenced in our catalog. The code stays in the external repo; users install it directly via Lola. The external owner maintains their pack. To request federation, open a PR adding the module to `marketplace/rh-agentic-collection.yml` with the `federation` label. Maintainers evaluate the pack using the [Federation Review Guide](FEDERATION_REVIEW_GUIDE.md) and the `/federation-review` skill.
+**Federation** — An external repository containing a complete, independent Lola pack is referenced in our catalog. The code stays in the external repo; users install the **full pack** (all skills at `path`) directly via Lola. The external owner maintains their pack. To request federation, follow [FEDERATION_REQUEST_GUIDE.md](FEDERATION_REQUEST_GUIDE.md) or run `/federation-request` in Claude Code. Maintainers evaluate requests using [FEDERATION_REVIEW_GUIDE.md](FEDERATION_REVIEW_GUIDE.md) and the `/federation-review` skill.
 
 ## Working with Agentic Collections
 

CONTRIBUTING.md

@@ -72,7 +72,8 @@ Both tiers must pass before submitting a PR.
 ## Resources
 
 - [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) -- Design principles and templates
-- [Federation Review Guide](FEDERATION_REVIEW_GUIDE.md) -- How external packs are evaluated for federation
+- [FEDERATION_REQUEST_GUIDE.md](FEDERATION_REQUEST_GUIDE.md) -- How to federate an external pack into the marketplace
+- [FEDERATION_REVIEW_GUIDE.md](FEDERATION_REVIEW_GUIDE.md) -- How external packs are evaluated for federation
 - [agentskills.io specification](https://agentskills.io/specification) -- Base skill standard
 - [Documentation site](https://rhecosystemappeng.github.io/agentic-collections) -- Browse all collections
 - [GitHub Issues](https://github.com/RHEcosystemAppEng/agentic-collections/issues) -- Report bugs or ask questions

FEDERATION_REQUEST_GUIDE.md

@@ -0,0 +1,123 @@
+# Federation Request Guide
+
+List your external Lola pack in the Red Hat Agentic Collections marketplace **without moving code into this repo**. Users install from your repository via [Lola](https://github.com/LobsterTrap/lola). Maintainer review: [FEDERATION_REVIEW_GUIDE.md](FEDERATION_REVIEW_GUIDE.md).
+
+> **Install scope:** `lola install -f <name>` installs the **full pack** at `path` (same as in-repo modules). No per-skill subset in marketplace YAML.  
+> **Lola `ref`:** Required here as a 40-character commit SHA for CI/catalog pinning. Lola ignores it at install until [lola#180](https://github.com/LobsterTrap/lola/issues/180).
+
+## Process
+
+```mermaid
+flowchart TB
+  subgraph contributor ["Contributor"]
+    A["Prepare external pack<br/>(Lola layout, LICENSE, skills)"]
+    B["validate_federation.py"]
+    C{Path}
+    D["/federation-request"]
+    E["Manual edits"]
+    F["PR: marketplace YAML + plugins.json<br/>+ federation/modules/&lt;name&gt;/.catalog/"]
+    A --> B --> C
+    C -->|recommended| D --> F
+    C -->|this guide| E --> F
+  end
+
+  subgraph ci ["CI (federation label)"]
+    G["Federation Validation workflow<br/>Tier 1 blocks · Tier 2 warns · MCP when applicable"]
+    F --> G
+  end
+
+  subgraph maintainer ["Maintainer"]
+    H{Path}
+    I["/federation-review"]
+    J["FEDERATION_REVIEW_GUIDE.md"]
+    K["Merge"]
+    G --> H
+    H -->|recommended| I --> K
+    H -->|manual| J --> K
+  end
+
+  K --> L["Users: lola install -f &lt;name&gt;"]
+```
+
+| Skill | Role | When |
+|-------|------|------|
+| **`/federation-request`** | Contributor | Infer metadata from repo URL + pack path; prepare the PR |
+| **`/create-collection`** | Contributor | Generate `federation/modules/<name>/.catalog/` from the external pack |
+| **`/federation-review`** | Maintainer | Run checks and guide approval |
+| **`/agentic-contribution-skill`** | Contributor | **Not federation** — add skills inside this repo ([CONTRIBUTING.md](CONTRIBUTING.md)) |
+
+---
+
+## Requirements
+
+| Requirement | Details | CI |
+|-------------|---------|-----|
+| **Lola pack** | `CLAUDE.md`, `README.md`, `skills/` at declared `path` | Blocks |
+| **License** | Apache-2.0–compatible LICENSE in your repo | Manual |
+| **Tier 1** | [agentskills.io](https://agentskills.io/specification) linter | Blocks |
+| **Tier 2** | [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) | **Warns** |
+| **MCP** | If `mcps.json` has servers: pin images; `${ENV_VAR}` for secrets | Blocks when applicable |
+| **Public repo + pinned `ref`** | Cloneable; 40-character commit SHA in marketplace entry | Blocks |
+
+```bash
+uv run python scripts/validate_federation.py <repo-url> --ref <40-char-sha>
+uv run python scripts/validate_federation.py <repo-url> --ref <sha> --pack-path <path>
+```
+
+---
+
+## Prepare the PR
+
+**Inputs** (for `/federation-request`): public **repository** URL and pack **path** (`.` at repo root). Everything else is inferred from a clone — `name`, `title`, `description`, `version`, `ref`, `tags`; override before opening the PR. Default maturity: **`ORANGE`**.
+
+**Three files to add or update:**
+
+1. **`marketplace/rh-agentic-collection.yml`**
+
+```yaml
+  - name: "<name>"
+    description: "<description>"
+    version: "<version>"
+    repository: "<repository>"
+    ref: "<40-char-commit-sha>"
+    path: "<path>"
+    tags: ["<tag>", "federation"]
+```
+
+2. **`docs/plugins.json`** — `"<name>": { "title": "<human-readable title>" }`
+3. **`federation/modules/<name>/.catalog/`** — catalog at `ref` (`id:` = module `name`)
+
+```bash
+git checkout -b feat/federate-<name>
+git add marketplace/rh-agentic-collection.yml docs/plugins.json federation/modules/<name>/
+git commit -m "feat: federate <name> module from <repository>"
+gh pr create --title "feat: federate <name> module" --label "federation"
+```
+
+The **`federation`** label triggers CI. Full check list: [FEDERATION_REVIEW_GUIDE.md](FEDERATION_REVIEW_GUIDE.md#automated-validation-recommended).
+
+---
+
+## After merge
+
+```bash
+lola market add rh-agentic-collections https://raw.githubusercontent.com/RHEcosystemAppEng/agentic-collections/main/marketplace/rh-agentic-collection.yml
+lola install -f <name>
+```
+
+**Updates:** bump `version` and `ref` (new SHA), refresh `.catalog/` if needed, open a PR with the `federation` label. Promotion to **`GREEN`** lists the pack on the [documentation site](https://rhecosystemappeng.github.io/agentic-collections).
+
+---
+
+## FAQ
+
+| Question | Answer |
+|----------|--------|
+| Subset of skills from a larger repo? | Use a dedicated pack subdirectory; set `path` to it. |
+| Private repo or monorepo? | Public only; monorepos OK via `path`. |
+| Tag instead of SHA for `ref`? | No — use `git rev-parse <tag>` and pin the SHA. |
+| Federation vs direct contribution? | Federation = external pack; direct = skills in this repo via `/agentic-contribution-skill`. |
+
+## Resources
+
+- [FEDERATION_REVIEW_GUIDE.md](FEDERATION_REVIEW_GUIDE.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) · [COLLECTION_SPEC.md](COLLECTION_SPEC.md) · [Lola](https://github.com/LobsterTrap/lola)

FEDERATION_REVIEW_GUIDE.md

@@ -4,6 +4,10 @@ Step-by-step guide for maintainers evaluating a federation PR.
 
 Federation means referencing an **external agentic pack** in our catalog. The code stays in the external repo — we don't copy or modify it. Users install federated packs directly from the external repo via Lola.
 
+Contributors: see [FEDERATION_REQUEST_GUIDE.md](FEDERATION_REQUEST_GUIDE.md) for how to open a federation PR.
+
+> **Lola `ref` field:** Marketplace `ref` is required here for validation and catalog pinning, but **Lola ignores it at install time** until [LobsterTrap/lola#180](https://github.com/LobsterTrap/lola/issues/180) is fixed.
+
 ## Two ways to review
 
 | Method | When to use |
@@ -26,9 +30,6 @@ uv run python scripts/validate_federation.py <repo-url> --ref <40-character-comm
 # Pack in a subdirectory
 uv run python scripts/validate_federation.py <repo-url> --ref <commit-sha> --pack-path <path>
 
-# Only specific skills
-uv run python scripts/validate_federation.py <repo-url> --ref <commit-sha> --skills <skill1> <skill2>
-
 # JSON output (for CI)
 uv run python scripts/validate_federation.py <repo-url> --ref <commit-sha> --json
 ```
@@ -79,9 +80,9 @@ The module entry in `marketplace/rh-agentic-collection.yml` must have the requir
 | `description` | Yes | Brief description |
 | `version` | Yes | Module version |
 | `repository` | Yes | Git URL to the external repo |
-| `ref` | Yes (project extension) | 40-character commit SHA pinning the pack (not a Lola field; required by this repo) |
+| `ref` | Yes (project extension) | 40-character commit SHA (required by this repo; **Lola ignores until [lola#180](https://github.com/LobsterTrap/lola/issues/180)**) |
 
-If the request is for a **subset of skills** (not the full pack), verify only the listed skill paths exist.
+All skills under the pack's `path` are validated and installed — the same scope as in-repo marketplace modules.
 
 ### Step 3: Validate skills — Tier 1 (agentskills.io spec)
 

README.md

@@ -4,7 +4,7 @@
 
 ## Installation (Lola package manager)
 
-Install collections using [Lola](https://github.com/RedHatProductSecurity/lola), the AI skills package manager. **Installation applies to the current folder only** — run commands from your project directory.
+Install collections using [Lola](https://github.com/LobsterTrap/lola), the AI skills package manager. **Installation applies to the current folder only** — run commands from your project directory.
 
 ### One-time setup: add marketplace
 
@@ -144,7 +144,7 @@ Each plugin has additional requirements:
 
 **New skill idea?** Run `/agentic-contribution-skill` in Claude Code.
 **Have an existing skill?** Run `/agentic-contribution-skill` and choose import mode.
-**Want to federate your own pack?** Follow the [Federation Guide](docs/federation_guide.md).
+**Want to federate your own pack?** Follow the [Federation Request Guide](FEDERATION_REQUEST_GUIDE.md).
 **Full guide:** [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ---
@@ -515,7 +515,7 @@ That CLI checks marketplace/plugin manifests for that workflow, including `plugi
 - **[Documentation Site](https://rhecosystemappeng.github.io/agentic-collections)**: Browse all collections, skills, and MCP servers
 - **[CLAUDE.md](CLAUDE.md)**: Repository structure and development workflow
 - **[Skill Design Principles](SKILL_DESIGN_PRINCIPLES.md)**: Quality guidelines for skills
-- **[Federation Guide](docs/federation_guide.md)**: How to federate your external pack into the marketplace
+- **[Federation Request Guide](FEDERATION_REQUEST_GUIDE.md)**: How to federate your external pack into the marketplace
 - **[Federation Review Guide](FEDERATION_REVIEW_GUIDE.md)**: How we evaluate external packs for federation
 - **[VALIDATION_REPORT.md](VALIDATION_REPORT.md)**: Marketplace compliance verification
 - **[Security Policy](SECURITY.md)**: Credential handling and vulnerability reporting

SKILL_DESIGN_PRINCIPLES.md

@@ -4,7 +4,7 @@ Repository-specific design principles for creating skills and agents in agentic
 
 **Scope**: Tier 2 requirements - repository enhancements beyond base agentskills.io specification (Tier 1 validated by linter).
 
-**Distribution (Lola):** Packs are installed with the [Lola](https://github.com/RedHatProductSecurity/lola) package manager from the registry in [`marketplace/rh-agentic-collection.yml`](marketplace/rh-agentic-collection.yml). Layout and install flow are documented in [CLAUDE.md](CLAUDE.md) and the root [README.md](README.md).
+**Distribution (Lola):** Packs are installed with the [Lola](https://github.com/LobsterTrap/lola) package manager from the registry in [`marketplace/rh-agentic-collection.yml`](marketplace/rh-agentic-collection.yml). Layout and install flow are documented in [CLAUDE.md](CLAUDE.md) and the root [README.md](README.md).
 
 **Collection catalog (pack-local):** Each pack may include **`<pack>/.catalog/collection.yaml`** and a **`collection.json`** mirror so tooling and docs can show a structured view of the collection. Authors follow [COLLECTION_SPEC.md](COLLECTION_SPEC.md) and the **create-collection** skill; field constraints are defined in **[`catalog/schema.yaml`](catalog/schema.yaml)** (JSON Schema in YAML). Pack **`SKILL.md`**, **`README.md`**, **`CLAUDE.md`**, and **`marketplace/rh-agentic-collection.yml`** stay the **sources of truth**; the catalog aggregates and summarizes them and does **not** replace or regenerate README or marketplace content.
 

docs/app.js

@@ -911,7 +911,7 @@ lola install -f ${moduleName}`;
     lolaLink.style.marginTop = '0.5rem';
     lolaLink.style.fontSize = '0.85rem';
     const lolaAnchor = document.createElement('a');
-    lolaAnchor.href = 'https://github.com/RedHatProductSecurity/lola';
+    lolaAnchor.href = 'https://github.com/LobsterTrap/lola';
     lolaAnchor.target = '_blank';
     lolaAnchor.textContent = 'Lola →';
     lolaAnchor.style.color = 'var(--primary)';

docs/index.html

@@ -51,7 +51,7 @@ <h1>Red Hat Agentic Catalog</h1>
     <div class="install-callout collapsed" id="install-callout">
         <div class="install-callout-toggle" onclick="toggleInstallCallout()" onkeydown="if(event.key==='Enter'||event.key===' ') { event.preventDefault(); toggleInstallCallout(); }" role="button" tabindex="0" aria-expanded="false" aria-controls="install-callout-body" title="Click to expand installation instructions">
             <span class="install-callout-arrow">▶</span>
-            <span class="install-callout-label">Install with <a href="https://github.com/RedHatProductSecurity/lola" target="_blank" onclick="event.stopPropagation()">Lola</a></span>
+            <span class="install-callout-label">Install with <a href="https://github.com/LobsterTrap/lola" target="_blank" onclick="event.stopPropagation()">Lola</a></span>
             <a href="https://github.com/RHEcosystemAppEng/agentic-collections#installation-lola-package-manager" target="_blank" class="install-callout-link" onclick="event.stopPropagation()">Full instructions →</a>
         </div>
         <div class="install-callout-body" id="install-callout-body">