best-practices: expand id/naming rule (collisions + namespacing)

[topkoa]

Summary

Refines the id/naming best-practice (rule 2) with the real collision and namespacing gotchas, ground-truthed against the plugin loader — the "what should I name it and what will bite me?" guidance.

What it now covers

• How far the id reaches. It's interpolated into the routes module (plugin_<id>_routes), the screen container (plugin-<id>), a visualization's factory global (window.feedBackViz_<id>), the diagnostics path (plugins/<id>/), and the localStorage prefix — so a collision or rename ripples through all of them.
• Exact-case folder rule + why the charset matters. Folder name MUST equal id exactly including case (the Scaffold the feedBack plugin specification (v0.1.0 draft) #1 "why won't it load?"), and ^[a-z0-9][a-z0-9_-]*$ isn't cosmetic — the id becomes a Python module name and DOM/JS identifiers, so uppercase/dots/spaces break discovery or module loading. The validator rejects them.
• Collision resolution (not "last wins"). A bundled id always wins — a user plugin reusing a bundled id is silently ignored (kept only as a fallback). Between two non-bundled plugins, the first discovered wins and the other silently doesn't load.
• Reserved ids. capability_inspector and the app_tour_* prefix are always-enabled (can't be disabled) — don't collide with them.
• Namespace what the id doesn't do for you. All plugins share one window and one document, so prefix localStorage keys, window globals, routes, and CSS by id — two plugins writing window.state or localStorage["theme"] clobber each other silently.

Cross-links the normative rules in spec §4.2 (id) and §5.2 (directory-name rule). Added matching checklist items.

Scope & stacking

Docs only (spec/best-practices.md + CHANGELOG.md). No version bump; rule enriched in place so numbering is unchanged (1–25). The normative id rules already live in the spec (§4.2 charset/stability, §5.3 bundled-wins precedence) — this is the actionable advice layer, so no spec change needed.

Stacked on #5 (base docs/best-practices-visualizations). Full stack: #2 → #4 → #3 → #5 → #6. mkdocs build --strict and check_versions.py pass.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: eef81817-3683-4b6c-a74d-7bcbd10ba388

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/best-practices-id-naming

---

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

[Copilot]

Pull request overview

This PR refines the non-normative best-practices guidance around plugin id selection, focusing on real-world collision behavior and the practical namespacing implications across Host-derived surfaces.

Changes:

• Expanded best-practices rule 2 to document id scope/derivations, collision precedence, reserved ids, and shared-namespace namespacing guidance.
• Added matching items to the pre-publish checklist.
• Documented the update in the [Unreleased] changelog entry.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
spec/best-practices.md	Expands rule 2 (id/naming) and updates the publish checklist accordingly.
CHANGELOG.md	Adds an [Unreleased] entry summarizing the best-practices update.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.