docs(meta): declare the repository description and topic set (#12)

.github/repository-topics.json

@@ -0,0 +1,130 @@
+{
+  "description": "Discovery metadata for GitHub repository topics and bot-readable repository classification.",
+
+  "repository": "hyperpolymath/hotchocolabot",
+  "rationale": "docs/REPO_METADATA.adoc",
+  "issue": "https://github.com/hyperpolymath/hotchocolabot/issues/12",
+
+  "description_text": "Educational robotics platform: an intentionally over-engineered hot chocolate dispenser, in Rust for Raspberry Pi, that teaches reverse engineering, systems thinking and safety-critical design to students aged 12–18 — with a mock-hardware HAL, a Certified Null Operations (CNO) safety state machine, and a full workshop curriculum.",
+  "short_description": "Educational robotics: a deliberately over-engineered hot chocolate dispenser for teaching reverse engineering and systems thinking.",
+
+  "minimum_topic_count": 7,
+  "recommended_topic_count": 20,
+  "description_max_chars": 350,
+
+  "topics": [
+    "epistemic-computing",
+    "epistemic-infrastructure",
+    "equivalence-aware-computing",
+    "hyperpolymath",
+    "typed-provenance",
+    "veridical-computing",
+    "open-source",
+    "robotics",
+    "education",
+    "teaching",
+    "reverse-engineering",
+    "stem-education",
+    "rust",
+    "raspberry-pi",
+    "embedded",
+    "mechatronics",
+    "state-machine",
+    "safety-critical",
+    "formal-verification",
+    "certified-null-operations"
+  ],
+
+  "topic_groups": {
+    "estate_spine": [
+      "epistemic-computing",
+      "epistemic-infrastructure",
+      "equivalence-aware-computing",
+      "hyperpolymath",
+      "typed-provenance",
+      "veridical-computing"
+    ],
+    "estate_convention": ["open-source"],
+    "project": [
+      "robotics",
+      "education",
+      "teaching",
+      "reverse-engineering",
+      "stem-education",
+      "mechatronics"
+    ],
+    "platform": ["rust", "raspberry-pi", "embedded", "state-machine"],
+    "method": [
+      "safety-critical",
+      "formal-verification",
+      "certified-null-operations"
+    ]
+  },
+
+  "selection_rationale": {
+    "bot_discovery": [
+      "robotics",
+      "education",
+      "reverse-engineering",
+      "mechatronics",
+      "stem-education",
+      "safety-critical",
+      "state-machine",
+      "certified-null-operations",
+      "formal-verification",
+      "embedded"
+    ],
+    "human_discovery": [
+      "robotics",
+      "education",
+      "teaching",
+      "reverse-engineering",
+      "stem-education",
+      "rust",
+      "raspberry-pi",
+      "embedded"
+    ],
+    "domain_accuracy": [
+      "mechatronics",
+      "state-machine",
+      "safety-critical",
+      "formal-verification",
+      "certified-null-operations"
+    ]
+  },
+
+  "related_repositories": [
+    {
+      "repo": "hyperpolymath/absolute-zero",
+      "relation": "CNO is formalised there; this repo is the taught, physical instantiation"
+    },
+    {
+      "repo": "hyperpolymath/robot-vacuum-cleaner",
+      "relation": "Sibling robotics build in the same Rust toolchain"
+    },
+    {
+      "repo": "hyperpolymath/lustreiser",
+      "relation": "Sibling safety-critical embedded work sharing the state-machine and formal-methods vocabulary"
+    },
+    {
+      "repo": "hyperpolymath/JuliaKids.jl",
+      "relation": "Sibling CS-education-for-children package"
+    },
+    {
+      "repo": "hyperpolymath/pseudoscript",
+      "relation": "Sibling pedagogy project (pseudocode as a first language)"
+    },
+    {
+      "repo": "hyperpolymath/gitbot-fleet",
+      "relation": "Repository quality enforcement fleet; also the historical mirror path for this project"
+    },
+    {
+      "repo": "hyperpolymath/methodologies",
+      "relation": "Where the captured design decisions behind this build live"
+    },
+    {
+      "repo": "hyperpolymath/palimpsest-license",
+      "relation": "Licence referenced by this repository"
+    }
+  ]
+}

CHANGELOG.adoc

@@ -8,6 +8,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 == [Unreleased]
 
+=== Added
+- **Repository metadata** (closes #12): the GitHub description and topic set are
+  now declared in `.github/repository-topics.json` and explained in
+  `docs/REPO_METADATA.adoc`, with `scripts/repo-metadata.sh` and three `just`
+  recipes to show, audit and apply them. Fills in the empty repository
+  description, adds the 14 domain topics the repository was missing, and adds the
+  `open-source` convention tag carried by 338 of the estate's ~343 repositories.
+- **Related projects table** in `README.adoc`, linking this repository to the
+  sibling work it shares vocabulary and audiences with (`absolute-zero`,
+  `lustreiser`, `robot-vacuum-cleaner`, `JuliaKids.jl`, `pseudoscript`,
+  `methodologies`, `gitbot-fleet`).
+
 === Planned
 - Hardware assembly and testing
 - Workshop pilot delivery (3 sessions, 15+ students)

Justfile

@@ -337,4 +337,28 @@ help:
     @echo "  just audit            - Security audit"
     @echo "  just rsr-check        - Check RSR compliance"
     @echo ""
+    @echo "Repository metadata (GitHub description + topics):"
+    @echo "  just repo-metadata       - Show the declared description/topics"
+    @echo "  just repo-metadata-audit - Check GitHub against the declaration"
+    @echo "  just repo-metadata-apply - Push them to GitHub (needs admin)"
+    @echo ""
     @echo "For full list: just --list"
+
+# === Repository Metadata Recipes ===
+# The GitHub "About" box (description + topics) lives in repository settings, not
+# in the tree, so it cannot be reviewed in a diff and cannot be enforced by CI.
+# These recipes make .github/repository-topics.json the reviewable source of truth.
+# Requires: jq, gh. Rationale for every value: docs/REPO_METADATA.adoc
+
+# Show the canonical description and topics declared for this repository
+repo-metadata:
+    @scripts/repo-metadata.sh show
+
+# Compare GitHub's live settings against the declared metadata (read-only; non-zero on drift)
+# Pass REPO= to audit a sibling repository in the estate instead
+repo-metadata-audit REPO="hyperpolymath/hotchocolabot":
+    @scripts/repo-metadata.sh audit "{{REPO}}"
+
+# Push the declared description and topics to GitHub (needs admin on the repository)
+repo-metadata-apply REPO="hyperpolymath/hotchocolabot":
+    @scripts/repo-metadata.sh apply "{{REPO}}"

README.adoc

@@ -18,6 +18,19 @@ Canonical home for HotChocolaBot is this repo: `https://github.com/hyperpolymath
 The old `gitbot-fleet` nested path is a mirror, not the source of truth.
 ====
 
+[NOTE]
+====
+Discovery tags for bots and humans: `epistemic-computing`, `epistemic-infrastructure`,
+`equivalence-aware-computing`, `hyperpolymath`, `typed-provenance`, `veridical-computing`,
+`open-source`, `robotics`, `education`, `teaching`, `reverse-engineering`, `stem-education`,
+`rust`, `raspberry-pi`, `embedded`, `mechatronics`, `state-machine`, `safety-critical`,
+`formal-verification`, `certified-null-operations`.
+
+The machine-readable source for these recommended GitHub topics is
+link:.github/repository-topics.json[`.github/repository-topics.json`].
+Rationale for each one: link:docs/REPO_METADATA.adoc[`docs/REPO_METADATA.adoc`].
+====
+
 == Overview
 
 HotChocolaBot is an over-engineered hot chocolate dispenser designed to teach reverse engineering, systems thinking, and problem-solving skills through heutagogic (self-directed) learning. Students deconstruct and analyze the system to understand complex engineering principles in an engaging, hands-on environment.
@@ -273,6 +286,21 @@ HotChocolaBot demonstrates concepts from ongoing research:
 - *UPM (Universal Project Manager)*: Case study for project management theory
 - *Formal Verification*: State machine approach bridges theory to practice
 
+=== Related Projects
+
+Where the ideas above are taken further, in this and neighbouring repositories:
+
+| Repository | Relationship |
+|-----------|--------------|
+| link:https://github.com/hyperpolymath/absolute-zero[absolute-zero] | CNO formalised across Coq, Lean 4 and Agda. This project is the taught, physical instantiation |
+| link:https://github.com/hyperpolymath/lustreiser[lustreiser] | Sibling safety-critical embedded work; shares the state-machine and formal-methods vocabulary |
+| link:https://github.com/hyperpolymath/robot-vacuum-cleaner[robot-vacuum-cleaner] | Sibling robotics build in the same Rust toolchain |
+| link:https://github.com/hyperpolymath/JuliaKids.jl[JuliaKids.jl] | Sibling CS-education-for-children package |
+| link:https://github.com/hyperpolymath/pseudoscript[pseudoscript] | Sibling pedagogy project — pseudocode as a first language |
+| link:https://github.com/hyperpolymath/methodologies[methodologies] | Where the captured design decisions behind this build live |
+| link:https://github.com/hyperpolymath/gitbot-fleet[gitbot-fleet] | Repository quality enforcement fleet; also the historical mirror path for this project |
+| link:https://github.com/hyperpolymath/palimpsest-license[palimpsest-license] | The licence referenced by this repository |
+
 == Competition Submission
 
 === Target: Robotics for Good Youth Challenge 2025-2026
@@ -337,6 +365,24 @@ image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: MPL-2.0,li
 cargo bench
 ```
 
+== Repository Metadata
+
+This repository's GitHub description and topics — the text GitHub indexes that
+lives outside the tree — are declared in `.github/repository-topics.json` and
+explained in link:docs/REPO_METADATA.adoc[docs/REPO_METADATA.adoc]. Change the
+JSON, not GitHub's settings, so the change is reviewable in a diff:
+
+```bash
+= Show the declared description and topics
+just repo-metadata
+
+= Check GitHub against the declaration (read-only)
+just repo-metadata-audit
+
+= Push them to GitHub (needs admin on the repository)
+just repo-metadata-apply
+```
+
 == License
 
 Code is under MPL-2.0 and docs are under CC-BY-SA-4.0.