docs: flag bootstrap overwrite behavior as not yet implemented

[jwm4]

Summary

• Add warning to docs/user-guide.md noting that the "never overwrites existing files" guarantee is not yet fully implemented (only CONTRIBUTING.md and CODE_OF_CONDUCT.md are protected)
• Fix stale _file_exists() reference in docs/developer-guide.md to reflect the actual _write_file() method and its current behavior
• Both warnings link to bug: bootstrap overwrites existing files despite "never overwrites" guarantee #449 for tracking the fix

Test plan

• Verify links to bug: bootstrap overwrites existing files despite "never overwrites" guarantee #449 resolve correctly
• Docs render correctly on GitHub

Submitted by Bill Murdock with assistance from Claude Code.

Summary by CodeRabbit

• Documentation
  • Updated documentation to clarify current file handling behavior and limitations regarding protection from overwrites. Specifically noted that existing-file protection is not yet fully implemented and currently applies only to specific configuration files.

[coderabbitai]

📝 Walkthrough

Walkthrough

Two documentation updates clarify the current state of file overwrite protection in the bootstrap process. The developer guide now states that _write_file() overwrites existing files, while the user guide removes a misleading claim about universal file protection and notes that only two files are currently shielded from overwrites.

Changes

File Overwrite Behavior Documentation

Layer / File(s)	Summary
File overwrite behavior clarification docs/developer-guide.md, docs/user-guide.md	Developer guide updates _write_file() documentation to reflect that it overwrites existing files (with reference to issue #449), removing mention of the _file_exists() conflict-check method. User guide removes the generic "never overwrites" claim and clarifies that protection is incomplete, covering only CONTRIBUTING.md and CODE_OF_CONDUCT.md.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title follows Conventional Commits format with 'docs' type and accurately describes the main change: updating documentation to clarify bootstrap overwrite behavior limitations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ 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/bootstrap-overwrite-warning

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch docs/bootstrap-overwrite-warning

---

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: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/user-guide.md`:
- Line 101: Update the contradictory statements so both occurrences convey the
same current behavior: replace the sentence that reads "Never overwrites
existing files (⚠️ [not yet fully implemented]..., currently only
`CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` are protected)" and the line saying
bootstrap “never overwrites files by design” with a single consistent phrasing
that reflects the actual state (e.g., "Bootstrap aims to avoid overwriting files
but full overwrite protection is not yet implemented — currently only
`CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` are protected; see issue `#449`"), and
keep the link to the issue; ensure both the earlier mention (the one from the
diff) and the later bootstrap claim use that exact updated text.

🪄 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: ASSERTIVE

Plan: Enterprise

Run ID: aef0178e-7c69-4116-a929-44442cc0e234

📥 Commits

Reviewing files that changed from the base of the PR and between b65727a and ef66e65.

📒 Files selected for processing (2)

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

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Resolve contradictory overwrite guidance in the same page

Line 101 says overwrite protection is not fully implemented, but Line 331 still says bootstrap “never overwrites files by design.” That conflict can lead users to run bootstrap with incorrect safety assumptions.

Suggested doc fix

-**"File already exists" (Bootstrap)** — Bootstrap never overwrites files by design. Remove existing files first if regenerating.
+**"File already exists" (Bootstrap)** — Overwrite protection is not yet fully implemented (see [`#449`](https://github.com/ambient-code/agentready/issues/449)); currently only `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` are protected. Use `--dry-run` and review `git status` before applying changes.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/user-guide.md` at line 101, Update the contradictory statements so both
occurrences convey the same current behavior: replace the sentence that reads
"Never overwrites existing files (⚠️ [not yet fully implemented]..., currently
only `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` are protected)" and the line
saying bootstrap “never overwrites files by design” with a single consistent
phrasing that reflects the actual state (e.g., "Bootstrap aims to avoid
overwriting files but full overwrite protection is not yet implemented —
currently only `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` are protected; see
issue `#449`"), and keep the link to the issue; ensure both the earlier mention
(the one from the diff) and the later bootstrap claim use that exact updated
text.

[github-actions]

📈 Test Coverage Report

Branch	Coverage
This PR	73.7%
Main	73.7%
Diff	✅ +0%

---

Coverage calculated from unit tests only

[github-actions]

🎉 This PR is included in version 2.39.2 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀