View source for GitHub Re-Connection & Workflow 260202

= Wiki: GitHub Re-Connection & Workflow =

This wiki is designed for the "Busy Hobbyist"—someone who manages the vision but only touches the code once or twice a year. Its primary purpose is to help you rapidly recollect the project state so you can build, contribute, or create tickets after a long hiatus. Additionally, this document serves as a curriculum for teaching a student or new staff member how to navigate the repository and begin contributing effectively.

You are working in a specific environment: '''Ubuntu 24.04''', utilizing '''GitHub''' for version control and AI tools like '''Gemini Pro''' for reverse engineering. Your local repository for the ''mneme-world-generator-pwa'' is located at <tt>~/mwg</tt>.

== 1. The Annual Re-Connection ==

Because of your infrequent usage, your authentication has likely expired. The first step is always re-establishing your identity with the cloud using the GitHub CLI (<tt>gh</tt>) to refresh your session.

=== Prerequisite Check ===

# Open Terminal.
# Go to project: <tt>cd ~/mwg</tt>
# Check connection: <tt>git remote -v</tt>
#* ''Should point to: https://github.com/StevenTiu22/mneme-world-generator-pwa.git''

=== Authentication Steps ===

Run the login command:

<syntaxhighlight lang="bash">
gh auth login
</syntaxhighlight>

'''Follow this specific sequence (based on your setup):'''

# '''Account:''' <tt>GitHub.com</tt>
# '''Protocol:''' <tt>SSH</tt>
# '''Upload Public Key:''' <tt>Skip</tt> (Assuming keys are already managed, or if this fails later, switch to HTTPS)
# '''Auth Method:''' <tt>Login with a web browser</tt>

'''The Handshake:'''

# The terminal will show a '''one-time code''' (e.g., <tt>XXXX-XXXX</tt>). Copy it.
# Press '''Enter'''. A browser window will open.
# Paste the code and authorize.
# *Ignore <tt>Sandbox: CanCreateUserNamespace</tt> errors if they appear.*
# Look for: <tt>✓ Authentication complete.</tt>

== 2. Catching Up (Syncing Code) ==

Always do this before looking at code or creating tickets to ensure you aren't looking at outdated info.

# '''Switch to Main:'''
<syntaxhighlight lang="bash">
git checkout main
</syntaxhighlight>
# '''Download Updates:'''
<syntaxhighlight lang="bash">
git pull
</syntaxhighlight>
#* ''Success msg: "Already up to date" or list of changed files.''

== 3. Building/Running the App ==

Because this is a PWA (Progressive Web App), it likely needs Node.js dependencies refreshed.

# '''Refresh Libraries:'''
<syntaxhighlight lang="bash">
npm install
</syntaxhighlight>
# '''Start Local Server:'''
<syntaxhighlight lang="bash">
npm start
</syntaxhighlight>
#* ''(Press <tt>Ctrl+C</tt> to stop).''

== 4. The "Light Touch" Contribution ==

Use this flow for minor edits (README fixes, config tweaks) to avoid breaking the main codebase.

# '''Create a Branch''' (Don't edit <tt>main</tt> directly):
<syntaxhighlight lang="bash">
git checkout -b username/fix-description
</syntaxhighlight>
# '''Make your changes''' in your editor.
# '''Save & Commit:'''
<syntaxhighlight lang="bash">
git add .
git commit -m "Update project description for 2026"
</syntaxhighlight>
# '''Upload:'''
<syntaxhighlight lang="bash">
git push -u origin HEAD
</syntaxhighlight>
# '''Finalize:'''
#* Click the '''Create Pull Request''' link that appears in the terminal.
#* Or go to the GitHub dashboard to merge.

== 5. Creating Tickets (Issues) ==

You can do this entirely from the terminal without leaving your flow.

'''Command:'''

<syntaxhighlight lang="bash">
gh issue create
</syntaxhighlight>

'''Interactive Prompts:'''

# '''Title:''' Short summary (e.g., "Update dependencies for Q1 Security Audit").
# '''Body:''' Details of what needs to be done.
# '''Submit:''' Select <tt>Submit</tt>.

== 6. Reverse Engineering & Documentation (AI-Assisted) ==

This workflow uses tools like Claude Code or Google's Code app to examine all files and reverse engineer the logic. The goal is to create documentation tools that a student can follow to understand the code and determine next actions.

=== Tool Selection & Pricing ===

When choosing an AI agent to read your entire repository, be aware of the significant cost differences.

{| class="wikitable"
|-
! Tool !! Link !! Cost / Notes
|-
| '''Claude Code''' || [https://code.claude.com code.claude.com] || '''High Cost.'''<br />• '''Individual:''' ~$100/mo (Claude Max) is recommended for heavy agentic use.<br />• '''Team:''' Min. 5 users @ $25/mo = '''$125/mo minimum'''.<br />• ''Best for shared teams optimizing token usage.''
|-
| '''Google Jules''' || [https://jules.google/docs/environment/ jules.google] || '''Async Agent.'''<br />• Automates PRs and multi-file changes.<br />• Deeply integrated with GitHub contexts.
|-
| '''Gemini Code Assist''' || [https://codeassist.google/ codeassist.google] || '''Free for Individuals.'''<br />• Generous quotas (no cost).<br />• Enterprise plans available (~$19/user/mo).
|-
| '''Gemini CLI''' || [https://github.com/google-gemini/gemini-cli Github Repo] || '''Free (Open Source).'''<br />• Uses free tier API.<br />• Limits: 1,000 req/day, 60 req/min.<br />• ''Recommended starting point for hobbyists.''
|}

=== Example Session: 260202 Reverse Engineering with Claude Code ===

'''Session Date:''' 2026-02-02<br />
'''Tool:''' Claude Code (Claude Opus 4.5)<br />
'''Project:''' <tt>mneme-world-generator-pwa</tt><br />
'''Repository:''' https://github.com/StevenTiu22/mneme-world-generator-pwa

==== Overview ====

This session focused on exploring the Mneme World Generator PWA codebase and consolidating project documentation into the GitHub Wiki.

==== Activities Completed ====

# '''Codebase Exploration'''
#* '''Location:''' <tt>~/mwg</tt>
#* '''Tech Stack Identified:''' React 19, TypeScript, Vite 7, Tailwind CSS v4, shadcn/ui
#* '''Project Structure Mapped:'''
#** <tt>src/pages/</tt> - 17 page components (CreatePrimaryStar, CreateMainWorld, etc.)
#** <tt>src/components/</tt> - UI components (layout, shared, stellar, ui)
#** <tt>src/lib/</tt> - Business logic (generators, db, stellar calculations)
#** <tt>src/models/</tt> - TypeScript interfaces (stellar, world, common)
# '''Wiki Setup'''
#* Cloned wiki repo: <tt>https://github.com/StevenTiu22/mneme-world-generator-pwa.wiki.git</tt>
#* Local storage: <tt>~/mwg/wiki</tt>
# '''Architecture Page Created (<tt>Architecture.md</tt>)'''
#* Tech stack overview with external references.
#* Project structure diagram.
#* '''Data Flow:''' User → Page → Generator → Model → DB → UI.
#* '''Sections:''' Pages anatomy, UI components, Business Logic (Generators), PWA features.
# '''Challenges Page Created (<tt>Challenges-260115.md</tt>)'''
#* Source: <tt>~/Downloads/260115 wgpwa challenges World Generator.docx</tt>
#* '''Content:''' Version 1.5 strategy, UI/UX challenges (Next button, mobile layout), Module status, Planetary system mechanics (moons, rings, waterfall).
# '''Mneme Logic Specification Page Created (<tt>Mneme-Logic-Specification-260202.md</tt>)'''
#* Source: <tt>~/Downloads/260202 Mneme Logic Specification.docx</tt>
#* '''Core Philosophy:''' Simulationist, Recursive, Modular.
#* '''Mechanics:''' Procedural star generation, Companion star mechanics (Rule of Five), Waterfall Habitability, Mutual Hill Radius formula, Gravitational Queue.
# '''Home Page Updated (<tt>Home.md</tt>)'''
#* Added links to Specifications and Development Notes.

==== Key Findings ====

* '''Procedural Generation:''' Uses dice-based logic (5D6 rolls mapped to lookup tables).
* '''Logic Location:''' Generators found in <tt>src/lib/generators/</tt>.
* '''Database:''' Uses Dexie (IndexedDB wrapper) for offline-first PWA support.
* '''Reactivity:''' Uses <tt>useLiveQuery</tt> hook from <tt>dexie-react-hooks</tt>.

==== Naming Convention ====

* Date codes use '''YYMMDD''' format (e.g., 260202 = 2026-02-02).
* Allows versioning of documents over time while preserving history.

==== Wiki URLs ====

* [https://github.com/StevenTiu22/mneme-world-generator-pwa/wiki Home Wiki]
* [https://github.com/StevenTiu22/mneme-world-generator-pwa/wiki/Architecture Architecture]
* [https://github.com/StevenTiu22/mneme-world-generator-pwa/wiki/Challenges-260115 Challenges]
* [https://github.com/StevenTiu22/mneme-world-generator-pwa/wiki/Mneme-Logic-Specification-260202 Logic Spec]

== Cheat Sheet ==

{| class="wikitable"
|-
! Action !! Command
|-
| '''Go to Project''' || <tt>cd ~/mwg</tt>
|-
| '''Check Login''' || <tt>gh auth status</tt>
|-
| '''Login''' || <tt>gh auth login</tt>
|-
| '''Get Latest Code''' || <tt>git checkout main && git pull</tt>
|-
| '''New Task''' || <tt>git checkout -b username/<task-name></tt>
|-
| '''Create Ticket''' || <tt>gh issue create</tt>
|}