Skip to main content

Guided Installer — Completion Report

Final report for the guided installer and compatibility wizard feature (merged 2026-07-11).

Summary​

ADL now leads with a personalized "Get Started" path: a local-first wizard at /get-started that assesses device compatibility across 15 dimensions (each with its own status and evidence confidence), recommends a distribution / desktop / display method / audio path / browser / accessories with human-readable reasons, and generates an app-by-app, command-by-command installation guide gated behind an explicit five-part risk acknowledgment. The knowledge base, compatibility platform, and all existing routes are unchanged; the feature is purely additive.

Homepage changes​

  • "Get Started →" is the dominant CTA (large primary button, above the fold on mobile and desktop, aria-label "Get Started with your personalized Linux installation guide"), with the microcopy "Answer a few questions, check your device, and receive a tailored installation path."
  • The required purpose statement sits under the retained title ("A Full Linux Desktop on Your Android Device") and tagline ("The Open Knowledge Base for Desktop Linux on Android").
  • New "Three steps to your Linux desktop" section (Check your device → Choose your setup → Follow the guide) with a repeated CTA, plus a final CTA section. "Browse the Knowledge Base" is the visually subordinate secondary action; former hero links moved into the navbar/footer.
  • Navbar gained "Get Started" (first item); the footer's Get Started column gained "Guided installer".

New routes​

  • /get-started — wizard, review, assessment, acknowledgment, guide (client-rendered; <noscript> fallback links to manual paths).
  • /docs/get-started/start-here, /docs/get-started/methodology, /docs/get-started/disclaimer
  • /docs/learn/concepts/linux-on-android-explained
  • /docs/learn/hardware/external-displays
  • /docs/troubleshooting/symptom-index
  • /docs/downloads/scripts
  • Static: /downloads/scripts/*.sh, SHA256SUMS, manifest.json; data mirrors at /data/{device-catalog,wizard-issues,sources}.json.

Wizard architecture​

Local-first React (no backend, no account, GitHub Pages compatible). Eight questionnaire sections + review; conditional questions; "I don't know" everywhere; versioned localStorage save/resume; JSON export/import; device report paste-import with review-before-apply; full reset. Pure TypeScript engine (src/lib/compatibility/) and guide generator (src/lib/guide/) with zero React dependencies; usernames and display numbers pass allowlist sanitizers before reaching command templates. Versioned: questionnaire schema, device-report schema, rules, saved state, plan exports, disclaimer.

Compatibility methodology​

15 dimensions × 7 status levels × 6 evidence-confidence levels; documented RAM/storage/architecture heuristic bands (labeled as ADL planning heuristics); hard blockers separated from preferences; unknown devices get specification-based results, never rejection; missing wired video out is never treated as "incompatible with Linux". Full write-up: methodology.

Device-data coverage​

17 variant-aware records researched against official sources (accessed 2026-07-11): Samsung S22+/S23/S24/Z Fold5/Tab S9/A54/A14/J5-2015, Pixel 6/8/9, Motorola Edge+ 2023/ThinkPhone/Edge 40, OnePlus 11/12, Xiaomi 14. DisplayPort Alt Mode recorded as true/false/unknown strictly by source quality (OnePlus/Xiaomi honestly unknown). 18 structured issue records; 25-entry source registry with access dates and reliability ratings.

New KB pages​

Listed under "New routes". Existing canonical pages were extended instead of duplicated: browsers.md (Ubuntu Snap-stub browsers, Mozilla apt repository, removal of the previous --no-sandbox guidance in favor of non-root usage), audio.md (added the auth-ip-acl=127.0.0.1 localhost restriction to every PulseAudio command and the Android 16 known issue), and the Galaxy S22+ device page (field report with per-symptom confirmed/uncertain analysis).

Scripts created​

11 scripts in static/downloads/scripts/ (device-report, preflight, install-base, install-distro, create-user, install-desktop, configure-audio, create-launcher, doctor, backup, remove-installation) — strict mode, environment detection with refusal to run in the wrong environment, argument allowlists, --help/--version (+ --dry-run where meaningful), typed confirmations before deletions, no Android security changes, no personal data. All pass ShellCheck (-S style); SHA-256 checksums + manifest generated by scripts/generate-script-checksums.mjs and verified in CI.

Research sources used​

Primary: termux-app / termux-x11 / proot-distro READMEs and releases, agnostic-apollo's Android-Docs (phantom processes), Samsung DeX and Auto Blocker support pages + official spec sheets, Google Pixel display-support page + Android Developers blog, Motorola Smart Connect chart + Lenovo PSREF, packages.mozilla.org repo metadata, Debian/Ubuntu package pages, GNOME/KDE project blogs, Chromium sandbox docs. Registry with dates: data/sources.json. Key recency findings encoded: proot-distro v5's OCI switch (May 2026), Termux:X11's Android 8 minimum, GNOME's systemd/X11 status, Plasma 6.8 X11 removal timeline, Pixel 8+ DisplayPort enablement, and the Android 16 audio issue.

Tests run and results​

  • npm test (vitest): 34/34 pass, including all 18 required fixtures.
  • npm run typecheck: pass.
  • npm run build (onBrokenLinks: "throw"): pass — all links valid.
  • npm run validate:data: 17 devices, 18 issues, 25 sources — 0 errors.
  • node scripts/generate-script-checksums.mjs --check: pass.
  • ShellCheck (-S style) on all 11 scripts: clean.
  • markdownlint on changed docs: 0 errors.
  • Browser e2e (Playwright, production build): 29/29 checks — homepage CTA dominance/above-fold at 1440px and 390px, full S22+ path (assessment content, Auto Blocker surfacing, five-checkbox gating with nothing pre-checked, guide environment labels, audio forwarding, no --no-sandbox commands, progress + reload resume), unknown-device path (spec-based labeling, no rejection), CLI-only path on mobile.

Accessibility checks​

Keyboard-first controls (fieldset/legend groups, labeled inputs, focus moved to each step's heading), role=alert validation with instructions, aria progressbar, visible focus outlines, no color-only status (badges carry text), reduced-motion support, print styles, 44px-class touch targets, mobile-first layout verified at 390px. Automated axe-style audit was not run in this environment — listed under limitations.

Known limitations​

  • Physical-device validation is pending for everything except the S22+ field report; all other device rows are labeled inferred from specifications.
  • The Arch Linux route is labeled advanced/experimental: under proot-distro v5 (OCI images) ARM64 image availability for archlinux needs confirmation; the installer script warns accordingly.
  • Local Desktop is positioned in the methods list but has no dedicated guide yet (honestly labeled; not presented as documented).
  • Wireless-display and VNC flows are documented but not maintainer-tested.
  • The wizard's e2e coverage is a repeatable local Playwright script (kept in the session workspace), not a committed CI e2e suite — CI runs the unit/data/shell gates.
  • Tag pushes were rejected by the hosting environment's git proxy; tags exist locally (see rollback record).

Items requiring physical-device validation​

Audio on Android 16; Termux:X11 flags per device; DeX vs mirrored Termux:X11 behavior on One UI 7/8; OnePlus 12 / Xiaomi 14 USB-C video output; Pixel 8/9 Termux:X11-on-external-display behavior; LXQt/Plasma session quality on 4 GB devices.

Git record​

See the rollback record — checkpoint dd9f7ff, feature branch feature/guided-linux-installer (kept), feature commit a0f9c6d, merge commit 7c003cc (--no-ff), tags pre-guided-installer-20260711-0258 and guided-installer-v1-20260711. Rollback: git revert -m 1 7c003cc. No force-pushes; no history rewritten.