docs: clarify extension registration parity scope

Author: PascalThuet

src/specify_cli/extensions.py

@@ -1637,16 +1637,12 @@ def unregister_agent_artifacts(self, agent_name: str) -> None:
     def register_enabled_extensions_for_agent(self, agent_name: str) -> None:
         """Register installed, enabled extensions for ``agent_name``.
 
-        This is intended to be called after switching integrations. Command
-        registration is scoped to the explicit ``agent_name`` argument, but some
-        behavior still depends on the current init-options state (for example,
-        skills-mode handling uses the active ``ai`` / ``ai_skills`` settings).
-
-        Callers should therefore pass the agent that has just been made active
-        in init-options; in normal use, ``agent_name`` is expected to match the
-        current ``ai`` value. This mirrors extension install behavior while
-        avoiding stale default-mode command directories when that active agent
-        is running in skills mode (notably Copilot ``--skills``).
+        Command-file registration is scoped to the explicit ``agent_name``
+        argument, so this method can be used after install, upgrade, or switch.
+        Extension skill rendering is still scoped to the active ``ai`` /
+        ``ai_skills`` settings in init-options, so non-active skills-mode
+        targets receive command files here. Per-agent skills parity is tracked
+        separately in #2948.
         """
         if not agent_name:
             return

src/specify_cli/integrations/_helpers.py

@@ -425,8 +425,7 @@ def _register_extensions_for_agent(
 
     ``switch`` has always re-registered enabled extensions for the agent it
     activates; ``install`` and ``upgrade`` call this so a newly added (or
-    refreshed) agent reaches the same parity — every installed agent ends up
-    with every enabled extension's commands. See issue #2886.
+    refreshed) agent reaches command-registration parity. See issue #2886.
 
     Known limitation: extension *skill* rendering is scoped to the active
     agent (init-options track a single ``ai`` / ``ai_skills`` pair). A

src/specify_cli/integrations/_install_commands.py

@@ -190,10 +190,11 @@ def integration_install(
         raise typer.Exit(1)
 
     # Register enabled extensions for the newly installed agent so it gets the
-    # same extension commands the existing agents already have (full parity with
-    # switch); otherwise a second integration silently lacks the first agent's
-    # extension commands. See #2886. Done after the try/except (the install has
-    # committed) so this best-effort step can never trigger the rollback above.
+    # same extension commands the existing agents already have for command
+    # registration parity with switch; otherwise a second integration silently
+    # lacks the first agent's extension commands. See #2886. Done after the
+    # try/except (the install has committed) so this best-effort step can never
+    # trigger the rollback above.
     _register_extensions_for_agent(
         project_root,
         integration.key,

src/specify_cli/integrations/_migrate_commands.py

@@ -475,9 +475,10 @@ def integration_upgrade(
 
     # Re-register enabled extensions for the upgraded agent so its extension
     # commands are (re)created — including agents installed before this
-    # back-fill existed. Mirrors switch; see #2886. Done after the upgrade has
-    # fully settled (Phase 2 included) and outside the try/except above so this
-    # best-effort step cannot affect upgrade success.
+    # back-fill existed. Mirrors switch for command registration; see #2886.
+    # Done after the upgrade has fully settled (Phase 2 included) and outside
+    # the try/except above so this best-effort step cannot affect upgrade
+    # success.
     _register_extensions_for_agent(
         project_root,
         key,

tests/integrations/test_integration_subcommand.py

@@ -1245,7 +1245,9 @@ def test_install_registers_extension_commands_for_new_agent(self, tmp_path):
         Regression for #2886: only ``switch`` used to register extension
         commands for the newly active agent, so a second integration added via
         ``install`` was silently missing the extension commands the first agent
-        had. ``install`` must reach full parity with ``switch``.
+        had. ``install`` must reach command-registration parity with
+        ``switch``; active-agent-scoped extension skill rendering remains
+        tracked in #2948.
         """
         project = _init_project(tmp_path, "claude")