From fea320e92aecf3c479154ef8793b06bfaa5877ca Mon Sep 17 00:00:00 2001 From: suraj-markup Date: Tue, 24 Mar 2026 18:09:00 +0530 Subject: [PATCH] docs: add prerequisite matrix and install behavior details Expand the Interactive Prerequisite Prompts section with: - Full prerequisite matrix table (tmux, git, agent runtime, gh, docker) showing required status, prompts, install methods per platform, and failure behavior - Key behaviors list (consent-first, logging, blocking, non-TTY fallback) - Example terminal output for fresh machine install flow Co-Authored-By: Claude Opus 4.6 --- docs/design-npm-global-install-fixes.html | 109 +++++++++++++++++++--- 1 file changed, 94 insertions(+), 15 deletions(-) diff --git a/docs/design-npm-global-install-fixes.html b/docs/design-npm-global-install-fixes.html index 29f3b0b4c..cfb8b9680 100644 --- a/docs/design-npm-global-install-fixes.html +++ b/docs/design-npm-global-install-fixes.html @@ -717,27 +717,106 @@ async function ensureTmux(): Promise<void> {

Interactive Prerequisite Prompts (TTY)

- For human/TTY runs, ao start asks before attempting installs via askYesNo(). - Non-interactive callers keep deterministic behavior (no prompts, defaults apply). - All install helpers follow the same pattern: tryInstallWithAttempts() logs each - command before running it, so the user knows exactly what's happening. + When ao start detects a missing prerequisite on a fresh machine, it prompts + the user before attempting any install. This ensures no surprises — no silent + sudo, no unexpected package manager invocations.

+

Prerequisite Matrix

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PrerequisiteRequired?PromptInstall methods (by platform)On failure
tmuxYes (for runtime: "tmux")Install tmux now? [Y/n] + macOS: brew install tmux
+ Linux: apt-get → dnf + 		blocks — prints platform hints + exit 1
gitYes (for URL clone & add-project)Install Git now? [Y/n] + macOS: brew install git
+ Linux: apt-get → dnf
+ Windows: winget install Git.Git + 		blocks — prints platform hints + exit 1
Agent runtime
(Claude Code, Codex, Aider, OpenCode)		Yes (at least one)Numbered menu:
Choose runtime to install [1-5]		 + 1. Claude Code (npm i -g @anthropic-ai/claude-code)
+ 2. Codex (npm i -g @openai/codex)
+ 3. Aider (pipx install aider-chat)
+ 4. OpenCode (go install ...)
+ 5. Skip + 		Config generation continues — user can install later
GitHub CLI (gh)No (optional)Install GitHub CLI now? [y/N]
(defaults to no)		 + macOS: brew install gh
+ Linux: apt-get → dnf
+ Windows: winget install GitHub.cli + 		Skipped silently — optional dependency
DockerNoNot prompted—— (no runtime-docker plugin registered)
+ +

Key Behaviors

-

Clear Error on Failure

-

- If install is declined or fails, ao start exits with a clear, actionable message - instead of silently degrading to a limited runtime: -

+

Example: Fresh Machine Flow

+ 
$ ao start
+  Detecting environment...
+  ✓ Agent runtime: claude-code
+  ✓ Config created: agent-orchestrator.yaml
+  ⚠ tmux not found — will prompt to install at startup
 
-  
✗ tmux is required but is not installed.
+  ⚠ tmux is required for runtime "tmux".
+  Install tmux now? [Y/n]: y
+    Running: brew install tmux
+  ✓ tmux installed successfully
+
+  Starting dashboard on port 3000...
+  ✓ Dashboard: http://localhost:3000

+
+  
If the user declines or install fails:

+  
  Install tmux now? [Y/n]: n
+
+  ✗ tmux is required but is not installed.
 
   Install tmux manually, then re-run ao start: