Add universal GitNexus skills for Cursor and Hermes.

Consolidate connect, graph, and search workflows with mobile endpoint defaults and shared installation docs. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-01 16:08:15 +02:00
parent fa48844fb3
commit 287c08ebfc
6 changed files with 428 additions and 35 deletions
@@ -1,29 +1,45 @@
-# Workspace skills (`/home/test-user/cursor/skills`)
+# Workspace skills (`$HOME/Pulpit/cursor/skills`)

 Wspólne skille dla **Cursor** i **Hermes** w ekosystemie agency-ai.

-## Skille
-
-| Skill | Wywołanie | Opis |
-|-------|-----------|------|
-| [gitnexus-search](gitnexus-search/SKILL.md) | `gitnexus-search <repo> <prompt...>` | Przeszukiwanie zdalnego GitNexus po nazwie repo |
-
-## Cursor
-
-Skills w tym katalogu nie są automatycznie widoczne w Cursor — utwórz symlink:
+Domyślna ścieżka:

 ```bash
+SKILLS_ROOT="${SKILLS_ROOT:-$HOME/Pulpit/cursor/skills}"
+```
+
+## Skille GitNexus
+
+| Skill | Wywołanie / trigger | Opis |
+|-------|---------------------|------|
+| [gitnexus-connect](gitnexus-connect/SKILL.md) | setup MCP, health check, problemy z połączeniem | Bootstrap połączenia z `gitnexus.mobile.agency-ai.dev` |
+| [gitnexus-graph](gitnexus-graph/SKILL.md) | architektura, zależności, impact, refaktoryzacja | Graph-first: `query` / `context` / `impact` przez MCP |
+| [gitnexus-search](gitnexus-search/SKILL.md) | `gitnexus-search <repo> <prompt...>` | Jawne wyszukiwanie po nazwie repo + prompt |
+
+## Endpointy
+
+| Zastosowanie | Zdalny (domyślny) | Lokalny (dev na hoście GitNexus) |
+|--------------|-------------------|-----------------------------------|
+| MCP | `https://gitnexus.mobile.agency-ai.dev/api/mcp` | `http://127.0.0.1:4747/api/mcp` |
+| REST API | `https://gitnexus.mobile.agency-ai.dev` | `http://127.0.0.1:4747` |
+| UI (opcjonalnie) | osobna subdomena → 4173 | `http://127.0.0.1:4173` |
+
+Szczegóły: [gitnexus-connect/reference.md](gitnexus-connect/reference.md).
+
+## Cursor — instalacja
+
+Symlinki do skilli (po sklonowaniu repo):
+
+```bash
+SKILLS_ROOT="$HOME/Pulpit/cursor/skills"
 mkdir -p ~/.cursor/skills
-ln -sfn /home/test-user/cursor/skills/gitnexus-search ~/.cursor/skills/gitnexus-search
+
+ln -sfn "$SKILLS_ROOT/gitnexus-connect" ~/.cursor/skills/gitnexus-connect
+ln -sfn "$SKILLS_ROOT/gitnexus-graph"    ~/.cursor/skills/gitnexus-graph
+ln -sfn "$SKILLS_ROOT/gitnexus-search"   ~/.cursor/skills/gitnexus-search
 ```

-Opcjonalnie cały katalog:
-
-```bash
-ln -sfn /home/test-user/cursor/skills ~/.cursor/skills-workspace
-```
-
-Wymagany MCP GitNexus w `~/.cursor/mcp.json`:
+MCP w `~/.cursor/mcp.json`:

 ```json
 {
@@ -35,28 +51,58 @@ Wymagany MCP GitNexus w `~/.cursor/mcp.json`:
 }
 ```

+Lokalnie (ten sam host co Docker): zamień URL na `http://127.0.0.1:4747/api/mcp`.
+
 Po symlinku: **Reload Window** + nowa sesja chatu.

-## Hermes (m3gan)
-
-W promptcie systemowym lub `INSTALL-AGENT.md` podaj ścieżkę bezwzględną do skilla:
-
-```text
-/home/test-user/cursor/skills/gitnexus-search/SKILL.md
-```
-
-Hermes używa REST (skrypt), gdy MCP niedostępny:
+Health check:

 ```bash
-python3 /home/test-user/cursor/skills/gitnexus-search/scripts/gitnexus-search.py \
+bash "$SKILLS_ROOT/gitnexus-connect/scripts/gitnexus-health.sh"
+```
+
+## Hermes — instalacja
+
+W promptcie systemowym lub `INSTALL-AGENT.md` podaj ścieżki do skilli:
+
+```text
+$SKILLS_ROOT/gitnexus-connect/SKILL.md
+$SKILLS_ROOT/gitnexus-graph/SKILL.md
+$SKILLS_ROOT/gitnexus-search/SKILL.md
+```
+
+Zmienne środowiskowe:
+
+```bash
+export GITNEXUS_SERVER_URL=https://gitnexus.mobile.agency-ai.dev
+export GITNEXUS_DEFAULT_REPO=one-gateway
+export SKILLS_ROOT="$HOME/Pulpit/cursor/skills"
+```
+
+Hermes używa MCP HTTP (ten sam URL co Cursor) lub REST fallback:
+
+```bash
+python3 "$SKILLS_ROOT/gitnexus-search/scripts/gitnexus-search.py" \
  one-gateway "deploy_runner"
 ```

 Więcej: [one-gateway/docs/hermes/GITNEXUS-CLIENT.md](../one-gateway/docs/hermes/GITNEXUS-CLIENT.md).

-## Przykład
+## Przykłady

 ```text
 gitnexus-search ai-lawyer-srvr routes_paperless admin
 gitnexus-search gateway gitnexus_workspace_dir
 ```
+
+## Extended documentation (one-gateway)
+
+Szczegółowa dokumentacja deployu i operatora — w repo `one-gateway`:
+
+- `coding-agent/31-gitnexus-deployment-report.md`
+- `coding-agent/33-gitnexus-m3gan-remote-client.md`
+- `coding-agent/34-gitnexus-npmplus-edge-setup.md`
+- `coding-agent/35-cursor-gitnexus-mcp-setup.md`
+- `coding-agent/36-gitnexus-repo-connection-guide.md`
+
+Canonical source skilli: **ten katalog** (`cursor/skills`). Kopia `one-gateway/.cursor/skills/gitnexus-graph-first` nie jest utrzymywana — używaj `gitnexus-graph` stąd.
@@ -0,0 +1,95 @@
+---
+name: gitnexus-connect
+description: >-
+  Konfiguruje połączenie z GitNexus (MCP dla Cursora, REST/MCP dla Hermesa).
+  Użyj przy setupie MCP, health checku, problemach z połączeniem,
+  lub gdy agent nie widzi serwera gitnexus.
+disable-model-invocation: true
+---
+
+# gitnexus-connect
+
+Bootstrap połączenia z GitNexus dla **Cursor** (MCP) i **Hermes** (MCP lub REST).
+
+## Domyślny endpoint (zdalny)
+
+```text
+https://gitnexus.mobile.agency-ai.dev/api/mcp
+```
+
+## Lokalny override (ten sam host co Docker one-gateway)
+
+```text
+http://127.0.0.1:4747/api/mcp
+```
+
+Ustaw `GITNEXUS_SERVER_URL=http://127.0.0.1:4747` gdy pracujesz lokalnie na hoście z kontenerem `one-gateway-gitnexus-server`.
+
+## Cursor — konfiguracja MCP
+
+Plik `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "gitnexus": {
+      "url": "https://gitnexus.mobile.agency-ai.dev/api/mcp"
+    }
+  }
+}
+```
+
+Lokalnie zamień URL na `http://127.0.0.1:4747/api/mcp`.
+
+Po zmianie: **Reload Window** → panel MCP → status `gitnexus` = **Connected**.
+
+## Hermes — zmienne środowiskowe
+
+```bash
+export GITNEXUS_SERVER_URL=https://gitnexus.mobile.agency-ai.dev
+export GITNEXUS_DEFAULT_REPO=one-gateway   # opcjonalnie
+```
+
+Hermes może używać MCP HTTP (ten sam URL co Cursor) lub REST fallback przez skrypt z `gitnexus-search`.
+
+## Procedura agenta
+
+1. Uruchom health check:
+
+```bash
+bash "$SKILLS_ROOT/gitnexus-connect/scripts/gitnexus-health.sh"
+```
+
+Domyślnie `SKILLS_ROOT=$HOME/Pulpit/cursor/skills`. Możesz też podać pełną ścieżkę.
+
+2. Sprawdź `GET /api/repos` — czy docelowe repo jest zaindeksowane (`stats.files > 0`).
+3. Cursor: Reload Window → MCP panel → `gitnexus` = Connected.
+4. Jeśli repo **brak na liście** — nie szukaj lokalnie. Operator musi zamontować repo na hoście GitNexus i wykonać `analyze` (szczegóły w [`reference.md`](reference.md)).
+
+## Szybki test ręczny
+
+```bash
+curl -fsS https://gitnexus.mobile.agency-ai.dev/api/health
+curl -fsS https://gitnexus.mobile.agency-ai.dev/api/repos
+```
+
+## Błędy
+
+| Sytuacja | Akcja |
+|----------|-------|
+| MCP Error / timeout | Sprawdź health; użyj REST przez `gitnexus-search.py` |
+| Repo nie na liście | Operator: `docker exec -w /workspace one-gateway-gitnexus-server gitnexus analyze /workspace` |
+| Port 4747 zajęty lokalnie | Nie uruchamiaj drugiego `gitnexus serve` — użyj istniejącego kontenera |
+| Brak auth na zdalnym URL | NPMplus Access List / Basic Auth (patrz `reference.md`) |
+
+## Powiązane skille
+
+| Skill | Kiedy |
+|-------|-------|
+| [`gitnexus-graph`](../gitnexus-graph/SKILL.md) | Architektura, zależności, impact — użyj MCP po połączeniu |
+| [`gitnexus-search`](../gitnexus-search/SKILL.md) | Jawne wyszukiwanie `repo + prompt`; REST fallback |
+
+## Referencja
+
+- Szczegóły URL, porty, bezpieczeństwo: [`reference.md`](reference.md)
+- Extended docs (one-gateway): `coding-agent/33–36*.md`
@@ -0,0 +1,112 @@
+# GitNexus — referencja połączeń
+
+## Endpointy
+
+| Zastosowanie | Zdalny (domyślny) | Lokalny (dev) |
+|--------------|-------------------|---------------|
+| REST API + MCP | `https://gitnexus.mobile.agency-ai.dev` | `http://127.0.0.1:4747` |
+| MCP HTTP | `…/api/mcp` | `http://127.0.0.1:4747/api/mcp` |
+| Health | `…/api/health` | `http://127.0.0.1:4747/api/health` |
+| Lista repo | `…/api/repos` | `http://127.0.0.1:4747/api/repos` |
+| UI (opcjonalnie) | osobna subdomena → port 4173 | `http://127.0.0.1:4173` |
+
+## Scenariusz 1 — lokalny host (Docker one-gateway)
+
+Kontener `one-gateway-gitnexus-server` nasłuchuje na `127.0.0.1:4747`.
+
+```bash
+curl -fsS http://127.0.0.1:4747/api/health
+curl -fsS http://127.0.0.1:4747/api/repos
+docker exec one-gateway-gitnexus-server gitnexus list
+```
+
+**Ważne:** przy działającym kontenerze **nie uruchamiaj** dodatkowego `gitnexus serve` na hoście — konflikt na porcie 4747.
+
+Cursor MCP lokalnie:
+
+```json
+{
+  "mcpServers": {
+    "gitnexus": {
+      "url": "http://127.0.0.1:4747/api/mcp"
+    }
+  }
+}
+```
+
+## Scenariusz 2 — zdalny agent (Cursor / Hermes na innym hoście)
+
+NPMplus forward: `gitnexus.mobile.agency-ai.dev` → `127.0.0.1:4747` (websockets ON, SSL).
+
+```bash
+curl -fsS https://gitnexus.mobile.agency-ai.dev/api/health
+curl -fsS https://gitnexus.mobile.agency-ai.dev/api/repos
+```
+
+MCP:
+
+```text
+https://gitnexus.mobile.agency-ai.dev/api/mcp
+```
+
+Zdalny agent może:
+
+- czytać listę repo
+- używać `query`, `context`, `impact`
+- korzystać z REST i MCP jako **read-only knowledge source**
+
+Zdalny agent **nie** dodaje automatycznie swojego lokalnego repo do indeksu hosta mobile.
+
+## Indeksowanie nowego repo
+
+Repo musi być **na hoście GitNexus** (zamontowane lub sklonowane), potem:
+
+```bash
+docker exec -w /workspace one-gateway-gitnexus-server gitnexus analyze /workspace
+```
+
+lub dla konkretnej ścieżki:
+
+```bash
+docker exec -w /data/gitnexus/repos/MOJE-REPO one-gateway-gitnexus-server \
+  gitnexus analyze /data/gitnexus/repos/MOJE-REPO
+```
+
+Jeśli repo nie ma w `GET /api/repos` — agent nie może go „podłączyć” zdalnie; operator musi zaindeksować na serwerze.
+
+## Zmienne środowiskowe
+
+| Zmienna | Domyślnie | Opis |
+|---------|-----------|------|
+| `GITNEXUS_SERVER_URL` | `https://gitnexus.mobile.agency-ai.dev` | Bazowy URL API (bez `/api/mcp`) |
+| `GITNEXUS_DEFAULT_REPO` | `one-gateway` | Repo sprawdzane przez `gitnexus-health.sh` |
+| `SKILLS_ROOT` | `$HOME/Pulpit/cursor/skills` | Katalog ze skillami (dla ścieżek w skryptach) |
+
+## Bezpieczeństwo
+
+GitNexus `serve` **nie ma własnego auth**. Przy wystawieniu `gitnexus.mobile.agency-ai.dev` zabezpiecz przez:
+
+- Access List w NPMplus
+- Basic Auth
+- VPN / prywatny routing
+
+Bez zabezpieczenia publicznie udostępniasz metadane repo, strukturę kodu i wyniki search/context/impact.
+
+## Troubleshooting
+
+| Problem | Rozwiązanie |
+|---------|-------------|
+| Timeout na zdalnym URL | Sprawdź NPMplus forward na 4747, websockets, SSL |
+| MCP Connected ale puste wyniki | `GET /api/repos` — czy `stats.files > 0`? |
+| Repo nie na liście | Operator: mount + `analyze` na hoście GitNexus |
+| Lokalny 4747 zajęty | `docker ps` — użyj kontenera, nie drugiego `serve` |
+| Hermes bez MCP | REST: `gitnexus-search/scripts/gitnexus-search.py` |
+
+## Extended documentation (one-gateway)
+
+- `coding-agent/31-gitnexus-deployment-report.md`
+- `coding-agent/33-gitnexus-m3gan-remote-client.md`
+- `coding-agent/34-gitnexus-npmplus-edge-setup.md`
+- `coding-agent/35-cursor-gitnexus-mcp-setup.md`
+- `coding-agent/36-gitnexus-repo-connection-guide.md`
+- `docs/hermes/GITNEXUS-CLIENT.md`
@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# GitNexus health check — Cursor, Hermes, operator.
+set -euo pipefail
+
+BASE="${GITNEXUS_SERVER_URL:-https://gitnexus.mobile.agency-ai.dev}"
+BASE="${BASE%/}"
+REPO="${GITNEXUS_DEFAULT_REPO:-one-gateway}"
+
+echo "=== GitNexus health ==="
+echo "Server: $BASE"
+echo
+
+echo "--- GET /api/health ---"
+HEALTH=$(curl -fsS "$BASE/api/health" 2>&1) || {
+  echo "FAIL: cannot reach $BASE/api/health"
+  echo "$HEALTH"
+  exit 1
+}
+echo "$HEALTH"
+echo
+
+echo "--- GET /api/repos ---"
+REPOS=$(curl -fsS "$BASE/api/repos" 2>&1) || {
+  echo "FAIL: cannot reach $BASE/api/repos"
+  echo "$REPOS"
+  exit 1
+}
+echo "$REPOS"
+echo
+
+if command -v python3 >/dev/null 2>&1; then
+  if echo "$REPOS" | python3 -c "
+import json, sys
+repos = json.load(sys.stdin)
+names = [r.get('name', '') for r in repos]
+target = sys.argv[1]
+sys.exit(0 if target in names else 1)
+" "$REPO" 2>/dev/null; then
+    echo "OK: repo '$REPO' is indexed"
+  else
+    echo "WARN: repo '$REPO' not found in index (check analyze on server)"
+    exit 1
+  fi
+else
+  if echo "$REPOS" | grep -q "\"name\":\"$REPO\"" || echo "$REPOS" | grep -q "\"name\": \"$REPO\""; then
+    echo "OK: repo '$REPO' appears in response"
+  else
+    echo "WARN: repo '$REPO' not found in response"
+    exit 1
+  fi
+fi
+
+echo
+echo "=== All checks passed ==="
@@ -0,0 +1,75 @@
+---
+name: gitnexus-graph
+description: >-
+  Preferuj GitNexus przy zrozumieniu architektury, zależności, impact analysis,
+  łańcuchów wywołań, przepływu danych lub refaktoryzacji cross-file.
+  Użyj gdy MCP gitnexus jest dostępny i zadanie zależy od relacji w kodzie.
+disable-model-invocation: true
+---
+
+# gitnexus-graph
+
+Graph-first workflow dla **Cursor** (MCP) i **Hermes** (MCP lub REST fallback).
+
+## Kiedy używać GitNexus
+
+- MCP `gitnexus` jest Connected (lub REST działa — patrz `gitnexus-connect`)
+- użytkownik pyta o architekturę
+- zadanie zależy od zależności lub powiązanych plików
+- potrzebujesz impact analysis przed refaktoryzacją
+- śledzisz łańcuch wywołań lub przepływ danych
+- potrzebujesz kontekstu na poziomie symboli w wielu plikach
+
+## Kiedy NIE wymagać GitNexus
+
+- poprawka literówki
+- edycja jednego oczywistego pliku
+- mechaniczny rename lub formatowanie
+- proste „gdzie jest X?” gdy `rg` wystarczy
+
+## Startup checklist
+
+1. Jeśli brak połączenia — najpierw [`gitnexus-connect`](../gitnexus-connect/SKILL.md)
+2. `list_repos` — potwierdź, że docelowe repo jest zaindeksowane (`stats.files > 0`)
+3. Pytanie o symbol → `context` najpierw
+4. Przed refaktoryzacją → `impact`
+5. Eksploracja otwarta → `query`
+
+## Narzędzia MCP
+
+| Narzędzie | Zastosowanie |
+|-----------|--------------|
+| `list_repos` | Lista zaindeksowanych repo |
+| `query` | Semantyczne wyszukiwanie w grafie |
+| `context` | Kontekst wokół symbolu lub pliku |
+| `impact` | Wpływ zmiany na resztę kodu |
+
+Przy wielu repo podawaj `repo` explicite (nazwa lub ścieżka bezwzględna z indeksu).
+
+## Default workflow
+
+1. Oceń, czy zadanie jest relationship-heavy czy proste/lokalne.
+2. Jeśli relationship-heavy i MCP dostępny — GitNexus najpierw.
+3. Po wynikach grafu czytaj tylko najbardziej relevantne pliki lokalnie.
+4. Fallback na `rg` / Read / SemanticSearch gdy GitNexus niedostępny lub niekompletny.
+
+## Fallback
+
+| MCP niedostępny | Akcja |
+|-----------------|-------|
+| Cursor | `gitnexus-connect` → napraw MCP; lub `gitnexus-search` (REST) |
+| Hermes | REST: `gitnexus-search/scripts/gitnexus-search.py` |
+| Ogólnie | `rg`, Read, SemanticSearch |
+
+## Przykładowe prompty
+
+- „Jak działa ten moduł?”
+- „Które pliki są powiązane z `gitnexus_workspace_dir`?”
+- „Co może się zepsuć, jeśli zmienię `deploy_runner.py`?”
+- „Pokaż impact zmiany ścieżki instalatora.”
+
+## Powiązane
+
+- Setup: [`gitnexus-connect`](../gitnexus-connect/SKILL.md)
+- Jawne wyszukiwanie: [`gitnexus-search`](../gitnexus-search/SKILL.md)
+- Extended docs: `one-gateway/coding-agent/35-cursor-gitnexus-mcp-setup.md`
@@ -11,6 +11,15 @@ disable-model-invocation: true

 Jawne wyszukiwanie w zdalnym GitNexus (`https://gitnexus.mobile.agency-ai.dev`). Działa w **Cursor** (MCP) i **Hermes** (REST).

+**Przed pierwszym użyciem:** jeśli brak połączenia lub MCP Error — przeczytaj [`gitnexus-connect`](../gitnexus-connect/SKILL.md).
+
+## Ścieżki
+
+```bash
+SKILLS_ROOT="${SKILLS_ROOT:-$HOME/Pulpit/cursor/skills}"
+SEARCH_SCRIPT="$SKILLS_ROOT/gitnexus-search/scripts/gitnexus-search.py"
+```
+
 ## Format wejścia

 ```text
@@ -53,11 +62,11 @@ Gdy MCP `gitnexus` jest Connected:
 Gdy MCP niedostępny — **od razu** REST, bez pytania użytkownika:

 ```bash
-python3 /home/test-user/cursor/skills/gitnexus-search/scripts/gitnexus-search.py \
+python3 "$SKILLS_ROOT/gitnexus-search/scripts/gitnexus-search.py" \
  <repo> "<prompt>"
 ```

-Opcjonalnie: `--limit N`, `--json`.
+Opcjonalnie: `--limit N`, `--json`, `--server URL`.

 ## Format odpowiedzi

@@ -71,12 +80,14 @@ Opcjonalnie: `--limit N`, `--json`.
 | Sytuacja | Akcja |
 |----------|-------|
 | Repo nieznane | Lista z `/api/repos` |
-| Indeks pusty (`files: 0`) | Wskazówka: re-index (`gitnexus-index-remote.py` w projekcie) |
+| Indeks pusty (`files: 0`) | Operator: re-index na hoście GitNexus (`gitnexus-connect/reference.md`) |
 | MCP Error / brak narzędzi | REST przez `gitnexus-search.py` |
-| HTTP / timeout | `curl -fsS $GITNEXUS_SERVER_URL/api/health` |
+| HTTP / timeout | `bash "$SKILLS_ROOT/gitnexus-connect/scripts/gitnexus-health.sh"` |

 ## Powiązane

+- Setup: [`gitnexus-connect`](../gitnexus-connect/SKILL.md)
+- Graph workflow: [`gitnexus-graph`](../gitnexus-graph/SKILL.md)
 - Skrypt: [`scripts/gitnexus-search.py`](scripts/gitnexus-search.py)
- Hermes: [`one-gateway/docs/hermes/GITNEXUS-CLIENT.md`](../../one-gateway/docs/hermes/GITNEXUS-CLIENT.md)
- Workspace skills: [`../README.md`](../README.md)
+- Hermes: `one-gateway/docs/hermes/GITNEXUS-CLIENT.md`
+- Indeks skilli: [`../README.md`](../README.md)