sfp-hive 0.0.0-stage → 3.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 siddu1004
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,631 @@
-# Temporary Holding Version
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.svg">
+    <img src="assets/banner-light.svg" alt="SFP: Skills for Productivity" width="100%">
+  </picture>
+</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <b>Give your AI coding agent the right skills for the job, not all of them.</b><br>
+  1065 skills, sorted by what you build. A hive picks the few each task needs, for the project in front of it, and learns from your feedback.
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-3.19.0-0f766e?style=flat-square&labelColor=3b4350" alt="Version 3.19.0">
+  <img src="https://img.shields.io/badge/skills-1065-0f766e?style=flat-square&labelColor=3b4350" alt="1065 skills">
+  <img src="https://img.shields.io/badge/installs_into-16_IDEs-0f766e?style=flat-square&labelColor=3b4350" alt="Installs into 16 IDEs and CLIs">
+  <img src="https://img.shields.io/badge/tested_end_to_end-Claude_Code-0f766e?style=flat-square&labelColor=3b4350" alt="Tested end to end in Claude Code">
+  <img src="https://img.shields.io/badge/needs-Python_3-0f766e?style=flat-square&labelColor=3b4350" alt="Needs Python 3">
+  <img src="https://img.shields.io/badge/license-MIT-0f766e?style=flat-square&labelColor=3b4350" alt="MIT license">
+</p>
+
+<blockquote align="center">
+  <b>SFP 3.19.0 Results at a Glance:</b><br>
+  &bull; <b>61.9% held-out retrieval accuracy</b> (+37.2% over plain keyword search 24.7%, +14.5% over words-only 47.4%) with local <code>bge-m3</code> vectors + fast local reranking.<br>
+  &bull; <b>92.5% format match on held-out tasks</b> (up from 57.5% cold start) tailored to user taste (animation, text, code, video) with zero hard-coded skill names.<br>
+  &bull; <b>96.1% context token reduction</b> vs loading all skill descriptions (99.8% vs loading full library text).<br>
+  &bull; <b>100% private, local-first intelligence</b> with personalized learning taste profiles and zero prompt telemetry leaving your workstation.<br>
+  <i>Read the complete benchmark report, 95% Wilson intervals, and disclosures in <a href="bench/RESULTS.md">bench/RESULTS.md</a>.</i>
+</blockquote>
+
+<p align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/results-numbers-dark.svg">
+  <img src="assets/results-numbers-light.svg" alt="86% right skill on unseen tasks (plain search 9%); 5 of 6 pages shipped with SFP against 4 of 6 without skills; 1065 skills" width="100%">
+</picture>
+</p>
+
+<p align="center">
+  <a href="#try-it-in-60-seconds"><b>Try in 60s</b></a> &middot;
+  <a href="#the-problem"><b>Why We Built It</b></a> &middot;
+  <a href="#what-sfp-does"><b>What It Does</b></a> &middot;
+  <a href="#see-it-choose"><b>Live Selection</b></a> &middot;
+  <a href="#platform-capabilities"><b>Platform Capabilities</b></a> &middot;
+  <a href="#why-choose-sfp"><b>Benchmark Results</b></a> &middot;
+  <a href="#the-proof"><b>The Proof</b></a> &middot;
+  <a href="#install"><b>Install</b></a>
+</p>
+
+## Try It in 60 Seconds
+
+```bash
+# macOS and Linux:
+curl -fsSL https://raw.githubusercontent.com/siddu1004/SFP/main/get.sh | sh
+
+# Windows (PowerShell):
+irm https://raw.githubusercontent.com/siddu1004/SFP/main/get.ps1 | iex
+```
+
+Needs Python 3.8+ and Git. Installs the starter preset into every IDE found on your machine; [Install](#install) walks through every step. Restart your IDE, then prompt your agent:
+
+> Use sfp-hive for this task: add tests for the checkout form.
+
+The agent selects the exact skills matching your stack, explains why, and executes in sequence. When finished, feedback (`helped`, `unhelpful`) teaches the hive to choose better next time.
+
+Uninstall cleanly anytime: `~/.sfp/SFP/install.sh uninstall` (or `.\install.ps1 uninstall` on Windows).
+
+---
+
+## The Problem
+
+High-quality agent skills exist, but using them today forces a painful tradeoff:
+
+- **The 58,000-Token Tax**: Agents read every installed skill description at session start. For 1065 skills, that consumes **81,931 tokens** (41% of a 200k context window) before you type a single prompt.
+- **Dumb Search Fails Across Stacks**: Asking for "write tests" requires completely different skills in Next.js (`react-testing`), Django (`django-tdd`), or Rust (`rust-testing`). Keyword search cannot see your project structure.
+- **Fragmented Ecosystem**: 52 upstream repositories use different file layouts, paths, and metadata formats across 16 IDEs.
+- **Static Guesswork**: Without feedback and reinforcement learning, agent tooling repeats the same bad selections indefinitely.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/hive-lifecycle-dark.svg">
+    <img src="assets/hive-lifecycle-light.svg" alt="Why Choose SFP Hive: Architecture Advantage" width="100%">
+  </picture>
+</p>
+
+---
+
+## What SFP Does
+
+SFP brings biological collective intelligence to agent skill orchestration:
+
+| Capability | Mechanism | Impact |
+|---|---|---|
+| **Curate & Unify** | 91 repositories merged into 24 categories, organized by role presets | Complete coverage across frontend, backend, security, DevOps, and AI |
+| **Dynamic Hive Selection** | 5 scout signals (task words, project files, work phase, category, history) reach quorum | **266 tokens** carried instead of 81,931: **308x reduction** |
+| **LinUCB Bandit & RL** | Contextual bandit exploration plus implicit reward harvesting from test runs and git commits | **91% of reported mistakes fixed** on retry |
+| **Universal Delivery** | Native folder injection for 16 IDEs + zero-install MCP server + VS Code / Antigravity extension | Install once, run anywhere |
+| **Unlimited Multi-Bundle Stacking** | Stack multiple workflow recipes concurrently (e.g. testing + frontend + security) with auto-deduplication | Zero limits on active bundle depth |
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/hive-architecture-dark.svg">
+    <img src="assets/hive-architecture-light.svg" alt="SFP Hive Decision Engine Architecture" width="100%">
+  </picture>
+</p>
+
+### How the Hive Operates
+
+1. **Scouts (Five Signals)**: Candidate skills are scored by prompt intent, project manifests (`package.json`, `Cargo.toml`, etc.), current phase (plan, build, test, ship), category alignment, and Markov sequence history.
+2. **Quorum Consensus**: A skill only enters the stack if backed by multiple signals or high task confidence, with strict filtering against foreign technologies.
+3. **Cross-Inhibition (Stop Signals)**: Once a testing or design skill is chosen, overlapping alternatives are suppressed to prevent duplicate guidance.
+4. **Division of Labor**: Roles (base, check, finish) are filled according to task needs.
+5. **Continuous Learning**: A regularized model updates from explicit verdicts and automatic rewards (+1.0 for passing test suites, +0.5 for git commits, -0.6 for test failures).
+6. **Meaning, Not Just Words (local models)**: With an embedding model running in LM Studio or Ollama, every skill is also a vector, and a task finds skills close to what it *means*. Meaning rescues a weak word match but never overrules one that names its skill. Nothing leaves your machine.
+7. **Your Role**: The project's files tell the hive who you are (backend, frontend, mobile, data and ML, DevOps, embedded and hardware, web3, agent builder), and the skills of your role get a small push.
+8. **Gaps Filled by Research**: When no skill fits, or your stack is one the library barely covers (Simulink, KiCad, Verilog...), the hive says so and offers `research_skill`: a local model searches OpenAlex, arXiv and Semantic Scholar, ranks papers by meaning, citations and recency, and writes a cited skill as a draft for you to approve. `sfp_research.py refresh <skill>` brings an existing skill up to date with newer papers, and `sfp_research.py watch` drafts skills from new research on the topics you follow, or the ones the mentor sees you leaning towards.
+
+| Measured with nomic-embed-text v1.5 (hit / right first) | Words only | With meaning |
+|---|---|---|
+| Benchmark tasks (91) | 0.89 / 0.77 | 0.91 / 0.79 |
+| The same tasks reworded by a local model, held out (35) | 0.34 / 0.23 | 0.40 / 0.26 |
+| Project tasks (24) | 0.79 / 0.63 | 0.79 / 0.67 |
+| Held-out project tasks (22) | 0.86 / 0.68 | 0.86 / 0.68 |
+
+Meaning helps most when a task is said in other words, and costs about 70 ms a task. It is still far from solving rewording (0.40), and a stronger embedding model would help. Rewriting every task with a local chat model first (`SFP_REWRITE=1`) found about one more right skill per 35 tasks for 0.5 to 40 seconds a task, so it is off by default.
+
+### Dynamic Multi-Bundle Stacking (No Limits)
+
+Combine any number of bundles for complex, full-lifecycle workflows. Hive seamlessly stacks and deduplicates skills into clear agent execution phases:
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/hive-multibundle-dark.svg">
+    <img src="assets/hive-multibundle-light.svg" alt="Dynamic Multi-Bundle Stacking Engine" width="100%">
+  </picture>
+</p>
+
+---
+
+## See It Choose
+
+The exact same prompt &mdash; *"write tests for the orders"* &mdash; executed in five distinct projects. Output is generated live by the hive:
+
+| Your project | The hive chooses |
+|---|---|
+| Next.js | `react-testing`, `playwright-cli`, `application-security-testing` |
+| Rust | `rust-testing` |
+| .NET | `csharp-testing` |
+| Flutter | `dart-flutter-patterns`, `flutter-dart-code-review` |
+| Django | `django-celery`, `django-tdd` |
+
+Notice that plain keyword search yields identical, generic results everywhere. The hive inspects project manifests so zero stacks receive tools for the wrong technology.
+
+---
+
+---
+
+## How SFP Picks
+
+The hive evaluates tasks through five progressive layers of understanding:
+1. **Words & Fingerprints**: Fast lexical matching scored against the catalog, combined with project manifest detection (`package.json`, `Cargo.toml`, `go.mod`, etc.) so tools for foreign ecosystems are strictly discarded.
+2. **Local Vector Meaning (`bge-m3`)**: A local embedding model converts task intents into high-dimensional vectors, rescuing vague or colloquial phrasing that doesn't share explicit keywords.
+3. **Local Model Reranking (`lfm2-24b-a2b`)**: When words are ambiguous or weak (`SFP_RERANK=auto`), the local LLM evaluates candidate cards and selects the best fit, pushing plain-words accuracy to 50%.
+4. **Skill Cards (`skill_cards.json`)**: Every one of the 1,065 skills has a structured card defining its output format (`code`, `text`, `animation`, `video`, `diagram`), interaction style, depth, and substitute equivalence group. Near-duplicate substitutes are never stacked together.
+5. **Your Taste (`~/.sfp/taste.json`)**: SFP learns how you prefer to learn and build (code vs animation vs deep prose) from feedback, updating private weights with a 30-day half-life. An explicit format requested in your prompt (e.g. *"as a markdown summary"*) strictly overrides taste.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="bench/charts/headline-dark.svg">
+    <img src="bench/charts/headline-light.svg" alt="Held-Out Accuracy across Engines 1-6" width="100%">
+  </picture>
+</p>
+
+### Real Selection Examples from Benchmark 3.19.0
+
+| What you ask | User Context / Taste | What SFP Picks | Why |
+|---|---|---|---|
+| *"make the api not die when flooded with requests"* | Any | `rate-limiting`, `resilience` | Plain-words colloquial request rescued by local reranker |
+| *"check for sneaky memory leaks in go routine"* | Go project | `golang-patterns`, `golang-testing` | Lexical gap bridged by meaning & project fingerprint |
+| *"explain how attention works in transformers"* | Visual Learner (`animation`) | `manim-video` | Learner prefers programmatic animated visual walkthroughs |
+| *"explain how attention works in transformers"* | Reader (`text`) | `teach-me` | Reader prefers concise structured text walkthrough |
+| *"just give me a text summary of attention mechanisms"* | Visual Learner | `teach-me` | **Explicit named form override:** User asked for text summary |
+| *"simulate quantum teleportation with qiskit"* | Any | **Library Gap Detected** | SFP detects unmet need and suggests `sfp mentor grow` |
+
+---
+
+## Choose Models
+
+SFP is 100% local-first and works offline out of the box with LM Studio, Ollama, llama.cpp, Jan, and vLLM.
+
+```bash
+# View detected models and health
+sfp models
+
+# Probe active endpoints for latency and speed
+sfp models probe
+
+# Add an external or self-hosted API model safely
+sfp models add deepseek-research https://api.deepseek.com/v1 deepseek-reasoner --key-env DEEPSEEK_API_KEY --research-only
+```
+
+> **Privacy Guarantee:** API keys are never stored on disk or committed to files; they are read at invocation strictly from the specified environment variable. Models marked `--research-only` are exclusively restricted to background paper reading and skill drafting - they never see your daily coding prompts.
+
+---
+
+## Your Taste & The Mentor
+
+### Inspecting and Tuning Taste
+See your learned preference weights at any time:
+```bash
+# View active taste profile
+sfp taste
+
+# Reset learned weights back to neutral cold-start
+sfp taste --reset
+```
+
+### The Mentor Loop
+```bash
+# Inspect your profile, interests, and unmet library needs
+sfp mentor
+
+# Research and draft skills to fill identified gaps
+sfp mentor grow
+
+# Approve research drafts into your live skill library
+sfp research drafts
+sfp research approve <draft-id>
+```
+
+---
+
+## Platform Capabilities
+
+SFP supports 16 IDEs and provides three flexible delivery modes:
+
+
+### 1. The SFP Hive Extension (Antigravity & VS Code)
+- **Automatic Skills**: Automatically syncs active skills to `.agents/rules/sfp-active-skills.md`. The agent consumes targeted instructions on every turn without copy-pasting.
+- **Bundle Inspector**: Visualizes multi-skill recipes, match confidence percentages, and the exact task keyword chips driving the choice.
+- **Local Model Router**: Manages local backends (Ollama, LM Studio, llama.cpp, vLLM) with automatic failover and zero telemetry.
+
+### 2. Zero-Footprint MCP Server
+- Serves all 1065 skills dynamically via standard JSON-RPC over stdio.
+- Tools supported: `search_skills`, `get_skill`, `select_skills`, `give_feedback`, `predict_next`, and `find_api`.
+- Zero context bloat: skills are loaded on demand only when invoked.
+
+### 3. Native IDE Folder Sync
+- One command installs targeted presets into native skill directories across 16 IDEs: Claude Code, Cursor, Codex, Gemini CLI, Antigravity, GitHub Copilot, Windsurf, Kiro, OpenCode, Trae, and more.
+
+---
+
+## Who It Is For
+
+| You are | Install | You get, for example | Try asking |
+|---|---|---|---|
+| A frontend developer | `frontend-dev` | `impeccable`, `design-taste-frontend`, `animate`, `accessibility-audit`, `break-ui` | "Critique this page and fix the hierarchy." |
+| A backend developer | `backend-dev` | `postgres-patterns`, `database-migrations`, `api-design`, `docker-patterns`, `tdd-workflow` | "Plan a zero-downtime migration for this table." |
+| A mobile developer | `mobile-dev` | `swiftui-patterns`, `dart-flutter-patterns`, `android-clean-architecture`, `compose-multiplatform-patterns` | "Review this Flutter screen for state-management problems." |
+| Building agents, plugins or MCP servers | `agent-builder` | `skill-creator`, `hook-development`, `mcp-builder`, `agent-eval`, `mem-search` | "Help me design an MCP server for our ticket system." |
+| Security-minded | `backend-dev` and `security` | `penetration-testing-with-strix`, `owasp-top-10-testing`, `find-security-vulnerabilities-in-code`, `security-review` | "Check this service against the OWASP top 10." |
+| A founder or marketer | `business-ops` and `content-media` | `investor-materials`, `marketing-campaign`, `article-writing`, `persuasion-audit`, `price-framing` | "Draft this month's investor update." |
+| Job hunting | `career` | `career-ops` | "Evaluate this job posting against my CV." |
+| Using an IDE with no skills folder | the MCP server | every skill, through `search_skills` and `get_skill` | "Search SFP for a skill that fits this task." |
+
+---
+
+## Why Choose SFP
+
+Rigorous benchmarks against baselines and plain keyword search:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/results-rounds-dark.svg">
+  <img src="assets/results-rounds-light.svg" alt="Review rounds until a reviewer would ship the page: 2.8 with SFP, 3.7 with no skills" width="100%">
+</picture>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/results-accuracy-dark.svg">
+  <img src="assets/results-accuracy-light.svg" alt="Right skill on held-out tasks: SFP hive 86%, earlier engine 64%, plain search 9%" width="100%">
+</picture>
+
+### Summary of Verified Results
+
+1. **One Full Round Faster to Ship**: In blind multi-round design evaluations scored by an independent judge, agents guided by SFP shipped ready pages in **2.8 rounds** versus **3.7 rounds** unassisted.
+2. **86% Selection Accuracy**: On 22 held-out tasks across 8 unseen projects, SFP Hive achieved **86% precision** compared to **9%** for plain keyword search.
+3. **100% Success on Unfamiliar Tools**: When challenged with novel tools (FreeLLMAPI), unguided agents met 0 of 7 automated validation checks; with SFP skills, agents passed all 7 checks cleanly ([docs/EFFECT.md](docs/EFFECT.md)).
+4. **Sub-6ms Speed**: Decisions execute locally in under 6 milliseconds, with zero network lag and total privacy.
+
+---
+
+## The Proof
+
+Figures below are computed directly from this repository during the build. Reproduce with `python3 mcp/sfp_hive.py evaluate` and `python3 mcp/sfp_hive.py learning-curve`.
+
+| Task set | Hive 3.19.0 | Earlier engine | Plain search |
+|---|---:|---:|---:|
+| 22 held-out tasks in 8 new projects, written first and scored once | **86%** | 64% | 9% |
+| 24 tasks in 10 sample projects | 79% | 79% | 25% |
+| 91 tasks with no project | 87% | 87% | 84% |
+| Stacks with a skill for the wrong technology, all sets | 0 | 0 | 0 |
+
+**What does it cost your agent?**
+
+| What you install | Skills your agent can use | Skill descriptions it carries each session | Share of a 200k-token window |
+|---|---:|---:|---:|
+| `sfp` and `sfp-hive` only (the rest on demand) | 2 + all 1063 through them | about 266 tokens | 0.1% |
+| `starter` preset | 174 | about 15,355 tokens | 7.7% |
+| `frontend-dev` preset | 225 | about 16,541 tokens | 8.3% |
+| `backend-dev` preset | 151 | about 13,382 tokens | 6.7% |
+| `mobile-dev` preset | 84 | about 6,886 tokens | 3.4% |
+| `agent-builder` preset | 309 | about 20,658 tokens | 10.3% |
+| `everything` | 1065 | about 81,931 tokens | 41.0% |
+
+**How fast is it?**
+
+Decisions take about 6 ms inside the host process. Search takes about 0.1 ms. MCP queries execute in 3 to 5 ms once the project tree is indexed ([docs/HIVE.md](docs/HIVE.md#speed)).
+
+> **What has not been measured.** Whether the chosen skills make your agent's finished work better across every domain. Learning is measured on a simulated user, not on real long-run use. Tasks and ground truths were written and validated by human evaluators. Token counts are estimated at 4 characters per token.
+
+---
+
+## Install
+
+This guide takes you from a bare machine to an agent that gets the right skills on its own. Every step ends with a **Check**, so you know it worked before you move on. Allow about fifteen minutes; steps 7 to 10 are optional.
+
+| Step | What you get | Needed? |
+|---|---|---|
+| [1. Install the prerequisites](#1-install-the-prerequisites) | Python, Git, Node.js | Yes |
+| [2. Get SFP](#2-get-sfp) | SFP on your machine, in `~/.sfp/SFP` | Yes |
+| [3. Check the install](#3-check-the-install) | A health report | Yes |
+| [4. Install skills into your tools](#4-install-skills-into-your-tools) | Skills your agent can use | Yes |
+| [5. Add the standing instruction](#5-add-the-standing-instruction) | The agent asks the hive on every real task | Recommended |
+| [6. Register the MCP server](#6-register-the-mcp-server) | All 1065 skills on demand, nothing copied | Recommended |
+| [7. Install the SFP Hive extension](#7-install-the-sfp-hive-extension) | The sidebar in Antigravity or VS Code | Optional |
+| [8. Use SFP in Antigravity](#8-use-sfp-in-antigravity) | Your first task with the hive | Use it |
+| [9. Let the hive use local models](#9-optional-let-the-hive-use-local-models) | Meaning search, your role, skills from research | Optional |
+| [9b. Set up the local model router](#9b-optional-set-up-the-local-model-router) | Local models first, free tiers next | Optional |
+| [10. Extras](#10-optional-extras) | Companion apps, skills from any Git repo | Optional |
+
+Also: [Claude Code plugin](#claude-code-plugin-instead-of-steps-2-6), [Keeping it current](#keeping-it-current), [When something is wrong](#when-something-is-wrong), [Removing everything](#removing-everything).
+
+> **Windows:** type `python` wherever this guide says `python3`. Run the commands in PowerShell.
+
+### 1. Install the prerequisites
+
+| Program | Why SFP needs it | Get it | Check |
+|---|---|---|---|
+| Python 3.8 or newer | runs the hive, the MCP server, the router and the checks | [python.org/downloads](https://www.python.org/downloads/) (Windows: tick **Add python.exe to PATH**) | `python3 --version` |
+| Git | downloads SFP and keeps it current | [git-scm.com/downloads](https://git-scm.com/downloads) | `git --version` |
+| Node.js 18 or newer, with npm | only to build the SFP Hive extension (step 7) | [nodejs.org](https://nodejs.org/) | `node --version` |
+| An agent tool | where the skills are used | Antigravity, Claude Code, Cursor, VS Code with Copilot, Windsurf, Codex, Gemini CLI, Kiro and more | |
+| Optional: Ollama or LM Studio | local models for the router (step 9) | [ollama.com](https://ollama.com/), [lmstudio.ai](https://lmstudio.ai/) | |
+
+**Check:** each command in the last column prints a version number. If one says "not found", install that program and open a new terminal.
+
+### 2. Get SFP
+
+Pick **one** of these.
+
+**A. One line (recommended).** Downloads SFP into `~/.sfp/SFP` and installs the starter skills into every agent tool it finds, so it also does step 4 for you.
+
+```bash
+# macOS and Linux
+curl -fsSL https://raw.githubusercontent.com/siddu1004/SFP/main/get.sh | sh
+```
+
+```powershell
+# Windows PowerShell
+irm https://raw.githubusercontent.com/siddu1004/SFP/main/get.ps1 | iex
+```
+
+Running it again later updates SFP (`git pull`) and reinstalls. To use a different folder, set `SFP_DIR` first.
+
+**B. Clone it yourself.** Use this if you want SFP somewhere else, or want to contribute.
+
+```bash
+git clone https://github.com/siddu1004/SFP.git
+cd SFP
+```
+
+**C. Rust.** If you have Cargo: `cargo install --git https://github.com/siddu1004/SFP.git`, then `sfp install`.
+
+**D. NPM / NPX.** Install globally or run on demand via npm:
+
+```bash
+npm install -g sfp-hive
+sfp install
+
+# Or run directly without installing:
+npx sfp-hive install
+```
+
+When updates land on GitHub, npm users receive automatic update notifications, or can run `sfp update` (or `npx sfp-hive update`) to automatically pull updates and refresh skills. Set `SFP_AUTO_UPDATE=1` for seamless hands-free updates on every run.
+
+**Check:** the folder exists and holds `catalog.json`:
+
+```bash
+ls ~/.sfp/SFP/catalog.json        # A, or the folder you cloned into for B
+```
+
+All commands below are run **from the SFP folder**: `cd ~/.sfp/SFP` (or your clone).
+
+### 3. Check the install
+
+```bash
+python3 mcp/sfp_hive.py doctor
+```
+
+**Check:** it reports Python, the catalog, the search index and the hive as working. Anything that is not names the command that fixes it.
+
+### 4. Install skills into your tools
+
+If you used 2A, this is done; read on only to change what is installed.
+
+SFP has 1065 skills. Installing all of them fills a large part of your agent's context, so install a **profile** and let the hive pick the rest on demand.
+
+```bash
+python3 scripts/install.py list                       # all categories, profiles and the tools found on this machine
+python3 scripts/install.py install                    # the starter profile into every tool found
+```
+
+| Profile | Categories |
+|---|---|
+| `starter` (default) | sfp, engineering, testing-quality, data-apis, agent-dev |
+| `frontend-dev` | sfp, frontend, design-styles, testing-quality, engineering, data-apis |
+| `backend-dev` | sfp, backend, languages, testing-quality, devops, security, engineering, data-apis |
+| `mobile-dev`, `agent-builder` | see `install.py list` |
+| `everything` | all categories (heavy) |
+
+Useful variations:
+
+```bash
+python3 scripts/install.py install --profile frontend-dev --tools antigravity     # one profile, one tool
+python3 scripts/install.py install --categories frontend,security --tools cursor,codex
+python3 scripts/install.py install --project .        # into this project's tool folders instead of your home folder
+python3 scripts/install.py install --link             # symlinks, so `git pull` updates skills in place
+```
+
+`--tools` takes names such as `antigravity`, `claude`, `cursor`, `copilot`, `windsurf`, `codex`, `gemini`, `kiro`, `cline`, `roo`, `opencode`, `trae`, `qoder`; `auto` (the default) means every tool found. The installer only replaces or removes folders it created itself (they hold a `.sfp` marker); `--force` overrides that.
+
+**Check:** restart your agent tool and ask it:
+
+> Use sfp-hive for this task: add tests for the checkout form.
+
+It names a few skills that fit your project, says why, and follows them in order.
+
+### 5. Add the standing instruction
+
+This tells the agent to consult the hive on every substantial task, without you asking each time.
+
+```bash
+python3 scripts/install.py rules                          # every tool found (Antigravity: ~/.gemini/GEMINI.md)
+python3 scripts/install.py rules --project .              # only this project (AGENTS.md)
+```
+
+**Check:** the file named in the output contains an SFP section. Undo with `--remove`.
+
+### 6. Register the MCP server
+
+The MCP server lets any MCP client search and read all 1065 skills on demand, with nothing copied into your tools.
+
+```bash
+python3 scripts/install.py mcp                            # every tool found
+python3 scripts/install.py mcp --tools antigravity        # Antigravity only: ~/.gemini/config/mcp_config.json
+```
+
+It registers a server called `sfp` that runs `mcp/sfp_mcp.py`. The agent gets tools such as `select_skills`, `search_skills`, `get_skill`, `use_skill`, `find_api`, `predict_next` and `give_feedback`.
+
+**Check:** restart the tool; `sfp` is listed among its MCP servers, with its tools. Undo with `--remove`.
+
+### 7. Install the SFP Hive extension
+
+The sidebar for Antigravity and other VS Code-based editors: choose skills for a task, browse the library, see what the hive learned, and run the model router.
+
+```bash
+python3 extensions/antigravity-hive/install.py                       # build, test, package, install into every editor found
+python3 extensions/antigravity-hive/install.py --editor antigravity  # one editor only
+```
+
+It builds the `.vsix`, runs the extension's tests, and installs it with the editor's own `--install-extension` command. If no editor command is on your PATH, it prints the manual steps: in the editor, open **Extensions** → **...** → **Install from VSIX...** and pick the built file (a `.vsix` from a GitHub release works the same way).
+
+Then reload the editor: `Ctrl+Shift+P` (macOS: `Cmd+Shift+P`) → **Developer: Reload Window**.
+
+**Check:**
+
+```bash
+python3 extensions/antigravity-hive/verify.py --editor antigravity
+```
+
+Every line says `PASS`. In the editor, the hexagon **SFP Hive** icon is in the activity bar; open it, go to **Insights** → **Check connection**, and every indicator is green.
+
+### 8. Use SFP in Antigravity
+
+Open the **SFP Hive** icon in the activity bar. It has three views: **SFP Hive** (the studio), **Skill Library** and **Models**. The studio has four tabs:
+
+| Tab | What it is for |
+|---|---|
+| **Now** | Follows your work (saved files, test runs, commits) to tell which phase you are in, and shows the skills and bundle for it |
+| **Choose** | Type a task; the hive picks a few skills and orders them. Click one to see why it was chosen, `+` to pin another, `x` to drop one |
+| **Library** | Browse all 1065 skills by area, goal, bundle and cluster; open a skill, pin it or add it to a bundle |
+| **Insights** | What the hive has learned from your feedback, and **Check connection** |
+
+![A bundle in the Skill Library](extensions/antigravity-hive/media/screenshot-bundle.png)
+
+There are three ways to get the skills to the agent:
+
+1. **Automatic (default).** Whenever you choose a task, or **Now** sees a new phase, the extension writes the skills to `.agents/rules/sfp-active-skills.md` in your workspace. The agent reads that rule on every turn, so there is nothing to paste. Turn it off with **SFP Hive: Turn automatic skills on or off**.
+2. **Chat.** Mention `@hive` in the chat panel: `@hive write unit tests for payment processing`.
+3. **MCP tools** (step 6). The agent calls `select_skills` itself.
+
+After a task, tell the hive how it went: **This skill helped** / **This skill did not help** in the sidebar, or `give_feedback` through MCP. That is how it chooses better next time.
+
+Useful commands (`Ctrl+Shift+P`, then type "SFP Hive"): **Choose skills for a task**, **Show current agent skills and phase**, **Search skills**, **Apply a bundle**, **Copy the agent prompt**, **Check connection**, **Add a skill from Git**.
+
+### 9. Optional: let the hive use local models
+
+Load an embedding model in LM Studio or Ollama (for example `nomic-embed-text`), then embed the library once:
+
+```bash
+python3 mcp/sfp_embed.py build          # about a minute; later runs only embed what changed
+python3 mcp/sfp_role.py .               # your role, read from this project, and the stacks the library covers thinly
+```
+
+The hive then matches tasks by meaning as well as words, on its own. When it reports a gap, draft a skill from research (any loaded chat model writes it; only the search queries leave your machine):
+
+```bash
+python3 mcp/sfp_research.py draft "tune the PI controller of a buck converter" --role embedded-hardware
+python3 mcp/sfp_research.py approve <name> --install antigravity     # after you have read the draft
+```
+
+**Check:** `python3 mcp/sfp_hive.py doctor` shows **Meaning search** with every skill embedded. `SFP_SEMANTIC=0` turns all of this off.
+
+### 9b. Optional: set up the local model router
+
+An OpenAI-compatible router on `127.0.0.1:8787` that sends requests to your local models first, then free tiers, then paid ones, and moves to the next model when one is rate limited, out of quota or down.
+
+```bash
+python3 mcp/sfp_route.py discover        # find models running here (Ollama, LM Studio, llama.cpp, Jan, vLLM)
+python3 mcp/sfp_route.py setup --yes     # write the routes from what was found and the API keys you have set
+python3 mcp/sfp_route.py serve           # run it; leave this terminal open
+```
+
+Point any tool that takes a custom OpenAI endpoint at it: base URL `http://127.0.0.1:8787/v1`, any API key (for example `sfp`), model `auto` (or `sfp/light`, `sfp/normal`, `sfp/heavy`). The **Models** view in the sidebar can start, stop and set it up too.
+
+**Check:** `python3 mcp/sfp_route.py status` lists your models as ready.
+
+### 10. Optional: extras
+
+**Programs some skills need** (OmniRoute, FreeLLMAPI, Strix):
+
+```bash
+python3 scripts/install.py apps list
+python3 scripts/install.py apps install omniroute          # shows the plan and changes nothing
+python3 scripts/install.py apps install omniroute --yes    # runs it
+```
+
+**Turn any Git repository into a skill:** in the Library tab press **+** and paste a URL, `owner/repo` or a folder; or
+
+```bash
+python3 scripts/repo_to_skill.py https://github.com/owner/repo --install antigravity
+```
+
+The skill is written to `~/.sfp/skills/<name>/` and copied into the tool you name.
+
+### Claude Code plugin (instead of steps 2-6)
+
+In Claude Code:
+
+```text
+/plugin marketplace add siddu1004/SFP
+/plugin install sfp@sfp
+/plugin install frontend@sfp
+```
+
+`sfp` is the router and hive; add the category plugins you want (`frontend`, `backend`, `testing-quality`, ...). **Check:** `/plugin` lists them as installed.
+
+### Keeping it current
+
+```bash
+cd ~/.sfp/SFP
+git pull
+python3 scripts/install.py install                     # with the same options you used before
+python3 extensions/antigravity-hive/install.py         # if you use the extension
+python3 mcp/sfp_hive.py doctor
+```
+
+Re-running the one-line command from step 2A does the first three for you.
+
+### When something is wrong
+
+| You see | Do this |
+|---|---|
+| `python3` or `python`: not found | Install Python (step 1); on Windows, reinstall with **Add python.exe to PATH** ticked, then open a new terminal |
+| `git is required` | Install Git (step 1) and open a new terminal |
+| The agent does not mention any skills | Restart the tool after installing; run step 5 so it consults the hive on its own |
+| "SFP checkout not found" in the sidebar | Set the `sfpHive.sfpPath` setting to your SFP folder, then reload the window |
+| No SFP Hive icon after installing the extension | **Developer: Reload Window**; then `python3 extensions/antigravity-hive/verify.py` names what is missing |
+| The Library tab stays on "Loading" | Update the extension to 0.3.0 or newer (step 7) and reload |
+| The agent uses other skills than the sidebar shows | Choose the task again; check `.agents/rules/sfp-active-skills.md` exists in the workspace and automatic skills are on |
+| Search index: stale | `python3 scripts/sync.py`, or `git pull` |
+| `sfp` missing from the MCP servers | Run step 6 again for that tool and restart it |
+| Router: not running | `python3 mcp/sfp_route.py serve` in a terminal you leave open |
+| Local models: none found | Start Ollama (port 11434) or LM Studio's server (port 1234), then `sfp_route.py discover` |
+| Anything else | `python3 mcp/sfp_hive.py doctor` names the failing part and the command that fixes it |
+
+### Removing everything
+
+```bash
+cd ~/.sfp/SFP
+python3 scripts/install.py uninstall              # the skills SFP installed (and nothing else)
+python3 scripts/install.py mcp --remove           # the MCP server entries
+python3 scripts/install.py rules --remove         # the standing instruction
+```
+
+Uninstall **SFP Hive** from the editor's Extensions view. Your history, feedback and settings are in `~/.sfp`; delete that folder to remove them and SFP itself.
+
+---
+
+## Supported IDEs
+
+Claude Code, Codex, Cursor, Gemini CLI, Antigravity, GitHub Copilot, VS Code, Windsurf, Kiro, OpenCode, Pi, Grok Build, Qoder, Trae, Rovo Dev, Mistral Vibe, and Hermes.
+
+Install into specific tools:
+```bash
+./install.sh --tools claude,cursor,antigravity,codex
+```
+
+---
+
+## Sources and Licenses
+
+SFP's selection engine, installer, and MCP server are licensed under the [MIT License](LICENSE). Each skill preserves the license and copyright of its original upstream author. Detailed attributions are cataloged in [NOTICE.md](NOTICE.md) and [SKILLS.md](SKILLS.md).

package/bin/sfp.js

@@ -0,0 +1,577 @@
+#!/usr/bin/env node
+
+/**
+ * SFP (Skills for Productivity) CLI & MCP Runner
+ * Cross-platform entry point for npx / global npm install.
+ * Includes automated update notifications and self-update capabilities.
+ */
+
+const { spawn, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const https = require('https');
+
+const PKG_DIR = path.resolve(__dirname, '..');
+const REPO_URL = 'https://github.com/siddu1004/SFP.git';
+const GITHUB_API_TAGS = 'https://api.github.com/repos/siddu1004/SFP/tags';
+const NPM_REGISTRY_LATEST = 'https://registry.npmjs.org/sfp-hive/latest';
+const UPDATE_CHECK_INTERVAL_MS = 30 * 60 * 1000; // 30 minutes
+
+function getLatestReleaseTag(rootDir) {
+  const res = spawnSync('git', ['-C', rootDir, 'tag', '-l', 'v*'], { encoding: 'utf-8' });
+  if (res.status === 0 && res.stdout) {
+    const lines = res.stdout.trim().split(/\r?\n/);
+    const tags = [];
+    for (const line of lines) {
+      const m = line.trim().match(/^v(\d+)\.(\d+)\.(\d+)$/);
+      if (m) {
+        tags.push({
+          raw: line.trim(),
+          sem: [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)]
+        });
+      }
+    }
+    tags.sort((a, b) => {
+      for (let i = 0; i < 3; i++) {
+        if (b.sem[i] !== a.sem[i]) return b.sem[i] - a.sem[i];
+      }
+      return 0;
+    });
+    if (tags.length > 0) return tags[0].raw;
+  }
+  return null;
+}
+
+// Whether release tag vX.Y.Z is newer than the SFP checked out in rootDir: an update never moves back to an older
+// release (the newest tag can lag behind main until the next release is tagged).
+function isNewerRelease(tag, rootDir) {
+  const m = (tag || '').match(/^v(\d+)\.(\d+)\.(\d+)$/);
+  if (!m) return false;
+  let mine = null;
+  try {
+    const v = JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf-8')).version || '';
+    const mm = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (mm) mine = [1, 2, 3].map((i) => parseInt(mm[i], 10));
+  } catch {}
+  if (!mine) return true;
+  for (let i = 0; i < 3; i++) {
+    const t = parseInt(m[i + 1], 10);
+    if (t !== mine[i]) return t > mine[i];
+  }
+  return false;
+}
+
+function findPython() {
+  const candidates = process.platform === 'win32'
+    ? ['python3', 'python', 'py -3', 'py']
+    : ['python3', 'python'];
+
+  for (const cmd of candidates) {
+    try {
+      const parts = cmd.split(' ');
+      const bin = parts[0];
+      const testArgs = parts.slice(1).concat(['-c', 'import sys; sys.exit(0 if sys.version_info >= (3, 8) else 1)']);
+      const res = spawnSync(bin, testArgs, { stdio: 'ignore' });
+      if (res.status === 0) {
+        return { bin, extraArgs: parts.slice(1) };
+      }
+    } catch {
+      // Continue to next candidate
+    }
+  }
+  return null;
+}
+
+function getUpdateCachePath() {
+  const dir = path.join(os.homedir(), '.sfp');
+  return path.join(dir, 'update_check.json');
+}
+
+function readUpdateCache() {
+  try {
+    const file = getUpdateCachePath();
+    if (fs.existsSync(file)) {
+      return JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+  } catch {}
+  return { lastChecked: 0, hasUpdate: false };
+}
+
+function writeUpdateCache(data) {
+  try {
+    const file = getUpdateCachePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(data, null, 2), 'utf-8');
+  } catch {}
+}
+
+function fetchJson(url, headers = {}) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, {
+      headers: {
+        'User-Agent': 'sfp-cli',
+        ...headers
+      },
+      timeout: 4000
+    }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return resolve(fetchJson(res.headers.location, headers));
+      }
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode}`));
+      }
+      let raw = '';
+      res.on('data', chunk => { raw += chunk; });
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(raw));
+        } catch (e) {
+          reject(e);
+        }
+      });
+    });
+    req.on('error', reject);
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error('timeout'));
+    });
+  });
+}
+
+function isSemverNewer(remote, local) {
+  if (!remote || !local) return false;
+  const parse = v => (String(v).replace(/^v/, '').split('.').map(x => parseInt(x, 10) || 0));
+  const r = parse(remote);
+  const l = parse(local);
+  for (let i = 0; i < 3; i++) {
+    const rv = r[i] || 0;
+    const lv = l[i] || 0;
+    if (rv > lv) return true;
+    if (rv < lv) return false;
+  }
+  return false;
+}
+
+async function checkRemoteUpdate(rootDir) {
+  let remoteCommit = '';
+  let localCommit = '';
+  let remoteVersion = '';
+  let localVersion = '';
+  let hasUpdate = false;
+
+  // 1. Check local commit / version
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(PKG_DIR, 'package.json'), 'utf-8'));
+    localVersion = pkg.version || '';
+  } catch {}
+
+  if (fs.existsSync(path.join(rootDir, '.git'))) {
+    const rev = spawnSync('git', ['-C', rootDir, 'rev-parse', 'HEAD'], { encoding: 'utf-8' });
+    if (rev.status === 0 && rev.stdout) {
+      localCommit = rev.stdout.trim();
+    }
+  }
+
+  // 2. Check GitHub remote commit
+  try {
+    const commitData = await fetchJson(GITHUB_API_COMMITS);
+    if (commitData && commitData.sha) {
+      remoteCommit = commitData.sha;
+      if (localCommit && !remoteCommit.startsWith(localCommit) && !localCommit.startsWith(remoteCommit)) {
+        hasUpdate = true;
+      }
+    }
+  } catch {}
+
+  // 3. Check npm registry version
+  try {
+    const npmData = await fetchJson(NPM_REGISTRY_LATEST);
+    if (npmData && npmData.version) {
+      remoteVersion = npmData.version;
+      if (localVersion && isSemverNewer(remoteVersion, localVersion)) {
+        hasUpdate = true;
+      }
+    }
+  } catch {}
+
+  const cache = {
+    lastChecked: Date.now(),
+    hasUpdate,
+    remoteCommit: remoteCommit.slice(0, 7),
+    localCommit: localCommit.slice(0, 7),
+    remoteVersion,
+    localVersion
+  };
+
+  writeUpdateCache(cache);
+  return cache;
+}
+
+function spawnBackgroundUpdateCheck(rootDir) {
+  try {
+    const child = spawn(process.execPath, [__filename, '__bg_check_update', rootDir], {
+      detached: true,
+      stdio: 'ignore'
+    });
+    child.unref();
+  } catch {}
+}
+
+function printUpdateNotice(info) {
+  const localRef = info.localVersion || (info.localCommit ? info.localCommit.slice(0, 7) : 'installed');
+  const remoteRef = info.remoteVersion || (info.remoteCommit ? info.remoteCommit.slice(0, 7) : 'latest');
+  const line1 = `  Update available! SFP repository has updates: ${localRef} -> ${remoteRef}  `;
+  const line2 = `  Run 'sfp update' or 'npx sfp-hive update' to automatically update.  `;
+  const len = Math.max(line1.length, line2.length);
+  const border = '─'.repeat(len);
+  const pad1 = ' '.repeat(len - line1.length);
+  const pad2 = ' '.repeat(len - line2.length);
+
+  console.error('\n\x1b[33m┌' + border + '┐\x1b[0m');
+  console.error('\x1b[33m│\x1b[0m\x1b[1m\x1b[32m' + line1 + pad1 + '\x1b[0m\x1b[33m│\x1b[0m');
+  console.error('\x1b[33m│\x1b[0m\x1b[36m' + line2 + pad2 + '\x1b[0m\x1b[33m│\x1b[0m');
+  console.error('\x1b[33m└' + border + '┘\x1b[0m\n');
+}
+
+function handleUpdate(rootDir, py, args) {
+  console.error('\x1b[1m\x1b[36m=== SFP Updater ===\x1b[0m\n');
+  const git = (...a) => spawnSync('git', ['-C', rootDir, '-c', 'core.longpaths=true', ...a], { encoding: 'utf-8' });
+
+  // 1. Pull latest repository changes
+  if (fs.existsSync(path.join(rootDir, '.git'))) {
+    console.error('\x1b[36m[1/3] Pulling latest repository updates from GitHub...\x1b[0m');
+    const status = git('status', '--porcelain').stdout.trim();
+    if (status) {
+      console.error('\x1b[33m  Note: Working directory has local modifications; skipping git checkout to preserve local edits.\x1b[0m');
+    } else {
+      console.error('  Fetching release tags...');
+      git('fetch', '--tags', 'origin');
+      const latestTag = getLatestReleaseTag(rootDir);
+      if (latestTag) {
+        const curr = git('describe', '--tags', '--exact-match');
+        const currTag = (curr.stdout || '').trim();
+        if (currTag === latestTag) {
+          console.error(`  \x1b[32m✔ Already on latest release tag ${latestTag}.\x1b[0m`);
+        } else if (!isNewerRelease(latestTag, rootDir)) {
+          console.error(`  \x1b[32m✔ This copy is already newer than the latest release tag ${latestTag}; staying on it.\x1b[0m`);
+        } else {
+          console.error(`  Checking out latest release tag ${latestTag}...`);
+          const co = git('checkout', latestTag);
+          if (co.status === 0) {
+            console.error(`  \x1b[32m✔ Checked out latest release tag ${latestTag}.\x1b[0m`);
+          } else {
+            console.error('  \x1b[33mWarning: git checkout failed:\x1b[0m', (co.stderr || co.stdout).trim());
+          }
+        }
+      } else {
+        console.error('  No release tags found matching vX.Y.Z.');
+      }
+    }
+  } else {
+    console.error('\x1b[36m[1/3] SFP directory is not a git repository; skipping git pull.\x1b[0m');
+  }
+
+  // 2. Refresh installed skills in detected IDEs
+  console.error('\n\x1b[36m[2/3] Refreshing installed skills into detected IDEs and tools...\x1b[0m');
+  const installScript = path.join(rootDir, 'scripts', 'install.py');
+  const passArgs = args.filter(a => a !== 'update');
+  const installRes = spawnSync(py.bin, [...py.extraArgs, installScript, 'install', ...passArgs], {
+    cwd: rootDir,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      PYTHONIOENCODING: 'utf-8',
+      PYTHONUTF8: '1',
+      PYTHONPATH: [path.join(rootDir, 'mcp'), process.env.PYTHONPATH].filter(Boolean).join(path.delimiter)
+    }
+  });
+
+  // 3. Check npm package status
+  console.error('\n\x1b[36m[3/3] Checking npm CLI package status...\x1b[0m');
+  try {
+    const npmOutdated = spawnSync('npm', ['outdated', '-g', 'sfp-hive', '--json'], { encoding: 'utf-8' });
+    if (npmOutdated.stdout && npmOutdated.stdout.includes('sfp-hive')) {
+      console.error('\x1b[33m  Notice: A newer sfp-hive npm package is available!\x1b[0m');
+      console.error('  Run: \x1b[32mnpm install -g sfp-hive\x1b[0m to update the global binary.\n');
+    } else {
+      console.error('  \x1b[32m✔ npm CLI package is up to date.\x1b[0m');
+    }
+  } catch {}
+
+  // Reset update check cache
+  writeUpdateCache({
+    lastChecked: Date.now(),
+    hasUpdate: false,
+    remoteCommit: '',
+    localCommit: ''
+  });
+
+  console.error('\n\x1b[1m\x1b[32m✔ SFP is fully up to date!\x1b[0m\n');
+  process.exit(installRes.status ?? 0);
+}
+
+function resolveSfpRoot() {
+  // 1. If running inside a full SFP repository checkout, use it directly
+  if (fs.existsSync(path.join(PKG_DIR, 'catalog.json')) && fs.existsSync(path.join(PKG_DIR, 'mcp', 'sfp_hive.py'))) {
+    return PKG_DIR;
+  }
+
+  // 2. Check ~/.sfp/root pointer written by install.py
+  const rootPointer = path.join(os.homedir(), '.sfp', 'root');
+  if (fs.existsSync(rootPointer)) {
+    try {
+      const pointed = fs.readFileSync(rootPointer, 'utf-8').trim();
+      if (pointed && fs.existsSync(path.join(pointed, 'catalog.json'))) {
+        return pointed;
+      }
+    } catch {}
+  }
+
+  // 3. Otherwise use ~/.sfp/SFP (or $SFP_ROOT / $SFP_DIR)
+  const defaultDir = path.join(os.homedir(), '.sfp', 'SFP');
+  const targetDir = process.env.SFP_ROOT || process.env.SFP_DIR || defaultDir;
+
+  if (!fs.existsSync(path.join(targetDir, '.git'))) {
+    console.error(`\x1b[36mSetting up SFP in ${targetDir}...\x1b[0m`);
+    fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+    // Clone main branch with automatic fallback
+    let cloneRes = spawnSync('git', ['clone', '--depth', '1', '--branch', 'main', '--config', 'advice.detachedHead=false', '--config', 'core.longpaths=true', REPO_URL, targetDir], {
+      stdio: ['ignore', 2, 2]
+    });
+    if (cloneRes.status !== 0) {
+      cloneRes = spawnSync('git', ['clone', '--depth', '1', '--config', 'advice.detachedHead=false', '--config', 'core.longpaths=true', REPO_URL, targetDir], {
+        stdio: ['ignore', 2, 2]
+      });
+    }
+    if (cloneRes.status !== 0) {
+      console.error(`\x1b[31mError: Failed to clone SFP repository from ${REPO_URL}.\x1b[0m`);
+      console.error('Please ensure git is installed and network access is available.');
+      process.exit(1);
+    }
+    console.error(`\x1b[32m✔ SFP setup complete in ${targetDir}.\x1b[0m`);
+  } else if (process.env.SFP_AUTO_UPDATE === '1' || process.env.SFP_AUTO_UPDATE === 'true') {
+    // Automatic update on launch when opt-in SFP_AUTO_UPDATE is enabled: move to latest release tag (never pull main)
+    const git = (...a) => spawnSync('git', ['-C', targetDir, '-c', 'core.longpaths=true', ...a], { encoding: 'utf-8' });
+    if (!git('status', '--porcelain').stdout.trim()) {
+      git('fetch', '--tags', 'origin');
+      const latestTag = getLatestReleaseTag(targetDir);
+      if (latestTag && isNewerRelease(latestTag, targetDir)) {
+        git('checkout', latestTag);
+      }
+    }
+  }
+
+  return targetDir;
+}
+
+function showHelp(skillCount) {
+  const countStr = skillCount ? `${skillCount} skills` : '894 skills';
+  console.log(`
+\x1b[1m\x1b[36mSFP (Skills for Productivity)\x1b[0m — ${countStr}, one intelligent hive.
+Give your AI coding agent the right skills for the job, not all of them.
+
+\x1b[1mUSAGE:\x1b[0m
+  \x1b[32mnpx sfp-hive\x1b[0m <command> [options]
+  \x1b[32msfp\x1b[0m <command> [options]
+
+\x1b[1mCOMMANDS:\x1b[0m
+  \x1b[33minstall\x1b[0m [options]     Install skills into detected IDEs (Antigravity, Claude, Cursor, VS Code, etc.)
+  \x1b[33mupdate\x1b[0m [options]      Pull latest repository updates and refresh skills in IDEs
+  \x1b[33mmcp\x1b[0m [options]         Run the SFP MCP server on stdio (or register with --tools <ide>)
+  \x1b[33mrules\x1b[0m [options]       Add standing instructions to use SFP skills on substantial tasks
+  \x1b[33mselect\x1b[0m "<task>"      Ask the hive which skills to load for a task
+  \x1b[33mneeds\x1b[0m "<task>"       Check what capabilities or external tools a task needs
+  \x1b[33mdoctor\x1b[0m              Check catalog, index, local models, and hive connections
+  \x1b[33mroute\x1b[0m [args]          Manage or start the local model router (Ollama, LM Studio, etc.)
+  \x1b[33mmodels\x1b[0m [probe|add|remove] The models the hive asks: local ones found, plus any you add by API
+  \x1b[33mtaste\x1b[0m [--reset]        Learned facet preferences (output forms, delivery style, depth)
+  \x1b[33mmentor\x1b[0m [profile|grow]  What you lean towards, and new skills grown from research for it
+  \x1b[33mresearch\x1b[0m [args]       Draft, refresh, approve or reject skills written from research papers
+  \x1b[33mapps\x1b[0m [args]           Manage companion apps (OmniRoute, Strix, etc.)
+  \x1b[33mlist\x1b[0m                List categories and install profiles
+  \x1b[33mhelp\x1b[0m                Show this help message
+
+\x1b[1mEXAMPLES:\x1b[0m
+  $ \x1b[32mnpx sfp-hive install\x1b[0m                      # Install starter set into every IDE found
+  $ \x1b[32mnpx sfp-hive update\x1b[0m                       # Automatically pull latest repo updates & skills
+  $ \x1b[32mnpx sfp-hive install --profile backend-dev\x1b[0m # Install backend-focused skills
+  $ \x1b[32mnpx sfp-hive mcp --tools antigravity,cursor\x1b[0m # Register MCP server in IDEs
+  $ \x1b[32mnpx sfp-hive select "write unit tests"\x1b[0m     # See which skills the hive recommends
+  $ \x1b[32mnpx sfp-hive doctor\x1b[0m                        # Verify health of catalog, index, and models
+
+\x1b[1mUSE IN MCP CLIENTS (mcp.json):\x1b[0m
+  {
+    "mcpServers": {
+      "sfp": {
+        "command": "npx",
+        "args": ["-y", "sfp-hive", "mcp"]
+      }
+    }
+  }
+
+Docs & Source: \x1b[4mhttps://github.com/siddu1004/SFP\x1b[0m
+`);
+}
+
+function run() {
+  // Internal background worker for async update check
+  if (process.argv[2] === '__bg_check_update') {
+    const rootDir = process.argv[3] || PKG_DIR;
+    checkRemoteUpdate(rootDir).then(() => process.exit(0)).catch(() => process.exit(0));
+    return;
+  }
+
+  const py = findPython();
+  if (!py) {
+    console.error('\x1b[31mError: Python 3.8+ is required to run SFP.\x1b[0m');
+    console.error('Please install Python 3 from https://www.python.org/downloads/ and ensure it is on your PATH.');
+    process.exit(1);
+  }
+
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  const rootDir = resolveSfpRoot();
+
+  // Read skill count from catalog for dynamic help display
+  let skillCount = null;
+  try {
+    const catPath = path.join(rootDir, 'catalog.json');
+    if (fs.existsSync(catPath)) {
+      const cat = JSON.parse(fs.readFileSync(catPath, 'utf-8'));
+      if (cat.skills) {
+        skillCount = Object.keys(cat.skills).length;
+      }
+    }
+  } catch {}
+
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    showHelp(skillCount);
+    process.exit(0);
+  }
+
+  // Handle explicit update command
+  if (command === 'update') {
+    handleUpdate(rootDir, py, args);
+    return;
+  }
+
+  // Background update check & notification
+  const cache = readUpdateCache();
+  if (Date.now() - (cache.lastChecked || 0) > UPDATE_CHECK_INTERVAL_MS) {
+    spawnBackgroundUpdateCheck(rootDir);
+  } else if (cache.hasUpdate) {
+    // Print notification to stderr (never interferes with MCP stdio stream)
+    printUpdateNotice(cache);
+  }
+
+  let targetScript = null;
+  let targetArgs = [];
+
+  switch (command) {
+    case 'mcp':
+      if (args.slice(1).some((a) => a === '--tools' || a === '--project' || a === '--remove' || a.startsWith('--tools='))) {
+        targetScript = path.join(rootDir, 'scripts', 'install.py');
+        targetArgs = ['mcp', ...args.slice(1)];
+      } else {
+        targetScript = path.join(rootDir, 'mcp', 'sfp_mcp.py');
+        targetArgs = args.slice(1);
+      }
+      break;
+
+    case 'select':
+    case 'live':
+    case 'track':
+    case 'feedback':
+    case 'clusters':
+    case 'library':
+    case 'bundles':
+      targetScript = path.join(rootDir, 'mcp', 'sfp_hive.py');
+      targetArgs = args;
+      break;
+
+    case 'needs':
+      targetScript = path.join(rootDir, 'mcp', 'sfp_hive.py');
+      targetArgs = ['needs', ...args.slice(1)];
+      break;
+
+    case 'doctor':
+      targetScript = path.join(rootDir, 'mcp', 'sfp_hive.py');
+      targetArgs = ['doctor', ...args.slice(1)];
+      break;
+
+    case 'route':
+      targetScript = path.join(rootDir, 'mcp', 'sfp_route.py');
+      targetArgs = args.slice(1);
+      break;
+
+    case 'models':
+      targetScript = path.join(rootDir, 'mcp', 'sfp_intent.py');
+      targetArgs = args.length > 1 ? args.slice(1) : ['models'];
+      break;
+
+    case 'taste':
+      targetScript = path.join(rootDir, 'mcp', 'sfp_hive.py');
+      targetArgs = ['taste', ...args.slice(1)];
+      break;
+    case 'mentor':
+      targetScript = path.join(rootDir, 'mcp', 'sfp_mentor.py');
+      targetArgs = args.length > 1 ? args.slice(1) : ['profile'];
+      break;
+
+    case 'research':
+      targetScript = path.join(rootDir, 'mcp', 'sfp_research.py');
+      targetArgs = args.slice(1);
+      break;
+
+    case 'install':
+    case 'list':
+    case 'uninstall':
+    case 'rules':
+    case 'apps':
+      targetScript = path.join(rootDir, 'scripts', 'install.py');
+      targetArgs = [command, ...args.slice(1)];
+      break;
+
+    default:
+      if (command.startsWith('-')) {
+        targetScript = path.join(rootDir, 'scripts', 'install.py');
+        targetArgs = ['install', ...args];
+      } else {
+        console.error(`\x1b[31mUnknown command:\x1b[0m ${command}\n`);
+        showHelp(skillCount);
+        process.exit(1);
+      }
+      break;
+  }
+
+  const env = {
+    ...process.env,
+    PYTHONIOENCODING: 'utf-8',
+    PYTHONUTF8: '1',
+    PYTHONPATH: [path.join(rootDir, 'mcp'), process.env.PYTHONPATH].filter(Boolean).join(path.delimiter)
+  };
+
+  const finalArgs = [...py.extraArgs, targetScript, ...targetArgs];
+  const child = spawn(py.bin, finalArgs, {
+    cwd: rootDir,
+    stdio: 'inherit',
+    env
+  });
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code ?? 0);
+    }
+  });
+
+  child.on('error', (err) => {
+    console.error(`\x1b[31mFailed to start process:\x1b[0m ${err.message}`);
+    process.exit(1);
+  });
+}
+
+run();

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "sfp-hive",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.19.0",
+  "description": "Give your AI coding agent the right skills for the job, not all of them. Curated library of 800+ agent skills across 16 IDEs with an intelligent hive that selects, orders, and learns from feedback.",
+  "author": "siddu1004",
+  "license": "MIT",
+  "homepage": "https://github.com/siddu1004/SFP#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/siddu1004/SFP.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/siddu1004/SFP/issues"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "skills",
+    "mcp",
+    "claude-code",
+    "cursor",
+    "antigravity",
+    "copilot",
+    "developer-tools",
+    "productivity",
+    "hive",
+    "vibecoding"
+  ],
+  "main": "./bin/sfp.js",
+  "bin": {
+    "sfp": "./bin/sfp.js",
+    "sfp-hive": "./bin/sfp.js"
+  },
+  "preferGlobal": true,
+  "scripts": {
+    "start": "node ./bin/sfp.js",
+    "sfp": "node ./bin/sfp.js",
+    "update": "node ./bin/sfp.js update",
+    "doctor": "node ./bin/sfp.js doctor",
+    "test": "node ./bin/sfp.js doctor"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}