graph-agents-cli 0.3.1__py3-none-any.whl

graph_agents_cli/secrets/_required.py

@@ -0,0 +1,188 @@
+# Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Which allow-listed Secret keys an environment cannot run without.
+
+A missing key only shows up once the pods start: a crash loop (no provider key,
+no database URI) or every request answered 503 (no ``API_KEY`` under
+``shared-bearer``). Outside dev the chart requires the Secret itself
+(``secretOptional: false``), so a missing Secret keeps the pods from starting,
+but it cannot tell which keys the Secret holds.
+``deploy`` checks the live Secret against this list before ``helm upgrade``,
+and ``secrets status`` exits 1 only when one of these is missing, so both work
+as gates while optional keys (judge key, LangSmith key, API tokens) stay
+optional.
+
+The list follows the environment's merged chart values, the same inputs the pod
+gets: ``env.MODEL_PROVIDER`` (the manifest's provider when unset) needs its
+key, except ``openai-compatible`` servers (often keyless on-network) and the
+``fake`` test model; ``env.AUTH_POLICY`` ``shared-bearer`` needs ``API_KEY``;
+the database and Redis URIs are needed unless the bundled subchart provides
+them (``postgresql.enabled`` / ``redis.enabled``) or ``env.CHECKPOINTER`` is
+``memory``. A key set as a plain chart ``env`` value does not need the Secret.
+Only keys in the manifest's ``secrets.keys`` are ever required; removing one
+from the allow-list is how a deployment opts out.
+
+One key joins the allow-list without being listed there: ``AUTH_JWT_SECRET``,
+the shared secret of the ``jwt`` policy's HS* algorithms. A project opts into
+HS* with ``AUTH_JWT_ALLOW_HS=true`` / ``AUTH_JWT_ALGORITHMS=HS256`` in the
+environment's chart values or its env file; the secret itself must then reach
+the pods through the Secret (never the ConfigMap). It is required when the
+chart values list an HS* algorithm: the pod refuses to start without it.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Mapping
+from typing import Any
+
+from graph_agents_cli._defaults import PROVIDER_KEY_VARS, normalize_auth_policy
+from graph_agents_cli._output import Console
+from graph_agents_cli.deploy._config import DeploySettings
+
+# Providers whose key is optional: on-network OpenAI-compatible servers are often
+# keyless, and the fake model needs none.
+KEYLESS_PROVIDERS = frozenset({"openai-compatible", "fake"})
+
+JWT_SECRET_KEY = "AUTH_JWT_SECRET"
+# The HS* settings the app reads (see the template's app/app_utils/auth.py).
+JWT_HS_SETTINGS = ("AUTH_JWT_ALLOW_HS", "AUTH_JWT_ALGORITHMS")
+_HMAC_ALGORITHMS = frozenset({"HS256", "HS384", "HS512"})
+_TRUE = ("1", "true", "yes", "on")
+
+
+def _env_value(values: dict[str, Any], key: str) -> str:
+    env = values.get("env") if isinstance(values.get("env"), dict) else {}
+    value = env.get(key)
+    return "" if value is None else str(value).strip()
+
+
+def _auth_policy(settings: DeploySettings, values: dict[str, Any]) -> str:
+    return normalize_auth_policy(
+        _env_value(values, "AUTH_POLICY") or settings.auth_policy, warn=False
+    )
+
+
+def _lists_hmac(algorithms: str) -> bool:
+    return any(a.strip().upper() in _HMAC_ALGORITHMS for a in algorithms.split(","))
+
+
+def _hs_settings(source: Mapping[str, Any]) -> tuple[bool, bool]:
+    """``(allow_hs, lists_hs)`` read from one source of settings."""
+    allow = str(source.get("AUTH_JWT_ALLOW_HS") or "").strip().lower() in _TRUE
+    return allow, _lists_hmac(str(source.get("AUTH_JWT_ALGORITHMS") or ""))
+
+
+def jwt_hs_in_values(settings: DeploySettings, values: dict[str, Any]) -> bool:
+    """The chart values run the ``jwt`` policy with an HS* algorithm (the pod needs the secret)."""
+    env = values.get("env") if isinstance(values.get("env"), dict) else {}
+    return _auth_policy(settings, values) == "jwt" and _hs_settings(env)[1]
+
+
+def jwt_hs_indicated(
+    settings: DeploySettings, values: dict[str, Any], file_values: Mapping[str, str] | None = None
+) -> bool:
+    """HS* JWTs are opted into by the chart values or the env file (``jwt`` policy only)."""
+    if _auth_policy(settings, values) != "jwt":
+        return False
+    env = values.get("env") if isinstance(values.get("env"), dict) else {}
+    return any(any(_hs_settings(source)) for source in (env, file_values or {}))
+
+
+def for_environment(
+    settings: DeploySettings, values: dict[str, Any], file_values: Mapping[str, str] | None = None
+) -> DeploySettings:
+    """``settings`` whose allow-list also holds ``AUTH_JWT_SECRET`` when HS* JWTs are in use."""
+    if JWT_SECRET_KEY in settings.secret_keys or not jwt_hs_indicated(
+        settings, values, file_values
+    ):
+        return settings
+    return dataclasses.replace(settings, secret_keys=[*settings.secret_keys, JWT_SECRET_KEY])
+
+
+def _enabled(values: dict[str, Any], section: str) -> bool:
+    block = values.get(section) if isinstance(values.get(section), dict) else {}
+    value = block.get("enabled")
+    return value is True or (
+        isinstance(value, str) and value.strip().lower() in ("true", "yes", "1")
+    )
+
+
+def required_keys(settings: DeploySettings, values: dict[str, Any]) -> list[str]:
+    """Allow-listed keys the pods need from the Secret, in allow-list order."""
+    needed: set[str] = set()
+    provider = (_env_value(values, "MODEL_PROVIDER") or settings.model_provider).lower()
+    if provider not in KEYLESS_PROVIDERS:
+        needed.add(PROVIDER_KEY_VARS.get(provider, "MODEL_API_KEY"))
+    if _auth_policy(settings, values) == "shared-bearer":
+        needed.add("API_KEY")
+    if jwt_hs_in_values(settings, values):
+        needed.add(JWT_SECRET_KEY)
+    if settings.runtime == "langgraph-server":
+        if not _enabled(values, "postgresql"):
+            needed.add("DATABASE_URI")
+        if not _enabled(values, "redis"):
+            needed.add("REDIS_URI")
+    elif (
+        not _enabled(values, "postgresql")
+        and (_env_value(values, "CHECKPOINTER") or "postgres").lower() != "memory"
+    ):
+        needed.add("POSTGRES_DSN")
+    allowed = for_environment(settings, values).secret_keys
+    return [k for k in allowed if k in needed and not _env_value(values, k)]
+
+
+def optional_keys(settings: DeploySettings, values: dict[str, Any]) -> list[str]:
+    """The allow-listed keys that are not required, in allow-list order."""
+    required = set(required_keys(settings, values))
+    return [k for k in for_environment(settings, values).secret_keys if k not in required]
+
+
+def unreached_hs_settings(
+    settings: DeploySettings, values: dict[str, Any], file_values: Mapping[str, str]
+) -> list[str]:
+    """HS* settings the env file sets that never reach the pods.
+
+    Only allow-listed keys go from the env file into the Secret, and these are
+    plain settings that belong in the chart values' ``env`` (the ConfigMap).
+    """
+    if _auth_policy(settings, values) != "jwt":
+        return []
+    return [
+        key
+        for key in JWT_HS_SETTINGS
+        if str(file_values.get(key) or "").strip()
+        and key not in settings.secret_keys
+        and not _env_value(values, key)
+    ]
+
+
+def print_unreached_hs_settings(
+    settings: DeploySettings,
+    env: str,
+    values: dict[str, Any],
+    file_values: Mapping[str, str],
+    *,
+    source: object,
+    console: Console,
+) -> None:
+    """Warn that HS* settings in the env file stay local (see :func:`unreached_hs_settings`)."""
+    keys = unreached_hs_settings(settings, values, file_values)
+    if keys:
+        console.print(
+            f"  {', '.join(keys)} in {source} never reach the pods (only allow-listed keys go "
+            f"into the Secret); set them under env: in {settings.values_file(env)}.",
+            style="yellow",
+            markup=False,
+        )

graph_agents_cli/secrets/cmd_secrets.py

@@ -0,0 +1,211 @@
+# Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""graph-agents-cli secrets commands — provision and inspect the app Secret."""
+
+from __future__ import annotations
+
+import click
+
+from graph_agents_cli._click import LazyGroup
+from graph_agents_cli._output import Console
+from graph_agents_cli.deploy import _modes, _preflight
+from graph_agents_cli.deploy._config import DeploySettings, load_settings
+from graph_agents_cli.deploy._kube import Target
+from graph_agents_cli.deploy._values import load_chart_values
+from graph_agents_cli.secrets import _apply, _required
+
+
+@click.group("secrets", cls=LazyGroup)
+def secrets_group() -> None:
+    """Provision and inspect the application Secret per environment.
+
+    \b
+    Subcommands:
+      apply   Create or update <name>-app from the allow-listed keys of an env file
+      status  List which allow-listed keys are present (values are never printed)
+    """
+
+
+def _resolve(
+    settings: DeploySettings, env: str, context: str | None
+) -> tuple[_modes.ResolvedContext, Target]:
+    namespace = settings.target(env).namespace
+    resolved = _modes.resolve(settings, env, context)
+    return resolved, Target(context=resolved.name, namespace=namespace)
+
+
+_CONTEXT_HELP = "Kube context to use instead of environments.<env>.context."
+
+
+def _default_env_file_values(env: str) -> dict[str, str]:
+    """The env file ``secrets apply --env <env>`` reads by default (empty when absent or unreadable)."""
+    path = _apply.resolve_env_file(env, None)
+    if path is None:
+        return {}
+    try:
+        return _apply.read_env_file(path)
+    except (OSError, UnicodeDecodeError):
+        return {}
+
+
+@secrets_group.command("apply")
+@click.option("--env", "env", required=True, help="Target environment (dev, staging, prod).")
+@click.option(
+    "--env-file",
+    "env_file",
+    default=None,
+    help="Env file; defaults to .env.<env> (dev also falls back to .env).",
+)
+@click.option("--context", "context", default=None, help=_CONTEXT_HELP)
+@click.option(
+    "--yes",
+    "-y",
+    "yes",
+    is_flag=True,
+    help="Accept the kubeconfig's current context outside dev without prompting.",
+)
+@click.option(
+    "--rotate-api-key",
+    "rotate_api_key",
+    is_flag=True,
+    help="Replace the live API_KEY with the one in the env file (otherwise the live key wins).",
+)
+@click.option(
+    "--dry-run", "dry_run", is_flag=True, help="Print the kubectl pipeline and a redacted manifest."
+)
+def cmd_secrets_apply(
+    env: str,
+    env_file: str | None,
+    context: str | None,
+    yes: bool,
+    rotate_api_key: bool,
+    dry_run: bool,
+) -> None:
+    """Create or update the app Secret from the allow-listed keys of an env file."""
+    console = Console()
+    settings = load_settings()
+    resolved, target = _resolve(settings, env, context)
+    path = _apply.resolve_env_file(env, env_file)
+    chart_values = load_chart_values(settings.chart_dir, env)
+    if path is None:
+        raise _apply.missing_env_file_error(
+            env, _required.for_environment(settings, chart_values).secret_keys
+        )
+    values = _apply.read_env_file(path)
+    # The allow-list for this environment (AUTH_JWT_SECRET joins it for HS* JWTs).
+    settings = _required.for_environment(settings, chart_values, values)
+    _apply.check_file_values(
+        values, settings.secret_keys, rotate_api_key=rotate_api_key, source=path
+    )
+    console.print(f"Secret {settings.secret_name} in {target.namespace} from {path}")
+    _modes.announce(env, resolved, console=console)
+    _modes.confirm(
+        env, resolved, yes=yes, dry_run=dry_run, console=console, action="apply the Secret for"
+    )
+    _required.print_unreached_hs_settings(
+        settings, env, chart_values, values, source=path, console=console
+    )
+    plan = _apply.provision(
+        name=settings.secret_name,
+        env=env,
+        target=target,
+        allowed=settings.secret_keys,
+        path=path,
+        values=values,
+        rotate_api_key=rotate_api_key,
+        dry_run=dry_run,
+        console=console,
+        # Only the shared-bearer policy reads API_KEY: never mint one it would not use.
+        mint_api_key=_preflight.effective_auth_policy(settings, chart_values) == "shared-bearer",
+        metrics_name=settings.metrics_secret_name,
+    )
+    if not _modes.is_dev_env(env):
+        for key in _preflight.dsn_keys(settings, chart_values):
+            dsn = plan.data.get(key) or ""
+            if (
+                dsn
+                and dsn != _apply.PENDING_PLACEHOLDER
+                and _preflight.dsn_without_tls(chart_values, dsn)
+            ):
+                console.print(
+                    f"  Warning: {_preflight.dsn_tls_warning(key)}", style="yellow", markup=False
+                )
+
+
+@secrets_group.command("status")
+@click.option("--env", "env", required=True, help="Target environment (dev, staging, prod).")
+@click.option("--context", "context", default=None, help=_CONTEXT_HELP)
+@click.option(
+    "--strict",
+    "strict",
+    is_flag=True,
+    help="Also exit 1 when an optional allow-listed key is missing.",
+)
+@click.option(
+    "--dry-run", "dry_run", is_flag=True, help="Print the kubectl command without running it."
+)
+def cmd_secrets_status(env: str, context: str | None, strict: bool, dry_run: bool) -> None:
+    """List which allow-listed keys are present in the app Secret (never values).
+
+    \b
+    Exit codes (usable as a CI or pre-deploy gate):
+      0  the Secret holds every required key (optional ones may be missing)
+      1  the Secret is missing, or a required key is (any key with --strict)
+      2  kubectl failed (unreachable cluster, credentials, RBAC)
+      3  configuration error (unknown environment or kube context, no manifest)
+    Required keys follow the environment's chart values: the model provider's key
+    (not for openai-compatible), API_KEY under shared-bearer, AUTH_JWT_SECRET under
+    jwt with an HS* algorithm, and POSTGRES_DSN or DATABASE_URI/REDIS_URI unless the
+    bundled subchart provides them.
+    """
+    console = Console()
+    settings = load_settings()
+    resolved, target = _resolve(settings, env, context)
+    _modes.announce(env, resolved, console=console)
+    _modes.require_known_context(env, resolved, dry_run=dry_run, console=console)
+    values = load_chart_values(settings.chart_dir, env)
+    # The env file `secrets apply` would read (never printed) tells whether the
+    # environment uses HS* JWTs, which adds AUTH_JWT_SECRET to the allow-list.
+    settings = _required.for_environment(settings, values, _default_env_file_values(env))
+    required = _required.required_keys(settings, values)
+    optional = [k for k in settings.secret_keys if k not in required]
+    present = _apply.secret_keys_present(
+        settings.secret_name, target, dry_run=dry_run, console=console
+    )
+    if dry_run:
+        return
+    if present is None:
+        console.print(
+            f"Secret {settings.secret_name} not found in namespace {target.namespace}.", style="red"
+        )
+        console.print("  Missing: " + ", ".join(settings.secret_keys))
+        raise SystemExit(1)
+    missing_required = [k for k in required if k not in present]
+    missing_optional = [k for k in optional if k not in present]
+    found = [k for k in settings.secret_keys if k in present]
+    extra = sorted(present - set(settings.secret_keys))
+    console.print(f"Secret {settings.secret_name} in {target.namespace}:")
+    console.print("  present: " + (", ".join(found) or "(none)"), style="green")
+    console.print(
+        "  missing required: " + (", ".join(missing_required) or "(none)"),
+        style="red" if missing_required else "green",
+    )
+    console.print(
+        "  missing optional: " + (", ".join(missing_optional) or "(none)"),
+        style="yellow" if missing_optional else "green",
+    )
+    if extra:
+        console.print("  not in the allow-list: " + ", ".join(extra), style="dim")
+    if missing_required or (strict and missing_optional):
+        raise SystemExit(1)

graph_agents_cli/setup/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

graph_agents_cli/setup/_antigravity.py

@@ -0,0 +1,221 @@
+# Copyright 2026 Google LLC
+# Modifications Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Mirror globally-installed skills into Antigravity's skill directories.
+
+Temporary workaround until `npx skills` fully supports Antigravity's IDE / CLI /
+2.0 skill paths. Today `npx skills ... -g` installs global skills into the
+canonical ``~/.agents/skills`` store, but Antigravity does not read from there:
+the IDE and Antigravity 2.0 read ``~/.gemini/config/skills`` and the Antigravity
+CLI reads ``~/.gemini/antigravity-cli/skills``. This module bridges that gap by
+linking each canonical skill into both locations so a global ``graph-agents-cli setup``
+makes the skills visible to Antigravity. Once upstream installs to the correct
+locations directly, this module can be removed.
+
+Both locations are mirrored ourselves rather than relying on ``npx skills``,
+whose global install is currently unreliable (vercel-labs/skills#1362).
+
+Links are directory symlinks, falling back to directory junctions on Windows
+(which work without elevation). Links auto-track the canonical store, so updates
+to a skill are seen by Antigravity with no re-link needed.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+# Canonical store that ``npx skills ... -g`` writes to.
+_CANONICAL_SUBPATH = (".agents", "skills")
+
+# Where Antigravity looks for global skills: IDE / 2.0 first, then the CLI.
+_ANTIGRAVITY_SUBPATHS = (
+    (".gemini", "config", "skills"),
+    (".gemini", "antigravity-cli", "skills"),
+)
+
+
+def _display(path: Path, home: Path) -> str:
+    """Render ``path`` with the home directory collapsed to ``~`` for output."""
+    try:
+        return f"~/{path.relative_to(home)}"
+    except ValueError:
+        return str(path)
+
+
+def _is_link(path: Path) -> bool:
+    """Return True if ``path`` is a symlink or a Windows directory junction.
+
+    ``Path.is_symlink()`` does not report junctions, so fall back to
+    ``os.readlink``, which succeeds for both and raises for real directories.
+    """
+    if path.is_symlink():
+        return True
+    try:
+        os.readlink(path)
+        return True
+    except OSError:
+        return False
+
+
+def _link_target_into(entry: Path, source_root: Path) -> bool:
+    """Return True if the link at ``entry`` points somewhere under ``source_root``."""
+    try:
+        target_str = os.readlink(entry)
+        # Windows-specific path prefix handling:
+        # - "\??\" is the NT Object Manager namespace prefix, often returned by
+        #   os.readlink for Windows junctions.
+        # - "\\?\" is the Win32 device namespace prefix, used for long paths.
+        # Python's pathlib.Path does not recognize these prefixes as absolute roots
+        # (e.g., Path("\??\C:\foo").is_absolute() may return False or behave incorrectly),
+        # so we strip the 4-character prefix to get a standard absolute path.
+        if target_str.startswith("\\??\\"):
+            target_str = target_str[4:]
+        elif target_str.startswith("\\\\?\\"):
+            target_str = target_str[4:]
+        target = Path(target_str)
+    except OSError:
+        return False
+    if not target.is_absolute():
+        target = entry.parent / target
+    try:
+        resolved_parent = target.parent.resolve()
+        resolved_source = source_root.resolve()
+        return resolved_source == resolved_parent or resolved_source in resolved_parent.parents
+    except OSError:
+        return False
+
+
+def _link_dir(source: Path, link: Path) -> bool:
+    """Point ``link`` at ``source`` with a directory link (junction on Windows).
+
+    Idempotent: a link already resolving to ``source`` is left as-is. A stale or
+    mis-pointing link is replaced, but a real (non-link) file or directory is left
+    untouched and reported as a failure so user data is never clobbered.
+    """
+    try:
+        if link.exists() and os.path.realpath(link) == os.path.realpath(source):
+            return True
+    except OSError:
+        pass
+
+    if _is_link(link):
+        try:
+            link.unlink()
+        except OSError:
+            pass
+    elif link.exists():
+        return False
+
+    link.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        os.symlink(source, link, target_is_directory=True)
+        return True
+    except (OSError, NotImplementedError):
+        pass
+
+    # Windows without symlink privilege: a junction works without elevation.
+    if os.name == "nt":
+        import subprocess
+
+        from graph_agents_cli._runner import run_resolved
+
+        try:
+            run_resolved(
+                ["cmd", "/c", "mklink", "/J", str(link), str(source)],
+                resolve_executable=False,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            return True
+        except (OSError, subprocess.CalledProcessError):
+            pass
+
+    logging.warning(
+        "Could not link skill '%s' into %s "
+        "(on Windows, enable Developer Mode or run as administrator).",
+        source.name,
+        link.parent,
+    )
+    return False
+
+
+def _prune_dead_links(target_root: Path, source_root: Path) -> None:
+    """Remove broken links under ``target_root`` that point into ``source_root``.
+
+    Keeps the mirror in sync when a skill is removed from the canonical store.
+    Only ever removes links (symlinks/junctions), never real files or directories.
+    """
+    if not target_root.is_dir():
+        return
+    for entry in target_root.iterdir():
+        if entry.exists() or not _link_target_into(entry, source_root):
+            continue
+        try:
+            entry.unlink()
+        except OSError as e:
+            logging.warning("Could not remove stale skill link %s: %s", entry, e)
+
+
+def link_skills_for_antigravity(
+    *, home: Path | None = None, skills_dir: Path | None = None
+) -> list[str]:
+    """Link each canonical global skill into Antigravity's skill directories.
+
+    No-op (returns an empty list) when Antigravity/Gemini is not present
+    (no ``~/.gemini``) or when the canonical store is missing. Best-effort:
+    individual link failures are logged, never raised.
+
+    Returns a list of human-readable summary lines describing what was linked.
+    """
+    home = home or Path.home()
+
+    if not (home / ".gemini").is_dir():
+        return []
+
+    source_root = skills_dir or home.joinpath(*_CANONICAL_SUBPATH)
+    if not source_root.is_dir():
+        # This runs right after npx installs skills, so a missing canonical store
+        # means npx no longer writes there — surface it instead of silently
+        # no-op'ing (see module docstring).
+        logging.warning(
+            "Skills store %s not found; skills were not mirrored to Antigravity.",
+            source_root,
+        )
+        return []
+
+    skill_dirs = [
+        d for d in sorted(source_root.iterdir()) if d.is_dir() and (d / "SKILL.md").is_file()
+    ]
+    if not skill_dirs:
+        # Same expectation as above: npx just ran, so an empty store is surprising.
+        # Fall through so dead links from previously-linked skills still get pruned.
+        logging.warning("Skills store %s has no skills to mirror to Antigravity.", source_root)
+
+    summary: list[str] = []
+    for subpath in _ANTIGRAVITY_SUBPATHS:
+        target_root = home.joinpath(*subpath)
+        # Link each skill individually rather than pointing the whole target dir
+        # at the canonical store: ~/.gemini/.../skills is owned by Antigravity and
+        # may already hold skills from other sources. A top-level symlink would
+        # fail (dir exists) or shadow those; per-skill links coexist with them.
+        linked = sum(_link_dir(skill_dir, target_root / skill_dir.name) for skill_dir in skill_dirs)
+        _prune_dead_links(target_root, source_root)
+        if linked:
+            summary.append(f"Linked {linked} skill(s) into {_display(target_root, home)}")
+    return summary