@clawpump/claw-agent 0.1.5 → 0.1.7

package/agent/hermes_cli/plugins_cmd.py

@@ -135,34 +135,116 @@ def _sanitize_plugin_name(
     return target
 
 
-def _resolve_git_url(identifier: str) -> str:
-    """Turn an identifier into a cloneable Git URL.
+_GITHUB_BROWSER_SEGMENTS = {
+    "actions",
+    "blob",
+    "commit",
+    "commits",
+    "issues",
+    "pull",
+    "pulls",
+    "releases",
+    "tree",
+    "wiki",
+}
+
+
+def _resolve_git_url(identifier: str) -> tuple[str, Optional[str]]:
+    """Turn an identifier into a cloneable Git URL and optional subdirectory.
+
+    Returns ``(git_url, subdir)`` where ``subdir`` is the path within the
+    cloned repository that contains the plugin (``None`` when the plugin lives
+    at the repo root).
 
     Accepted formats:
     - Full URL: https://github.com/owner/repo.git
     - Full URL: git@github.com:owner/repo.git
     - Full URL: ssh://git@github.com/owner/repo.git
+    - Browser URL: https://github.com/owner/repo/tree/main/path
+      →  (https://github.com/owner/repo.git, "path")
     - Shorthand: owner/repo  →  https://github.com/owner/repo.git
+    - Shorthand w/ subdir: owner/repo/path/to/plugin
+      →  (https://github.com/owner/repo.git, "path/to/plugin")
+    - Full URL w/ subdir (``.git`` boundary):
+      https://github.com/owner/repo.git/path/to/plugin
+      →  (https://github.com/owner/repo.git, "path/to/plugin")
+    - Any URL w/ explicit subdir fragment (works for every scheme, incl.
+      ``file://`` and ssh): <url>#path/to/plugin
+      →  (<url>, "path/to/plugin")
 
     NOTE: ``http://`` and ``file://`` schemes are accepted but will trigger a
     security warning at install time.
     """
-    # Already a URL
+    # Already a URL.
     if identifier.startswith(("https://", "http://", "git@", "ssh://", "file://")):
-        return identifier
-
-    # owner/repo shorthand
-    parts = identifier.strip("/").split("/")
-    if len(parts) == 2:
-        owner, repo = parts
-        return f"https://github.com/{owner}/{repo}.git"
+        if identifier.startswith("https://github.com/"):
+            path = identifier[len("https://github.com/") :]
+            path = path.split("?", 1)[0].split("#", 1)[0].strip("/")
+            parts = path.split("/")
+            if len(parts) >= 3 and all(parts[:2]) and parts[2] in _GITHUB_BROWSER_SEGMENTS:
+                repo = parts[1].removesuffix(".git")
+                subdir = None
+                if parts[2] == "tree" and len(parts) >= 5:
+                    subdir = "/".join(p for p in parts[4:] if p).strip("/") or None
+                return f"https://github.com/{parts[0]}/{repo}.git", subdir
+
+        # Explicit ``#subdir`` fragment — unambiguous for any scheme.
+        if "#" in identifier:
+            git_url, _, frag = identifier.partition("#")
+            return git_url, (frag.strip("/") or None)
+        # Natural ``.git/`` boundary (GitHub-style URLs).
+        marker = ".git/"
+        idx = identifier.find(marker)
+        if idx != -1:
+            git_url = identifier[: idx + len(".git")]
+            subdir = identifier[idx + len(marker) :].strip("/")
+            return git_url, (subdir or None)
+        return identifier, None
+
+    # owner/repo[/subdir...] shorthand
+    parts = [p for p in identifier.strip("/").split("/") if p]
+    if len(parts) >= 2:
+        owner, repo = parts[0], parts[1]
+        subdir = "/".join(parts[2:]).strip("/")
+        git_url = f"https://github.com/{owner}/{repo}.git"
+        return git_url, (subdir or None)
 
     raise ValueError(
         f"Invalid plugin identifier: '{identifier}'. "
-        "Use a Git URL or owner/repo shorthand."
+        "Use a Git URL or 'owner/repo' shorthand (optionally with a subdirectory: "
+        "'owner/repo/path/to/plugin')."
     )
 
 
+def _resolve_subdir_within(clone_root: Path, subdir: str) -> Path:
+    """Resolve ``subdir`` inside ``clone_root``, rejecting path traversal.
+
+    Guards against ``..`` segments, absolute paths, and symlinks that would
+    escape the cloned repository. Returns the resolved directory path.
+    Raises ``PluginOperationError`` if the path escapes the clone, doesn't
+    exist, or is not a directory.
+    """
+    clone_root = clone_root.resolve()
+    candidate = (clone_root / subdir).resolve()
+
+    # The resolved candidate must stay within the clone root.
+    if candidate != clone_root and clone_root not in candidate.parents:
+        raise PluginOperationError(
+            f"Plugin subdirectory '{subdir}' escapes the repository.",
+        )
+
+    if not candidate.exists():
+        raise PluginOperationError(
+            f"Plugin subdirectory '{subdir}' does not exist in the repository.",
+        )
+    if not candidate.is_dir():
+        raise PluginOperationError(
+            f"Plugin subdirectory '{subdir}' is not a directory.",
+        )
+
+    return candidate
+
+
 def _repo_name_from_url(url: str) -> str:
     """Extract the repo name from a Git URL for the plugin directory name."""
     # Strip trailing .git and slashes
@@ -372,14 +454,14 @@ def _install_plugin_core(identifier: str, *, force: bool) -> tuple[Path, dict, s
     import tempfile
 
     try:
-        git_url = _resolve_git_url(identifier)
+        git_url, subdir = _resolve_git_url(identifier)
     except ValueError as e:
         raise PluginOperationError(str(e)) from e
 
     plugins_dir = _plugins_dir()
 
     with tempfile.TemporaryDirectory() as tmp:
-        tmp_target = Path(tmp) / "plugin"
+        tmp_clone = Path(tmp) / "plugin"
 
         git_exe = _resolve_git_executable()
         if not git_exe:
@@ -387,7 +469,7 @@ def _install_plugin_core(identifier: str, *, force: bool) -> tuple[Path, dict, s
 
         try:
             result = subprocess.run(
-                [git_exe, "clone", "--depth", "1", git_url, str(tmp_target)],
+                [git_exe, "clone", "--depth", "1", git_url, str(tmp_clone)],
                 capture_output=True,
                 text=True,
                 timeout=60,
@@ -405,8 +487,16 @@ def _install_plugin_core(identifier: str, *, force: bool) -> tuple[Path, dict, s
             err = (result.stderr or result.stdout or "").strip()
             raise PluginOperationError(f"Git clone failed:\n{err}")
 
+        # Resolve the directory within the clone that holds the plugin.
+        if subdir:
+            tmp_target = _resolve_subdir_within(tmp_clone, subdir)
+        else:
+            tmp_target = tmp_clone
+
         manifest = _read_manifest(tmp_target)
-        plugin_name = manifest.get("name") or _repo_name_from_url(git_url)
+        plugin_name = manifest.get("name") or (
+            subdir.rstrip("/").rsplit("/", 1)[-1] if subdir else _repo_name_from_url(git_url)
+        )
 
         try:
             target = _sanitize_plugin_name(plugin_name, plugins_dir)
@@ -471,7 +561,7 @@ def cmd_install(
     console = Console()
 
     try:
-        git_url = _resolve_git_url(identifier)
+        git_url, _subdir = _resolve_git_url(identifier)
     except ValueError as e:
         console.print(f"[red]Error:[/red] {e}")
         sys.exit(1)
@@ -482,7 +572,10 @@ def cmd_install(
             "Consider using https:// or git@ for production installs.",
         )
 
-    console.print(f"[dim]Cloning {git_url}...[/dim]")
+    if _subdir:
+        console.print(f"[dim]Cloning {git_url} (subdir: {_subdir})...[/dim]")
+    else:
+        console.print(f"[dim]Cloning {git_url}...[/dim]")
 
     try:
         target, installed_manifest, installed_name = _install_plugin_core(
@@ -649,29 +742,62 @@ def _save_enabled_set(enabled: set) -> None:
     save_config(config)
 
 
+def _resolve_plugin_key(name: str) -> Optional[str]:
+    """Resolve a user-supplied plugin identifier to its canonical registry key.
+
+    Accepts either the bare manifest name (``nemo_relay``), the directory
+    name, or the full path-derived key (``observability/nemo_relay``) and
+    returns the canonical key the loader gates on (``manifest.key`` or, for a
+    flat plugin, the bare name). Returns ``None`` when no plugin matches.
+
+    This is the single normalization point so ``hermes plugins enable`` /
+    ``disable`` write the same key that ``PluginManager`` matches against —
+    nested category plugins (e.g. ``observability/nemo_relay``) included.
+    """
+    entries = _discover_all_plugins()
+    # 1. Exact match on canonical key or manifest name — always unambiguous.
+    for entry in entries:
+        # entry = (name, version, description, source, dir_path, key)
+        if name == entry[5] or name == entry[0]:
+            return entry[5]
+    # 2. Fall back to a bare leaf-name match (e.g. "nemo_relay" ->
+    #    "observability/nemo_relay"), but only when it resolves to exactly one
+    #    plugin so we never silently pick the wrong same-named nested plugin.
+    leaf_matches = [entry[5] for entry in entries if name == entry[5].split("/")[-1]]
+    if len(leaf_matches) == 1:
+        return leaf_matches[0]
+    return None
+
+
 def cmd_enable(name: str) -> None:
     """Add a plugin to the enabled allow-list (and remove it from disabled)."""
     from rich.console import Console
 
     console = Console()
-    # Discover the plugin — check installed (user) AND bundled.
-    if not _plugin_exists(name):
+    # Discover the plugin — check installed (user) AND bundled, including
+    # nested category plugins — and normalize to its canonical registry key.
+    key = _resolve_plugin_key(name)
+    if key is None:
         console.print(f"[red]Plugin '{name}' is not installed or bundled.[/red]")
         sys.exit(1)
 
     enabled = _get_enabled_set()
     disabled = _get_disabled_set()
 
-    if name in enabled and name not in disabled:
-        console.print(f"[dim]Plugin '{name}' is already enabled.[/dim]")
+    if key in enabled and key not in disabled:
+        console.print(f"[dim]Plugin '{key}' is already enabled.[/dim]")
         return
 
-    enabled.add(name)
-    disabled.discard(name)
+    enabled.add(key)
+    disabled.discard(key)
+    # Drop any legacy bare-name entry so the two don't drift out of sync.
+    bare = key.split("/")[-1]
+    if bare != key:
+        disabled.discard(bare)
     _save_enabled_set(enabled)
     _save_disabled_set(disabled)
     console.print(
-        f"[green]✓[/green] Plugin [bold]{name}[/bold] enabled. "
+        f"[green]✓[/green] Plugin [bold]{key}[/bold] enabled. "
         "Takes effect on next session."
     )
 
@@ -681,111 +807,129 @@ def cmd_disable(name: str) -> None:
     from rich.console import Console
 
     console = Console()
-    if not _plugin_exists(name):
+    key = _resolve_plugin_key(name)
+    if key is None:
         console.print(f"[red]Plugin '{name}' is not installed or bundled.[/red]")
         sys.exit(1)
 
     enabled = _get_enabled_set()
     disabled = _get_disabled_set()
 
-    if name not in enabled and name in disabled:
-        console.print(f"[dim]Plugin '{name}' is already disabled.[/dim]")
+    if key not in enabled and key in disabled:
+        console.print(f"[dim]Plugin '{key}' is already disabled.[/dim]")
         return
 
-    enabled.discard(name)
-    disabled.add(name)
+    enabled.discard(key)
+    # Drop any legacy bare-name entry from the allow-list too, so a stale
+    # bare name can't keep a nested plugin loading after an explicit disable.
+    bare = key.split("/")[-1]
+    if bare != key:
+        enabled.discard(bare)
+    disabled.add(key)
     _save_enabled_set(enabled)
     _save_disabled_set(disabled)
     console.print(
-        f"[yellow]\u2298[/yellow] Plugin [bold]{name}[/bold] disabled. "
+        f"[yellow]\u2298[/yellow] Plugin [bold]{key}[/bold] disabled. "
         "Takes effect on next session."
     )
 
 
 def _plugin_exists(name: str) -> bool:
-    """Return True if a plugin with *name* is installed (user) or bundled."""
-    # Installed: directory name or manifest name match in user plugins dir
-    user_dir = _plugins_dir()
-    if user_dir.is_dir():
-        if (user_dir / name).is_dir():
-            return True
-        for child in user_dir.iterdir():
-            if not child.is_dir():
-                continue
-            manifest = _read_manifest(child)
-            if manifest.get("name") == name:
-                return True
-    # Bundled: <repo>/plugins/<name>/ (or HERMES_BUNDLED_PLUGINS on Nix).
-    from hermes_cli.plugins import get_bundled_plugins_dir
-    repo_plugins = get_bundled_plugins_dir()
-    if repo_plugins.is_dir():
-        candidate = repo_plugins / name
-        if candidate.is_dir() and (
-            (candidate / "plugin.yaml").exists()
-            or (candidate / "plugin.yml").exists()
-        ):
-            return True
-    return False
+    """Return True if a plugin with *name* (bare name or key) exists."""
+    return _resolve_plugin_key(name) is not None
 
 
-def _discover_all_plugins() -> list:
-    """Return a list of (name, version, description, source, dir_path) for
-    every plugin the loader can see — user + bundled + project.
+def _read_manifest_info(d: Path, prefix: str):
+    """Read a plugin.yaml manifest and return (name, version, description, key).
 
-    Matches the ordering/dedup of ``PluginManager.discover_and_load``:
-    bundled first, then user, then project; user overrides bundled on
-    name collision.
+    Returns None if no manifest file exists.
     """
+    manifest_file = d / "plugin.yaml"
+    if not manifest_file.exists():
+        manifest_file = d / "plugin.yml"
+    if not manifest_file.exists():
+        return None
     try:
         import yaml
     except ImportError:
         yaml = None
+    name = d.name
+    version = ""
+    description = ""
+    if yaml:
+        try:
+            with open(manifest_file, encoding="utf-8") as f:
+                manifest = yaml.safe_load(f) or {}
+            name = manifest.get("name", d.name)
+            version = manifest.get("version", "")
+            description = manifest.get("description", "")
+        except Exception:
+            pass
+    key = f"{prefix}/{d.name}" if prefix else name
+    return name, version, description, key
 
-    seen: dict = {}  # name -> (name, version, description, source, path)
 
-    # Bundled (<repo>/plugins/<name>/), excluding memory/ and context_engine/
-    from hermes_cli.plugins import get_bundled_plugins_dir
-    repo_plugins = get_bundled_plugins_dir()
-    for base, source in ((repo_plugins, "bundled"), (_plugins_dir(), "user")):
-        if not base.is_dir():
+def _scan_level(
+    base: Path,
+    source: str,
+    skip_names: set,
+    prefix: str,
+    depth: int,
+    seen: dict,
+) -> None:
+    """Recursive directory scan matching PluginManager._scan_directory_level.
+
+    Populates *seen* with key -> (name, version, description, source, dir, key).
+    """
+    if not base.is_dir():
+        return
+    for d in sorted(base.iterdir()):
+        if not d.is_dir():
             continue
-        for d in sorted(base.iterdir()):
-            if not d.is_dir():
-                continue
-            if source == "bundled" and d.name in {"memory", "context_engine"}:
-                continue
-            manifest_file = d / "plugin.yaml"
-            if not manifest_file.exists():
-                manifest_file = d / "plugin.yml"
-            if not manifest_file.exists():
-                continue
-            name = d.name
-            version = ""
-            description = ""
-            if yaml:
-                try:
-                    with open(manifest_file, encoding="utf-8") as f:
-                        manifest = yaml.safe_load(f) or {}
-                    name = manifest.get("name", d.name)
-                    version = manifest.get("version", "")
-                    description = manifest.get("description", "")
-                except Exception:
-                    pass
-            # User plugins override bundled on name collision.
-            if name in seen and source == "bundled":
+        if depth == 0 and skip_names and d.name in skip_names:
+            continue
+        info = _read_manifest_info(d, prefix)
+        if info is not None:
+            name, version, description, key = info
+            if key in seen and source == "bundled":
                 continue
             src_label = source
             if source == "user" and (d / ".git").exists():
                 src_label = "git"
-            seen[name] = (name, version, description, src_label, d)
+            seen[key] = (name, version, description, src_label, d, key)
+            continue
+        if depth >= 1:
+            continue
+        sub_prefix = f"{prefix}/{d.name}" if prefix else d.name
+        _scan_level(d, source, set(), sub_prefix, depth + 1, seen)
+
+
+def _discover_all_plugins() -> list:
+    """Return a list of (name, version, description, source, dir_path, key) for
+    every plugin the loader can see — user + bundled + project.
+
+    Matches the ordering/dedup of ``PluginManager.discover_and_load``:
+    bundled first, then user, then project; user overrides bundled on
+    key collision.
+    """
+    seen: dict = {}  # key -> (name, version, description, source, path, key)
+
+    # Bundled (<repo>/plugins/<name>/), excluding memory/ and context_engine/
+    from hermes_cli.plugins import get_bundled_plugins_dir
+    repo_plugins = get_bundled_plugins_dir()
+    for base, source, skip in (
+        (repo_plugins, "bundled", {"memory", "context_engine"}),
+        (_plugins_dir(), "user", set()),
+    ):
+        _scan_level(base, source, skip, "", 0, seen)
     return list(seen.values())
 
 
-def _plugin_status(name: str, enabled: set, disabled: set) -> str:
-    """Return the user-facing activation state for a plugin name."""
-    if name in disabled:
+def _plugin_status(name: str, enabled: set, disabled: set, key: str = "") -> str:
+    """Return the user-facing activation state for a plugin name or key."""
+    if name in disabled or key in disabled:
         return "disabled"
-    if name in enabled:
+    if name in enabled or key in enabled:
         return "enabled"
     return "not enabled"
 
@@ -798,7 +942,7 @@ def _filter_plugin_entries(entries: list, args: Any, enabled: set, disabled: set
     if getattr(args, "enabled", False):
         filtered = [
             entry for entry in filtered
-            if _plugin_status(entry[0], enabled, disabled) == "enabled"
+            if _plugin_status(entry[0], enabled, disabled, key=entry[5]) == "enabled"
         ]
     return filtered
 
@@ -823,19 +967,19 @@ def cmd_list(args: Any | None = None) -> None:
         payload = [
             {
                 "name": name,
-                "status": _plugin_status(name, enabled, disabled),
+                "status": _plugin_status(name, enabled, disabled, key=key),
                 "version": str(version),
                 "description": description,
                 "source": source,
             }
-            for name, version, description, source, _dir in entries
+            for name, version, description, source, _dir, key in entries
         ]
         print(json.dumps(payload, indent=2))
         return
 
     if getattr(args, "plain", False):
-        for name, version, _description, source, _dir in entries:
-            status = _plugin_status(name, enabled, disabled)
+        for name, version, _description, source, _dir, key in entries:
+            status = _plugin_status(name, enabled, disabled, key=key)
             print(f"{status:12} {source:8} {str(version):8} {name}")
         return
 
@@ -850,8 +994,8 @@ def cmd_list(args: Any | None = None) -> None:
     table.add_column("Description")
     table.add_column("Source", style="dim")
 
-    for name, version, description, source, _dir in entries:
-        status_name = _plugin_status(name, enabled, disabled)
+    for name, version, description, source, _dir, key in entries:
+        status_name = _plugin_status(name, enabled, disabled, key=key)
         if status_name == "disabled":
             status = "[red]disabled[/red]"
         elif status_name == "enabled":
@@ -1051,14 +1195,14 @@ def cmd_toggle() -> None:
     plugin_labels = []
     plugin_selected = set()
 
-    for i, (name, _version, description, source, _d) in enumerate(entries):
+    for i, (name, _version, description, source, _d, key) in enumerate(entries):
         label = f"{name} \u2014 {description}" if description else name
         if source == "bundled":
             label = f"{label} [bundled]"
         plugin_names.append(name)
         plugin_labels.append(label)
         # Selected (enabled) when in enabled-set AND not in disabled-set
-        if name in enabled_set and name not in disabled_set:
+        if (name in enabled_set or key in enabled_set) and name not in disabled_set and key not in disabled_set:
             plugin_selected.add(i)
 
     # -- Provider categories --
@@ -1422,7 +1566,7 @@ def dashboard_install_plugin(
     """Non-interactive install for the web dashboard. Returns a JSON-serializable dict."""
     warnings: list[str] = []
     try:
-        git_url = _resolve_git_url(identifier)
+        git_url, _subdir = _resolve_git_url(identifier)
         if git_url.startswith(("http://", "file://")):
             warnings.append(
                 "Insecure URL scheme; prefer https:// or git@ for production installs.",
@@ -1641,7 +1785,7 @@ def _git_pull_plugin_dir(target: Path) -> tuple[bool, str]:
 def dashboard_remove_user_plugin(name: str) -> dict[str, Any]:
     """Delete a plugin tree under ``~/.hermes/plugins/`` only."""
     plugins_dir = _plugins_dir()
-    for n, _ver, _d, src, _path in _discover_all_plugins():
+    for n, _ver, _d, src, _path, _key in _discover_all_plugins():
         if n == name and src == "bundled":
             return {"ok": False, "error": "Bundled plugins cannot be removed from the dashboard."}
 

package/agent/hermes_cli/portal_cli.py

@@ -1,12 +1,21 @@
-"""``hermes portal`` — small CLI surface for Nous Portal users.
+"""``hermes portal`` — the human-readable entry point for Nous Portal.
+
+Running ``hermes portal`` with no subcommand performs the one-shot Portal
+onboarding: OAuth login, pick a Nous model, switch the inference provider to
+Nous, and offer to enable the Tool Gateway. It is the friendly alias for
+``hermes auth add nous --type oauth`` (which still works), is identical to
+``hermes setup --portal``, and runs the same Nous flow as the first-time quick
+setup.
 
 Subcommands:
-  status   Show Portal auth state + which Tool Gateway tools are routed.
+  (none)   Log in to Nous Portal + set it up (one-shot onboarding).
+  login    Explicit alias for the default one-shot onboarding.
+  info     Show Portal auth state + which Tool Gateway tools are routed.
   open     Open the Portal subscription page in the user's default browser.
   tools    List Tool Gateway tools and which are active in the current config.
 
 This command is intentionally minimal — it does not duplicate functionality
-already in ``hermes auth`` or ``hermes tools``. It's a discovery + status
+already in ``hermes auth`` or ``hermes tools``. It's the onboarding + discovery
 surface for the Portal subscription itself.
 """
 from __future__ import annotations
@@ -49,7 +58,7 @@ def _cmd_status(args) -> int:
     else:
         print(f"  Auth:    {color('not logged in', Colors.YELLOW)}")
         print(f"  Sign up: {SUBSCRIPTION_URL}")
-        print(f"  Login:   hermes auth add nous --type oauth")
+        print(f"  Login:   hermes portal")
 
     # Provider selection (independent of auth)
     model_cfg = config.get("model") if isinstance(config.get("model"), dict) else {}
@@ -134,7 +143,7 @@ def _cmd_tools(args) -> int:
     print(color("  ────────────────────", Colors.MAGENTA))
 
     if not features.nous_auth_present:
-        print(color("  Not logged into Nous Portal — sign in with `hermes auth add nous --type oauth`.", Colors.YELLOW))
+        print(color("  Not logged into Nous Portal — sign in with `hermes portal`.", Colors.YELLOW))
         print()
 
     label_width = max(len(label) for _, label, _ in catalog)
@@ -158,14 +167,37 @@ def _cmd_tools(args) -> int:
     return 0
 
 
+def _cmd_login(args) -> int:
+    """Run the one-shot Nous Portal onboarding (login + model + provider + tools).
+
+    This is the human-readable front door for `hermes auth add nous --type
+    oauth`. It reuses the exact wiring behind `hermes setup --portal` (which in
+    turn runs the same Nous flow as the first-time quick setup), so the
+    commands stay in lockstep: device-code login, pick a Nous model, switch the
+    inference provider to Nous, then offer the Tool Gateway opt-in.
+    """
+    from hermes_cli.setup import _run_portal_one_shot
+
+    config = load_config() or {}
+    try:
+        _run_portal_one_shot(config)
+    except (KeyboardInterrupt, EOFError):
+        print()
+        print("Portal setup cancelled.")
+        return 1
+    return 0
+
+
 def portal_command(args) -> int:
     """Top-level dispatch for `hermes portal <subcommand>`."""
     sub = getattr(args, "portal_command", None)
-    if sub in {None, ""}:
-        # Default to status — matches gh / kubectl conventions where the
-        # subcommand-less form gives a useful overview.
-        return _cmd_status(args)
-    if sub == "status":
+    if sub in {None, "", "login"}:
+        # Default to the one-shot onboarding — `hermes portal` is the
+        # human-readable alias for `hermes auth add nous --type oauth` /
+        # `hermes setup --portal`.
+        return _cmd_login(args)
+    if sub in {"info", "status"}:
+        # `status` kept as a back-compat alias for the prior default.
         return _cmd_status(args)
     if sub == "open":
         return _cmd_open(args)
@@ -180,19 +212,27 @@ def add_parser(subparsers) -> None:
     """Register `hermes portal` on the given argparse subparsers object."""
     portal_parser = subparsers.add_parser(
         "portal",
-        help="Nous Portal status, subscription, and Tool Gateway routing",
+        help="Set up Nous Portal (login, model pick, Tool Gateway); see also `portal info`",
         description=(
-            "Inspect Nous Portal auth, Tool Gateway routing, and open the "
-            "Portal subscription page. Subcommands: status (default), "
-            "open, tools."
+            "Run `hermes portal` with no subcommand to log in to Nous Portal "
+            "and set it up — pick a model, set Nous as your provider, and offer "
+            "the Tool Gateway (the human-readable alias for `hermes auth add "
+            "nous --type oauth`, identical to `hermes setup --portal`). "
+            "Subcommands: login (default), info, open, tools."
         ),
     )
     portal_sub = portal_parser.add_subparsers(dest="portal_command")
 
     portal_sub.add_parser(
-        "status",
-        help="Show Portal auth + Tool Gateway routing summary (default)",
+        "login",
+        help="Log in to Nous Portal + set it up (default; one-shot onboarding)",
+    )
+    portal_sub.add_parser(
+        "info",
+        help="Show Portal auth + Tool Gateway routing summary",
     )
+    # `status` retained as a hidden back-compat alias for `info`.
+    portal_sub.add_parser("status")
     portal_sub.add_parser(
         "open",
         help="Open the Portal subscription page in your default browser",