refactor: make catalog repository data-only

Author: xxg1413

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,15 +6,15 @@ Describe the problem, the change, and the reader or maintainer outcome.
 
 - [ ] Catalog resource or classification
 - [ ] Bilingual editorial content
-- [ ] Site or build code
+- [ ] Catalog export or consumer contract
 - [ ] Tests, tooling, or workflow
 - [ ] Governance or documentation
 
 ## Evidence and scope
 
 - Related issue:
 - Source or maintenance evidence:
-- User-visible pages affected:
+- Website consumer impact:
 - Intentionally out of scope:
 
 For catalog changes, explain the official source, review date, license or
@@ -27,8 +27,7 @@ List the actual results, not only the commands you intended to run.
 
 - [ ] `python -m pytest`
 - [ ] `python tools/validate_catalog.py`
-- [ ] `bundle exec jekyll build`
-- [ ] `bundle exec ruby tests/render_security_test.rb`
+- [ ] `python tools/export_catalog.py --check`
 - [ ] English and Chinese output remain consistent
 - [ ] No secrets, generated reports, local build output, or analytics IDs were committed
 

.github/dependabot.yml

@@ -1,25 +1,11 @@
 version: 2
 updates:
-  - package-ecosystem: bundler
-    directory: "/"
-    schedule:
-      interval: weekly
-      day: monday
-      time: "09:00"
-      timezone: Asia/Shanghai
-    open-pull-requests-limit: 5
-    groups:
-      jekyll-dependencies:
-        patterns:
-          - "github-pages"
-          - "jekyll-*"
-
   - package-ecosystem: pip
     directory: "/"
     schedule:
       interval: weekly
       day: monday
-      time: "09:15"
+      time: "09:00"
       timezone: Asia/Shanghai
     open-pull-requests-limit: 5
     groups:
@@ -32,7 +18,7 @@ updates:
     schedule:
       interval: weekly
       day: monday
-      time: "09:30"
+      time: "09:15"
       timezone: Asia/Shanghai
     open-pull-requests-limit: 5
     groups:

.github/workflows/validate.yml

@@ -36,13 +36,5 @@ jobs:
       - name: Validate catalog
         run: python tools/validate_catalog.py
 
-      - name: Set up Ruby and Bundler
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
-        with:
-          bundler-cache: true
-
-      - name: Build Jekyll site
-        run: bundle exec jekyll build
-
-      - name: Verify catalog output escaping
-        run: bundle exec ruby tests/render_security_test.rb
+      - name: Verify public JSON export
+        run: python tools/export_catalog.py --check

.gitignore

@@ -1,13 +1,3 @@
-# Jekyll
-_site/
-.sass-cache/
-.jekyll-cache/
-.jekyll-metadata
-
-# Ruby
-.bundle/
-vendor/
-
 # OS
 .DS_Store
 .DS_Store?

.ruby-version

@@ -2,37 +2,43 @@
 
 ## Mission
 
-This repository is the broad, community-maintained resource catalog behind
-FlyPython. Keep `flypython.com` focused on editorial learning paths and a small
-featured set; keep this repository focused on the larger reviewed catalog and
-its contribution workflow.
+This repository is the broad, community-maintained data catalog behind
+FlyPython. It is not a website. Keep `flypython.com` focused on editorial
+learning paths, task playbooks, and presentation; keep this repository focused
+on reviewed catalog data, its public JSON contract, and its contribution
+workflow.
 
 ## Content rules
 
 - Prefer official documentation and primary sources.
-- Every catalog entry must include a stable ID, path, source type, level,
-  rationale, review date, status, and any key or safety requirements.
+- Every catalog entry must include a stable ID, path, path-local order, source
+  type, level, rationale, review date, status, and any key or safety requirements.
 - Do not call a project production-ready without current maintenance, licensing,
   security, and adoption evidence.
 - Do not use an LLM or web-search API to generate resource descriptions.
   Descriptions and classifications require human review.
-- Keep English and Chinese pages generated from the same canonical resource
-  data. Do not hand-copy the full catalog into multiple Markdown files.
+- Keep English and Chinese website output generated from the same canonical
+  resource data. Do not hand-copy catalog content into website source files.
 - Treat HTTP 403, 429, and transient 5xx responses as review-needed states, not
   automatic proof that a resource is broken.
 
 ## Change workflow
 
 - Work on a feature branch and preserve unrelated contributor changes.
 - Run the repository validation workflow before committing.
+- Regenerate `catalog.json` after source changes and verify it with
+  `python tools/export_catalog.py --check`.
+- Website consumers must pin a full repository commit and verify the catalog
+  checksum. Do not make production builds depend on a moving branch.
 - Keep external-link checks read-only, rate-limited, retryable, and blocked from
   private or loopback network targets.
 - Do not add API keys, tokens, analytics IDs, or generated reports to git.
-- After merge, verify the GitHub Pages deployment and the production domain.
+- After merge, verify the immutable raw `catalog.json`. Verify flypython.com only
+  after a separate, deliberate consumer-version update.
 
 ## Review priorities
 
 1. Content accuracy and source quality.
-2. Deterministic generation and bilingual parity.
-3. Build, schema, link, accessibility, and SEO checks.
+2. Deterministic export and bilingual parity.
+3. Schema, consumer-contract, and safe link checks.
 4. Clear contribution and licensing boundaries.

AGENTS.md

@@ -1,39 +1,33 @@
 # Changelog
 
-This file records notable repository and catalog-process changes. The Git
-history remains the source for changes made before this changelog was added.
+This file records notable catalog-contract and maintenance changes.
 
 ## [Unreleased]
 
 ### Added
 
-- A single bilingual catalog source with 21 reviewed primary resources across
-  Python foundations, web and APIs, automation, and AI-agent paths.
-- Catalog schema validation and a safe external-link auditor with tests,
-  retry/backoff behavior, JSON reports, and SSRF/DNS-rebinding protection.
-- English and Chinese catalog pages generated from the same resource data,
-  plus a 1200x630 social preview image.
-- Contribution, conduct, security, and resource-curation policies.
-- Structured issue forms and a pull request review checklist.
-- Dependency update configuration and validation workflows.
-- Scheduled, manually dispatchable catalog-link auditing that does not run on
-  untrusted pull requests.
+- One source file per reviewed resource under `catalog/resources/`.
+- A deterministic, versioned `catalog.json` export for pinned website consumers.
+- A JSON Schema describing the public catalog v1 contract.
+- A pinned-revision and checksum contract for website consumers.
+- Export drift checks in tests and pull-request validation.
+- Positive, unique, consecutive ordering within each learning path.
+- Catalog validation and a safe external-link auditor with retry, report, and
+  SSRF/DNS-rebinding protection.
+- Contribution, conduct, security, issue, and resource-curation policies.
 
 ### Changed
 
-- Reframed the repository as the broad, community-maintained catalog behind
-  FlyPython while keeping the README files as short entry points.
-- Pinned the Python 3.12 and Ruby 3.3 build toolchains and their validation
-  dependencies for reproducible local and CI checks.
-
-### Fixed
-
-- Corrected repository links, dynamic resource counts, bilingual metadata,
-  canonical and hreflang output, robots rules, and duplicate heading/meta tags.
-- Escaped catalog-controlled HTML output, audited same-origin catalog links,
-  and made review-needed network results fail the scheduled audit.
+- Defined this repository as the canonical catalog-data and review layer behind
+  flypython.com, rather than a second public website.
+- Split catalog metadata, paths, and resources into independently reviewable
+  files while preserving the 21 existing human-reviewed resource records.
+- Required website consumers to pin a full repository commit and verify the
+  exported catalog checksum instead of following a moving branch.
+- Reduced the required local toolchain to Python 3.12 and locked Python
+  dependencies.
 
 ### Removed
 
-- Removed the legacy `README_cn` site route without adding a redirect, along
-  with unused feed, navigation, collection, theme, and inline-style config.
+- Removed Jekyll, Ruby, page templates, styles, scripts, social assets, CNAME,
+  robots configuration, and site-rendering tests.

CHANGELOG.md

@@ -1,102 +1,102 @@
-# Contributing to FlyPython
+# Contributing to the FlyPython catalog
 
-FlyPython is a bilingual, reviewed catalog of durable Python and AI-agent
-resources. Contributions should improve accuracy, source quality, or the
-catalog workflow. General Python questions belong in
-[GitHub Discussions](https://github.com/flypythoncom/python/discussions).
+FlyPython maintains a bilingual, reviewed source catalog used by
+[flypython.com](https://flypython.com/). Contributions should improve source
+quality, factual accuracy, or the maintenance workflow. General Python questions
+belong in [GitHub Discussions](https://github.com/flypythoncom/python/discussions).
 
-Before contributing, read the [curation policy](docs/CURATION_POLICY.md).
+Read the [curation policy](docs/CURATION_POLICY.md) before contributing.
 
 ## Permissions
 
-This repository currently does not grant a general license to reuse its
-content or code. Public visibility is not permission to copy, redistribute,
-or relicense repository material. Contributors must submit only material
-they have the right to submit and must preserve any required third-party
-notices. A contribution does not change the terms of third-party material.
+This repository currently does not grant a general license to reuse its content
+or code. Public visibility is not permission to copy, redistribute, or relicense
+repository material. Contributors must submit only material they have the right
+to submit and retain required third-party notices.
 
 ## Propose a change
 
 Use the matching issue form before a larger change:
 
-- **Resource proposal** for a new catalog entry.
+- **Resource proposal** for a new official source.
 - **Broken link** for an unreachable or replaced resource.
-- **Security report** for a vulnerability. Follow [SECURITY.md](SECURITY.md)
+- **Security report** for a vulnerability; follow [SECURITY.md](SECURITY.md)
   instead of opening a public issue.
 
-Small typo, metadata, or maintenance fixes may go directly to a pull request.
-Keep each pull request focused on one purpose.
+Small typo, metadata, or tooling fixes may go directly to a focused pull request.
 
-## Catalog changes
+## Catalog sources
 
-`_data/resources.yml` is the canonical catalog source. Do not add or change a
-resource only in a rendered Markdown page.
+The canonical source is the `catalog/` directory:
 
-Each resource entry must include these fields:
+- `catalog/catalog.yml` contains catalog-level review state.
+- `catalog/paths.yml` defines the four bilingual learning paths.
+- `catalog/resources/<id>.yml` contains one reviewed resource.
+- `catalog.json` is generated output and must not be edited by hand.
 
-- `id`, `path`, `title`, and `url`
+Every resource file must include:
+
+- `id`, `path`, `order`, `title`, and `url`
 - `source_type`, `level`, and `language`
 - `why_en` and `why_zh`
 - `reviewed_on` and `status`
 - `requires_key`, `risk`, and `featured`
 
+The filename must match the stable resource ID. Resource `order` values must be
+unique and consecutive within each path.
+
 Descriptions and classifications require human review. Do not use an LLM or a
 web-search API to generate them. Prefer official documentation, official
 standards, and official project pages.
 
-A 403, 429, or transient 5xx response is not enough to delete a resource. Mark
-it for review and provide repeatable evidence.
+A 403, 429, timeout, or transient 5xx response is not enough to delete a
+resource. Mark it for human review and provide repeatable evidence.
 
 ## Local setup
 
-Install the exact Python version from `.python-version`, Ruby, Bundler, and the
-repository dependencies:
+Install the exact Python version from `.python-version` and the locked
+development dependencies:
 
 ```bash
 python -m venv .venv
 . .venv/bin/activate
 python -m pip install -r requirements-dev.lock.txt
-bundle install
 ```
 
-## Required validation
+After changing catalog sources, regenerate the public export:
+
+```bash
+python tools/export_catalog.py
+```
 
-Run the same checks as CI before requesting review:
+Run the same deterministic checks as CI:
 
 ```bash
 python -m pytest
 python tools/validate_catalog.py
-bundle exec jekyll build
-bundle exec ruby tests/render_security_test.rb
+python tools/export_catalog.py --check
 ```
 
-Maintainers can run the networked link audit from GitHub Actions with the
-scheduled **Catalog link audit** workflow. For a deliberate local audit of
-every catalog entry, including same-origin URLs:
+Maintainers can run the networked link audit through GitHub Actions. For a
+deliberate local audit of every catalog entry:
 
 ```bash
 python tools/check_links.py --mode all --output reports/link-check.json
 ```
 
-Network link fetching is intentionally excluded from pull-request CI. A pull
-request can contain untrusted URLs, and status checks must remain deterministic.
-Any review-needed link result fails the scheduled audit so a maintainer must
-inspect it; it does not by itself justify removing the resource.
+Network fetching is excluded from pull-request CI. Any review-needed result
+fails the scheduled audit for maintainer inspection, but does not by itself
+justify removing a resource.
 
 ## Pull request checklist
 
-- Keep catalog data and bilingual output consistent.
-- Include evidence for maintenance, license, safety, and adoption claims.
+- Keep source data and the generated `catalog.json` consistent.
+- Preserve English and Chinese meaning.
+- Include evidence for maintenance, ownership, access, and safety claims.
 - Do not call a project production-ready without current evidence.
-- Do not commit secrets, API keys, analytics IDs, generated reports, or local
-  build output.
-- Submit only material you have the right to submit and retain any required
-  third-party notice.
-- Explain user-visible changes and list the commands you ran.
-
-## Review and merge
-
-Maintainers may request edits, reclassify an entry, or decline resources that
-do not meet the curation policy. Passing automated checks does not replace
-editorial review. After merge, maintainers verify the GitHub Pages deployment
-and the production domain.
+- Do not commit secrets, generated reports, caches, or local environments.
+- Explain consumer-visible changes and list the validation results.
+
+Passing automation does not replace editorial review. After merge, a website
+consumer must deliberately update its pinned catalog commit before the new data
+appears on flypython.com.