Skip to content

CLAUDE.md

Latest commit

 

History

History
70 lines (57 loc) · 3.69 KB

CLAUDE.md

File metadata and controls

70 lines (57 loc) · 3.69 KB
Raw

Fedora Master — project rules for Claude Code

Offline learning app for Fedora 44 / KDE Plasma 6.6. React + Vite single-file app (src/App.jsx), packaged as an Android APK via Capacitor and as an installable PWA via GitHub Pages. Public repo: LebaneseZorro/fedora-master.

Non-negotiable: privacy scrub before EVERY commit

This is a PUBLIC repo. Before any git commit, run:

grep -rinE 'REDACTED|\bjd\b|\bJD\b|192\.168\.1\.|REDACTED|REDACTED' src/ *.json *.html README.md 2>/dev/null || echo clean

It must print clean. If it matches anything, STOP and fix before committing. Never add personal names, hostnames, LAN IPs, or emails to any file. Example IPs in lesson content use 192.168.0.x, username user, hostname workstation.

Architecture (don't fight it)

  • The ENTIRE app is src/App.jsx — single file by design. Don't split it into modules/components files.
  • Data lives in big const arrays near the top: CMDS (command DB), SHORTCUTS, CMD_PLAIN + CONCEPTS → GLOSSARY (tappable terms), MODULES (lesson content), QUIZZES, ERRORS (error-explainer knowledge base), plus the terminal simulator (FS0, runCommand, SANDBOX_KNOWN).
  • Fully offline: NO fetch(), no API calls, no analytics, no external fonts/CDNs. Persistence is localStorage under key fedora-master-v1 only.
  • Glossary terms auto-mark in lessons (dotted underline → bottom sheet). New jargon in lesson prose should get a CONCEPTS entry: {t, cat, say, m, ex, al?}.
  • Lesson block types: p (prose), kv ([term, explanation] pairs), list, code ({lang, x}), note. New modules need: entry in MODULES, quiz in QUIZZES keyed by module id, and glossary entries for new terms.
  • Content voice: internals-first, "why before what", technical but plain-language, case-sensitive-aware (mobile users). Fedora 44 facts: kernel 6.19.14, Plasma 6.6, DNF5-only, Plasma Login Manager, Wayland-only, tuned-ppd power stack.

Build & ship

  • Web/dev check: npm run build (Vite + PWA plugin; must end ✓ built).
  • Android: npx cap sync android, then cd android && ./gradlew assembleDebug.
    • Gradle JDK: system JDK is too new for the wrapper. If sync/build fails on JDK version, ensure android/gradle.properties contains: org.gradle.java.home=/opt/android-studio/jbr — never point it at system Java.
    • If android/ doesn't exist: npx cap add android regenerates it (it's gitignored by design — never commit it).
  • Install to phone: adb install -r android/app/build/outputs/apk/debug/app-debug.apk (the real APK is under apk/debug/, NOT apk/androidTest/).
  • Debug-signed APKs only. Never create keystores or signing configs without asking.
  • Web deploy (iPhone/PWA users): npm run deploy (builds + pushes gh-pages). Live at https://LebaneseZorro.github.io/fedora-master/
  • Releases: gh release create vX.Y.Z "android/.../app-debug.apk#Fedora-Master-vX.Y.Z.apk" --title ... --notes ... Bump minor for content additions, patch for fixes.

Git

  • Commit style: short imperative summary of the actual change (e.g. "Add tappable glossary (~130 terms)").
  • Separate unrelated changes into separate commits.
  • Never commit: android/, dist/, node_modules/, *.apk, keystores (gitignore already covers these — don't weaken it).
  • assets/ (icon sources) and public/ (PWA icons) ARE committed.

Don't

  • Don't add npm dependencies without asking — the app deliberately has zero runtime deps beyond react/react-dom.
  • Don't change appId (com.fedoramaster.app) — installed phones update in place.
  • Don't reformat the whole of App.jsx (compact style is intentional; diffs matter).
  • Don't touch vite.config.js base ("") — required for both Capacitor and gh-pages.