Skip to content

Document Mac recovery and dual-boot support - #16673

Open
heymaaz wants to merge 4 commits into
omacom:quattrofrom
heymaaz:docs/mac-support-recovery
Open

heymaaz wants to merge 4 commits into
omacom:quattrofrom
heymaaz:docs/mac-support-recovery

Conversation

@heymaaz

@heymaaz heymaaz commented Oct 26, 2026 •

Copy link
Copy Markdown

Summary

Mac support documentation
  full-disk install ──> macOS removed
  free-space install ─> macOS preserved
                         ├─ useful for T1 machine data
                         └─ useful for T2 Wi-Fi firmware

T1 support ──> Touch Bar project + T1Bridge
              DKMS modules + target-kernel boot-image verification

Document the existing free-space installation path and explain why preserving macOS or a recovery path matters on T1 and T2 Macs.

Evidence

  • Before: the manual stated that Omarchy only supported being the only installed OS, although the installer supports free-space installation.
  • After: the Mac support page links to the dual-boot procedure, documents T1/T2 recovery prerequisites, and links the relevant community projects.
  • git diff --check passes.

Merge Danger

Door: Two-way

Documentation-only change; it can be reverted independently.

Blast Radius: Mac documentation

Hardware context

Existing documentation

The current Mac support page lists Touch Bar and sound as non-functional on T1 Macs. This PR links the community projects and documents the firmware/recovery precautions involved.

WhatsApp Image 2026-10-26 at 07 05 38

Community Touch Bar stack in use

A 2016 13-inch four-port MacBook Pro running Omarchy with an illuminated Touch Bar and media keys. This illustrates the community setup; this documentation PR does not automatically install or enable these drivers.

HVd-Nl7XAAAlmgv

Supporting setup record

The tested 2016 MacBook Pro recovery, dual-boot, T1, and kernel-maintenance record is documented in the Omarchy MacBook T1 setup gist. It provides supporting hardware context, not a prerequisite for this documentation change.

Copilot AI balanced review requested due to automatic review settings October 26, 2026 07:03
@greptile-apps

greptile-apps Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Low impact] The documentation appears safe to merge; no new actionable issues were found.

Summary

Documents how to keep macOS alongside Omarchy and prepare for Mac-specific recovery needs.

  • Mac owners can install Omarchy beside macOS using prepared free space.
  • T1 Mac owners get community Touch Bar options and setup guidance.
  • T2 Mac owners learn how to keep a source for Wi-Fi firmware.
  • The Mac support page notes that some automatic fixes depend on available firmware.

Reviews (4) · Last reviewed commit: "Require the T1 EFI backup before any ins..." · Reviewed by Greptile

Comment thread manual/44-mac-support.md Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The T1 guidance needs explicit EFI-data backup requirements and a warning against installing conflicting support stacks together.

2 open issues
What changed in this PR

Updates the Mac support manual to document the existing dual-boot installation path and explain recovery considerations for T1 and T2 hardware.

Changes:

  • Distinguishes full-disk and free-space installations and links the dual-boot procedure.
  • Adds T1 community-project links and kernel-module rebuild guidance.
  • Clarifies firmware availability and T2 Wi-Fi recovery requirements.
File Description
manual/​44-mac-support.md Documents Mac installation choices, recovery prerequisites, and community hardware support.

Review effort: Balanced

Comment thread manual/44-mac-support.md Resolved
Comment thread manual/44-mac-support.md Resolved
@omarchybot omarchybot added the documentation Improvements or additions to documentation label Nov 2, 2026
The Known Issues line grouped audio with the Touch Bar under community software, but neither linked project handles audio: T1Bridge's README lists speakers as out of its scope, and mbp-t1-touchbar drives only the Touch Bar. Restore the plain sound line and keep the community-software line to the Touch Bar.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Codex Medium <noreply@openai.com>
Co-Authored-By: muse-wonder <noreply@pi.dev>
@omarchybot omarchybot added the verified Omarchy Triage has verified that this issue is ready for final review label Nov 2, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed as a documentation change: only manual/44-mac-support.md changes, so nothing was run. Every command and claim the page makes was checked against the repository and the projects it links. The free-space install matches manual/50-dual-boot-install.md, and the ISO's disk-partitioning.sh only formats partitions it creates itself, so an existing Apple EFI partition is left alone. The diskutil apfs resizeContainer steps are correct, including that the size given is what macOS keeps. The T2 Wi-Fi paragraph matches the comment in install/hardware/apple/fix-t2.sh. The FDRData backup warning and the warning against installing both Touch Bar stacks match the T1Bridge setup guide and the mbp-t1-touchbar README.

One fix was pushed to this branch as d40bdfd. The T1 Known Issues said "Touch Bar and audio support require additional community-maintained software", but neither linked project handles audio, and T1Bridge's README lists speakers as out of its scope. The page now keeps "Sound is not functioning" and limits the community-software line to the Touch Bar.

Codex Medium and muse-wonder (via pi, thinking high) both reviewed it. Both flagged the audio wording in their first round, and both found nothing open in a second round at d40bdfd. They agreed with this review, but their independence from it is not guaranteed.

This waits on the maintainer, for two reasons:

The T1 FDRData backup steps sat under the free-space section, but a full-disk install erases the Apple EFI partition too. Point T1 owners at the backup before any install.

The T2 fallback now links the t2linux Wi-Fi guide and says its recovery-image method needs another connection and does not work on the iMac Pro.
@heymaaz

heymaaz commented Nov 2, 2026 •

Copy link
Copy Markdown
Author

Thanks for the review. I've pulled d40bdfd and agree with it: T1 speakers need a separate CS8409 driver, which neither linked project provides. That is #15776's scope.

I pushed 63e0de9 with two follow-ups:

  • T1: the Apple EFI/FDRData backup is now a prerequisite for any install, not only a free-space one. A full-disk install erases the Apple EFI partition too.
  • T2: the fallback now links the t2linux Wi-Fi and Bluetooth guide. It also says the recovery-image method needs another way online and does not work on the iMac Pro.

T2 and #16427 / omacom/omarchy-iso#356: my T2 paragraph describes today's ISO, where a full-disk install can leave a T2 Mac without Wi-Fi. Once omacom/omarchy-iso#356 is in a released ISO and #16427 merges, I'll replace that paragraph with a pointer to #16427's "Wi-Fi Firmware on T2 Macs" section. I'll also stop presenting T2 Wi-Fi as a reason to keep macOS. Until then, the warning stays as it is.

Overlap with #15776, #16101 and #16427: I'll rebase this onto whichever of them lands first and merge the overlapping Known Issues and T2 text.

@omarchybot omarchybot removed the verified Omarchy Triage has verified that this issue is ready for final review label Nov 3, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

Re-reviewed 63e0de9, focusing on the changes since d40bdfd. The T1 backup warning now covers full-disk installs, and the T2 recovery link, alternative-network requirement and iMac Pro exclusion match the linked upstream guides. The T2 warning also matches install/hardware/apple/fix-t2.sh; omacom/omarchy-iso#356 is still open. Only Markdown changes, so this was checked by reading; no hardware tests or suite were run.

Codex High reviewed the revision, with second opinions from Opus 5.5 High and muse-wonder via pi, thinking high. Both agreed that the two revised caveats are accurate; independence from this review is not guaranteed. Both also identified competing T1 guidance in the older #16101. This PR's pre-install EFI backup guidance is being handed to that PR's review for inclusion with credit to @heymaaz. The APFS free-space preparation is separate work, so this is not an exact duplicate and remains open.

This waits on the maintainer to decide how to separate the dual-boot instructions from the overlapping T1/T2 material in #16101 and #16427. There is also a current merge conflict in manual/44-mac-support.md: the T2 firmware paragraph needs to stay before the newer “iMac Retina 5K (2017)” section, preserving both sections when the conflict is resolved.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants