[bradygaster]

Summary

Get-started page cleanup addressing tamirdresher's review comment from #1426, first-session REPL regression fix, and page consolidation. This is WS-D of the four-part #1426 replacement strategy.

⚠️ Merge order note: This PR modifies docs/src/navigation.ts and docs/tests/build-output.test.mjs to include the WS-B restructure plus one addition. Merge squad/1426-b-concepts-nav (PR #1571) before this PR to avoid a navigation.ts conflict, or rebase this branch on merged dev after WS-B lands.

File Scope

File	Change
docs/src/content/docs/get-started/installation.md	Fix tamirdresher's comment: bare squad → squad --version
docs/src/content/docs/get-started/first-session.md	Fix bare squad → squad init (REPL artifact)
docs/src/content/docs/get-started/five-minute-start.md	Remove ⚠️ Experimental banner, voice pass
docs/src/content/docs/get-started/choose-your-interface.md	Remove REPL sections, update feature matrix, voice pass
docs/src/content/docs/get-started/choosing-your-path.md	Deleted — no inbound links; content consolidated into choose-your-interface.md
docs/src/navigation.ts	WS-B restructure + add choose-your-interface to Guides
docs/tests/build-output.test.mjs	Sync knownSections to match new nav structure

Changes Applied

installation.md — tamirdresher's fix

The ## Try this: block previously showed bare squad as the post-install verification. The ## Verify section further down already showed squad --version. Now consistent throughout.

Before:

npm install -g @bradygaster/squad-cli
squad

After:

npm install -g @bradygaster/squad-cli
squad --version

first-session.md — REPL regression fix

All bare squad (no subcommand) in code blocks replaced with squad init. The bare squad command was the interactive REPL entrypoint, which has been retired. Without this fix, new users following the guide would run a command that either prints help text or does nothing.

Page consolidation

• choosing-your-path.md deleted — no inbound links confirmed; the 3-mode decision content overlapped with choose-your-interface.md
• choose-your-interface.md added to Guides nav section as the canonical mode-comparison page

Validation

• npm run build in docs/: ✅ passes
• grep -n '^squad$' docs/src/content/docs/get-started/*.md → 0 matches ✅
• grep 'squad --version' installation.md → appears in Try this block ✅
• grep 'squad init' first-session.md → present ✅

Reviewer Note

This PR resolves tamirdresher's unresolved review thread on #1426 (2026-07-03, installation quick-start bare squad command).

Supersedes part of #1426
Working as PAO (DevRel)

[github-actions]

🟡 Impact Analysis — PR #1573

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	6
Files added	0
Files modified	5
Files deleted	1
Modules touched	1

🎯 Risk Factors

• 6 files changed (6-20 → MEDIUM)
• 1 module(s) touched (≤1 → LOW)
• 1 file(s) deleted

📦 Modules Affected

docs (6 files)

• docs/src/content/docs/get-started/choose-your-interface.md
• docs/src/content/docs/get-started/choosing-your-path.md
• docs/src/content/docs/get-started/first-session.md
• docs/src/content/docs/get-started/five-minute-start.md
• docs/src/content/docs/get-started/installation.md
• docs/src/navigation.ts

---

This report is generated automatically for every PR. See #733 for details.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit ec8498c

PR Scope: 🔧 Infrastructure

⚠️ 2 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	No source files changed — changeset not required
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
❌	Copilot threads resolved	4 unresolved Copilot thread(s) — fix and resolve before merging
✅	CI passing	All checks passing

Files Changed (6 files, +190 −574)

File	+/−
docs/src/content/docs/get-started/choose-your-interface.md	+120 −178
docs/src/content/docs/get-started/choosing-your-path.md	+0 −82
docs/src/content/docs/get-started/first-session.md	+4 −85
docs/src/content/docs/get-started/five-minute-start.md	+58 −87
docs/src/content/docs/get-started/installation.md	+7 −142
docs/src/navigation.ts	+1 −0

Total: +190 −574

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[Copilot]

Pull request overview

This PR cleans up the Get Started docs to remove retired “bare squad”/REPL artifacts, consolidates interface guidance, and aligns the docs navigation + build-output assertions with the updated section structure (WS-D follow-on to the WS-B nav restructure).

Changes:

• Fixes Get Started command snippets to use squad --version / squad init instead of bare squad.
• Consolidates “choose a mode/interface” content by deleting choosing-your-path.md and updating choose-your-interface.md.
• Updates docs/src/navigation.ts and docs/tests/build-output.test.mjs to reflect the new nav/section taxonomy.

Show a summary per file

File	Description
docs/tests/build-output.test.mjs	Updates the expected Pagefind “section” values to match the new nav section titles.
docs/src/navigation.ts	Restructures nav sections (Concepts promoted; Features split; Guides updated; Scenarios reordered).
docs/src/content/docs/get-started/installation.md	Updates install verification command and trims/simplifies troubleshooting + setup guidance.
docs/src/content/docs/get-started/five-minute-start.md	Removes experimental banner and refines quick start wording/structure.
docs/src/content/docs/get-started/first-session.md	Replaces bare squad with squad init in walkthrough code blocks.
docs/src/content/docs/get-started/choosing-your-path.md	Deletes the page as part of consolidation.
docs/src/content/docs/get-started/choose-your-interface.md	Removes deprecated REPL/interface sections and updates the comparison/positioning content.

Review details

Suppressed comments (2)

docs/src/navigation.ts:94

• This section mixes slugs from other top-level dirs (get-started/*, cookbook/*) into the Guides section. Because Pagefind section metadata is derived from the slug’s first path segment (see DocsLayout.astro), these pages will still be indexed under Get Started or the fallback Docs, not Guides—so sidebar grouping and search section facets will disagree.

    items: [
      { title: 'Choose Your Interface', slug: 'get-started/choose-your-interface' },
      { title: 'Tips & Tricks', slug: 'guide/tips-and-tricks' },
      { title: 'Sample Prompts', slug: 'guide/sample-prompts' },
      { title: 'Recipes', slug: 'cookbook/recipes' },

docs/src/navigation.ts:121

• Migration Guide is placed under the Scenarios nav section, but its slug is get-started/migration. With the current section-metadata logic (slug prefix → section), this page will still be indexed as Get Started, not Scenarios, which makes nav grouping and search facets inconsistent.

      { title: 'Migration Guide', slug: 'get-started/migration' },

• Files reviewed: 7/7 changed files
• Comments generated: 5
• Review effort level: Lite