@pushrec/skills 0.3.2 → 0.3.4

package/README.md

@@ -2,7 +2,15 @@
 
 CLI for the pushREC Agent Skills Marketplace. Install, manage, and update Claude Code skills.
 
-**Version:** `0.1.0` | **Published:** 2026-02-19
+**Local repo version target:** `0.3.4`
+
+**Do not assume npm latest from this file.** Verify before customer-facing instructions:
+
+```bash
+npm view @pushrec/skills version
+```
+
+As of 2026-02-27: npm `latest` = `0.2.0`, `next` = `0.3.2`. Local tree at `0.3.4` (Windows readiness). 19 test files, 139 tests passing.
 
 ## Quick Start
 
@@ -30,19 +38,22 @@ pushrec-skills auth login
 
 | Command | Description |
 |---------|-------------|
-| `pushrec-skills list` | Browse available skills |
-| `pushrec-skills install <name>` | Install a skill |
-| `pushrec-skills install --all` | Install all licensed skills |
-| `pushrec-skills update [name]` | Update installed skills |
-| `pushrec-skills search <query>` | Search the catalog |
-| `pushrec-skills info <name>` | Get skill details |
-| `pushrec-skills uninstall <name>` | Remove a skill |
+| `pushrec-skills install [name]` | Install a skill (or `--all` for all available) |
+| `pushrec-skills update [name]` | Update installed skills to latest versions |
+| `pushrec-skills sync [name]` | Synchronize local skills with the registry (install missing + update installed) |
+| `pushrec-skills list` | List available or installed skills |
+| `pushrec-skills search <query>` | Search skills by keyword |
+| `pushrec-skills info <name>` | Show detailed information about a skill |
+| `pushrec-skills uninstall <name>` | Uninstall a skill from the active skills root |
+| `pushrec-skills rollback <name>` | Rollback an installed skill to a backup snapshot |
 
-### Utility
+### Setup & Utility
 
 | Command | Description |
 |---------|-------------|
-| `pushrec-skills health` | Check registry connectivity |
+| `pushrec-skills setup` | One-command onboarding: verify license, activate device, install all skills |
+| `pushrec-skills health` | Check registry server health (use `--full` for full diagnostic) |
+| `pushrec-skills dashboard` | Launch the Generative UI dashboard |
 
 ## Registry
 

package/bundled-skills/pushrec-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pushrec-skills
-version: 1.0.0
+version: 1.1.0
 description: "Universal entry point for all pushREC skill operations. Onboarding, skill discovery, troubleshooting, API key setup, and update guidance. Use when: first time using pushREC skills, need help finding the right skill, skill isn't working, setting up API keys, updating skills, or asking how skills work. Aliases: /onboarding, /start, /get-started, /help, /skills, /pushrec."
 category: meta-tools
 aliases: [onboarding, start, get-started, help, skills, pushrec]
@@ -143,7 +143,7 @@ Write `progress.json` with `first_win: {status: "completed", skill_recommended:
 Present a personalized overview of available skills organized by level. Show only levels relevant to their profile.
 
 **Structure:**
-- **Level 0 -- Foundation (available now):** Group by category relevant to their profile. Highlight 5-8 most relevant skills with one-line descriptions. Mention total count (80+ skills).
+- **Level 0 -- Foundation (available now):** Group by category relevant to their profile. Highlight 5-8 most relevant skills with one-line descriptions. Mention total count (check `~/.claude/skills/registry.json` for current `skill_count` — never hardcode).
 - **Level 1 -- Google Workspace:** List capabilities unlocked (Gmail, Sheets, Docs, Calendar, Drive, Contacts, Slides). Note: "~15 minutes one-time setup."
 - **Level 2 -- Creative and Data:** List key capabilities (AI image generation, voice synthesis, vision analysis, CRM). Note per-service setup time.
 - **Level 3 -- Communication:** List capabilities (SMS, AI phone agents, web scraping). Note KYC requirements.
@@ -232,6 +232,10 @@ Check for missing prerequisites, missing API keys, or license issues.
 | Skill produces no output | Skill invocation issue | Verify skill name, try `/skill-name` syntax |
 | Import errors in scripts | Missing Python dependencies | Check skill's requirements, run `pip install` or `uv run --with` |
 | License validation fails | License issue | Run `npx @pushrec/skills auth login` to re-authenticate |
+| Hook errors in session output | Broken or incompatible hook | Check `~/.claude/settings.json` hooks array, remove or fix the offending hook |
+| Rate limit / throttle errors | API quota exceeded | Wait and retry, or check service dashboard for quota limits |
+| "No space left on device" | Disk full | Free disk space, check `df -h` output |
+| Version mismatch warnings | Claude Code outdated | Run `claude update` to update to latest version |
 
 ### Step 4: Escalation
 
@@ -316,6 +320,7 @@ Note: `install --all` skips already-installed skills (no duplicates). Running it
 | Skipping the diagnostic on first run | Always run diagnostic.py in Phase 0 |
 | Proceeding after critical failures | STOP and help fix prerequisites before continuing |
 | Recommending L1+ skills without mentioning API key requirements | Always state the setup requirement alongside the recommendation |
+| Hardcoding skill counts | Always query dynamically or use safe-floor estimates |
 
 ### Verification Checklist
 
@@ -338,6 +343,7 @@ Before finishing any response, verify:
 | Update skills | `npx @pushrec/skills update` |
 | Install new skills | `npx @pushrec/skills install --all` |
 | List all skills | `npx @pushrec/skills list` |
+| Check CLI version | `npx @pushrec/skills --version` |
 | Get help | Post in skool.com/pushrec-2909 |
 | Reset onboarding | Type `/pushrec-skills` and say "reset" |
 
@@ -349,12 +355,27 @@ Before finishing any response, verify:
 
 ### State Files
 
+The `state/` directory is created automatically on first write. No manual setup needed.
+
 | File | Purpose |
 |------|---------|
 | `state/profile.json` | Business profile from adaptive profiling |
 | `state/progress.json` | Completed phases, unlocked levels, skills invoked |
 
+**Error recovery:** If `profile.json` or `progress.json` fails to parse (corrupt JSON), offer the user a reset: `rm ~/.claude/skills/pushrec-skills/state/*.json` and restart onboarding.
+
 ### Community
 
 - **Skool:** skool.com/pushrec-2909
 - **Live Q&A:** check Skool for scheduled sessions
+
+---
+
+## See Also
+
+| Resource | Path | Purpose |
+|----------|------|---------|
+| Agent Skills Marketplace | `~/pushrec-vault/1-Projects/agent-skills-marketplace/` | License-gated skill distribution (ThriveCart + Convex + Vercel) |
+| GTM Sprint | `~/pushrec-vault/1-Projects/gtm-sprint-claude-skills/` | Launch strategy, offer tiers, voice bible |
+| Generative UI Dashboard | `~/.claude/skills/generative-ui/` | Visual dashboard with SkillBrowser (verify count via registry.json), SetupChecklist |
+| Registry Runbook | `~/pushrec-vault/1-Projects/agent-skills-marketplace/registry/CLAUDE.md` | Zero-assumptions technical reference (687 lines) |

package/bundled-skills/pushrec-skills/hooks/session_start.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""SessionStart hook for pushREC Skills onboarding nudge.
+
+Reads progress.json and outputs a brief reminder if onboarding is incomplete.
+Exit code 0 always — hooks must never fail the session.
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+PROGRESS_FILE = os.path.expanduser(
+    "~/.claude/skills/pushrec-skills/state/progress.json"
+)
+
+# Canonical phase order for determining which phase comes next
+PHASE_ORDER = [
+    ("diagnostic", "System Diagnostic"),
+    ("profiling", "Adaptive Profiling"),
+    ("cc101", "Claude Code 101"),
+    ("first_win", "First Win"),
+    ("skill_map", "Skill Map"),
+    ("unlock_guide", "Progressive Unlock"),
+]
+
+
+def main():
+    # Prevent hook loops
+    if os.environ.get("stop_hook_active"):
+        return
+
+    # No progress file -> first-time user
+    if not os.path.exists(PROGRESS_FILE):
+        print(
+            "pushREC Skills: Welcome! Type /pushrec-skills to start your "
+            "personalized onboarding (takes ~30 min)."
+        )
+        return
+
+    # Read and parse progress
+    try:
+        with open(PROGRESS_FILE, "r") as f:
+            progress = json.load(f)
+    except json.JSONDecodeError as exc:
+        sys.stderr.write(f"pushrec-skills: progress.json parse error: {exc}\n")
+        return
+    except OSError as exc:
+        sys.stderr.write(f"pushrec-skills: progress.json read error: {exc}\n")
+        return
+
+    phases = progress.get("phases", {})
+    total_phases = len(PHASE_ORDER)
+    completed_count = sum(
+        1
+        for p in phases.values()
+        if isinstance(p, dict) and p.get("status") in ("completed", "skipped")
+    )
+
+    # All phases done -- nothing to show
+    if completed_count >= total_phases:
+        return
+
+    # Determine the next incomplete phase
+    next_phase_name = None
+    for phase_key, phase_label in PHASE_ORDER:
+        phase_data = phases.get(phase_key, {})
+        if not isinstance(phase_data, dict) or phase_data.get("status") not in (
+            "completed",
+            "skipped",
+        ):
+            next_phase_name = phase_label
+            break
+
+    # Build the nudge message
+    prefix = ""
+    last_session_at = progress.get("last_session_at")
+    if last_session_at:
+        try:
+            last_dt = datetime.fromisoformat(last_session_at.replace("Z", "+00:00"))
+            now = datetime.now(timezone.utc)
+            days_since = (now - last_dt).days
+            if days_since > 7:
+                prefix = "Welcome back! It's been a while. "
+        except (ValueError, TypeError):
+            pass
+
+    if next_phase_name:
+        print(
+            f"{prefix}pushREC Skills: {completed_count}/{total_phases} phases complete. "
+            f"Next up: {next_phase_name}. Type /pushrec-skills to continue."
+        )
+    else:
+        print(
+            f"{prefix}pushREC Skills: {completed_count}/{total_phases} phases complete. "
+            "Type /pushrec-skills to continue where you left off."
+        )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass  # Never crash the session
+    sys.exit(0)

package/bundled-skills/pushrec-skills/references/prerequisites.yaml

@@ -1,5 +1,5 @@
 # pushREC Skills Prerequisites
-# version: 1.0.0
+# version: 1.1.0
 #
 # Skills NOT listed here require NO API keys or credentials (Level 0).
 # 80+ skills work immediately after install with zero configuration.
@@ -24,7 +24,7 @@ gmail:
       service: Google Cloud Console
       setup_url: https://console.cloud.google.com/apis/credentials
       setup_time: "15 minutes (one-time for all Google services)"
-      credentials_path: "~/.gmail-mcp/gcp-oauth.keys.json"
+      credentials_path: "~/.claude/.credentials/gmail-oauth.keys.json"
       notes: "OAuth2 browser consent flow. Tokens stored at ~/.gmail-mcp/credentials.json"
 
 google-sheets:
@@ -57,7 +57,7 @@ google-calendar:
       service: Google Cloud Console
       setup_url: https://console.cloud.google.com/apis/credentials
       setup_time: "15 minutes (shared with other Google services)"
-      credentials_path: "~/.calendar-mcp/gcp-oauth.keys.json"
+      credentials_path: "~/.claude/.credentials/calendar-oauth.keys.json"
       notes: "OAuth2 browser consent flow."
 
 google-drive:
@@ -68,7 +68,7 @@ google-drive:
       service: Google Cloud Console
       setup_url: https://console.cloud.google.com/apis/credentials
       setup_time: "15 minutes (shared with other Google services)"
-      credentials_path: "~/.drive-mcp/gcp-oauth.keys.json"
+      credentials_path: "~/.claude/.credentials/drive-oauth.keys.json"
       notes: "OAuth2 browser consent flow."
 
 google-contacts:
@@ -79,7 +79,7 @@ google-contacts:
       service: Google Cloud Console
       setup_url: https://console.cloud.google.com/apis/credentials
       setup_time: "15 minutes (shared with other Google services)"
-      credentials_path: "~/.contacts-mcp/gcp-oauth.keys.json"
+      credentials_path: "~/.claude/.credentials/contacts-oauth.keys.json"
       notes: "Read-only. Shares GCP project with Gmail."
 
 google-slides:
@@ -156,7 +156,13 @@ ocr-processor:
       service: Google AI Studio
       setup_url: https://aistudio.google.com/apikey
       setup_time: "2 minutes (shared with gemini-vision)"
-      notes: "Primary provider: Gemini. Also supports MISTRAL_API_KEY as alternative."
+      notes: "Primary provider: Gemini."
+    - env: MISTRAL_API_KEY
+      type: api_key
+      service: Mistral AI
+      setup_url: https://console.mistral.ai/api-keys
+      setup_time: "2 minutes"
+      notes: "Alternative provider for OCR. Set in ~/.claude/.env as MISTRAL_API_KEY=xxx"
 
 airtable:
   level: 2
@@ -248,6 +254,37 @@ skool-api:
       setup_time: "5 minutes (browser login)"
       notes: "Cookie-based auth persisted at ~/.skool/cookies.json. No API key - uses browser login."
 
+# ============================================================================
+# LEVEL 2 (continued): General-purpose API keys
+# Used by multiple skills or for advanced integrations.
+# ============================================================================
+
+deep-research:
+  level: 2
+  requires:
+    - env: OPENAI_API_KEY
+      type: api_key
+      service: OpenAI
+      setup_url: https://platform.openai.com/api-keys
+      setup_time: "2 minutes"
+      notes: "Used by deep-research and other skills that support OpenAI models."
+    - env: ANTHROPIC_API_KEY
+      type: api_key
+      service: Anthropic
+      setup_url: https://console.anthropic.com/settings/keys
+      setup_time: "2 minutes"
+      notes: "Used for API-routed sub-agents and headless operations."
+
+browser-automation:
+  level: 2
+  requires:
+    - env: RAPIDAPI_KEY
+      type: api_key
+      service: RapidAPI
+      setup_url: https://rapidapi.com/developer/dashboard
+      setup_time: "3 minutes"
+      notes: "Used by browser-automation and data enrichment integrations."
+
 # ============================================================================
 # LEVEL 3: Service Accounts
 # Require KYC verification, usage-based billing, or special configuration.

package/bundled-skills/pushrec-skills/scripts/diagnostic.py

@@ -14,12 +14,14 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
-VERSION = "1.0.0"
+VERSION = "1.1.0"
 SKILLS_DIR = Path.home() / ".claude" / "skills"
 CONFIG_PATH = Path.home() / ".pushrec" / "config.json"
 ENV_PATH = Path.home() / ".claude" / ".env"
+PREREQUISITES_PATH = Path(__file__).resolve().parent.parent / "references" / "prerequisites.yaml"
 
-KNOWN_KEY_PREFIXES = [
+# Fallback list used when prerequisites.yaml cannot be read
+_FALLBACK_KEY_PREFIXES = [
     "ELEVENLABS_API_KEY",
     "OPENAI_API_KEY",
     "ANTHROPIC_API_KEY",
@@ -41,6 +43,29 @@ KNOWN_KEY_PREFIXES = [
 ]
 
 
+def load_key_prefixes():
+    """Load API key env var names from prerequisites.yaml, falling back to hardcoded list."""
+    try:
+        with open(PREREQUISITES_PATH, "r") as f:
+            content = f.read()
+        # Simple YAML parsing: extract all `env: VALUE` lines (no PyYAML dependency)
+        prefixes = set()
+        for line in content.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("- env:") or stripped.startswith("env:"):
+                value = stripped.split(":", 1)[1].strip()
+                if value:
+                    prefixes.add(value)
+        if prefixes:
+            return sorted(prefixes)
+    except (OSError, ValueError):
+        pass
+    return _FALLBACK_KEY_PREFIXES
+
+
+KNOWN_KEY_PREFIXES = load_key_prefixes()
+
+
 def run_command(args):
     """Run a shell command and return (success, stdout_stripped)."""
     try:
@@ -176,6 +201,8 @@ def check_obsidian():
 
 
 def main():
+    # Exit silently in headless mode — hooks must never block headless sessions
+    # (e.g. CI pipelines, sub-agents) with interactive diagnostics or stdout noise.
     if os.environ.get("CLAUDE_HEADLESS"):
         sys.exit(0)
 
@@ -219,6 +246,8 @@ def main():
         "version": VERSION,
         "timestamp": datetime.now(timezone.utc).isoformat(),
         "platform": platform.system().lower(),
+        "npm_version": checks["npm"].get("version"),
+        "skills_count": checks["skills_installed"].get("count", 0),
         "checks": checks,
         "exit_code": exit_code,
         "summary": summary,