Maintain a Multi-Language Resource List Built from Data Files, Not Hand-Edited Pages

## Know That the List Pages Are Built from Data Files You maintain a curated knowledge base whose human-facing outputs are **generated**, not authored. Understand the split before touching anything: - **Source of truth** is a set of structured data files: a category/section tree (defining anchors and the table of contents) and one entry file per section. - **Generated artifacts** — the human-readable listing documents (one per supported language) and any machine-readable index — are produced from that data by a generator script. They are disposable and rebuilt on demand. - The same underlying data may also feed a runtime query interface for automated agents, so data quality has consumers beyond the rendered documents. There is typically no application runtime, build, or test suite here. Every change is one of three things: structured data, tooling scripts, or documentation. Keep that mental model — it prevents the most common and most damaging mistake: editing an output that will be overwritten. ## Change the Data and Rebuild the Pages Instead of Editing Them - **Never edit a generated output document directly.** Edits are blown away on the next regeneration. To change what a reader sees, change the underlying data. - To add or modify an item, edit the relevant section's entry file. - To add a new section, edit the category/section-tree file first, then create the matching entry file. Afterward run the anchor-verification tool to confirm no externally referenced anchor was lost. - After any data change, run the generator locally to refresh all generated files before committing. Continuous integration will reject a working tree that diverges from freshly generated output — so regenerate, don't guess. - Do not hand-edit the machine-readable index; it is fully regenerated by the generator. ## Fill In Each Entry's Fields and Write a One-Sentence Description for Readers Each entry is a structured record with required fields (a stable unique id, URL, title, category, type, difficulty level, language set, date added, status) and optional fields filled in by automation (archive URL, last-checked timestamp, content fingerprint). Respect the controlled vocabularies for type, difficulty, language, and status — do not invent values. Treat the free-text description that accompanies an entry as **public-facing, third-party-readable copy**: - **Include** a single factual sentence describing what the resource is, optionally followed by an author byline. - **Exclude** anything internal: references to this project, issue or change-request numbers, "originally proposed by" phrasing, or any historical metadata. Version-control history already preserves attribution; an outside reader must not be able to infer any relationship between the entry and this repository. - Leave machine-migrated values untouched unless the original is wrong or stale. - Opt an entry out of external archiving only when the original author has explicitly requested it (paywalled content, takedown requests). ## Keep Section Link Names Unchanged So Outside Links Don't Break External sites and the internal table of contents both point at named anchors. Renaming or removing an existing anchor silently breaks every inbound link that targets it. - **Never rename or remove an existing anchor.** Add new anchors for new sections instead. - A continuous-integration guard compares the current anchor set against the baseline and fails the build if any baseline anchor is missing. Treat that guard as a hard gate, not a suggestion. - Because the generator sorts entries deterministically (by date added, then title), never bulk-reorder entries by hand. To move an entry earlier in the list, change its date-added value rather than rearranging records. ## Keep Code and Notes in One Main Language and Choose Each Entry's Editions Project-authored content is written in one primary language. Multiple languages appear only where multilingualism is intrinsic to the artifact: translated output documents, localized section-title overrides, per-entry titles that preserve the resource's original language, and trigger phrases meant to activate on non-primary-language prompts. Everything else — code, comments, field names, templates, pipeline output, labels, commit messages — stays in the primary language. A single entry may appear in several language editions, controlled by its language set: - New entry with no language hint → list it in the primary language only, and ask the contributor whether they also want it in other editions. - Locale-specific resource → tag it with only that locale. - Genuinely cross-cultural canonical resource → tag it across the relevant languages, or use the wildcard sparingly. - Never force-translate or force-mirror an entry across editions just to make the structures match. Each edition may contain entries the others don't. ## Bring In Contributions Without Losing the Contributor's Credit Inbound requests arrive in two shapes and must be ported so credit is never lost: - **Structured proposal (no branch):** port the entry directly into the data model, regenerate, run the verifiers, and commit with a co-author trailer crediting the submitter — that trailer is their only credit. - **Direct change request (contributor edited files on their own branch):** port the work *on their branch* so their change merges with full attribution. Never route a direct contributor change through an automated assistant that opens its own competing request and closes the contributor's — that destroys their merge credit. An automated coding assistant may serve as an **async fallback for structured proposals only**, when the maintainer is unavailable and the queue must keep moving. It is not the default path; a human still reviews the result before merge. The assistant saves typing, not judgment. ## Check Every Change Automatically and Let the Review Bot Only Give Advice On every change touching data or generator scripts, the pipeline should: 1. Run schema validation and anchor validation. 2. Re-run the generator and warn if the working tree diverges from freshly generated output (a sign the contributor forgot to regenerate). 3. Invoke an automated review bot that grades each new entry against a published rubric, posts one structured comment, and applies advisory labels. Design the review bot conservatively: detect the contributor's language deterministically (not via the model) and pass that in as a directive; when the model call fails, fall back to deterministic reachability and format checks under a distinct "review-failed" label. **The bot never auto-merges and never auto-rejects** — it advises, humans decide. ## Never Hand-Edit Pages, and Stop to Ask About Changes the Rules Don't Cover Do not: - Edit generated output documents or the machine-readable index by hand. - Rename or remove existing anchors. - Introduce markup beyond the project's allowed tag whitelist in templates. - Bulk-reorder existing entries instead of adjusting sort keys. - Edit contribution guidelines, code-of-conduct, or workflow definitions unless explicitly asked. - Create commits or push unless explicitly asked. When a change crosses into territory these rules don't cover — a new language edition, a new schema field, a new section taxonomy — stop and ask rather than improvising. Match the spirit of the contribution guide and scoring rubric, and when in doubt, confirm with a human before acting.