[droid-ash]

Summary

• Rewrites the README to optimize for new users going from zero to first test quickly
• Extracts the full environment/secrets deep-dive to docs/environment.md (was ~40% of the README)
• Adds .env.example template for easy onboarding
• Adds new sections: Zero to First Test walkthrough, Troubleshooting, Using with AI Coding Agents
• Groups CLI commands by tier, documents --app/--debug flags, moves social links to bottom

Changes

File	What changed
README.md	Full restructure — onboarding-first flow, concrete hero, copy-paste Quick Start, tiered CLI commands, troubleshooting
docs/environment.md	New — full environment/secrets/prerequisites guide extracted from README
.env.example	New — template with provider keys and test secret placeholders
.gitignore	Added !.env.example so the template is tracked by git

Test plan

• Verify all internal anchor links in README resolve correctly
• Verify docs/environment.md link from README works
• Confirm .env.example appears in git (not ignored by .env.* pattern)
• Read through "Zero to First Test" as a new user — each step should be unambiguous
• Verify no mention of finalrun report serve remains in README

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Major README rewrite with a concise install/get-started and AI-driven “write and run your first test” walkthrough
  • Added docs: CLI reference, workspace configuration, environment/secrets resolution, YAML test format, troubleshooting
  • Updated docs and examples to reference the OpenAI model label openai/gpt-5.4-mini

• Configuration

  • Added a tracked .env.example template with commented AI provider API-key and test credential placeholders; adjusted ignore rules so the template is included

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)

• .github/resources/finalrun-demo.gif is excluded by !**/*.gif

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 300433ce-c28e-450b-9e59-2a09411e1ab1

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Added a tracked .env.example and updated .gitignore; introduced multiple documentation pages (environment, CLI reference, configuration, YAML tests, troubleshooting); rewrote README; and updated test fixtures/examples to use the OpenAI model label openai/gpt-5.4-mini. No runtime code or public API changes.

Changes

Cohort / File(s)	Summary
Environment config /.env.example, /.gitignore	Add a committed .env.example with commented AI provider API-key and test-secret templates; adjust .gitignore to allow the example file.
Top-level README & docs README.md, docs/environment.md, docs/codebase-walkthrough.md, docs/cli-reference.md, docs/configuration.md, docs/yaml-tests.md, docs/troubleshooting.md	Rewrite README onboarding to AI-agent-focused workflow; add detailed docs for dotenv/env YAML resolution, workspace layout, CLI reference, configuration semantics, YAML test schema, and troubleshooting.
CLI package tests & examples packages/cli/src/finalrun.test.ts, packages/cli/src/env.test.ts, packages/cli/src/reportTemplates.test.ts, packages/cli/src/runIndex.test.ts, packages/cli/src/sessionRunner.ts, packages/cli/src/terminalRenderer.test.ts, packages/cli/src/testRunner.test.ts	Update tests, fixtures, and inline examples to replace openai/gpt-4o with openai/gpt-5.4-mini; no functional logic changes.
Goal-executor package tests & examples packages/goal-executor/src/ActionExecutor.test.ts, packages/goal-executor/src/TestExecutor.test.ts, packages/goal-executor/src/ai/AIAgent.test.ts, packages/goal-executor/src/ai/AIAgent.ts	Adjust test inputs, expected messages, and example comments to use gpt-5.4-mini; no runtime/API changes.
Report-web package tests packages/report-web/src/artifacts.test.ts, packages/report-web/src/renderers.test.ts	Update persisted run fixtures, manifest fields, and HTML assertions to reflect openai/gpt-5.4-mini.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related PRs

• Secrets feature fix from env file #37 — implements runtime dotenv/env secret-resolution that the new docs and .env.example describe.
• [codex] Add README demo video #42 — related README/demo updates (visual/demo materials).
• [codex] Clarify FinalRun prerequisites in README #45 — overlapping README/docs edits and finalrun doctor / host-readiness guidance.

Suggested reviewers

• arnoldlaishram

Poem

🐰 I nibble keys and comment lines,

A dotted map of API signs.
Docs refreshed and models renamed,
Tests hop forward, fixtures reclaimed.
A happy rabbit ships the change.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'docs: restructure README for onboarding-first experience' is concise, specific, and accurately describes the main change: restructuring the README with an onboarding-first focus.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/readme-restructure

---

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]

Actionable comments posted: 2

🧹 Nitpick comments (1)

docs/environment.md (1)

49-50: Clarify where ${secrets.*} is actually defined

On Line 49, wording implies ${secrets.*} appears in .finalrun/env/*.yaml. It doesn’t—those files define secrets mappings from ${ENV_VAR} placeholders, and ${secrets.*} is used in test spec files. This can confuse onboarding.

Proposed doc fix

-- Resolving **`${secrets.*}`** references defined in `.finalrun/env/*.yaml`.
+- Resolving `secrets` mappings declared in `.finalrun/env/*.yaml` (from `${ENV_VAR}` placeholders), which are then referenced as `${secrets.*}` in test specs.

🤖 Prompt for AI Agents

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

In `@docs/environment.md` around lines 49 - 50, The docs currently imply
`${secrets.*}` is defined inside `.finalrun/env/*.yaml`; update the wording to
clarify that `.finalrun/env/*.yaml` files instead define `secrets` mappings that
point to environment variables (e.g., `${ENV_VAR}`), and that `${secrets.*}`
placeholders are used in test spec files (e.g., references inside test
manifests) and resolved at runtime by `finalrun test` and `finalrun suite`;
mention both the mapping role of `.finalrun/env/*.yaml` and where `${secrets.*}`
is actually used to avoid confusion.

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In @.env.example:
- Line 6: Update the inaccurate template comment that mentions "${secrets.*}"
for .finalrun/env/*.yaml: replace the line that reads "# Test Secrets
(referenced via ${secrets.*} in .finalrun/env/*.yaml)" with a corrected comment
stating that .finalrun/env/*.yaml uses ${TEST_*}-style env placeholders (e.g.,
${TEST_USER_EMAIL}), and note that ${secrets.*} is only used in test YAML step
references; edit the comment text accordingly to reflect these two distinct
placeholder usages.

In `@README.md`:
- Around line 111-114: The README assumes a local .env.example file exists (the
`cp .env.example .env` step), which breaks onboarding for fresh app repos;
update the instructions to handle both cases by: instructing users to copy from
the template only if .env.example exists (mention `.env.example`) and otherwise
provide the fallback `echo "GOOGLE_API_KEY=your-key-here" > .env` or a one‑liner
to create .env manually; ensure the README text around the `cp .env.example
.env` step and the shown alternative command are updated so new users can create
.env without relying on a preexisting .env.example.

---

Nitpick comments:
In `@docs/environment.md`:
- Around line 49-50: The docs currently imply `${secrets.*}` is defined inside
`.finalrun/env/*.yaml`; update the wording to clarify that
`.finalrun/env/*.yaml` files instead define `secrets` mappings that point to
environment variables (e.g., `${ENV_VAR}`), and that `${secrets.*}` placeholders
are used in test spec files (e.g., references inside test manifests) and
resolved at runtime by `finalrun test` and `finalrun suite`; mention both the
mapping role of `.finalrun/env/*.yaml` and where `${secrets.*}` is actually used
to avoid confusion.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4c7e37af-74e7-4f82-8874-9f1d1d462383

📥 Commits

Reviewing files that changed from the base of the PR and between 0328623 and 7d9c7ac.

📒 Files selected for processing (4)

• .env.example
• .gitignore
• README.md
• docs/environment.md

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@README.md`:
- Line 257: The troubleshooting anchor link "[Supported AI
Providers](`#supported-ai-providers`)" is broken; update the README entry to point
to an existing heading (for example change the fragment to "#api-keys") or add a
matching heading "Supported AI Providers" to the document so the anchor
resolves; make this change in the README.md line that contains the link text so
navigation works.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 01e16df0-a517-4c24-b806-fbd9ed2a7064

📥 Commits

Reviewing files that changed from the base of the PR and between 08e61c6 and 92b8481.

📒 Files selected for processing (1)

• README.md

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

README.md (1)

57-57: Consider removing specific agent branding to maintain agent-agnostic positioning.

Line 57 mentions "adds FinalRun skills for Claude Code / Codex," but the PR objectives state that commits "removed Claude Code–specific language" to be "agent-agnostic." Consider revising to:

adds FinalRun skills for AI coding agents

🤖 Prompt for AI Agents

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

In `@README.md` at line 57, The README line still references vendor-specific
agents ("FinalRun skills for Claude Code / Codex"); update the sentence to be
agent-agnostic by replacing that phrase with a neutral term such as "FinalRun
skills for AI coding agents" (edit the sentence containing "adds FinalRun skills
for Claude Code / Codex" to the suggested wording) and ensure surrounding
wording remains consistent with the PR's removed Claude-specific language.

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@docs/environment.md`:
- Around line 84-86: Fix the ambiguous bullet list by splitting the combined
sentence into two clear bullets: one stating that `scrcpy` must be on PATH and
is required by FinalRun for Android screen recording, and a separate bullet
stating that FinalRun bundles Android driver assets which the published CLI
installs automatically; update the lines mentioning `scrcpy` and "Bundled
FinalRun Android driver assets" so they are distinct list items with parallel
phrasing.

---

Nitpick comments:
In `@README.md`:
- Line 57: The README line still references vendor-specific agents ("FinalRun
skills for Claude Code / Codex"); update the sentence to be agent-agnostic by
replacing that phrase with a neutral term such as "FinalRun skills for AI coding
agents" (edit the sentence containing "adds FinalRun skills for Claude Code /
Codex" to the suggested wording) and ensure surrounding wording remains
consistent with the PR's removed Claude-specific language.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b39e1372-9bb3-4afa-bcd0-3383861f6ffb

📥 Commits

Reviewing files that changed from the base of the PR and between 92b8481 and 4ba5a15.

📒 Files selected for processing (6)

• .env.example
• README.md
• docs/cli-reference.md
• docs/configuration.md
• docs/environment.md
• docs/yaml-tests.md

✅ Files skipped from review due to trivial changes (4)

• .env.example
• docs/cli-reference.md
• docs/yaml-tests.md
• docs/configuration.md

[coderabbitai]

🧹 Nitpick comments (1)

README.md (1)

85-85: Consider mentioning .env.example alongside direct creation.

Since this PR adds .env.example to the repository, you might optionally reference it here for users who clone the FinalRun repo (vs adding FinalRun to their own app):

-echo "GOOGLE_API_KEY=your-key-here" > .env
+# If you cloned this repo:
+cp .env.example .env
+# Or create directly:
+echo "GOOGLE_API_KEY=your-key-here" > .env

This keeps the simple onboarding path while acknowledging the new template file.

🤖 Prompt for AI Agents

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

In `@README.md` at line 85, Update the README instruction that currently shows
creating a .env with echo so it also references the new .env.example template:
keep the existing echo example (echo "GOOGLE_API_KEY=your-key-here" > .env) but
add an alternative sentence like "Or copy the provided .env.example: cp
.env.example .env and then set GOOGLE_API_KEY" so users cloning the repo can use
the template; mention both options in the same paragraph for clarity.

🤖 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`:
- Line 85: Update the README instruction that currently shows creating a .env
with echo so it also references the new .env.example template: keep the existing
echo example (echo "GOOGLE_API_KEY=your-key-here" > .env) but add an alternative
sentence like "Or copy the provided .env.example: cp .env.example .env and then
set GOOGLE_API_KEY" so users cloning the repo can use the template; mention both
options in the same paragraph for clarity.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4f07e6aa-a15f-4d87-a5bc-2d9878068cfb

📥 Commits

Reviewing files that changed from the base of the PR and between 4ba5a15 and 7194c46.

📒 Files selected for processing (3)

• README.md
• docs/environment.md
• docs/troubleshooting.md

✅ Files skipped from review due to trivial changes (2)

• docs/troubleshooting.md
• docs/environment.md