[Medium] User docs missing cargo install --path . flow documentation

[coderabbitai]

Problem

User docs still describe cargo run -p whitaker-installer without the new cargo install --path . flow, leaving the primary UX goal undocumented.

References

• docs/users-guide.md:73-81

Context

Raised during review of PR #93: #93

Priority

Medium

[traycerai]

Warning

Rate limit exceeded. Please try after 517838 seconds.

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Approach

Update installation documentation to reflect the modern cargo install --path installer workflow, addressing outdated cargo run -p whitaker-installer references discovered during PR #93 review.

Observations

The Whitaker project has two primary documentation files for installation: docs/users-guide.md for end users and docs/developers-guide.md for contributors. The exploration revealed that the ticket's line references (73-81) actually point to version pinning configuration, not installation instructions. The cargo run -p whitaker-installer pattern exists only in docs/developers-guide.md (line 46), while docs/users-guide.md already correctly documents cargo install whitaker-installer. Per Issue #94's completion, the correct local installation command is cargo install --path installer (not --path . as the ticket states).

Assumptions

Assumption 1: Target file clarification based on exploration findings

Options Considered:

1. Update only docs/developers-guide.md where the old pattern actually exists
2. Update docs/users-guide.md lines 73-81 as the ticket literally states
3. Update both files comprehensively

Chosen Option: 1

Rationale: The exploration definitively shows the outdated command exists only in developers-guide.md; users-guide.md already has correct instructions.

Assumption 2: Correct installation command based on Issue `#94`

Options Considered:

1. Use cargo install --path . as the ticket states
2. Use cargo install --path installer as documented in Issue #94

Chosen Option: 2

Rationale: Issue #94's execution plan explicitly documents that cargo install --path installer is correct because the workspace root no longer exposes the binary.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Update Developer Documentation

This phase updates the developers-guide.md to replace the outdated cargo run pattern with the modern install-based workflow, ensuring consistency with the changes established by Issue #94.

Task 1: Modernize Installation Instructions in Developer Guide

Update the "Using whitaker-installer" section in docs/developers-guide.md to present the install-based workflow as the primary method for contributors.

• Modify docs/developers-guide.md around line 46 to replace or supplement cargo run --release -p whitaker-installer with cargo install --path installer followed by whitaker-installer
• Ensure the section explains both approaches: the install method for typical contributor workflows and optionally retain the cargo run method for rapid iteration during active installer development
• Maintain consistency with the existing style and structure of the developers-guide.md document
• Verify the updated instructions align with the pattern already documented at line 52 of the same file

Task 2: Validate Documentation Consistency

Perform a final review to ensure all installation references across documentation are consistent.

• Confirm docs/users-guide.md line 25 (cargo install whitaker-installer) remains the correct end-user instruction
• Verify no other files contain outdated cargo run -p whitaker-installer references
• Ensure the distinction between end-user installation (from crates.io) and contributor installation (from local path) is clearly maintained

🤖 Prompt for AI agents

Update the developer documentation to modernize the installation workflow from
`cargo run` to `cargo install --path installer`.

**Task 1: Modernize Installation Instructions in Developer Guide**

In `docs/developers-guide.md` around line 46:
- Replace or supplement the existing `cargo run --release -p whitaker-installer`
command with the modern approach: `cargo install --path installer` followed by
`whitaker-installer`
- Present the install-based workflow as the primary method for contributors
- Explain both approaches:
- The `cargo install --path installer` method for typical contributor workflows
- Optionally retain the `cargo run` method for rapid iteration during active
installer development
- Maintain consistency with the existing document style and structure
- Ensure alignment with the pattern documented at line 52 of the same file

**Task 2: Validate Documentation Consistency**

Perform a comprehensive review:
- Verify that `docs/users-guide.md` line 25 correctly shows `cargo install
whitaker-installer` for end-user installation from crates.io
- Search for and confirm no other files contain outdated `cargo run -p
whitaker-installer` references
- Ensure clear distinction between:
  - End-user installation: `cargo install whitaker-installer` (from crates.io)
- Contributor installation: `cargo install --path installer` (from local
workspace)

---

🚀 Next Steps

🤖 All AI agent prompts combined

Update the developer documentation to modernize the installation workflow from
`cargo run` to `cargo install --path installer`.

**Task 1: Modernize Installation Instructions in Developer Guide**

In `docs/developers-guide.md` around line 46:
- Replace or supplement the existing `cargo run --release -p whitaker-installer`
command with the modern approach: `cargo install --path installer` followed by
`whitaker-installer`
- Present the install-based workflow as the primary method for contributors
- Explain both approaches:
- The `cargo install --path installer` method for typical contributor workflows
- Optionally retain the `cargo run` method for rapid iteration during active
installer development
- Maintain consistency with the existing document style and structure
- Ensure alignment with the pattern documented at line 52 of the same file

**Task 2: Validate Documentation Consistency**

Perform a comprehensive review:
- Verify that `docs/users-guide.md` line 25 correctly shows `cargo install
whitaker-installer` for end-user installation from crates.io
- Search for and confirm no other files contain outdated `cargo run -p
whitaker-installer` references
- Ensure clear distinction between:
  - End-user installation: `cargo install whitaker-installer` (from crates.io)
- Contributor installation: `cargo install --path installer` (from local
workspace)

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!