feat: understand-onboard writes docs/ONBOARDING.md — collides with existing team-onboarding docs

[NickPiperno]

What problem are you trying to solve?

skills/understand-onboard/SKILL.md step 9:

9. Offer to save the guide to docs/ONBOARDING.md in the project

docs/ONBOARDING.md is one of the most common pre-existing filenames in a repo — it's the conventional place for human onboarding docs (how to get a laptop set up, who to ask, team norms). The generated guide is a different thing: an orientation to the code.

Two problems:

1. Clobber risk. The skill has no existence check anywhere — step 9 just names the path. An agent following it will write to docs/ONBOARDING.md, overwriting whatever is already there. Some clients guard blind overwrites, but the plugin also targets Codex, Cursor, Copilot, and Gemini CLI, where that guard may not exist. This is the part I'd prioritize regardless of the naming decision.
2. Semantic collision. For any product that itself has an onboarding feature (a signup/first-run flow), docs/ONBOARDING.md is genuinely ambiguous — it reads like documentation of that feature. In my case the repo has an in-app onboarding flow, so docs/ONBOARDING.md next to it would be actively misleading to a new teammate.

I worked around it by instructing my agent to always write docs/CODE_ONBOARDING.md instead, but that's a per-repo patch of a default that will bite anyone with an existing ONBOARDING.md.

Proposed solution (optional)

In rough priority order — (1) stands alone even if the name never changes:

1. Check before writing. Add an explicit step: if the target exists and wasn't generated by this tool, don't overwrite — ask, or write alongside it. A generated-by marker (an HTML comment header) would make "is this ours?" answerable on re-runs.
2. Change the default to a name that says what the file is — my suggestion is docs/CODE_ONBOARDING.md. It describes the content (onboarding onto the code), stays readable to a teammate browsing docs/, and doesn't collide with the conventional human-onboarding file.
3. Make it configurable via $UA_DIR/config.json (e.g. "onboardingFileName": "docs/CODE_ONBOARDING.md"), consistent with how outputLanguage and autoUpdate are already stored there.

Alternatives you've considered

• UA_ONBOARDING.md — namespacing to the tool guarantees no collision, and matches the .ua/ convention. I'd lean away from it: docs filenames are read by humans, and a teammate opening docs/ won't know what "UA" means. But if you'd rather have a hard namespace than a descriptive name, this is the better of the two — it's collision-proof.
• Keep ONBOARDING.md, add existence check only — fixes the data-loss risk but leaves the ambiguity for products that have an onboarding feature.
• Status quo + document it — cheapest, but the default silently targets a common filename, so the failure lands on the user.

Happy to send a PR for whichever combination you prefer — (1) plus a config key is a small change to the skill text.

Which part of the project?

skills/understand-onboard

[Lum1104]

Hi, @NickPiperno , sounds good, to make this simple, we can use UA_ONBOARDING.md or make UA_{part}_ONBOARDING.md? Feel free to open a PR~