Editing Zermatt GitHub and Collaboration

{{Lux-Ear Header}}
__TOC__

== Zermatt — GitHub Repository & Collaboration Setup ==

{| class="wikitable" style="font-size:14px; width:100%"
|-
! style="background:#1E5F8E; color:white; width:20%" | Field
! style="background:#1E5F8E; color:white" | Detail
|-
| '''Repository URL''' || https://github.com/mcgregor94086/zermatt
|-
| '''Visibility''' || Private
|-
| '''Owner''' || Scott L. McGregor (mcgregor94086)
|-
| '''Status''' || Active — hardware sprint complete
|-
| '''Classification''' || CONFIDENTIAL — PATENT PENDING
|-
| '''Last updated''' || {{CURRENTDAY}} {{CURRENTMONTHNAME}} {{CURRENTYEAR}}
|}

---

=== What this page covers ===

This page documents:
* The structure of the Zermatt GitHub repository
* How to invite and manage collaborators (specifically Akien MacIain)
* How to authenticate from your Mac (Personal Access Token)
* How to push sprint files using the automation script
* The Notion/Google Docs knowledge-sharing workflow

---

== Repository Structure ==

{| class="wikitable" style="font-size:14px; width:100%"
|-
! style="background:#1E5F8E; color:white" | Folder
! style="background:#1E5F8E; color:white" | Contents
|-
| <code>hardware/pcb/</code> || KiCad 8 PCB files — Zermatt_v0.kicad_pcb + .kicad_pro
|-
| <code>hardware/docs/</code> || Circuit schematic, wiring diagram, PCB layout (SVG + DOCX)
|-
| <code>hardware/bom/</code> || Bill of materials (Zermatt_v0_BOM.xlsx)
|-
| <code>docs/architecture/</code> || v0 full architecture document (DOCX)
|-
| <code>docs/assembly/</code> || Step-by-step assembly manual with diagrams (DOCX)
|-
| <code>docs/patent/</code> || Provisional patent application (DOCX)
|-
| <code>software/firmware/</code> || ESP32 MicroPython firmware
|-
| <code>software/app/</code> || React Native iOS/Android app
|-
| <code>software/server/</code> || PHP server code (DreamHost)
|-
| <code>presentations/</code> || Architecture overview deck (PPTX)
|-
| <code>DECISIONS.md</code> || Architecture decision log — updated before every commit
|-
| <code>README.md</code> || Project overview and quick-start guide
|}

---

== Collaborators ==

{| class="wikitable" style="font-size:14px; width:100%"
|-
! style="background:#1E5F8E; color:white" | Name
! style="background:#1E5F8E; color:white" | GitHub Username
! style="background:#1E5F8E; color:white" | Role
! style="background:#1E5F8E; color:white" | Status
|-
| Scott L. McGregor || mcgregor94086 || Owner || Active
|-
| Akien MacIain || akienm || Collaborator (read/write) || Invitation sent — awaiting acceptance
|-
| Wolfgang Herwald || WolfgangHerwald || Collaborator || Active — NDA on file
|}

'''To invite a new collaborator:'''
# Go to https://github.com/mcgregor94086/zermatt/settings/access
# Click '''Add people'''
# Enter their GitHub username or email
# They receive an email — they must click Accept to gain access

---

== Authentication: Personal Access Token ==

GitHub stopped accepting passwords in 2021. You need a '''Personal Access Token (PAT)''' to push from Terminal.

=== Generating a new token ===

# Go directly to: https://github.com/settings/tokens
# Click '''Generate new token (classic)'''
# Name: <code>MacBook Zermatt</code>
# Expiration: 1 year
# Check the '''repo''' scope checkbox
# Click '''Generate token'''
# '''Copy it immediately''' — GitHub shows it only once. It looks like: <code>ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx</code>

=== Saving to Mac Keychain ===

The first time you run <code>git push</code> after generating a token:
* Username: your GitHub username (<code>mcgregor94086</code>)
* Password: paste the token

Mac Keychain saves it automatically — you will not be asked again until the token expires.

{{Note|If you see "Authentication failed", your token has expired. Generate a new one at https://github.com/settings/tokens and repeat the steps above.}}

---

== Pushing Files: Sprint Automation Script ==

The push script <code>zermatt_github_push.sh</code> automates the full file organisation and commit workflow.

=== What it does ===
# Pulls latest from GitHub
# Creates the correct folder structure if missing
# Copies all downloaded sprint files to the right folders
# Updates <code>DECISIONS.md</code> with new ADR entries
# Updates <code>README.md</code> if missing
# Stages all files, commits with a detailed message, and pushes

=== How to run it ===

Open Terminal and paste these two commands:

<syntaxhighlight lang="bash">
cd ~/Projects/Lux-Ear/zermatt
bash ~/Downloads/zermatt_github_push.sh
</syntaxhighlight>

=== Commit message tag convention ===

{| class="wikitable" style="font-size:14px"
|-
! style="background:#1E5F8E; color:white" | Tag
! style="background:#1E5F8E; color:white" | Use for
|-
| <code>[HARDWARE]</code> || PCB files, schematics, wiring, BOM
|-
| <code>[FIRMWARE]</code> || ESP32 MicroPython code
|-
| <code>[APP]</code> || React Native iOS/Android app code
|-
| <code>[SERVER]</code> || PHP server code
|-
| <code>[DOCS]</code> || Word docs, assembly manual, architecture
|-
| <code>[DECISIONS]</code> || DECISIONS.md updates
|-
| <code>[ADMIN]</code> || README, GitHub Issues, project management
|}

---

== Daily Git Commands Cheat Sheet ==

{| class="wikitable" style="font-family:monospace; font-size:14px; width:100%"
|-
! style="background:#1E5F8E; color:white" | What you want to do
! style="background:#1E5F8E; color:white" | Type this in Terminal
|-
| Go to your Zermatt folder || <code>cd ~/Projects/Lux-Ear/zermatt</code>
|-
| Check what has changed || <code>git status</code>
|-
| Pull latest from GitHub || <code>git pull</code>
|-
| Stage all files || <code>git add -A</code>
|-
| Commit with a message || <code>git commit -m "[DOCS] Updated assembly notes"</code>
|-
| Push to GitHub || <code>git push</code>
|-
| Run the sprint push script || <code>bash ~/Downloads/zermatt_github_push.sh</code>
|-
| See recent history || <code>git log --oneline -10</code>
|-
| Undo last commit (keep files) || <code>git reset --soft HEAD~1</code>
|}

---

== Troubleshooting ==

{| class="wikitable" style="font-size:14px; width:100%"
|-
! style="background:#C0392B; color:white" | Error message
! style="background:#C0392B; color:white" | What it means
! style="background:#C0392B; color:white" | Fix
|-
| Authentication failed || Token expired or wrong || Generate new PAT at https://github.com/settings/tokens
|-
| rejected, non-fast-forward || GitHub has newer changes || Run <code>git pull --rebase</code> then <code>git push</code>
|-
| nothing to commit || No changes since last push || Normal — run <code>git status</code> to confirm
|-
| fatal: not a git repository || Wrong folder || Run <code>cd ~/Projects/Lux-Ear/zermatt</code> first
|-
| command not found: git || Git not installed || Run <code>xcode-select --install</code> in Terminal
|-
| Permission denied (publickey) || SSH not set up — use HTTPS || Run: <code>git remote set-url origin https://github.com/mcgregor94086/zermatt</code>
|}

---

== Notion / Google Docs: Sharing Context with Akien ==

The GitHub repo stores all files. A separate Notion page (or Google Doc) captures the '''human-readable sprint summaries''' and Claude conversation context that cannot live in GitHub.

=== Current recommended approach ===

{| class="wikitable" style="font-size:14px; width:100%"
|-
! style="background:#1E5F8E; color:white" | What
! style="background:#1E5F8E; color:white" | Where
! style="background:#1E5F8E; color:white" | How Akien accesses it
|-
| All code and generated files || GitHub repo || Browser preview or clone
|-
| KiCad PCB file || GitHub /hardware/pcb/ || Download → open in KiCad 8
|-
| Assembly manual, patent, BOM || GitHub /docs/ || Download → open in Pages/Numbers
|-
| Sprint summaries + diagrams || Notion page (or Google Doc) || Public share link — no login needed
|-
| Design decisions log || DECISIONS.md in GitHub || Read in browser
|-
| Task tracking || GitHub Issues || Comment, create new tasks
|}

=== Notion Free plan ===
* Free — no credit card, no expiry
* Unlimited pages
* 1 read-only guest (enough for Akien)
* Sign up at: https://notion.so

=== To share a Notion page with Akien (no account needed) ===
# Open the page in Notion
# Click '''Share''' (top right)
# Toggle '''Publish to web''' ON
# Copy the link and send to Akien by email or text

---

== Current Sprint Status ==

=== Hardware Sprint — Complete ===

{| class="wikitable" style="font-size:14px; width:100%"
|-
! style="background:#1A6B2A; color:white" | Deliverable
! style="background:#1A6B2A; color:white" | File
! style="background:#1A6B2A; color:white" | Status
|-
| KiCad PCB file || Zermatt_v0.kicad_pcb || ✅ Complete
|-
| KiCad project file || Zermatt_v0.kicad_pro || ✅ Complete
|-
| Circuit schematic || ZERM-SCH-001_Circuit_Schematic.svg || ✅ Complete
|-
| Wiring diagram || ZERM-WRG-001_Wiring_Diagram.svg || ✅ Complete
|-
| PCB layout plan || ZERM-PCB-001_PCB_Layout.svg || ✅ Complete
|-
| Hardware document || Zermatt_v0_Circuit_Wiring_PCB.docx || ✅ Complete
|-
| Bill of Materials || Zermatt_v0_BOM.xlsx || ✅ Complete
|-
| Architecture document || Zermatt_v0_Architecture.docx || ✅ Complete
|-
| Assembly manual || Zermatt_v0_Assembly_Manual.docx || ✅ Complete
|-
| Provisional patent || LuxEar_Zermatt_Provisional_Patent.docx || ✅ Complete
|-
| Architecture deck || LuxEar_Zermatt_Architecture_Overview.pptx || ✅ Complete
|}

=== Next Sprint — Firmware & App ===
* ESP32 MicroPython firmware (BLE, WiFi, motor control, LED, audio, camera trigger)
* React Native app skeleton (BLE pairing, scan UI, customer form)
* Server job intake API + database schema

---

== Related IKB Pages ==

* [[Zermatt Scanner — Hardware v0]]
* [[Zermatt Scanner — Architecture]]
* [[Lux-Ear — Active Projects]]
* [[Lux-Ear — Key Contacts]]

[[Category:Zermatt]] [[Category:GitHub]] [[Category:Operations]]