docs(catalog): move README catalog to website

Author: KSemenenko

.github/workflows/publish-catalog.yml

@@ -150,7 +150,7 @@ jobs:
           echo "version=$version" >> "$GITHUB_OUTPUT"
           echo "tag=${{ env.CATALOG_TAG_PREFIX }}$version" >> "$GITHUB_OUTPUT"
 
-      - name: Generate catalog outputs in CI
+      - name: Validate catalog metadata in CI
         if: steps.changes.outputs.has_new_commits == 'true'
         run: python3 scripts/generate_catalog.py
 
@@ -327,7 +327,7 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Generate GitHub Pages payload
+      - name: Validate catalog metadata for GitHub Pages
         run: python3 scripts/generate_catalog.py
 
       - name: Render GitHub Pages

AGENTS.md

@@ -249,7 +249,7 @@ Other important repository files:
 - [`cli/ManagedCode.DotnetAgents/ManagedCode.DotnetAgents.csproj`](cli/ManagedCode.DotnetAgents/ManagedCode.DotnetAgents.csproj): publishable `.NET` tool that installs orchestration agents through `dotnet agents ...`.
 - [`cli/ManagedCode.Agents/ManagedCode.Agents.csproj`](cli/ManagedCode.Agents/ManagedCode.Agents.csproj): publishable `.NET` tool that installs orchestration agents through `agents ...`.
 - [`dotnet-skills.slnx`](dotnet-skills.slnx): canonical solution entry point for repository-level `dotnet build` and `dotnet pack` commands.
-- [`scripts/generate_catalog.py`](scripts/generate_catalog.py): catalog scanner, README generator, and validation entry point.
+- [`scripts/generate_catalog.py`](scripts/generate_catalog.py): catalog scanner, validation entry point, and optional transient manifest exporter.
 - [`scripts/generate_catalog_definitions.py`](scripts/generate_catalog_definitions.py): build-time generator that derives catalog categories and type directories from scanned manifests and emits `.g.cs` definitions for the CLI runtime.
 - [`scripts/generate_agent_catalog.py`](scripts/generate_agent_catalog.py): agent-catalog validation and optional export helper.
 - [`scripts/smoke_test_tool.sh`](scripts/smoke_test_tool.sh): CI smoke test for the installable tool package.
@@ -380,21 +380,21 @@ Rules:
 
 ## README Maintenance Rules
 
-[`README.md`](README.md) is the public index for the catalog.
+[`README.md`](README.md) is the concise public entry point for the project. The browsable catalog belongs on [skills.managed-code.com](https://skills.managed-code.com/), not as an embedded skill table in the README.
 
 Whenever you add, rename, split, merge, or remove a skill:
 
 1. For repo-authored entries, update `SKILL.md` frontmatter only for `name`, `description`, or `compatibility`, and update the sibling `manifest.json` for `version`, `category`, `packages`, or `package_prefix`. For imported upstream entries, keep `SKILL.md` verbatim and put any local-only metadata in the sibling `manifest.json`.
-2. Update the skill count if it is listed.
+2. Do not add an exact skill count or a generated catalog table to README.
 3. Update automation notes if watch coverage changes.
-4. Let the release workflows generate fresh catalog outputs in CI; run `python3 scripts/generate_catalog.py` locally only when you need a preview.
+4. Keep the README catalog call to action linked to `https://skills.managed-code.com/skills/`.
 
 The source of truth is the scanned `catalog/<type>/<package>/` tree: package `manifest.json`, nested `skills/*/SKILL.md`, and nested `agents/*/AGENT.md`. Do not introduce or rely on checked-in aggregate catalog JSON files as the source of truth.
-Do not hand-edit the generated catalog section between `<!-- BEGIN GENERATED CATALOG -->` and `<!-- END GENERATED CATALOG -->`.
 
 Generated catalog outputs:
 
-- [`README.md`](README.md) catalog section
+- public site pages generated by [`scripts/generate_pages.py`](scripts/generate_pages.py)
+- transient release manifests generated explicitly with `scripts/generate_catalog.py --manifest-output <path>`
 
 Canonical generation point:
 
@@ -611,7 +611,7 @@ For skill and docs changes:
 - Verify README links and catalog entries are correct.
 - `python3 -m py_compile scripts/generate_catalog.py`
 - `python3 scripts/generate_catalog.py --validate-only`
-- run `python3 scripts/generate_catalog.py` locally only when you explicitly need a preview of the generated README and manifest
+- run `python3 scripts/generate_catalog.py --manifest-output <path>` only when you explicitly need a transient manifest export
 
 For agent and docs changes:
 
@@ -688,8 +688,8 @@ This repository should behave like a maintainable documentation-and-automation s
 - On dense directory pages such as `/skills/`, catalog cards must use a strict shared composition so the grid reads as deliberate: matching heights per row, stable title/summary/meta/action bands, and line clamping where needed instead of ragged card growth.
 - Directory cards that represent navigable resources such as categories should make the whole card feel interactive. Do not leave large dead zones where only a small nested button or heading opens the destination.
 - The public skills site should visually align with the main ManagedCode website rather than inventing a separate noisy catalog aesthetic. When redesigning the site, inspect live ManagedCode pages first and reuse their calmer premium typography, spacing, accent restraint, and overall tone.
-- Public README hero copy must avoid exact skill counts in the top badge and intro line; keep precise counts only in the generated catalog section where they can stay authoritative.
-- The README header generator must normalize duplicate generated lines after merges; one canonical top Skills badge and one canonical intro line only.
+- Public README copy must avoid exact skill counts and embedded skill tables. Direct catalog browsing to `https://skills.managed-code.com/skills/`.
+- Keep one canonical top Skills badge and one canonical intro line in README.
 - For internal `SKILL.md`, `AGENT.md`, and `references/` content, optimize first for model loading and token economy. Human clickability or decorative Markdown formatting is secondary unless it materially improves maintenance.
 
 ### Dislikes
@@ -707,17 +707,17 @@ This repository should behave like a maintainable documentation-and-automation s
 - Bloated spacing on the public landing page, especially in Quick Start shells, step stacks, and sidebar cards.
 - Broken skill-card footers where category badges and install commands overlap, wrap awkwardly, or compete for the same horizontal space.
 - Exact skill counts in the public README hero badge or intro copy, where they go stale and create pointless merge churn.
-- README generators that update only the first header occurrence and leave duplicate Skills badges or duplicate intro lines behind after merges.
+- Full generated catalog tables in README; the public site is the canonical browse surface.
 - Rewriting concise internal reference paths into verbose Markdown-link syntax when that does not help the model.
 
 ## Anti-Patterns
 
 Do not do these:
 
 - Create duplicate skill trees.
-- Add frameworks without updating the generated catalog inputs and regenerating README.
+- Add frameworks without updating the catalog inputs and validating the public site generator.
 - Add watch entries without mapping them to affected skills.
 - Hand-edit the state file instead of syncing it.
-- Hand-edit the generated README catalog section.
+- Embed or regenerate the full catalog in README.
 - Use noisy GitHub release watches without filtering mixed release streams.
 - Base skill logic on unofficial or stale sources when official docs exist.

CONTRIBUTING.md

@@ -216,7 +216,7 @@ The importer auto-discovers upstream plugins from vendored `plugin.json` files a
 
 For imported official upstream skills, keep the upstream skill or agent id unless there is a real compatibility reason to rename it.
 
-Do not hand-edit the generated catalog tables.
+Do not add generated catalog tables to `README.md`. The browsable catalog is published at [skills.managed-code.com](https://skills.managed-code.com/).
 
 Instead:
 
@@ -227,20 +227,21 @@ Instead:
 bash scripts/sync_external_catalog_sources.sh
 ```
 
-3. If you want a local preview of generated outputs, run:
+3. Validate the scanned catalog and render a local site preview:
 
 ```bash
-python3 scripts/generate_catalog.py
+python3 scripts/generate_catalog.py --validate-only
+python3 scripts/generate_pages.py
 ```
 
-This preview updates:
+The site preview is written to:
 
-- the generated catalog section in [`README.md`](README.md)
+- `artifacts/github-pages/`
 
-For metadata-only validation without rewriting generated files:
+To export a transient machine-readable release manifest explicitly:
 
 ```bash
-python3 scripts/generate_catalog.py --validate-only
+python3 scripts/generate_catalog.py --manifest-output /path/to/dotnet-skills-manifest.json
 ```
 
 ## Dotnet Tool Distribution