ATR-Lab · MarcoDotIO · Sep 30, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,55 @@
+name: Bug report
+description: Something in this repository doesn't work as documented.
+title: "Bug: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting. This issue is public: don't paste passwords, API keys, robot Wi-Fi credentials or data that identifies a study participant.
+        For a security vulnerability, don't open an issue; follow the repository's security policy instead.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What you did, what you expected and what happened instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Exact commands, launch files or clicks, in order.
+      placeholder: |
+        1. ros2 launch ...
+        2. ...
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs and error messages
+      description: Paste the full output. It is formatted as code automatically.
+      render: shell
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: OS and version, ROS 2 distribution, language or tool versions, and the branch or commit.
+      placeholder: "Ubuntu 24.04, ROS 2 Jazzy, commit abc1234"
+    validations:
+      required: true
+  - type: dropdown
+    id: hardware
+    attributes:
+      label: Does this involve a robot or other hardware?
+      options:
+        - "No, software only"
+        - "Yes (name the robot, firmware and how it was controlled below)"
+    validations:
+      required: true
+  - type: textarea
+    id: hardware-details
+    attributes:
+      label: Hardware details
+      description: Robot or device, firmware or software version, and whether it was teleoperated, autonomous or scripted.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Advanced Telerobotics Research Lab website
+    url: https://www.atr.cs.kent.edu/
+    about: Questions about joining or working with the lab.
+  - name: Getting started at the lab
+    url: https://github.com/ATR-Lab/getting-started-atr-lab
+    about: Lab rules, safety, research standards, tools and hardware for lab members.
diff --git a/.github/ISSUE_TEMPLATE/docs_fix.yml b/.github/ISSUE_TEMPLATE/docs_fix.yml
@@ -0,0 +1,24 @@
+name: Documentation fix
+description: A wrong fact, an outdated step, a broken link or something unclear in the docs.
+title: "Docs: "
+labels: ["documentation"]
+body:
+  - type: input
+    id: page
+    attributes:
+      label: Page
+      description: Link to the page (and the section, if you can).
+      placeholder: "/ATR-Lab/<repo>/blob/<branch>/<path>.md#<section>"
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: What's wrong or unclear?
+    validations:
+      required: true
+  - type: textarea
+    id: fix
+    attributes:
+      label: Suggested fix and source
+      description: The correct text or step, and where it comes from (an official doc, a vendor page, the lab). Facts about the lab need a source.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,29 @@
+name: Feature request
+description: Suggest an improvement or a new capability.
+title: "Feature: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+      description: Who needs it and what they can't do today.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What do you propose?
+      description: The change you have in mind. Sketches, links and examples help.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you considered
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Contributing
+      options:
+        - label: I'd like to work on this myself.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,19 @@
+## What this changes
+
+<!-- One or two sentences. Link the issue: "Closes #12". -->
+
+## Why
+
+<!-- The problem this solves or the reason for the change. -->
+
+## How I tested it
+
+<!-- Commands you ran, robots or simulators you tried it on, screenshots or a short video.
+     Label robot videos: teleoperated, autonomous, semi-autonomous or scripted, and the playback speed. -->
+
+## Checklist
+
+- [ ] It builds, and the tests and linters this repository uses pass (see `AGENTS.md`).
+- [ ] Docs, `README.md` and `AGENTS.md` are updated if behavior, files or commands changed.
+- [ ] No secrets, credentials, large binaries or data that identifies study participants are included.
+- [ ] If an AI coding assistant helped, I reviewed and tested every change it made.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,37 @@
+name: docs
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  schedule:
+    - cron: "0 9 * * 1" # Mondays: catch links that rot over time
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  markdown:
+    name: Markdown lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: DavidAnson/markdownlint-cli2-action@v24
+        with:
+          globs: "**/*.md"
+
+  links:
+    name: Link check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Pull requests check only links to files in this repository (--offline), because links to other
+      # ATR-Lab repositories may point at pages that are merged later. Pushes and the weekly run check everything.
+      - uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --no-progress --max-concurrency 8 --accept 200,206,429
+            ${{ github.event_name == 'pull_request' && '--offline' || '' }}
+            "**/*.md"
+          fail: true
diff --git a/.lycheeignore b/.lycheeignore
@@ -0,0 +1,13 @@
+# Sites that block automated link checkers (403/999 to bots). Check these by hand when you edit them.
+^https://dl\.acm\.org/
+^https://doi\.org/10\.1145/
+^https://ieeexplore\.ieee\.org/
+^https://(www\.)?linkedin\.com/
+^https://(www\.)?researchgate\.net/
+^https://(www\.)?instagram\.com/
+^https://(www\.)?x\.com/
+^https://(www\.)?twitter\.com/
+^https://(www\.)?reddit\.com/
+^https://(www\.)?raspberrypi\.com/
+^https://forums\.raspberrypi\.com/
+^https://support\.unitree\.com/
diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc
@@ -0,0 +1,20 @@
+// markdownlint rules for ATR Lab docs (https://github.com/DavidAnson/markdownlint)
+{
+  "default": true,
+  // Long lines are fine in prose; editors wrap them.
+  "MD013": false,
+  // READMEs open with an HTML header image instead of a "# Heading".
+  "MD041": false,
+  // HTML is allowed only for layout GitHub supports: centered headers, card grids, collapsible sections.
+  "MD033": {
+    "allowed_elements": ["p", "img", "a", "b", "br", "sub", "sup", "table", "tr", "td", "th", "thead", "tbody", "picture", "source", "details", "summary", "kbd", "div"]
+  },
+  // Repeated headings are fine in different sections (e.g. "Safety" under each robot).
+  "MD024": { "siblings_only": true },
+  // Numbered lists may use 1. 2. 3. or all 1.
+  "MD029": false,
+  // Table pipe spacing is cosmetic; "|---|" and "| --- |" are both fine.
+  "MD060": false,
+  // Emphasis used as a label ("**Read this when** ...") is not a heading.
+  "MD036": false
+}
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,103 @@
+# AGENTS.md: ATR-Lab/.github
+
+This is the special `.github` repository of the **ATR-Lab** GitHub organization, which belongs to the Advanced
+Telerobotics Research Lab (Department of Computer Science, Kent State University). It holds the organization's
+front page (`profile/README.md`) and the default community files that GitHub applies to every ATR-Lab repository
+without its own. It is **not** where lab documentation lives; this file also serves as the map of the whole
+organization, so start here when you need to know which repository answers a question.
+
+## Organization map: which repository answers which question
+
+| Question | Repository | Default branch |
+|---|---|---|
+| What is the lab, what does it research, what has it achieved, who is in it, where is the press kit? | [ATR-Lab/about](https://github.com/ATR-Lab/about) | `master` |
+| I'm new: rules, safety, research standards, LaTeX templates, tech stack, lab hardware? | [ATR-Lab/getting-started-atr-lab](https://github.com/ATR-Lab/getting-started-atr-lab) | `master` |
+| How should code look, which lint configs, Git and PR practice, rules for AI coding agents? | [ATR-Lab/dev-guidelines](https://github.com/ATR-Lab/dev-guidelines) | `master` |
+| ROS 2 concepts, distributions (Foxy to Lyrical), installation, commands, debugging, lab robots in ROS 2? | [ATR-Lab/all-things-ros2](https://github.com/ATR-Lab/all-things-ros2) | `main` |
+| Logos, colors, fonts, templates, brand and copy rules, verified lab facts? | [ATR-Lab/atr-lab-design-skill](https://github.com/ATR-Lab/atr-lab-design-skill) | `main` |
+| Reproducible ROS 2 environments with lockfiles? | [MarcoDotIO/rosenv](https://github.com/MarcoDotIO/rosenv) (a lab member's project, outside the org) | `main` |
+
+**Public project repositories** (many other lab repositories are private; don't name private ones in public
+files):
+
+| Platform or topic | Repositories |
+|---|---|
+| Unitree Go2 (quadruped) | `go2_ws` |
+| Booster K1 (humanoid) | `expressive-motion` |
+| SoftBank Pepper | `PepperKit`, `PepperLLMDemo`, `PepperLLMDemo-Server` |
+| Coffee Buddy (service robot) | `kami-head` |
+| Yahboom robots | `yahboom_r2l_ros2` |
+| Robot mower | `robo_mower_ws` |
+| TeleBot line (telepresence) | `TeleBot-4R`, `TeleBot-4R-XR` |
+| Dynamixel servos | `multi-servo-dynamixel-library` |
+| Other | `atr-dashboard`, `HRI-Tello-Drone-Controller`, `ATR-Lab.github.io` |
+
+Check visibility before linking any other repository:
+`gh repo view ATR-Lab/<name> --json visibility --jq .visibility`.
+
+## Repo map (this repository)
+
+| Path | Purpose |
+|---|---|
+| `profile/README.md` | Organization front page (keep it short; absolute image URLs) |
+| `profile/assets/header.png` | 1600 × 400 front-page header, built from the design skill's poster band and the official lockup |
+| `profile/assets/social-preview.png` | 1280 × 640 social preview (uploaded by hand in Settings) |
+| `profile/assets/icons/` | 96 px navy icon badges from the design skill, used in the "Start here" grid |
+| `README.md` | Explains this repository and the organization settings to fix by hand |
+| `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `SUPPORT.md` | Org-wide default community files |
+| `.github/ISSUE_TEMPLATE/` | Default issue forms (`bug_report.yml`, `feature_request.yml`, `docs_fix.yml`) and `config.yml` |
+| `.github/PULL_REQUEST_TEMPLATE.md` | Default pull request template |
+| `.github/workflows/docs.yml` | Markdown lint and link check for this repository only |
+| `.markdownlint.jsonc` | Markdown lint rules shared by all lab docs repositories |
+| `.lycheeignore` | Sites that block automated link checkers (check those links by hand) |
+| `AGENTS.md`, `CLAUDE.md` | This file; `CLAUDE.md` imports it |
+| `LICENSE` | MIT |
+
+## Sources of truth
+
+- **Lab facts** (names, director, projects, platforms, achievements and their exact wording, contacts, handles):
+  only `references/brand-foundation.md` in the ATR Lab design skill (installed locally at
+  `~/.claude/skills/atr-lab-design/`). Never invent names, rooms, results, dates or numbers; write a
+  `[bracketed placeholder]` and list it under "Open items".
+- **Never print** anything on the "Never print" list in `brand-foundation.md` §11 (a nonexistent social handle,
+  the director's office room and phone as the lab's, an outdated college name, "KSU" in running copy, "ATR"
+  alone, RoboCup placements, media-outlet counts). The brand check below catches most of these.
+- **GitHub behavior** (community health files, issue forms, profile READMEs): docs.github.com.
+
+## Writing rules
+
+- Kent State style: sentence-case headings, no Oxford comma, "and" not "&", dates like "Sept. 30, 2026", no emoji.
+- The lab's name: "Advanced Telerobotics Research Lab" on first reference, then "the lab"; "ATR Lab" only in
+  display text, always with Kent State nearby.
+- "ROS 2", never "ROS2", in prose. Cut hype words (cutting-edge, state-of-the-art, innovative, leverage, robust).
+- Default community files apply to about 100 repositories: keep them general, short and free of lab-only
+  details that could go stale.
+- Issue forms must stay valid against GitHub's issue-forms schema.
+
+## How to check your work
+
+```bash
+# Brand, facts and Kent State style (exit code 0 means no errors)
+PYTHONDONTWRITEBYTECODE=1 ~/.claude/skills/atr-lab-design/.venv/bin/python ~/.claude/skills/atr-lab-design/scripts/brand_check.py $(git ls-files --cached --others --exclude-standard '*.md')
+# Markdown structure
+npx --yes markdownlint-cli2 "**/*.md"
+# Issue forms parse as YAML
+uvx --with pyyaml python -c "import glob, yaml; [yaml.safe_load(open(f)) for f in glob.glob('.github/ISSUE_TEMPLATE/*.yml')]"
+```
+
+## Open items
+
+| Where | Placeholder | Who can fill it |
+|---|---|---|
+| `CODE_OF_CONDUCT.md` | `[conduct contact email]`, `[conduct contact role]`; the page is a draft until the director approves | Director |
+| `SECURITY.md` | `[security contact email]` | Director or lab manager |
+| `SUPPORT.md` | `[Slack channel]` | Lab manager |
+| `README.md` (org settings table) | `[a kent.edu lab address]` | Director |
+| Organization settings | Display name, description, location, email and avatar (see `README.md`) | An org owner |
+
+## Related repos
+
+- [about](https://github.com/ATR-Lab/about): what the lab is, research, achievements, press kit, members.
+- [getting-started-atr-lab](https://github.com/ATR-Lab/getting-started-atr-lab): onboarding, rules, safety, research standards, tech stack, hardware.
+- [dev-guidelines](https://github.com/ATR-Lab/dev-guidelines): code style, lint configs, Git, AI-assisted development.
+- [all-things-ros2](https://github.com/ATR-Lab/all-things-ros2): the lab's ROS 2 handbook.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,48 @@
+# Code of conduct
+
+> **Read this when** you take part in any ATR-Lab repository: issues, pull requests, reviews, discussions or
+> comments. A repository with its own `CODE_OF_CONDUCT.md` overrides this page.
+
+The Advanced Telerobotics Research Lab at Kent State University builds robots that help people rather than
+replace them, and we want our online spaces to work the same way: people first, work second.
+
+## What we expect
+
+- Be respectful and assume good intent. Critique ideas and code, never people.
+- Be welcoming to newcomers. Explain terms, link to docs and remember that everyone started somewhere.
+- Give credit. Name the people whose work, data or ideas you build on.
+- Be honest about results. Don't overstate what a robot, a model or a study can do.
+- Respect privacy. Don't post other people's personal information, photos or study data.
+
+## What is not acceptable
+
+- Harassment, insults, threats or discriminatory language or imagery, in public or in private messages.
+- Sexualized language or content, or unwelcome attention.
+- Publishing someone's private information without their explicit permission.
+- Sustained disruption of discussions, reviews or events.
+- Any other conduct that a reasonable person would find inappropriate in a professional setting.
+
+## Scope
+
+This code applies in every ATR-Lab repository and in any space where someone represents the lab online.
+Lab members are also bound by the
+[lab's code of conduct](https://github.com/ATR-Lab/getting-started-atr-lab/blob/master/lab-rules/code-of-conduct.md)
+and by Kent State University policies, including the
+[Student Code of Conduct](https://www.kent.edu/studentconduct/code-student-conduct).
+
+## Reporting
+
+Report a problem to [conduct contact email]. Reports are read by [conduct contact role] and handled as
+confidentially as the situation allows. If the concern involves that person, contact the lab director,
+Jong-Hoon Kim, associate professor of computer science, at <jkim72@kent.edu>.
+
+For discrimination, harassment or safety concerns, Kent State University's own reporting routes also apply;
+the lab will point you to the right university office.
+
+## Enforcement
+
+Maintainers may edit or remove comments, commits or issues that break this code, and may restrict or block
+anyone who does so repeatedly or seriously. Decisions are explained to the person involved when it is safe to
+do so.
+
+<sub>Last reviewed: Sept. 30, 2026 · Draft until the director approves</sub>