docs(worktree): fix stale rename example + document copyFiles properly

[Wirasm]

Summary

Three related fixes around worktree.copyFiles documentation. No code changes.

Context

The worktree.copyFiles primitive copies gitignored files/dirs from the canonical repo into new worktrees — exactly the mechanism that lets workflows, .env files, local plans, agent reports etc. reach isolated branches even when git worktree add alone would leave them behind. It's the right primitive for the common "team repo doesn't want `.archon/` committed" ask (see the #1144 close comment).

But the docs have three problems that make it easy to miss or misuse:

1. Stale rename syntax example that silently does nothing. Both reference/configuration.md and getting-started/overview.md showed - .env.example -> .env # Rename during copy. The -> parser was removed in 🐛 [Bug]: Fix DOCS inside project pls #739 (2026-03-19) after it caused the stale-credentials bug in Feature Request: consider loosening (or overriding) URL validity for knowledge scraping #228 — but the docs kept advertising it. A user writing .env.example -> .env today gets parseCopyFileEntry returning {source: '.env.example -> .env', destination: '.env.example -> .env'}, stat() fails with ENOENT, and the copy silently no-ops at debug level. No error surfaced.

2. No explanation of when or why to use it. Three mentions across all docs, all bare config snippets. No framing of the root cause (git worktree = tracked files only) or common entries beyond .env.

3. .archon/ default described vaguely, with no mention that users don't need to list it.

Changes

• reference/configuration.md

  • Drop the broken -> .env rename line from the main config example
  • Replace the one-line "Default behavior" note with a "Worktree file copying" subsection that explains the root cause, the .archon/ default, common entries (.env, .vscode/, .claude/, plans/, reports/, data fixtures), full semantics (source=destination, ENOENT silent skip, per-entry error isolation, path-traversal rejected), and interaction with worktree.path

• getting-started/overview.md

  • Update the example from .env.example + .env (which implied rename) to .env + plans/
  • Add a comment noting that .archon/ is auto-copied so users don't list it

Test plan

• bun run format:check and bun run lint green locally
• Reviewed rendered markdown — subsection nests correctly under ## Configuration siblings, links still intact

Summary by CodeRabbit

• Documentation
  • Updated worktree.copyFiles configuration examples in getting started guide
  • Expanded worktree.copyFiles documentation with detailed explanations of behavior, error handling, and common usage examples

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Documentation updates for the worktree.copyFiles configuration feature: replaced .env.example with .env in examples, expanded copyFiles list to include plans/, and added comprehensive semantics documentation clarifying automatic .archon/ copying and error handling behavior.

Changes

Cohort / File(s)	Summary
worktree.copyFiles Documentation packages/docs-web/src/content/docs/getting-started/overview.md, packages/docs-web/src/content/docs/reference/configuration.md	Updated configuration examples and expanded reference documentation: changed from copying .env.example to .env, added plans/ to copyFiles list, clarified that .archon/ is copied automatically, and added detailed semantics covering gitignored file copying behavior, path handling, error management, and consistency across worktree layout types.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 Hops through docs with gentle care,
Configuration now crystal clear,
Plans and envs, files now fair,
Archon paths need not appear!
Semantics bloom in text so bright ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the primary change: fixing a stale rename example and properly documenting the copyFiles feature for worktrees.
Description check	✅ Passed	The description is well-structured with clear sections covering summary, context, and detailed changes, though it does not follow the full template structure with UX Journey, Architecture Diagram, and other metadata sections.
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/worktree-copy-files-clarification

---

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.}