docs(readme): clarify Linux package quick start

[nisavid]

Summary

• Adds a README Start Here router and makes the normal package-managed path the first path.
• Replaces the old checkout-oriented quick start with make clean build-app package, distro package-manager install commands, and codex-app launch.
• Moves manual checkout runs, custom DMGs, side-by-side test apps, AppImage details, release-gate detail, and Computer Use persistence into focused sections or linked docs.
• Documents Linux Computer Use readiness as independent AT-SPI, screenshot, window, pointer, keyboard, and text-input paths, including ydotool socket and keyboard-layout caveats.
• Ignores local .impeccable/ critique snapshots so design-review artifacts do not pollute git status.

Verification

• git diff --check "$(git merge-base origin/main HEAD)"..HEAD passed.
• README/docs local link and anchor check passed.
• Conflict-marker, stale-section, old-anchor, and em dash grep passed.
• Ralph Review Cycle 1 reviewed the combined branch diff and the external global ~/.codex/AGENTS.md instruction text; no valid findings.
• Ralph Review Cycle 2 rechecked the final pre-rebase branch diff, docs wording traps, link/anchor validity, and worktree state; no findings.
• Rebased onto current origin/main, preserving the newer AppImage, bootstrap-native, remote-control, NixOS-output, and Fedora ydotool notes.
• Ralph Review Cycle 3 reviewed the rebased branch diff and reran whitespace, link/anchor, conflict-marker, stale-section, old-anchor, and em dash checks; no findings.
• Greptile found one valid README release-gate explanation gap; fixed by documenting REQUIRE_RELEASE_SIGNATURE=1 public-release behavior.
• Ralph Review Cycle 4 reviewed the amended branch and reran whitespace, link/anchor, conflict-marker, stale-section, old-anchor, and em dash checks; no findings.

Notes

• The global ~/.codex/AGENTS.md Computer Use guidance is intentionally outside this repository and is not part of this PR.
• Docs-only change; no app generation or local package build gate was needed.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR reorganizes user-facing documentation: adds a "Start Here" navigation, standardizes Quick Start and native packaging steps, simplifies release-gate verification, clarifies Linux Computer Use readiness and troubleshooting across README and docs, and adds .impeccable/ to .gitignore.

Changes

Documentation Reorganization & Linux Computer Use Alignment

Layer / File(s)	Summary
Version Control & Navigation Foundation .gitignore, README.md (.gitignore line 16, README.md lines 6, 23–146`)	Adds .impeccable/ to .gitignore; README introduces a "Start Here" navigation and refactors Quick Start with standardized build/install instructions and adjusted hero badge.
Build & Quick Start Flow README.md (README.md lines 159, 428–429)	Adjusts the build-from-DMG heading and standardizes build flow; stale app-tree troubleshooting now recommends make clean build-app package with an alternate ./install.sh --fresh option.
Native Package Build Documentation README.md (README.md lines 208–238, 277–280)	Replaces native packaging section with "Native Package Details"; documents make package, direct format targets (make deb/make rpm/make pacman), lifecycle helpers, and the make install convenience wrapper.
Release Gate Process Clarification README.md (README.md lines 294, 303–310)	Shortens release-gate guidance to require hash: DMG input and describe DMG hash verification, Electron output scanning, package metadata validation, checksum writing, and conditional checksum signing when CODEX_RELEASE_GPG_KEY is set.
Linux Computer Use Readiness & UI Setup README.md (README.md lines 347–361, 370–379), docs/usage/build-and-run.md (docs/usage/build-and-run.md lines 222–238)	README updates readiness text to emphasize AT-SPI inspection, screenshot capture via Desktop Portal/compositor, ydotool input synthesis, and keyboard-layout troubleshooting; build-and-run.md adds a subsection clarifying independent readiness checks and layout dependence for raw key synthesis.
Linux Computer Use Troubleshooting & Links docs/usage/troubleshooting.md (docs/usage/troubleshooting.md lines 67–71), README.md (README.md lines 446–448)	Troubleshooting replaces GNOME-only AT-SPI entry with "empty or sparse" guidance and adds rows for ydotool socket protocol mismatch, wrong keyboard characters, and missing text insertion; README "Learn More" links updated accordingly.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• nisavid/codex-app-linux#15: Related changes to Linux Computer Use opt-in and persisted settings handling across docs.
• nisavid/codex-app-linux#44: Overlapping edits to README and usage docs covering Linux Computer Use readiness and hardened /tmp guidance.

Poem

🐰 I hopped through docs with tidy paws,
I moved the starts and fixed the flaws.
Quick Starts sing, releases check their hash,
Computer Use now avoids the crash—
.impeccable/ sleeps in .gitignore's sash.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs(readme): clarify Linux package quick start' directly aligns with the main objective: reorganizing the README to emphasize package-managed installation as the primary quick-start path, with distro-specific install commands and standardized build flow.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[greptile-apps]

Greptile Summary

This docs-only PR restructures the README with a "Start Here" navigation router, promotes the package-managed install as the primary Quick Start path, and expands Linux Computer Use guidance in both the build-and-run guide and the troubleshooting table.

• README.md: Adds a "Start Here" router, rewrites Quick Start around make clean build-app package + distro package-manager install commands, condenses the Feature Status table into "Current State" bullets, and moves verbose blocks to linked docs with updated anchors.
• docs/usage/build-and-run.md: Adds independent-path readiness framing for AT-SPI, screenshot, window, pointer, and keyboard paths; notes the historical org.gnome.desktop.interface toolkit-accessibility key; and documents keyboard-layout caveats for raw key synthesis.
• docs/usage/troubleshooting.md: Adds three new Computer Use rows and broadens the AT-SPI empty-tree entry to a general sparse-tree note with a NO_AT_BRIDGE=1 environment check.

Confidence Score: 5/5

Documentation-only change with no app logic; safe to merge.

All internal anchor links resolve to existing sections; Make targets referenced in Quick Start are present in the documented target list; distro install commands follow standard local-file install syntax; no app code is added or removed.

No files require special attention.

Important Files Changed

Filename	Overview
.gitignore	Adds .impeccable/ to exclude local design-review critique snapshots from git status; minimal, correct change.
README.md	Major restructure: adds Start Here router, promotes package-managed Quick Start, condenses Feature Status table, adds Computer Use keyboard-layout note, and moves verbose blocks to linked docs. All internal anchors and Make targets verified.
docs/usage/build-and-run.md	Expands the Linux Computer Use UI Opt-In section with independent-path readiness framing and keyboard-layout debugging guidance. Anchor #linux-computer-use-ui-opt-in used in README is present and correct.
docs/usage/troubleshooting.md	Adds three new Computer Use rows and broadens the AT-SPI empty-tree entry from GNOME-only to a general sparse-tree note with NO_AT_BRIDGE check.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Start Here] --> B{Use case?}
    B -->|Normal install| C[Quick Start]
    B -->|NixOS| D[NixOS]
    B -->|Custom DMG / checkout| E[Manual and Custom Builds]
    B -->|AppImage / package details| F[Native Package Details]
    B -->|Computer Use / updater / release| G[Linux Computer Use]
    C --> H[Install distro package]
    H --> I[codex-app]
    G --> J{Readiness check}
    J --> K[AT-SPI path]
    J --> L[Screenshot portal path]
    J --> M[Window / pointer path]
    J --> N[Keyboard / ydotool path]

Loading

_{Reviews (2): Last reviewed commit: "docs(readme): clarify package quick star..." | Re-trigger Greptile}