@heytherevibin/skillforge 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.2.1
+
+- Same code as **0.2.0**. **npm never allows reusing a version** after it has been published once—even if you **unpublish** it and only **0.1.0** remains visible. The registry still blocks **`0.2.0`**; ship **`0.2.1`** (or higher) instead.
+
+## 0.2.0
+
+- **`skillforge route`**: CLI parity with MCP **`route_skills`** (same `build_router_and_skills` + `run_route_turn` pipeline); optional **`--project-root`**, **`--session-id`**, **`--user-id`**, **`--json-meta`**.
+- **`app.db_paths`**: **`global_db_path`** / **`resolve_orchestrator_db`** extracted for lightweight tests and reuse.
+- **MCP**: **`MCPServer.setup`** now uses **`build_router_and_skills`** (single router construction path with the CLI).
+- **CI**: **`pytest`** over **`python/tests/`** (no full ML install for DB path tests); **`py_compile`** includes **`db_paths.py`** and **`route_cli.py`**.
+
+## 0.1.0
+
+Initial public npm release: MCP stdio server, optional HTTP API, bundled skill catalog, per-project **`.skillforge/orchestrator.db`**, **`skillforge events`**, learning loop.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,34 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others’ private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Project maintainers may remove, edit, or reject comments, commits, code, and other contributions that are not aligned with this Code of Conduct, or ban temporarily or permanently any contributor for other conduct they deem inappropriate, threatening, offensive, or harmful.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the maintainers via GitHub (issue or direct message, as offered). All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1,
+available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

package/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+Thanks for helping improve skillforge.
+
+## How to contribute
+
+1. **Fork** the repository and create a branch from `main`.
+2. Make focused changes; match existing style in the touched files.
+3. Run local checks before pushing:
+   ```bash
+   node --check bin/cli.js && node --check lib/packs.js
+   npm test
+   ```
+4. Open a **pull request** into `main` with a clear description of the change and why.
+
+Pull requests should pass the **CI** workflow (see [RELEASING.md](RELEASING.md)).
+
+## Branch protection (maintainers)
+
+For an “enterprise-style” mainline, enable in GitHub: **Settings → Branches → Add rule** for `main`:
+
+- Require a pull request before merging
+- Require status checks to pass before merging (add **CI** / `verify`)
+- Optionally: require reviews, disallow force pushes
+
+This is configured in the GitHub UI; it is not stored in this repo.
+
+## Releases
+
+Maintainers: follow [RELEASING.md](RELEASING.md) for version bumps, tags, **`NPM_TOKEN`**, and npm **2FA**.
+
+## Code of conduct
+
+Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Report problems to the maintainers.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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

@@ -0,0 +1,337 @@
+# Skillforge
+
+<p align="left">
+  <a href="https://www.npmjs.com/package/@heytherevibin/skillforge"><img src="https://img.shields.io/npm/v/@heytherevibin/skillforge?label=npm&color=blue" alt="npm version" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT" /></a>
+  <a href="https://github.com/heytherevibin/skillforge/actions/workflows/ci.yml"><img src="https://github.com/heytherevibin/skillforge/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+</p>
+
+**Skillforge** is a **skill orchestration co-tool for Claude** (and other MCP hosts). It keeps a catalog of **`SKILL.md`** skills, **routes** the few that match each task using **local embeddings** and an optional **Haiku** step, and returns their bodies for **injection into the host model**. Optional **SQLite** learning improves routing over time.
+
+**Primary interface:** **stdio MCP** (`skillforge mcp`) — add it to Claude Desktop, Cursor, or Claude Code.
+
+**Optional:** **headless HTTP API** (`skillforge start`) for `/chat`, `/events`, and integrations. **Real-time usage:** run **`skillforge events --watch`** in a terminal (top skills, active sessions, and live **route** / **feedback** lines from SQLite).
+
+---
+
+## Table of contents
+
+- [Why Skillforge](#why-skillforge)
+- [Requirements](#requirements)
+- [Quick start](#quick-start)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Run modes](#run-modes)
+  - [Model Context Protocol (MCP)](#model-context-protocol-mcp)
+  - [Multi-user authentication](#multi-user-authentication)
+- [Skills and packs](#skills-and-packs)
+- [Routing pipeline](#routing-pipeline)
+- [Configuration](#configuration)
+- [HTTP API](#http-api)
+- [Local data and operations](#local-data-and-operations)
+- [Security considerations](#security-considerations)
+- [Contributing and governance](#contributing-and-governance)
+- [Releases and maintainers](#releases-and-maintainers)
+- [License](#license)
+
+---
+
+## Why Skillforge
+
+| Capability | Description |
+|------------|-------------|
+| **Focused context** | Injects only a small set of skill documents per turn instead of the full catalog. |
+| **Hybrid routing** | Embedding shortlist plus a fast **Claude Haiku** routing step for final selection. |
+| **Adaptation** | Re-routes when the conversation topic shifts (configurable threshold). |
+| **Learning loop** | Optional weights from usage and explicit feedback improve routing over time. |
+| **Observability** | **`skillforge events`**: snapshots of **usage** + **active sessions**, **`--watch`** for realtime; **`--verbose`** for route detail. No browser UI. |
+| **Project bootstrap** | MCP tools **`materialize_project`** and **`skillforge_bootstrap`** write `.cursor/rules`, **`docs/SKILLFORGE-PRD.md`**, and a **`CLAUDE.md`** section (map **`/skillforge`** in rules to MCP tools). |
+| **Extensibility** | Custom skills, git-based **packs**, and overrides under a single user config directory. |
+| **Deployment flexibility** | **MCP stdio** (default story), optional **HTTP API**, dev **`skillforge chat`** harness. |
+
+Bundled content includes **200+** curated skills (coding, security, research, frontend/backend patterns, and more). Exact counts are validated in CI.
+
+---
+
+## Requirements
+
+| Dependency | Version | Notes |
+|------------|---------|--------|
+| **Node.js** | **>= 18** | Required for the CLI bootstrapper. Continuous integration runs on **Node 22**. |
+| **Python** | **>= 3.10** | Used on the host PATH for embeddings and the FastAPI orchestrator. |
+| **Anthropic API** | — | **`ANTHROPIC_API_KEY`** is required for **HTTP**, **CLI chat**, and the **full** (Haiku) router. **MCP** can run **without** it when using **embedding-only** routing (default when the key is omitted; see [MCP](#model-context-protocol-mcp)). |
+
+**First run:** The CLI creates **`~/.skillforge/`**, a dedicated **Python venv**, installs Python dependencies, and caches the default embedding model (typically on the order of one to two minutes once; subsequent starts are fast).
+
+---
+
+## Quick start
+
+```bash
+npx --yes @heytherevibin/skillforge --help
+```
+
+Add Skillforge to your MCP config (see [MCP](#model-context-protocol-mcp)). No `ANTHROPIC_API_KEY` is required for **embedding-only** routing.
+
+Optional HTTP API (e.g. for `skillforge chat`): set **`ANTHROPIC_API_KEY`**, then:
+
+```bash
+skillforge start
+```
+
+Live log (usage + routes): **`skillforge events --watch`**.
+
+---
+
+## Installation
+
+**One-shot (recommended for evaluation)**
+
+```bash
+npx --yes @heytherevibin/skillforge --help
+```
+
+**Global install**
+
+```bash
+npm install -g @heytherevibin/skillforge
+skillforge --help
+```
+
+Package on npm: [@heytherevibin/skillforge](https://www.npmjs.com/package/@heytherevibin/skillforge).  
+Source and issues: [github.com/heytherevibin/skillforge](https://github.com/heytherevibin/skillforge).
+
+---
+
+## Usage
+
+### Run modes
+
+| Command | Purpose |
+|---------|---------|
+| `skillforge --help` | Recommended first step; **MCP** is the main integration. |
+| `skillforge mcp` | **stdio** MCP server (Claude, Cursor, …). |
+| `skillforge start [--port=8000]` | Optional **HTTP API** (no HTML or WebSocket UI). |
+| `skillforge events [--watch]` | **Terminal** log: usage snapshot + routes; see **`skillforge events --help`**. |
+| `skillforge route […]` | **Terminal** routing — same pipeline as MCP **`route_skills`** (loads embed model); see **`skillforge route --help`**. |
+| `skillforge mcp config [--local] [--with-anthropic]` | **stdout**: JSON snippet for **`mcp.json`** (merge manually). |
+| `skillforge chat` | Dev harness: HTTP client to **`POST /chat`** (needs **`start`** + API key). |
+
+### Model Context Protocol (MCP)
+
+You can run the MCP server **without** `ANTHROPIC_API_KEY`: routing uses **embeddings + shortlist only** (no Haiku call). The host still uses its own billing for the conversation.
+
+| `SKILLFORGE_ROUTER_MODE` | `ANTHROPIC_API_KEY` | MCP routing |
+|--------------------------|---------------------|-------------|
+| *(unset)* — auto | omitted | Embedding-only (keyless) |
+| *(unset)* — auto | set | Full router (Haiku) |
+| `embedding` | either | Embedding-only |
+| `full` | set recommended | Full router (Haiku); falls back on API errors |
+
+Add to your MCP host configuration (paths vary by product). Example for Claude Desktop on macOS (`claude_desktop_config.json`) **without** an extra API key:
+
+```json
+{
+  "mcpServers": {
+    "skillforge": {
+      "command": "npx",
+      "args": ["-y", "@heytherevibin/skillforge", "mcp"]
+    }
+  }
+}
+```
+
+With **Haiku** routing (uses your Anthropic key in the MCP process):
+
+```json
+{
+  "mcpServers": {
+    "skillforge": {
+      "command": "npx",
+      "args": ["-y", "@heytherevibin/skillforge", "mcp"],
+      "env": {
+        "ANTHROPIC_API_KEY": "sk-ant-..."
+      }
+    }
+  }
+}
+```
+
+**If the server shows as connected but lists “No tools”:** the MCP host only understands **JSON-RPC on stdout**. Older Skillforge builds printed setup text to **stdout**, which breaks **`tools/list`**. Update the npm package, run **`skillforge install`** once if needed, then **fully quit and reopen** Claude / Cursor. The CLI now sends banners and pip output to **stderr** only.
+
+**MCP tools exposed**
+
+| Tool | Purpose |
+|------|---------|
+| `route_skills` | Returns routed **`SKILL.md`** bodies. Pass **`project_root`** (workspace path) for per-repo SQLite under **`.skillforge/orchestrator.db`** and learning; or set env **`SKILLFORGE_PROJECT_ROOT`**. Optional **`session_id`**, **`user_id`** / **`SKILLFORGE_MCP_USER_ID`**. |
+| `list_skills` | Catalog overview; optional **`user_id`** scopes usage stats. |
+| `skill_feedback` | Feedback for the learning loop; optional **`user_id`**, **`session_id`** (for `/events`). |
+| `skill_referenced` | Mark a routed skill as **used** in the reply (increments **`referenced`** + weight; optional **`user_id`**). |
+| `disable_skill` | Toggle skills; optional **`user_id`**. |
+| `materialize_project` | Writes **`.cursor/rules/skillforge.mdc`**, **`docs/SKILLFORGE-PRD.md`**, updates **`CLAUDE.md`** (Skillforge block). Args: **`project_root`**, **`skill_names`** from **`route_skills`**. |
+| `skillforge_bootstrap` | **`route_skills`** + **`materialize_project`** in one call (needs **`project_root`**). |
+
+`/skillforge` is not registered by npm installs; add a **Cursor rule** or **CLAUDE.md** instruction so the agent calls these tools when the user asks.
+
+Route events go to **`~/.skillforge/data/orchestrator.db`**; use **`skillforge events`** or **`GET /events`** when HTTP is running.
+
+### Multi-user authentication
+
+Bearer tokens isolate sessions, weights, and events when enabled:
+
+```bash
+skillforge auth add <user-id>
+skillforge auth list
+skillforge auth remove <user-id>
+```
+
+When any token exists, protected **HTTP API** routes require **`Authorization: Bearer <token>`**. Single-user mode applies when no tokens are configured.
+
+---
+
+## Skills and packs
+
+**Bundled skills** ship inside the package. List them:
+
+```bash
+skillforge skills list
+```
+
+**Custom skill** layout: a directory containing **`SKILL.md`** with YAML frontmatter at minimum:
+
+```yaml
+---
+name: my-skill
+description: Clear trigger conditions—used by the router.
+---
+# My Skill
+```
+
+Register with `skillforge skills add ./my-skill` or copy the folder to **`~/.skillforge/skills/`**.
+
+**Skill packs** are git repositories with a root **`skillforge.json`** manifest listing skill folder names. Install:
+
+```bash
+skillforge pack install <org/repo>
+skillforge pack install https://example.com/repo.git
+skillforge pack list
+skillforge pack update <name>
+skillforge pack remove <name>
+```
+
+---
+
+## Routing pipeline
+
+```
+User prompt
+    → Local embeddings (sentence-transformers)
+    → Cosine similarity + per-user weights
+    → Top-K candidates
+    → Router model (Haiku) selects final active skills — *or* embedding-only mode takes top-N from candidates
+    → Skill bodies injected; response model answers (e.g. Opus)
+    → Usage signals update weights (optional)
+```
+
+Re-route: when overlap between successive active sets falls below a configurable threshold, the pipeline selects a new set for the next turn. Events are stored in SQLite; stream them with **`skillforge events --watch`** (or **`GET /events`** when HTTP is running).
+
+---
+
+## Configuration
+
+Environment variables (see also inline help and server defaults):
+
+| Variable | Default | Role |
+|----------|---------|------|
+| `ANTHROPIC_API_KEY` | — | **Required** for HTTP/CLI chat and answer streaming; **optional** for MCP if you use embedding-only routing (default when unset). |
+| `SKILLFORGE_ROUTER_MODE` | *(auto)* | `full` = always use Haiku for final pick (MCP: requires key for routing). `embedding` = skip Haiku; top `SKILLFORGE_MAX_ACTIVE` from shortlist. Unset = **auto**: MCP uses embedding-only when `ANTHROPIC_API_KEY` is absent, else full. HTTP: unset or `full` uses Haiku when key is present; set `embedding` to skip Haiku on the server (answer model still needs a key). |
+| `SKILLFORGE_PORT` | `8000` | HTTP listen port. |
+| `SKILLFORGE_EMBED_MODEL` | `all-MiniLM-L6-v2` | Embedding model id. |
+| `SKILLFORGE_ROUTER_MODEL` | `claude-haiku-4-5-20251001` | Routing model. |
+| `SKILLFORGE_ANSWER_MODEL` | `claude-opus-4-7` | Main response model. |
+| `SKILLFORGE_TOP_K` | `15` | Embedding shortlist size. |
+| `SKILLFORGE_MAX_ACTIVE` | `7` | Maximum skills injected per turn. |
+| `SKILLFORGE_REROUTE_THRESHOLD` | `0.4` | Re-route sensitivity (Jaccard distance). |
+| `SKILLFORGE_MCP_USER_ID` | `""` | Default logical **user id** for MCP tool calls when arguments omit `user_id` (weights, sessions, events—same SQLite namespace as HTTP `resolve_user`). |
+| `SKILLFORGE_PROJECT_ROOT` | `""` | Default workspace root when MCP **`project_root`** is omitted: events/weights/sessions live in **`<root>/.skillforge/orchestrator.db`**. Prefer passing **`project_root`** on each tool call from the host. |
+| `SKILLFORGE_SKILL_HOT_RELOAD` | `1` | When **`0`** / **`false`**, disable **SKILL.md** hot-reload; restart the MCP process to refresh the catalog. |
+| `SKILLFORGE_WATCH_SKILLS_INTERVAL` | `30` | Seconds between background catalog checks when hot reload is on. **`0`**: no background polling and no MCP **`tools.listChanged`**; **`tools/list`** and **`tools/call`** still reload when files change. |
+| `SKILLFORGE_MCP_LIST_CHANGED` | `1` | When **`0`** / **`false`**, never emit **`notifications/tools/list_changed`** (and **`listChanged`** is not advertised), even if a background interval is set. |
+
+---
+
+## HTTP API
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/chat` | Primary chat; SSE stream. |
+| `POST` | `/feedback` | Skill feedback for learning. |
+| `POST` | `/skills/disable` | Enable/disable a skill flag. |
+| `GET` | `/skills` | Catalog with stats and weights. |
+| `GET` | `/events` | Recent routing events (`?limit=`). |
+| `GET` | `/` | JSON service hint (use **`skillforge events --watch`** for a live terminal log). |
+| `GET` | `/healthz` | Health metadata (`skills_loaded`, **`live_log`** hint). |
+
+Authenticated mode applies **`Bearer`** tokens as described above. Do not expose unauthenticated instances beyond trusted networks.
+
+---
+
+## Local data and operations
+
+Optional **per-project** state (when **`project_root`** or **`SKILLFORGE_PROJECT_ROOT`** is set, or MCP passes **`project_root`** on tools):
+
+```
+<workspace>/.skillforge/
+├── orchestrator.db   # SQLite for this repo (sessions, weights, events)
+└── last_route.json   # Last route_skills snapshot (after a routed call)
+```
+
+Global default when no project root:
+
+```
+~/.skillforge/
+├── venv/                 # Python virtual environment
+├── data/orchestrator.db  # SQLite (sessions, weights, events)
+├── skills/               # User-added skills
+├── packs/<hash>/         # Cloned pack repositories
+├── packs.json            # Pack registry
+└── auth.json             # Tokens (POSIX mode 0600 when used)
+```
+
+| Command | Effect |
+|---------|--------|
+| `skillforge events` | Prints a **usage** snapshot and recent **`route`** / **`feedback`** rows; **`--watch`**, **`--project-root`** (per-repo DB), **`--user`**, **`--verbose`** (see **`--help`**). |
+| `skillforge reset` | Clears learning state and event history in the database. |
+| `skillforge install` | Re-runs bootstrap (venv and dependencies). |
+| `rm -rf ~/.skillforge` | Full removal of local state and venv. |
+
+---
+
+## Security considerations
+
+- Treat **`ANTHROPIC_API_KEY`** and bearer tokens as **secrets**. Prefer environment injection or secret stores, not committed files.
+- For **internet-facing** deployments, use **TLS**, **reverse proxies**, and **mandatory** bearer authentication; assume an open HTTP port is reachable by untrusted clients.
+- Vulnerability disclosure: see **[SECURITY.md](SECURITY.md)**.
+
+---
+
+## Contributing and governance
+
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — workflow, local checks, branch policy expectations.
+- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — community standards.
+- **[SECURITY.md](SECURITY.md)** — reporting security issues.
+
+---
+
+## Releases and maintainers
+
+- **Continuous integration:** `.github/workflows/ci.yml` (push and pull request to **`main`**).
+- **Release & npm publish:** **Skillforge release** runs when you push tag **`vX.Y.Z`** and **`package.json`** **`version`** is exactly **`X.Y.Z`** (e.g. **`v0.2.1`** ↔ **`0.2.1`**). That same number is what **`npm publish`** ships. GitHub releases are titled **`Skillforge <tag>`**.
+- **Procedure and npm tokens:** **[RELEASING.md](RELEASING.md)** (granular npm access tokens, **Bypass 2FA** for CI publish where applicable).
+- **License:** MIT — see **[LICENSE](LICENSE)**.
+
+---
+
+## License
+
+MIT © see [LICENSE](LICENSE).

package/RELEASING.md

@@ -0,0 +1,93 @@
+# Releasing skillforge
+
+## CI vs Release workflows
+
+| Workflow | File | When it runs |
+|----------|------|----------------|
+| **CI** | [.github/workflows/ci.yml](.github/workflows/ci.yml) | Every **push** and **pull request** to `main`; also **`workflow_dispatch`** (run manually from the Actions tab) |
+| **Skillforge release** | [.github/workflows/release.yml](.github/workflows/release.yml) | When a **`v*`** tag is **pushed** to the repository (e.g. `v0.2.1`) |
+
+In the GitHub UI, open **Actions** and look for **CI** and **Skillforge release** (not the older “publish to npm” name).
+
+## Keep GitHub and npm on the same version
+
+- **One release = one number:** The git tag (`v0.2.1`), **`package.json` `version`** (`0.2.1`), the **MCP** `serverInfo.version`, and the tarball npm serves must all use that **same** semver.
+- **Skillforge release** fails if `vX.Y.Z` ≠ `package.json` `X.Y.Z` (see the “Verify tag matches” step in [release.yml](.github/workflows/release.yml)).
+- **npm** will not accept a version that was ever published before (even after unpublish). If **`npm publish`** fails with “previously published”, **bump** `package.json` to a **new unused** version, commit to **`main`**, then push a **new** tag **`v` + that version** — do not reuse the blocked number.
+
+## Verify Actions without cutting a release
+
+1. Push any commit to `main`, or open a PR targeting `main`, and confirm the **CI** workflow turns green.
+2. Or go to **Actions → CI → Run workflow** (requires `workflow_dispatch` on `main`) and run against `main`.
+
+## Publish to npm and attach a GitHub Release (happy path)
+
+You need the **`NPM_TOKEN`** repository secret.
+
+**npm (2025+):** Legacy “classic” tokens (including the old **Automation** type) are **gone**. Use a [**granular access token**](https://docs.npmjs.com/about-access-tokens) with **read and write** permission for **`@heytherevibin`** / `@heytherevibin/skillforge`, and enable **Bypass 2FA** on that token. Without **Bypass 2FA**, `npm publish` in GitHub Actions often fails with **`EOTP`** because CI cannot enter an authenticator code.
+
+Create one at [npm → Access Tokens](https://www.npmjs.com/settings/~/tokens) (**Generate New Token** → **Granular Access Token**). Optionally explore [**trusted publishing** (OIDC)](https://docs.npmjs.com/trusted-publishers/) later to avoid long-lived tokens.
+
+1. On `main`, set **`version`** in `package.json` to the version you are releasing (must be **unused** on npm — e.g. `0.2.1`).
+2. Match **MCP** `serverInfo.version` in `python/app/mcp_server.py` and add a **`CHANGELOG.md`** section for that version.
+3. Commit and **`git push origin main`**. Wait for **CI** to pass.
+4. Create a tag whose name is **`v` + that exact version**:  
+   `git tag v0.2.1 && git push origin v0.2.1`
+5. Open **Actions → Skillforge release**. The job will **fail the version check** if the tag does not match `package.json`.
+6. Confirm on npm: `npm view @heytherevibin/skillforge version`  
+   Confirm the **GitHub Release** exists with title **`Skillforge <tag>`** (e.g. **`Skillforge v0.2.1`**) and the `.tgz` asset.
+
+Scoped packages require a **public** publish; the workflow already runs `npm publish --access public`.
+
+## Resetting npm and GitHub for a clean **0.1.0** line
+
+If older versions (e.g. **0.2.x**) were published and you want the public story to start at **0.1.0**:
+
+1. **npm:** Run `npm view @heytherevibin/skillforge versions --json`, then `npm unpublish @heytherevibin/skillforge@<version>` per published version you want removed ([unpublish policy](https://docs.npmjs.com/unpublishing-packages-from-the-registry) may block some). If unpublish fails, use `npm deprecate` or contact npm support. You **cannot** publish **0.1.0** if that version still exists on the registry—use **0.1.1** instead if needed.
+2. **GitHub:** Delete old **Releases**; delete remote tags, e.g. `git push origin :refs/tags/v0.2.2` (repeat for each).
+3. Set **`package.json`** **`version`** to **`0.1.0`** on **`main`**, push, then `git tag v0.1.0 && git push origin v0.1.0`.
+
+## Recover if a tag exists but npm was never updated
+
+Typical causes: the tag was created before **Skillforge release** existed on `main`, the tag was only created in the GitHub UI without a matching workflow run, or **`package.json` did not match the tag**.
+
+**Option A — reuse the same version (re-trigger Skillforge release)**
+
+1. Ensure `.github/workflows/release.yml` on `main` is the current one and **`package.json` `version`** matches the tag (without `v`).
+2. Delete the tag locally and on the remote, then push it again so GitHub emits a new `push` event for that tag:  
+   ```bash
+   git tag -d v0.1.0
+   git push origin :refs/tags/v0.1.0
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+**Option B — new version (cleanest)**
+
+1. Bump `version` in `package.json`, commit, push `main`.
+2. Push a **new** tag: `v` + new version.
+
+## Local sanity checks (before push)
+
+```bash
+node --check bin/cli.js && node --check lib/packs.js
+npm test
+```
+
+Python (syntax only):
+
+```bash
+for f in python/app/main.py python/app/cli.py python/app/mcp_server.py python/app/auth.py python/app/events_cli.py python/app/materialize.py python/app/db_paths.py python/app/route_cli.py; do python3 -m py_compile "$f"; done
+```
+
+## Troubleshooting: `EOTP` / one-time password in CI
+
+**Symptom:** `npm error code EOTP` / “This operation requires a one-time password from your authenticator.”
+
+**Cause:** The granular token in **`NPM_TOKEN`** does not have **Bypass 2FA** enabled (default is off), or it lacks write access to the package.
+
+**Fix:**
+
+1. On [npm → Access Tokens](https://www.npmjs.com/settings/~/tokens), create a **Granular Access Token** (or edit policy if npm allows): **Read and write**, scope **`@heytherevibin`**, **Bypass 2FA: on**.
+2. Update **`NPM_TOKEN`** in GitHub → **Settings → Secrets and variables → Actions**.
+3. Re-run the failed **Skillforge release** workflow, or delete and re-push the release tag (see “Recover if a tag exists…” above).

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are applied to the **latest** published minor release on the `main` branch. Older tags may not receive backports; upgrade to the current release when possible.
+
+## Reporting a vulnerability
+
+Please **do not** open a public GitHub issue for undisclosed security vulnerabilities.
+
+**Preferred:** use [GitHub Security Advisories](https://github.com/heytherevibin/skillforge/security/advisories/new) for this repository (if you have access).
+
+**Alternative:** open a **private** report via GitHub **Security → Report a vulnerability** on the repository, or contact the maintainer through a channel they publish on their GitHub profile.
+
+Include:
+
+- Description of the issue and impact
+- Steps to reproduce (if known)
+- Affected version or commit (if known)
+
+We aim to acknowledge valid reports within a few business days.
+
+## npm and supply chain
+
+- For **`NPM_TOKEN`** in GitHub Actions, use a [**granular access token**](https://docs.npmjs.com/about-access-tokens) with **read and write** to your scope and **Bypass 2FA** enabled, so **`npm publish`** does not return **`EOTP`**. Legacy automation/classic tokens are no longer available on npm as of 2025.
+- Keep **2FA** enabled on the npm account that owns the `@heytherevibin` scope.
+- Prefer pinning action versions or reviewing Dependabot PRs before merge.
+
+## Runtime hardening
+
+If you expose the HTTP server beyond **localhost**, treat it as internet-facing: use **bearer-token auth** (`skillforge auth …`), terminate TLS at a reverse proxy, and restrict network access appropriately. The default single-user setup assumes a trusted local environment.

package/STRATEGY.md

@@ -0,0 +1,26 @@
+# Skillforge strategy (Cursor-first)
+
+## Product intent
+
+Skillforge is an **npm-packaged skill orchestrator**: it routes tasks to a small set of **SKILL.md** documents (embeddings + optional Haiku) and returns their bodies for agent context. **Per-project** learning and telemetry live under **`<workspace>/.skillforge/`** when **`project_root`** (or **`SKILLFORGE_PROJECT_ROOT`**) is set; otherwise the global DB under **`~/.skillforge/data/`** is used.
+
+## Surfaces (today)
+
+- **MCP** (`skillforge mcp`): primary — `route_skills`, `list_skills`, feedback tools, `materialize_project`, `skillforge_bootstrap`.
+- **Terminal**: `skillforge events --watch` with optional **`--project-root`**.
+- **HTTP** (`skillforge start`): optional; still uses the global DB in **app_state** (not per-request project root unless extended later).
+
+## Cursor reality
+
+Native **`/skillforge`** in editor chat is **not** registered by this npm package. The practical pattern is **Cursor rules** (e.g. materialized **`skillforge.mdc`**) instructing the agent to call MCP tools; users may *say* `/skillforge` as shorthand.
+
+## Near-term backlog
+
+- Shared **`orchestrate()`** API for MCP + CLI parity.
+- HTTP: optional **`project_root`** header or body for `/chat` if needed.
+- Tests: MCP handshake + `resolve_orchestrator_db` behavior.
+
+## Non-goals (v1)
+
+- Auto-scanning every AI agent installed on the host.
+- VS Code extension (unless added as a separate track).