Skip to content

mirkosertic/Megahub / .claude/skills/documentation

documentation

Verified

Documentation structure and maintenance rules for the Megahub project. Use whenever making user-facing changes — adding features, changing behavior, fixing hardware compatibility, or modifying configuration. Describes which files to update, the README structure, and writing style.

Documentation — Megahub Project

File Map

FileAudienceMaintained byUpdate trigger
README.mdEnd users — builders, makers, beginnersAI (on every user-facing change)Any change to features, hardware support, configuration, or user workflow
BLOCKS.mdEnd users — visual programmersAuto-generated (npm run generate-docs in frontend/)Any Blockly block added, removed, or modified
HUBAPI.mdDevelopers using WiFi/REST modeHuman or AIAny REST endpoint added or changed in lib/hubwebserver/
LUMP.mdProtocol implementersHumanLEGO UART protocol changes only
CLAUDE.mdAI assistantHumanArchitecture changes, new conventions

Never edit BLOCKS.md manually — it is fully auto-generated and will be overwritten.


README.md Structure

The README is the primary user document. It must always contain these sections in this order:

1. Introduction (project overview, 2–3 sentences)
2. Key Features (bullet list — what the device can do)
3. Screenshots (visual overview — keep current)
4. Hardware Photos
5. Getting Started
   5a. Prerequisites
   5b. Building the Firmware
   5c. Flashing the Board
   5d. First Boot and Connection
6. Hardware Reference
   6a. LEGO Device Ports (ports 0–3, connector type, LUMP protocol)
   6b. GPIO Pins (FastLED pin options, SD card pins, I2C)
   6c. Supported LEGO Devices
7. Using the IDE
   7a. Connecting (BT mode — Web Bluetooth, supported browsers)
   7b. Creating a Project
   7c. Programming with Blockly
   7d. Running and Stopping Programs
   7e. Autostart
8. WiFi Mode
   8a. Switching from BT to WiFi
   8b. config.json format
   8c. Accessing the Web UI
9. Gamepad Support
   9a. Pairing a gamepad
   9b. Supported gamepads (8BitDo M30 tested)
   9c. Blockly blocks available
10. Hardware Features
    10a. LEGO Powered Up support
    10b. FastLED/NeoPixel addressable LEDs
    10c. IMU (MPU6050) — yaw/pitch/roll, acceleration
    10d. SD Card storage
11. Troubleshooting
    11a. Bluetooth not connecting
    11b. Device not found
    11c. LEGO device not responding
    11d. Serial monitor for debugging
12. Documentation (links to BLOCKS.md, HUBAPI.md, LUMP.md)
13. License / Contributing (if applicable)

Writing Style Rules

Audience: Makers and robotics enthusiasts. Assume they know hardware basics but not necessarily ESP32 or Bluetooth internals.

  • Active voice: "Click Connect" not "The Connect button should be clicked"
  • Concrete steps: Use numbered lists for procedures, not prose paragraphs
  • No jargon without explanation: "BLE (Bluetooth Low Energy)" on first use, then "BLE"
  • No internal implementation details: Users don't need to know about FreeRTOS tasks, GATTS, or lua_pcall(). Focus on what they can do, not how it works inside.
  • Code blocks for commands and config: Always use fenced code blocks
  • Present tense: "The device starts in Bluetooth mode" not "The device will start"
  • Remove stale "coming soon" notes: If a feature doesn't exist yet, don't mention it

Key Facts for README Content

Hardware (verified from source code)

LEGO ports: 4 ports (0–3), via SC16IS752 I2C-to-UART bridge. LEGO Powered Up UART protocol. Motor speed: -127 to +127.

FastLED GPIO options: 13, 16, 17, 25, 26, 27, 32, 33 (NeoPixel/WS2812B compatible)

SD card SPI pins: CLK=18, MOSI=23, MISO=19, CS=4

IMU outputs: YAW, PITCH, ROLL (degrees), ACCELERATION_X/Y/Z (m/s²). Update rate: 100ms.

Gamepad: Bluetooth Classic HID. 16 buttons, D-pad, 2 analog sticks (left/right X/Y, range -32768..32767). Tested: 8BitDo M30.

WiFi configuration (/config.json on SD card)

{
  "bluetoothEnabled": true,
  "wifiEnabled": false,
  "ssid": "YourNetwork",
  "pwd": "YourPassword"
}

WiFi web server runs on port 80. Default: BT mode.

Autostart (/autostart.json on SD card)

{ "project": "your-project-id" }

Set via the IDE (project list → autostart toggle). Persists across reboots.

Supported browsers (Web Bluetooth API)

Chrome, Edge, Opera — desktop only. Firefox and Safari are not supported.


Update Rules for AI

When making any code change, check:

  1. New feature or changed behavior → update the matching README section. Add the feature to "Key Features" if it's user-visible.
  2. New Blockly block → run npm run generate-docs in frontend/ to regenerate BLOCKS.md. Do not manually edit BLOCKS.md.
  3. New REST endpoint → update HUBAPI.md with the endpoint signature, request/response format, and example.
  4. New configuration option → update both README.md (user-facing explanation) and HUBAPI.md if it's exposed via API.
  5. Removed or renamed feature → remove stale references from README. Never leave "coming soon" for something that was dropped.
  6. Bug fix with user-visible impact → add to Troubleshooting if it was a common problem.

When updating README:

  • Keep existing sections intact unless they're wrong
  • Add new content in the correct section (use the structure above)
  • Do not restructure the whole document for a small change — find the right section and update it
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 196kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 196kUpdated Claude CodeCodexVerifiedInstall