Reconcile product direction and repair responsive foundation (#34)

Reconciles product and launch documentation with the deployed application, adds the repository development contract and canonical roadmap, and repairs hero and tablet responsive behavior.

Author: leonshimizu

AGENTS.md

@@ -0,0 +1,40 @@
+# Hafa Code development contract
+
+## Product boundary
+
+Hafa Code is a beginner-first browser coding workspace for Code School of Guam, Father Dueñas students, instructors, mentors, and alumni. Keep the first loop—open, write, run, understand, revise—simple. Rails stores source and classroom records but never executes learner code.
+
+Browser runtimes belong in dedicated workers. Web output belongs in the sandboxed preview. A remote terminal or general server-side execution environment is a separate product and security boundary.
+
+## Repository shape
+
+- `web/`: React, TypeScript, Vite, Monaco, browser runners, learning tools, and PWA assets.
+- `api/`: Rails API, Clerk authentication, PostgreSQL persistence, classroom permissions, feedback, sharing, and audit records.
+- `docs/`: current product, architecture, security, and launch decisions.
+
+Add project kinds and file-language behavior through `web/src/lib/languageRegistry.ts`. A supported language also needs storage/import validation, runner behavior, a guide, Practice Lab coverage, error coaching, tests, and documentation. Do not add parallel language switches inside UI components.
+
+## Local development
+
+- Frontend: `npm --prefix web run dev -- --host 127.0.0.1 --port 5173 --strictPort`
+- Rails API: `(cd api && bin/rails server -b 127.0.0.1 -p 3000)`
+- Full gate: `./scripts/gate.sh`
+- Frontend-only gate: `npm --prefix web run lint && npm --prefix web test && npm --prefix web run build && npm --prefix web audit --audit-level=high`
+
+Ports are configurable. Use distinct strict ports when another session already owns the defaults. Record and clean only resources started by the current session; never stop a borrowed listener, simulator, browser tab, database, or container.
+
+The app can run without Clerk as a local-only playground. Do not copy real credentials into documentation, tests, commits, or PR descriptions.
+
+## Change rules
+
+- Preserve the focused Learn workspace and its mobile navigation.
+- Keep instructor access to student projects read-only unless a separately approved collaboration mode changes that contract.
+- Use project language from the registry, deterministic learning checks, and complete starter files.
+- Keep new runtime dependencies lazy and measure first-run and warm-run behavior.
+- Maintain keyboard access, visible focus, reduced-motion support, non-color status cues, and practical 44px touch targets.
+- Test responsive UI at 390x844, 768x1024, 1280x720, and a wide desktop size.
+- Never weaken CSP, worker isolation, iframe sandboxing, authorization, or project validation merely to make a runtime easier to add.
+
+## Pull-request gate
+
+Before opening a PR, run the full gate and the affected flow in a real browser. After pushing, require green GitHub checks and a CodeRabbit review of the current head. Verify every review finding against the code, fix valid findings with regression coverage, and request a new review after each pushed fix. Merge only when the current head is clean and the task has explicit merge authorization.

README.md

@@ -1,10 +1,10 @@
 # Hafa Code
 
-A simple open-source coding playground for Code School of Guam, Father Dueñas students, alumni, and anyone learning to code.
+A beginner-first, open-source coding workspace for Code School of Guam, Father Dueñas students, alumni, and anyone learning to code.
 
 ## Vision
 
-A lightweight alternative to Replit focused on the languages CSG actually teaches first:
+A focused alternative to Replit that removes installation and account friction from the first coding session:
 
 - Ruby snippets powered by `ruby.wasm`
 - JavaScript snippets powered by QuickJS in a Web Worker
@@ -15,7 +15,9 @@ A lightweight alternative to Replit focused on the languages CSG actually teache
 - Save, fork, share, and remix beginner-friendly projects
 - Optional Clerk sign-in with Rails-backed cloud projects
 
-This project intentionally starts smaller than Replit. The first version should be fast, safe, cheap to host, and approachable for students to contribute to.
+Hafa Code intentionally stays smaller than a general cloud IDE. It keeps the first learning loop—open, write, run, understand, revise—fast and approachable, while classroom organizations add teacher visibility and feedback without giving teachers edit access to student source.
+
+Untrusted programs run in isolated browser workers or a sandboxed preview. Rails stores projects and classroom records; it does not execute student code. This keeps the hosted service comparatively inexpensive and avoids placing a general code-execution service beside student data.
 
 ## Monorepo
 
@@ -28,6 +30,7 @@ hafa-code/
 ## Planning Docs
 
 - [Product spec](docs/PRODUCT_SPEC.md)
+- [Product roadmap](docs/PRODUCT_ROADMAP.md)
 - [Architecture](docs/ARCHITECTURE.md)
 - [Frontend structure](docs/FRONTEND_STRUCTURE.md)
 - [Security model](docs/SECURITY.md)
@@ -50,6 +53,8 @@ Java is intentionally a focused practice environment rather than a full desktop
 
 ## Development
 
+The repository contract, ports, architecture boundaries, and complete validation gate are documented in [AGENTS.md](AGENTS.md).
+
 ```bash
 # frontend
 npm --prefix web install

docs/ARCHITECTURE.md

@@ -37,6 +37,8 @@ Benefits:
 - works well for snippets and web pages
 - easy for OSS contributors to run locally
 
+This boundary is also a product decision. Hafa Code is optimized for the short beginner loop, not for packages, shell access, deployment, or arbitrary backend frameworks. A future remote advanced workspace would be a separate authenticated system with its own isolation, cost, and operations model; it must not weaken the Learn workspace.
+
 ## Runners
 
 ### Ruby
@@ -124,6 +126,8 @@ type ProjectFile = {
 }
 ```
 
+`ProjectKind` and file-language behavior are implemented through the frontend language registry. New language work must extend that registry, runner protocol, guide, Practice Lab, error coaching, storage validation, import/export behavior, and documentation together rather than adding component-specific switches.
+
 ## Backend Choice
 
 Hafa Code uses the same broad shape as other Shimizu/CSG apps: Rails API + React frontend.