docs(readme): clarify onboarding and nix install

[caverav]

Summary

• move install and first-use guidance to the top of the README
• add persistent Nix install instructions alongside nix run
• align docs/user-guide.md with the new user-first flow

Testing

• not run (docs only)

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Enhanced README with clearer descriptions of available outputs (diff, startup, symbol-reporting artifacts).
  • Restructured documentation with new "Get Started" and "Common Commands" sections.
  • Added dedicated user guide sections for Function Scope and Single-Function Targeting workflows.
  • Expanded CLI examples and improved workflow guidance.

Walkthrough

Documentation updates to the flutterdec tool's README and user guide. The README was restructured to broaden output descriptions (adding diff, startup, and symbol-reporting artifacts) and reorganized with new "What It Is For", "Get Started", "First Use", and "Common Commands" sections. The user guide expanded the installation instructions, reorganized the workflow into ordered steps, and added dedicated sections for function scoping and single-function targeting with enhanced CLI examples.

Changes

Cohort / File(s)	Summary
Documentation Restructuring README.md	Broadened advertised outputs, removed pipeline narrative, added "What It Is For"/"Get Started"/"First Use"/"Common Commands" sections, expanded CLI examples for diff/ASM/IR/Ghidra/IDA outputs, refined "Output Layout" section with clarified report.json fields and script emission conditions.
User Guide Reorganization docs/user-guide.md	Expanded "Install And Run" section with nix run/profile/binary options, reorganized "Basic Commands" into ordered "First Use" workflow steps, added dedicated "Function Scope" and "Single-Function Targeting" sections, updated adapter backend documentation, simplified "Outputs" section.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers the main objectives and notes testing status, but is missing the validation checklist required by the template.	Add the validation checklist from the template (cargo fmt, clippy, test, and real-binary check) even if marked as N/A for docs-only changes, and include the scope checklist items.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main changes: documentation updates that clarify onboarding and Nix installation instructions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

🧹 Nitpick comments (3)

README.md (3)

262-269: Clarify the ambiguity resolution behavior.

The phrase "If <N> is ambiguous, flutterdec requires explicit id: or va:" could be clearer about what happens during ambiguity. Does it fail immediately, or does it prompt the user?

✏️ Suggested clarification

-If `<N>` is ambiguous, `flutterdec` requires explicit `id:` or `va:`. Selection details are emitted in `report.json.target_selection`.
+If `<N>` matches multiple functions (ambiguous), the command fails and requires you to use explicit `id:` or `va:` prefixes. Selection details are emitted in `report.json.target_selection`.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 262 - 269, Clarify the ambiguity behavior for
`--target`: update the README text around `--target` to state that when a
numeric `<N>` is ambiguous flutterdec will fail with an error (not prompt), exit
non-zero, and print a clear message instructing the user to disambiguate using
the `id:` or `va:` prefix; also mention that the resolved/attempted selection
details are written to `report.json.target_selection` for debugging and include
`--target` and `flutterdec` names so readers can find the related CLI usage.

---

304-308: Table formatting may not render consistently.

The "What To Look At" table uses --- separators which should render correctly in most Markdown parsers, but the content alignment could be clearer with explicit column alignment indicators.

📋 Optional table formatting improvement

 | If you want to... | Start with... | Why |
-| --- | --- | --- |
+| :--- | :--- | :--- |
 | Read recovered logic | `pseudocode/*.dartpseudo` | Best first pass for branches, loops, returns, and named callsites |

This adds explicit left-alignment to all columns.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 304 - 308, The "What To Look At" Markdown table uses
plain `---` separators which may not enforce column alignment consistently;
update the table's separator row to include explicit left-alignment indicators
for each column (e.g., use `:---` for left-align) so the three columns
containing "Read recovered logic", "Validate the decompiler", "Understand
startup", "Check analysis health", and "Review version-to-version changes"
render with consistent left alignment; locate the table in README.md and replace
the separator line under the header with a separator that has `:---` for each
column to ensure clear alignment.

---

332-334: Inconsistent description of adapter backend fallback behavior.

Line 332 says "try Blutter backend if configured, otherwise fall back" but line 260 in user-guide.md says "attempt Blutter bridge backend when configured, otherwise fallback". The terminology should be consistent (either "Blutter backend" or "Blutter bridge backend").

🔄 Align terminology

Choose one consistently:

• Either "Blutter backend" (shorter)
• Or "Blutter bridge backend" (matches user-guide.md line 260)

-- `--adapter-backend auto` (default): try Blutter backend if configured, otherwise fall back to the internal adapter
+- `--adapter-backend auto` (default): try Blutter bridge backend if configured, otherwise fall back to the internal adapter

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 332 - 334, Choose a single term for the Blutter
integration and make it consistent across docs: replace either "Blutter backend"
or "Blutter bridge backend" everywhere (including the README.md bullet that
currently reads "`--adapter-backend blutter`: require the Blutter backend..."
and the user-guide.md occurrence that says "Blutter bridge backend") so both
files use the exact same phrase; update all occurrences and adjacent explanatory
bullets to match the chosen term and run a quick find/replace to ensure no mixed
terminology remains.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@README.md`:
- Around line 262-269: Clarify the ambiguity behavior for `--target`: update the
README text around `--target` to state that when a numeric `<N>` is ambiguous
flutterdec will fail with an error (not prompt), exit non-zero, and print a
clear message instructing the user to disambiguate using the `id:` or `va:`
prefix; also mention that the resolved/attempted selection details are written
to `report.json.target_selection` for debugging and include `--target` and
`flutterdec` names so readers can find the related CLI usage.
- Around line 304-308: The "What To Look At" Markdown table uses plain `---`
separators which may not enforce column alignment consistently; update the
table's separator row to include explicit left-alignment indicators for each
column (e.g., use `:---` for left-align) so the three columns containing "Read
recovered logic", "Validate the decompiler", "Understand startup", "Check
analysis health", and "Review version-to-version changes" render with consistent
left alignment; locate the table in README.md and replace the separator line
under the header with a separator that has `:---` for each column to ensure
clear alignment.
- Around line 332-334: Choose a single term for the Blutter integration and make
it consistent across docs: replace either "Blutter backend" or "Blutter bridge
backend" everywhere (including the README.md bullet that currently reads
"`--adapter-backend blutter`: require the Blutter backend..." and the
user-guide.md occurrence that says "Blutter bridge backend") so both files use
the exact same phrase; update all occurrences and adjacent explanatory bullets
to match the chosen term and run a quick find/replace to ensure no mixed
terminology remains.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 24a963c9-b90c-414f-bc57-91a612491ea1

📥 Commits

Reviewing files that changed from the base of the PR and between 0cbcdb8 and 6ae32a8.

📒 Files selected for processing (2)

• README.md
• docs/user-guide.md