Hackathon Deliverable 1 Setup: WSL and Tools
📌 The first deliverable of the Governor House Hackathon involves creating a textbook for a "Physical AI and Humanoid Robotics" course using DocuSaurus and Spekit+, deployed via GitHub Pages.
🛠️ Key tools required are DocuSaurus (for book creation), Spekit+ (for project structure), and Clot Code CLI (using the Gemini API backend via Cloud Router).
🐧 The recommended environment is WSL (Windows Subsystem for Linux), specifically Ubuntu, because Spekit+ coordinates better with Bash environments than PowerShell.

Environment Setup & API Key Management
🖥️ Setup requires installing WSL, Node.js, UV, Clot Code, and Cloud Router CLI, verifying installations with version checks (e.g., `uv --version`).
🔑 Users must generate a Gemini API Key and configure it in the Cloud Router, ensuring the key is set in both the configuration file (e.g., `config` file in Cloud Router folder) and the environment variable (Bash/Shell) using the `export` command.
📂 The location of configuration files like `cloud.json` can be found using the command `explorer.exe .` within the project directory in WSL to open the GUI File Explorer.

Spekit+ Workflow and File Generation
🧩 Spekit+ structures the workflow using distinct phases: Constitution (setting coding standards), Specify (defining application requirements), Plan (outlining execution steps), and Task (breaking the plan into actionable items).
💡 An efficient method to get the required command prompts for file generation (`sp dot constitution`, `sp dot specify`, etc.) is to provide the hackathon README.md and the Spekit+ README to an LLM (like Clot or ChatGPT) and request step-by-step commands.
⚙️ Files are generated sequentially using commands like `sp dot constitution`, followed by execution via `sp dot implement`, which requires user interaction/permissions checks during the process.

Rate Limiting, Errors, and API Key Changes
🚫 The common Error 429 (Rate Limiting) occurs due to exhausting daily quotas (RPD - Requests Per Day) or per-minute limits (RPM - Requests Per Minute, TPM - Tokens Per Minute).
💡 Since input/output control is lost once implementation starts, token usage is high. A potential workaround for temporary blockages is to pause for 30-40 seconds when prompted for user input/permission during execution to allow the 1-minute RPM cycle to potentially reset.
🔄 When changing API keys due to exhaustion, users must update the key in two places: the configuration file (e.g., within the Cloud Router folder) AND the environment variable in the Bash terminal. After updating both, CCR must be stopped and restarted to reload the new configuration.

Project Execution and Deployment
🚀 To run the built project locally (Docusaurus site), navigate to the project directory in WSL and execute `npm run start`.
✅ Upon completion, submission requires deploying the built book to GitHub Pages (or Vercel), providing the GitHub repository link, the deployed book link, and a demo video showcasing the code, prompts used, and setup.

Key Points & Insights
➡️ Adhere strictly to sequential requirements: Do not move to the second deliverable until the first one is fully complete, as per the stated instructions.
➡️ Verify environment settings by using `echo $GOOGLE_API_KEY` after setting the new key to confirm the environment variable has updated, in addition to checking configuration files.
➡️ Restart CCR after updating API keys or configuration files to ensure the new settings are loaded into memory before attempting to resume or implement further steps.

📸 Video summarized with SummaryTube.com on Dec 23, 2025, 19:09 UTC