@deerdesign/deertools 1.0.4 → 1.2.0

package/README.md

@@ -13,8 +13,17 @@ Log in once from your computer, and grant your AI coding agent (Antigravity, Cur
 | `deliveries` | `dostawy` | DeerTools Deliveries | `https://ship.deergroup.pl/` | Logistics, site delivery schedules, supplier shipments, tracking |
 | `supplier` | — | Supplier Hub | `https://supplier.deergroup.pl/` | Supplier orders, line items, claims, delivery status |
 | `rendermind` | — | RenderMind | `https://rendermind.deergroup.pl/` | pCon 3D render pipelines, AI image generation, floor plan proxies |
+| `skills` | `hub`, `skill` | DeerSkills Hub | `https://skills.deergroup.pl/` | AI Agent Skills & MCP registry, versioning, bundles & promotion workflow |
 
-*(Both English names like `catalog`, `estimate`, `deliveries` and legacy Polish names like `katalog`, `kosztorys`, `dostawy` are supported interchangeably).*
+*(Both English names like `catalog`, `estimate`, `deliveries`, `skills` and legacy Polish names like `katalog`, `kosztorys`, `dostawy`, `umiejetnosci` are supported interchangeably).*
+
+---
+
+## 📊 Prezentacja dla Zespołu IT
+
+Dedykowana prezentacja architektoniczna i wdrożeniowa dla zespołów deweloperskich i DevOps:
+- 🌐 **[Slajdy interaktywne HTML (Reveal.js)](./docs/prezentacja-it-deertools.html)** — uruchom w dowolnej przeglądarce (`Space` / strzałki do nawigacji, `Esc` do widoku miniatur kafelkowych, `Cmd+P` do druku/eksportu PDF).
+- 📝 **[Wersja tekstowa Markdown](./docs/prezentacja-it-deertools.md)** — do szybkiego czytania bezpośrednio w GitHubie.
 
 ---
 
@@ -57,11 +66,13 @@ deertools login estimate         # or: deertools login kosztorys
 deertools login deliveries       # or: deertools login dostawy
 deertools login supplier
 deertools login rendermind
+deertools login skills           # or: deertools login hub
 
 # Request read + write scopes:
 deertools login catalog --write
+deertools login skills --write
 
-# Interactive login across all 5 products sequentially:
+# Interactive login across all 6 products sequentially:
 deertools login all
 
 # Check current authentication status and expiration:
@@ -116,26 +127,132 @@ deertools api rendermind POST /api/v1/visualizations --data '{"prompt":"Modern S
 deertools api rendermind POST /api/v1/visualizations --data-file request.json
 ```
 
-### 3. Specialized Helpers
+### 3. Specialized Helpers & Domain Commands
+
+DeerTools CLI provides first-class domain commands with colored table outputs and JSON flags:
 
 ```bash
-# Analyze architectural floor plan PDF and calculate cost estimate (Estimate / Kosztorys):
+# 1. Environment & API Doctor:
+deertools doctor
+deertools doctor --json
+
+# 2. Shell Autocompletion (Zsh, Bash, Fish):
+deertools completion install      # automatically configures ~/.zshrc or ~/.bashrc
+
+# 3. Catalog (Material Specs & Products):
+deertools catalog search "bateria nero" --package modern-life --limit 10
+deertools catalog get <sku_or_uuid>
+deertools catalog categories
+deertools catalog manufacturers
+
+# 4. Deliveries (Logistics & Shipments):
+deertools deliveries list --status active
+deertools deliveries track <tracking_number>
+deertools deliveries suppliers
+
+# 5. Estimate (Cost Calculations & Floor Plan AI):
+deertools estimate calculate 64.5 modern_life
+deertools estimate margins 64.5
 deertools estimate --file floorplan.pdf --kitchen 6
 
-# Auto-detect installed AI agents (Antigravity, Claude, Codex, Hermes, Cursor) and install skills:
-deertools skill install catalog
-deertools skill install all
+# 6. Supplier Hub (Discounts & Price Chains):
+deertools supplier discounts Flügger --postal_code 00-001
+deertools supplier markups warszawa
+deertools supplier calculate 1000 --discount 35 --markup 25
+
+# 7. RenderMind (Interior Styles & Presets):
+deertools rendermind styles
+
+# 8. BaseLinker Hub & MCP Proxy:
+deertools baselinker auth <X-BLToken>           # Zapisz token w credentials.json
+deertools baselinker test                       # Sprawdź połączenie i listę katalogów
+deertools baselinker serve --port 3456          # Uruchom lokalny dashboard Web UI + MCP SSE
+deertools baselinker mcp                        # Mostek MCP stdio (Cursor / Claude Desktop)
+deertools baselinker sync-schema                # Pobierz 204 metod z api.baselinker.com
+deertools baselinker search "relations"         # Wyszukaj metody i schematy parametrów
+deertools baselinker call getOrders             # Bezpośrednie wywołanie API z terminala
+deertools baselinker catalog search 105 "dąb"   # Wyszukaj produkty w katalogu BaseLinkera
+
+# 9. Local Stdio MCP Bridge (for Claude Desktop, Ollama, local LLM tools):
+deertools mcp serve
+
+# 10. Audit Log:
+deertools audit --limit 25
+deertools audit --clear
+
+# 11. Multi-Profile Management:
+deertools profile list
+deertools profile use staging
+
+# 12. AI Agent Skills (DeerSkills Hub):
+deertools skill list                         # Wyświetl skille (oficjalne globalne i Twoje)
+deertools skill search "kosztorys"           # Wyszukaj skille po nazwie, tagu lub opisie
+deertools skill install deer-kosztorys       # Zainstaluj skill w ~/.gemini/antigravity/skills lub .agents
+deertools skill install deer-kosztorys --version 1.0.0
+deertools skill install all                  # Zainstaluj wszystkie oficjalne skille Deer Design
+deertools skill push ./my-skill              # Opublikuj nową wersję z automatycznym skanerem sekretów
+deertools skill push ./my-skill --bump minor # Automatyczne podbicie wersji SemVer
+deertools skill update deer-kosztorys        # Zaktualizuj zainstalowany skill do najnowszej wersji
+deertools skill update                       # Zaktualizuj wszystkie zainstalowane skille
+deertools skill promote my-skill             # Zgłoś wniosek do admina o nominację do globalnego katalogu
+
+# 13. AI Agent MCP Registry & Configuration:
+deertools mcp list                           # Lista dostępnych serwerów MCP w ekosystemie
+deertools mcp config                         # Wygeneruj konfigurację JSON dla Cursor, Claude, Antigravity
+deertools mcp install                        # Automatycznie dopisz konfigurację do narzędzi AI
+```
 
-# Install for a specific agent platform:
-deertools skill install all --agent claude        # ~/.claude/skills/
-deertools skill install all --agent codex         # ~/.codex/skills/
-deertools skill install all --agent hermes        # ~/.hermes/skills/
-deertools skill install all --agent cursor        # .cursor/rules/*.mdc
-deertools skill install all --agent antigravity   # ~/.gemini/config/skills/
+---
 
-# Force install across all supported platforms simultaneously:
-deertools skill install all --all-agents
-```
+## BaseLinker MCP Proxy & Catalog Management
+
+`@deerdesign/deertools` includes a built-in, local **BaseLinker MCP Proxy & Hub** providing deep catalog management:
+
+1. **Product Catalog & Variations**:
+   - `bl_catalog_get_product`: Detailed product data with descriptions, features, channel-specific media, bundles and relations.
+   - `bl_catalog_create_or_update_product`: Create or update products with SKU, EAN, tax rate, dimensions, weight, manufacturer, category.
+   - `bl_catalog_search_products`: Filter products by name, SKU, EAN, category, or manufacturer.
+2. **Relationships & Cross-Selling**:
+   - `bl_catalog_set_relations`: Build product relationships (`related`, `substitution`, `upsell`, `downsell`, `crosssell`).
+3. **Product Features & Custom Text Fields**:
+   - `bl_catalog_set_descriptions_and_features`: Update descriptions and key-value parameter maps (`features`) per language.
+4. **Media & Image Galleries**:
+   - `bl_catalog_manage_images`: Add image URLs / base64 on positions 0–15, replace photos, or clear positions.
+5. **Categories, Manufacturers & Tags**:
+   - `bl_catalog_categories`, `bl_catalog_manufacturers`, `bl_catalog_tags`: Full CRUD for organizational taxonomies.
+6. **Bulk Price & Stock Updates**:
+   - `bl_catalog_update_prices_batch` & `bl_catalog_update_stock_batch`: Bulk updates up to 1000 items per call.
+7. **Rate Limiting & Safety**:
+   - Built-in token bucket rate-limiter prevents hitting BaseLinker's 100 req/min limit.
+8. **Live Web Dashboard**:
+   - Run `deertools baselinker serve` to open the local web UI at `http://localhost:3456` with token tester and real-time agent audit stream.
+
+---
+
+## DeerSkills Hub & MCP Ecosystem
+
+**DeerSkills Hub** (`https://skills.deergroup.pl`) to centralna platforma dystrybucji, wersjonowania i zarządzania umiejętnościami agentów AI (Skills) oraz serwerami MCP w ekosystemie Deer Design:
+
+1. **Struktura i Uprawnienia**:
+   - **Oficjalne Skille (`global`)**: Zweryfikowane, wersjonowane semantycznie (`v1.0.0`) narzędzia firmowe, zarządzane wyłącznie przez Administratorów.
+   - **Skille Użytkowników (`user`)**: Każdy pracownik może tworzyć i wersjonować własne skille pod przestrzenią `@uzytkownik/nazwa-skilla`.
+   - **Widoczność**: `shared` (dostępne wewnątrz firmy dla zalogowanych) lub `private` (widoczne tylko dla autora).
+2. **Automatyczny Skaner Sekretów**:
+   - Każde wywołanie `deertools skill push` automatycznie skanuje pliki skilla w poszukiwaniu niebezpiecznych tokenów (`deer_*_live_`, `ghp_`, `sk-`, `X-BLToken`, haseł).
+   - Próba wysłania niezanominizowanych kluczy kończy się natychmiastową blokadą z kodem błędu i listą wykrytych linii.
+3. **Wersjonowanie SemVer i Wizualny Diff**:
+   - Zmiany są wersjonowane (`1.0.0` -> `1.0.1` -> `1.1.0`).
+   - W portalu Web dostępny jest interaktywny widok Side-by-Side Diff porównujący wersje.
+   - CLI wspiera flagę `--bump patch|minor|major` przy publikacji.
+4. **Śledzenie Zależności (`.deertools-lock.json`)**:
+   - Zainstalowane skille są rejestrowane w pliku blokady z sumą kontrolną SHA-256 i zainstalowaną wersją.
+   - `deertools doctor` automatycznie wykrywa nieaktualne skille i proponuje aktualizację przez `deertools skill update`.
+5. **Ścieżka Awansu ("Nominuj do Globalnych")**:
+   - Użytkownicy mogą promować swoje prywatne lub zespołowe skille do oficjalnego katalogu firmowego komendą `deertools skill promote <slug>`.
+   - Administrator weryfikuje zgłoszenie w panelu `/settings` i zatwierdza jednym kliknięciem.
+6. **Integracja z Narzędziami AI (Cursor / Antigravity / Claude)**:
+   - DeerSkills udostępnia własny serwer MCP (`https://skills.deergroup.pl/functions/v1/skills-mcp`) implementujący specyfikację MCP 2024-11-05.
+   - Narzędzia: `hub_search_skills`, `hub_get_skill`, `hub_publish_skill_version`, `hub_list_mcp_servers`, `hub_get_ecosystem_products`.
 
 ---