hermes - 💡(How to fix) Fix Docs/Config: Plugin local scope enablement ambiguity [1 pull requests]

Verdict

Type: docs gap + UX/config ambiguity (not a runtime crash bug)

The current plugin docs mix project-local discovery with global enablement in a way that's easy to misread as project-scoped activation.

Evidence

• Docs describe project plugins at ./.hermes/plugins/ gated by HERMES_ENABLE_PROJECT_PLUGINS=true:
  • website/docs/user-guide/features/plugins.md lines 92, 124
• The same page tells users to enable with hermes plugins enable <name> / plugins.enabled:
  • website/docs/user-guide/features/plugins.md lines 145, 149, 164
• CLI plugins enable has no scope flag (--local / --project / --global):
  • hermes_cli/main.py lines 12483–12491
• Implementation of cmd_enable always persists to shared config (load_config/save_config):
  • hermes_cli/plugins_cmd.py lines 641–648 and 651–671

So discovery can be project-local, but enable/disable state is persisted in the global config namespace, with no explicit scoping control in CLI UX.

Why this matters

When users are testing a repo-specific plugin, they can reasonably expect “enable from this repo” to be local to that repo. Instead, the allow-list entry is global by default, which can unintentionally affect other sessions/environments using the same profile.

Minimal repro

1. In a repo, place a plugin under ./.hermes/plugins/<name>/.
2. Start Hermes with HERMES_ENABLE_PROJECT_PLUGINS=true.
3. Run: hermes plugins enable <name>.
4. Observe that enablement is written into the main profile config (plugins.enabled) rather than a project-scoped setting.

Expected behavior

One of these should be true (and explicit):

1. Scoped controls exist (e.g. --project / --global) and docs explain precedence, or
2. If global-only is intentional, CLI/docs should clearly say: project plugins are discoverable per-repo, but enable/disable writes to profile-global config.

Actual behavior

Current docs and CLI wording leave scope ambiguous; users can interpret project discovery + enable command as project-local activation.

Proposed fix

1. Docs clarification (short term):
   • Add a “Scope of enable/disable” callout in plugin docs and command docs.
   • Explicitly state that hermes plugins enable/disable updates profile config.
2. CLI UX (optional but better):
   • Add --project/--global semantics (or equivalent) if project-scoped activation is desired.
   • If not implementing scoped activation, print a one-line confirmation warning on enable/disable that the change is profile-global.
3. Tests:
   • Add a CLI test that asserts current persistence target and prevents accidental scope drift.

Duplicate check

I found similarly titled closed stubs (#34122, #34123, #34130) with no substantive body. This issue contains the full evidence/repro payload for maintainers to triage.