@heytherevibin/skillforge 0.10.0 → 0.11.7

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 0.11.7
+
+- **Python router:** Restore **`Router.__init__`** so skill embeddings, **`_by_name`**, hybrid/BM25, and chunk indexing initialize correctly (fixes **`AttributeError: 'Router' object has no attribute '_by_name'`** in **`route-eval`** / **`run_route_turn`** when router setup was mistakenly unreachable behind the **`anthropic`** accessor).
+- **Docs:** **`README`**, **`docs/`** guides, and **`RELEASING`** prose align release line **0.11.7** with **`package.json`**; MCP **`serverInfo.version`** sourcing is documented as **`python/app/npm_pkg_version.py`** (**`published_package_version()`**), not a duplicate field in **`mcp_server.py`**.
+
+## 0.11.6
+
+- **Documentation hub:** Added [`docs/`](docs/) with instructional guides (**[docs/README.md](docs/README.md)** lists them).
+- **README refreshed:** Repo root **`README.md`** is a compact hub (**npm**, **GitHub release**, **`package.json` on main**, CI, licence badges; links into **`docs/`**).
+- **npm package manifest:** **`docs/`** is included under **`files`** so published tarballs bundle the guides.
+- **Hygiene:** Added repository **`.gitignore`** covering **`__pycache__`**, **`*.pyc`**, **`.pytest_cache/`**.
+
+## 0.11.5
+
+- **`skillforge config validate`:** Lint **`~/.skillforge/env`** (errors exit **1**, missing profile exits **0**). Parser extracted to **`lib/user-env-profile.js`** (shared semantics with merge). **`npm test`** runs **`node --test ci/test-user-env-profile.cjs`**, **`skillforge config validate`**, plus **`skillforge --help`**.
+- **`skillforge mcp config --with-env`:** MCP snippet includes **`entry.env`** with **`SKILLFORGE_ROUTER_MODE=host`** (non-secret scaffold). **`--with-anthropic`** still replaces the **`env`** object entirely when both are passed.
+- **`SKILLFORGE_ROUTE_POLICIES` / file policies:** **`stderr`** warning when JSON is invalid (policies ignored); tests in **`python/tests/test_route_policies.py`**.
+- **README:** document **`validate`**, MCP **`--with-env`**, and that **`python -m app.*`** skips Node profile loading unless you replicate **`buildEnv`** yourself.
+- **CLI:** **`node bin/cli.js --help`** (and **`-h`** as the first argument) prints the same banner as **`skillforge --help`**.
+- **`capabilities` MCP bundle:** **`user_env_profile`** object with **`path_command`**, **`init_command`**, **`validate_command`**, **`file`** ( **`~/.skillforge/env`** ).
+
+## 0.11.4
+
+- **Operator env profile:** optional **`~/.skillforge/env`** dotenv-style file merged before **`process.env`** when spawning Python (**`skillforge config path`**, **`skillforge config init [--force]`**). Bootstrap **`SKILLFORGE_*_SKILLS`**, **`SKILLFORGE_DB_PATH`**, and **`PYTHONPATH`** still finalize last (**`bin/cli.js`**).
+- **`skillforge health`** reports **`user_env_profile`** (whether **`~/.skillforge/env`** exists). **`skillforge tips`** mentions **`skillforge config`** and the README configuration section.
+
+## 0.11.3
+
+- **MCP operator tools (read-only):** **`get_router_status`** — env + loaded router snapshot; **`project_index_status`** — project chunk counts / last index metadata (**`project_root`** required); **`weights_snapshot`** — same JSON shape as **`skillforge weights export`**; **`events_recent`** — recent SQLite events for **`user_id`** with optional **`event_type`** filter (**`_meta.rows`** capped at 100). Implementations in **`app/mcp_operator.py`**.
+
+## 0.11.2
+
+- **Routing calibration (`route_quality`):** Bump inner schema to **`route_quality/2`**. **`shortlist`** adds **`ambiguous`**, **`confidence_tier`** (`high`/`medium`/`low`), **`routing_score_margin`**, **`second_routing_score`**, and **`cosine_leader_matches_routing_top`** (alias of **`top1_dense_and_fused_agree`**). Tunables: **`SKILLFORGE_ROUTE_AMBIGUITY_COS_MARGIN`** (default `0.012`), **`SKILLFORGE_ROUTE_AMBIGUITY_ROUTE_MARGIN`** (default `0.018`), **`SKILLFORGE_ROUTE_AMBIGUITY_DISABLE`**. **`router.pick_diversify`** records optional per-source thinning (below).
+- **Pick diversify (opt-in):** When **`SKILLFORGE_PICK_DIVERSIFY=1`**, cap picks per **`source`** (**`bundled`** / **`user`**) via **`SKILLFORGE_PICK_MAX_PER_SOURCE`** (default **`2`**) **before** regex policy **`include`** merge. Applies to **`run_route_turn`** (MCP + CLI **`route`**) and **`explain_route`**.
+- **MCP contract:** **`MCP_RESPONSE_SCHEMA_VERSION` 1.8** (additive **`_meta`** semantics; embedded **`route_quality`** v2).
+
+## 0.11.1
+
+- **MCP `materialize_project` / `skillforge_bootstrap`:** Default **`hosts`** is **`auto`**. Resolution order when **`hosts`** is **`auto`** or omitted: **`SKILLFORGE_MATERIALIZE_HOSTS`** (**`both`**, **`cursor`**, or **`claude_code`**) if set, else MCP **`initialize`** **`clientInfo`** name/title (substring **`cursor`** → **`cursor`**, **`claude`** → **`claude_code`**), optional **`CURSOR_AGENT`** / **`CURSOR_TRACE_ID`** hints, else **`both`**. Explicit **`hosts: cursor`**, **`claude_code`**, or **`both`** on the tool always wins. Responses add **`hosts_resolution`** (**`explicit`**, **`environment`**, or **`inferred`**) plus **`hosts_requested`**, **`mcp_client_name`**, **`mcp_client_title`** in **`materialize`** **`_meta`**.
+
+## 0.11.0
+
+- **Breaking (routing default):** When **`SKILLFORGE_ROUTER_MODE` is unset**, Skillforge now defaults to **`host`** (two-step **`route_skills`**: shortlist, then **`picked_names`**). Restore the previous **auto** behavior (**Haiku in-process when **`ANTHROPIC_API_KEY`** is set**, else embedding-first) with **`SKILLFORGE_ROUTER_MODE=auto`** or an empty value. Use **`embedding`** or **`full`** as before.
+- **MCP config:** **`skillforge mcp config --with-anthropic`** now sets **`SKILLFORGE_ROUTER_MODE=auto`** together with the **`ANTHROPIC_API_KEY`** placeholder so the key is not ignored (default **host** mode does not call Anthropic).
+- **Refactor:** **`app/router_mode.py`** — **`normalise_skillforge_router_mode`**; unit tests in **`python/tests/test_router_mode_env.py`**.
+- **Docs / MCP tool text:** Describe default **host** routing and how to override (**README**, **`route_skills`** tool description).
+- **Global/project `/skillforge` command:** YAML **`description`** in frontmatter (**`cursor-skillforge-global.md`**, **`claude-code-skillforge-global.md`**, **`materialize_project`** Cursor command); **`<!-- skillforge-managed … -->`** moved to EOF so Composer no longer uses the HTML marker as tooltip text.
+- **`materialize_project`:** Optional **`hosts`**: **`cursor`**, **`claude_code`**, or **`both`** (default) — scaffold only the IDE folders you ask for instead of always writing **`.cursor/`** + **`.claude/`**.
+
+## 0.10.1
+
+- **README:** Clarify that **npm** **`latest`** and **`npm view`** are authoritative for semver; note CDN/browser cache can make the shields **npm** badge lag briefly after a publish. **Badge:** add **`cacheSeconds`** so the image URL refreshes sooner.
+
 ## 0.10.0
 
 - **CI:** Minimum bundled **`SKILL.md`** count is configured via **`ci/bundle-gate.json`** (`minSkillMdFiles`); **`.github/workflows/ci.yml`** reads that file. The **`ci/`** directory is included in the published package **`files`** list for transparency. Health + **route-eval** step chains both commands under a single **`cd python`** so the second command does not run from **`python/python`**.

package/CONTRIBUTING.md

@@ -6,10 +6,12 @@ Thank you for improving Skillforge.
 
 1. **Fork** the repository and create a branch from **`main`**.
 2. Keep changes **focused**; follow patterns in surrounding code.
-3. Run **local checks** before opening a PR from the **package root** (the directory that contains **`package.json`**):
+3. Operator / user-facing doc changes belong in **`docs/`** (`README.md` should stay the short hub + badges). Bump **`package.json`** / **`CHANGELOG.md`** when shipping user-visible doc releases.
+
+4. Run **local checks** before opening a PR from the **package root** (the directory that contains **`package.json`**):
 
    ```bash
-   node --check bin/cli.js && node --check lib/packs.js
+   node --check bin/cli.js && node --check lib/packs.js && node --check lib/user-env-profile.js
    npm test
    ```
 
@@ -23,7 +25,7 @@ Thank you for improving Skillforge.
 
    If you **intentionally** shrink or grow the bundled **`skills/`** tree below/above the current CI minimum, update **`ci/bundle-gate.json`** (`minSkillMdFiles`) and note it in the PR—see **[RELEASING.md](RELEASING.md)**.
 
-4. Open a **pull request** into **`main`** with:
+5. Open a **pull request** into **`main`** with:
    - What changed and **why**  
    - How you **verified** it (tests, manual MCP smoke, etc.)
 

package/README.md

@@ -1,378 +1,70 @@
 # 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="https://www.npmjs.com/package/@heytherevibin/skillforge"><img src="https://img.shields.io/npm/v/@heytherevibin/skillforge.svg?label=npm&logo=npm&logoColor=white&color=blue" alt="npm registry version" /></a>
+  <a href="https://github.com/heytherevibin/skillforge/releases/latest"><img src="https://img.shields.io/github/v/release/heytherevibin/skillforge?sort=semver&label=github%20release&logo=github&color=purple" alt="Latest GitHub release tag" /></a>
+  <a href="https://github.com/heytherevibin/skillforge/blob/main/package.json"><img src="https://img.shields.io/github/package-json/v/heytherevibin/skillforge?label=package.json%20%28main%29&logo=github" alt="package.json semver on GitHub default branch" /></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>
+  <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="GitHub Actions CI status" /></a>
 </p>
 
-**Skillforge** is a **local-first orchestration layer** for agent workflows: it maintains a catalog of **`SKILL.md`** documents, **routes** a small subset per task using **embedding-first retrieval**, optional **hybrid** sparse signals and **LLM** stages, optional **project-scoped** policies and notes, and returns **structured context** for downstream models. The **primary integration** is **stdio MCP**; the **CLI** provides parity, operations, and automation hooks.
+**Skillforge** is a **local-first** SKILL.md orchestration layer: embeddings pick a **small routed set** per task (optional hybrid + LLM stages), SQLite stores **sessions, learned weights, and events**, optional **project RAG** augments prompts, and the **production surface** is **stdio MCP**. A **Node** CLI (**`skillforge`**) bootstraps a managed **Python venv** under **`~/.skillforge/venv`**, merges **`~/.skillforge/env`**, mirrors MCP behaviours in **`skillforge route`**, **`skillforge tools`**, **`skillforge agent`**, and exposes operator CLIs (**`health`**, **`events`**, **`weights`**).
 
-**Published version:** see **`package.json`** and the npm badge above (they should match after each release). **Change history:** [CHANGELOG.md](CHANGELOG.md). **Product direction:** [STRATEGY.md](STRATEGY.md). **Vulnerability reporting:** [SECURITY.md](SECURITY.md). **Release process:** [RELEASING.md](RELEASING.md).
+**Semantic versions** should align across **`package.json`**, git tags (**`vX.Y.Z`**), MCP **`initialize.serverInfo.version`**, **npm tarball**, and the **GitHub Release** artifact—see [`RELEASING.md`](RELEASING.md). **Published line on `main`:** **`0.11.7`** (same value in **[`package.json` `version`](package.json#L3)** and **[`CHANGELOG`](CHANGELOG.md)** top section). The **`package.json`** shield tracks **`main`**; **`npm`** / **`release`** shields track **published** artefacts and may briefly lag immediately after tagging.
 
 ---
 
-## Table of contents
+## Documentation (start here)
 
-- [What Skillforge provides](#what-skillforge-provides)
-- [Architecture at a glance](#architecture-at-a-glance)
-- [Requirements](#requirements)
-- [Quick start](#quick-start)
-- [Installation](#installation)
-- [Operational interfaces](#operational-interfaces)
-- [Model Context Protocol (MCP)](#model-context-protocol-mcp)
-- [MCP response contract](#mcp-response-contract)
-- [Routing pipeline](#routing-pipeline)
-- [Route policies and project overlay](#route-policies-and-project-overlay)
-- [Project RAG](#project-rag)
-- [Learning, weights, and portability](#learning-weights-and-portability)
-- [Skills and packs](#skills-and-packs)
-- [Configuration](#configuration)
-- [Local data and paths](#local-data-and-paths)
-- [Security](#security)
-- [Contributing and governance](#contributing-and-governance)
-- [License](#license)
+| Guide | Audience |
+|-------|-----------|
+| [docs/README.md — index](docs/README.md) | Choose your path |
+| [Getting started](docs/getting-started.md) | Install MCP + sanity checks |
+| [Environment & configuration](docs/environment-and-configuration.md) | `~/.skillforge/env`, MCP host `entry.env`, and the full SKILLFORGE variable matrix |
+| [MCP integration](docs/mcp-integration.md) | Router modes (**`host`**, **`auto`**, …), tools, **`_meta`** |
+| [CLI reference](docs/cli-reference.md) | Subcommands (**`route`**, **`tools`**, **`agent`**, …) |
+| [Architecture & data](docs/architecture-and-data.md) | Pipeline, SQLite, policies, indexing |
+| [Troubleshooting](docs/troubleshooting.md) | Tools missing, npm **`EOTP`**, bad policy JSON |
 
----
-
-## What Skillforge provides
-
-| Area | Capability |
-|------|------------|
-| **Context control** | Returns only **relevant** skill (and optional project) chunks instead of an entire catalog. |
-| **Routing** | Dense embeddings on skill **cards** (title, description, optional triggers); optional **keyword / BM25** fusion; optional **LLM** rerank and final pick—or **embedding-only** or **host-delegated** selection. |
-| **Conversation-aware retrieval** | Recent turns can influence the **shortlist query** when enabled via environment (see [Configuration](#configuration)). |
-| **Governance** | Regex **policies** to append skills after routing; **project overlay** for excludes, score boosts, and **project notes** (notes require a declared **project root**). |
-| **Adaptation** | Per-user **SQLite** statistics and explicit feedback adjust routing over time (portable via **export/import**). |
-| **Project grounding** | Optional **index** of repository text into the same SQLite DB used for sessions (**project RAG**). |
-| **Observability** | Versioned **`_meta`** on MCP responses; route **events** in SQLite; **`skillforge events`** for operators. |
-| **Reliability hooks** | **`skillforge health`** (preflight) and **`skillforge route-eval`** (fixture-driven smoke checks; used in CI). |
-
----
-
-## Architecture at a glance
-
-```
-Host (Claude / Cursor / Claude Code / …)
-        │  MCP JSON-RPC (stdio)
-        ▼
-┌───────────────────────────────────────────────────────────┐
-│  skillforge mcp  →  Python: embed → shortlist → optional  │
-│  LLM stages → policies/overlay → context assembly         │
-└───────────────────────────────────────────────────────────┘
-        │
-        ├── SQLite (global ~/.skillforge or <project>/.skillforge)
-        └── Optional: Anthropic API (Haiku) in-process when enabled
-```
-
-**Trust boundary:** Skillforge runs **on the operator’s machine** (or your CI runner). Prompts and retrieved text should be handled per your org’s data policy. See [Security](#security).
-
----
-
-## Requirements
-
-| Dependency | Notes |
-|------------|--------|
-| **Node.js** | **≥ 18** (CLI bootstrap). CI validates on **Node 22** (see `.github/workflows/ci.yml`). |
-| **Python** | **≥ 3.10**; the CLI creates **`~/.skillforge/venv`** and installs `python/requirements.txt`. |
-| **Anthropic API** | **Optional.** Without **`ANTHROPIC_API_KEY`**, routing stays **embedding-first** unless you delegate picks to the host. |
-
-**First run** installs the virtualenv and Python dependencies and may download the default sentence-transformer model once; subsequent starts are typically fast.
-
----
-
-## Quick start
-
-```bash
-npx --yes @heytherevibin/skillforge --help
-```
-
-Configure **MCP** in your host (see [Model Context Protocol](#model-context-protocol-mcp)). **Embedding-only** operation does not require an Anthropic key.
-
-**Operator visibility:**
-
-```bash
-skillforge events --watch
-```
-
-**Preflight (after install):**
-
-```bash
-skillforge health --quick
-```
+**Project meta:** [`CHANGELOG.md`](CHANGELOG.md) · [`STRATEGY.md`](STRATEGY.md) · [`SECURITY.md`](SECURITY.md) · [`CONTRIBUTING.md`](CONTRIBUTING.md) · [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) · [`RELEASING.md`](RELEASING.md)
 
 ---
 
-## Installation
-
-**Evaluate without global install**
+## TL;DR — try it now
 
 ```bash
 npx --yes @heytherevibin/skillforge --help
+skillforge install            # provisions ~/.skillforge/venv when needed
+skillforge mcp config         # stdout JSON snippet → paste into ~/.cursor/mcp.json, then restart IDE
+skillforge tips && skillforge health --quick
+skillforge config init        # optional ~/.skillforge/env template · skillforge config validate
 ```
 
-**Global install**
-
-```bash
-npm install -g @heytherevibin/skillforge
-skillforge --help
-```
-
-- **npm:** [@heytherevibin/skillforge](https://www.npmjs.com/package/@heytherevibin/skillforge)  
-- **Source / issues:** [github.com/heytherevibin/skillforge](https://github.com/heytherevibin/skillforge)
-
----
-
-## Operational interfaces
-
-Skillforge is organized around a small **CLI** surface (implemented in **Node** spawning **Python** modules). Use **`skillforge <command> --help`** for flags.
-
-| Group | Commands | Purpose |
-|-------|----------|--------|
-| **Core** | `mcp`, `route`, `events`, `index` | Primary routing, logs, project indexing. |
-| **Reliability** | `health`, `route-eval` | Preflight checks; embedding-mode fixture evaluation (CI uses both). |
-| **Learning portability** | `weights export`, `weights import` | Snapshot / restore **`skill_weights`** rows (JSON). |
-| **Catalog** | `skills`, `pack` | User skills and git-backed **packs**. |
-| **Setup** | `install`, `hosts init`, `reset` | Bootstrap venv, global `/skillforge` commands, wipe local DB state. |
-
-**MCP config snippet (stdout):**
-
-```bash
-skillforge mcp config
-# Optional: --local (checkout), --with-anthropic (env placeholder)
-```
-
-**Important:** MCP requires a **clean stdout** stream (JSON-RPC). Logs belong on **stderr**. If tools do not appear in the host, update the package and fully restart the host after setup.
-
----
-
-## Model Context Protocol (MCP)
-
-### Router modes (`SKILLFORGE_ROUTER_MODE`)
-
-| Mode / default | Anthropic key | Behavior |
-|----------------|---------------|----------|
-| *(unset)* **auto** | optional | Embedding-first when key absent; full LLM routing when key present. |
-| `embedding` | ignored for routing | No in-process LLM pick; top candidates drive selection. |
-| `full` | recommended | LLM final pick; falls back per implementation on errors. |
-| `host` | optional for pick | **Two-step:** first `route_skills` returns shortlist; second call passes **`picked_names`**. |
-
-### MCP tools (summary)
-
-| Tool | Role |
-|------|------|
-| `route_skills` | Main routing: **prompt**, optional **conversation**, **`project_root`**, **`include_project_rag`**, **`session_id`**, **`user_id`**, **`picked_names`** (host or override). |
-| `search_skills` | Embedding shortlist for a **query** (read-only). |
-| `explain_route` | Diagnostics: shortlist + picks + policy audit **without** writing sessions. |
-| `get_skill`, `list_skills` | Catalog access. |
-| `skill_feedback`, `skill_referenced`, `disable_skill` | Learning loop and toggles. |
-| `materialize_project`, `skillforge_bootstrap` | Project file materialization (bootstrap **errors** in `host` mode by design—use two-step routing + materialize). |
-
-Full argument lists: tool definitions in **`python/app/mcp_server.py`** (source of truth).
-
----
-
-## MCP response contract
-
-Successful **`route_skills`** responses include **`_meta`** built in **`python/app/mcp_contract.py`**. The **`schema_version`** string tracks additive JSON shape changes (hosts may rely on it for parsing).
-
-**Authoritative version:** constant **`MCP_RESPONSE_SCHEMA_VERSION`** in **`app/mcp_contract.py`** (do not rely on this README if the two drift).
-
-**Notable `_meta` fields (non-exhaustive):**
-
-| Field | Description |
-|-------|-------------|
-| `schema_version` | Contract version string. |
-| `sources`, `budget` | Chunk citations and size accounting. |
-| `fusion` | Present when MMR-style fusion ran. |
-| `context_redaction` | Redaction hit counts when enabled. |
-| `route_quality` | Shortlist / router / policy / session telemetry for calibration. |
-| `feedback_effect` | Per-pick **learned weight** snapshot (uses / thumbs / reference rate). |
-| `routing_overlay` | Audit of **exclude** / **boost** / **project notes** application when configured. |
-| `host_pick_shortlist`, `host_pick_candidates` | Host-pick phase payloads. |
-
-Structured errors (e.g. empty prompt) return **`isError`: true** with **`_meta.error`** and **`schema_version`**.
-
----
-
-## Routing pipeline
-
-```
-User prompt (+ optional conversation-aware routing query)
-    → Encode routing query (skill cards + optional hybrid sparse signal)
-    → Fuse scores + per-user weights + optional project overlay boosts
-    → Shortlist (top-K)
-    → Optional LLM rerank / final pick (or embedding / host selection)
-    → Assemble context (skill chunks ± project chunks, optional fusion)
-    → Return markdown + _meta; optional SQLite events
-```
-
-Re-routing when the active skill set changes significantly is controlled by **`SKILLFORGE_REROUTE_THRESHOLD`** (see [Configuration](#configuration)).
-
----
-
-## Route policies and project overlay
-
-### Regex policies (post-pick merge)
-
-Rules match the user **`prompt`** with **`re.search`** (**`re.DOTALL`**). Matched **`include`** skills append after the router, capped by **`SKILLFORGE_MAX_ACTIVE`**. Audit lands on route **events** under **`policy`**.
-
-**Load order:** **`SKILLFORGE_ROUTE_POLICIES`** (inline JSON) → **`SKILLFORGE_ROUTE_POLICIES_FILE`** → **`<project_root>/.skillforge/policies.json`** → **`<project_root>/skillforge-policies.json`**.
-
-### Project routing overlay (same JSON document)
-
-Optional keys alongside **`rules`**:
-
-| Key | Aliases | Purpose |
-|-----|---------|--------|
-| `exclude_skills` | `host_exclude`, `denylist` | Remove skills from the embedding shortlist. |
-| `routing_boosts` | `skill_boosts` | Additive score delta after learned weight (clamped; see **route_policies** module). |
-| `project_notes` | `routing_notes`, `rag_notes` | Free text **prepended** to the internal routing query when **`project_root`** is set (not applied without a project root—mitigates accidental global injection from shared policy files). |
-
-**Example fragment** (illustrative—adjust skill ids to your catalog):
-
-```json
-{
-  "rules": [
-    {
-      "if_text_matches": "(?i)(auth|oauth|jwt)",
-      "include": ["security-review"]
-    }
-  ],
-  "project_notes": "Service stack and conventions for this repo (short, factual).",
-  "routing_boosts": { "python-testing": 0.15 },
-  "exclude_skills": ["legacy-skill-id"]
-}
-```
-
----
-
-## Project RAG
-
-1. **Index** repository text into **`<project>/.skillforge/orchestrator.db`**:
-
-   ```bash
-   skillforge index --project-root=/path/to/repo
-   ```
-
-2. Call **`route_skills`** with **`project_root`** and **`include_project_rag`** (or CLI **`--include-project-rag`**) when embeddings and schema match (see **`project_index.py`** for model/dimension guards).
-
-Chunk caps and ignore rules are **environment-driven** (see configuration table).
-
----
-
-## Learning, weights, and portability
-
-- **Signals:** route **`uses`**, **`skill_referenced`**, **`skill_feedback`** (thumbs), and **`disable_skill`** feed **SQLite** **`skill_weights`**.
-- **Transparency:** **`_meta.feedback_effect`** summarizes per-pick weight context after the route’s **`uses`** increment.
-- **Portability:**
-
-  ```bash
-  skillforge weights export -o weights.json
-  skillforge weights import weights.json
-  ```
-
-  Use **`--project-root`** / **`--user-id`** / **`--replace-user`** as documented in **`skillforge weights --help`** (implemented in **`python/app/weights_cli.py`**).
-
----
-
-## Skills and packs
-
-**Bundled catalog** ships inside the npm package. **CI** enforces a **minimum** bundled **`SKILL.md`** count so releases cannot silently ship an empty tree—the threshold lives in **`ci/bundle-gate.json`** (`minSkillMdFiles`); **`.github/workflows/ci.yml`** reads that file at build time.
-
-**Custom skills:** directory with **`SKILL.md`** and YAML frontmatter (`name`, `description`; optional **`triggers`** / **`anti_triggers`**).
-
-```bash
-skillforge skills add ./path/to/skill
-```
-
-**Packs:** repositories with **`skillforge.json`**:
-
-```bash
-skillforge pack install <org/repo>
-skillforge pack list
-```
-
----
-
-## Configuration
-
-Environment variables tune routing, context budgets, redaction, MCP defaults, and file watchers. **Authoritative defaults and parsing** live in **`python/app/main.py`** and related modules—treat the table below as **operator reference**, not a legal spec.
-
-| Variable | Role |
-|----------|------|
-| `ANTHROPIC_API_KEY` | Enables in-process **Haiku** routing / rerank when configured. |
-| `SKILLFORGE_ROUTER_MODE` | `full` · `embedding` · `host` · auto. |
-| `SKILLFORGE_EMBED_MODEL`, `SKILLFORGE_ROUTER_MODEL` | Model identifiers for embeddings / routing LLM. |
-| `SKILLFORGE_TOP_K`, `SKILLFORGE_MAX_ACTIVE` | Shortlist size and max simultaneous skills. |
-| `SKILLFORGE_REROUTE_THRESHOLD` | Re-route sensitivity (Jaccard distance). |
-| `SKILLFORGE_ROUTER_CONV_MAX_TURNS`, `SKILLFORGE_ROUTER_CONV_MSG_CHARS` | Conversation-aware routing query. |
-| `SKILLFORGE_ROUTER_HYBRID`, `SKILLFORGE_ROUTER_HYBRID_ALPHA` | Hybrid sparse/dense fusion. |
-| `SKILLFORGE_HAIKU_RERANK`, `SKILLFORGE_HAIKU_RERANK_MAX`, `SKILLFORGE_HAIKU_RERANK_MODEL` | Optional rerank stage. |
-| `SKILLFORGE_CONTEXT_MODE`, `SKILLFORGE_ROUTE_MAX_CHARS`, chunk envs | Skill body chunking vs full-body legacy. |
-| `SKILLFORGE_CONTEXT_FUSION`, `SKILLFORGE_CONTEXT_BUDGET_CHARS`, `SKILLFORGE_CONTEXT_MMR_LAMBDA`, pool sizes | Skill + project **MMR** fusion. |
-| `SKILLFORGE_PROJECT_RAG_MAX_CHARS`, `SKILLFORGE_PROJECT_RAG_MAX_CHUNKS` | Project chunk retrieval caps. |
-| `SKILLFORGE_PROJECT_NOTES_MAX_CHARS` | Cap for **`project_notes`** prepended to routing query. |
-| `SKILLFORGE_REDACT_CONTEXT`, `SKILLFORGE_REDACT_HOME_IN_PATHS` | Output redaction behavior. |
-| `SKILLFORGE_MCP_USER_ID`, `SKILLFORGE_PROJECT_ROOT` | MCP defaults for user scoping and DB resolution. |
-| `SKILLFORGE_ROUTE_POLICIES`, `SKILLFORGE_ROUTE_POLICIES_FILE` | Inline or file-backed policy JSON. |
-| `SKILLFORGE_HOST_PICK_MAX`, `SKILLFORGE_HOST_PICK_LINE_CHARS` | Host-mode shortlist sizing / formatting. |
-| Hot reload | `SKILLFORGE_SKILL_HOT_RELOAD`, `SKILLFORGE_WATCH_SKILLS_INTERVAL`, `SKILLFORGE_MCP_LIST_CHANGED`. |
-| Install hooks | `SKILLFORGE_SKIP_*`, `SKILLFORGE_*_GLOBAL_COMMAND`, etc. |
+**Default MCP routing (**`SKILLFORGE_ROUTER_MODE` unset ⇒ **`host`**) is two-step:** first **`route_skills`** shortlist · second finalize with **`picked_names`**.
 
 ---
 
-## Local data and paths
+## What ships in this repository
 
-**Per-project** (when **`project_root`** / **`SKILLFORGE_PROJECT_ROOT`** is used):
+| Path | Purpose |
+|------|---------|
+| `bin/cli.js` | Node entry (`skillforge`); merges env (**`buildEnv`**) and spawns Python |
+| `lib/` | Host setup, **`user-env-profile`** parser (`config validate`) |
+| `python/app/` | Router, MCP server, SQLite, CLIs, contracts |
+| `skills/` | Bundled SKILL.md corpus (CI minimum via `ci/bundle-gate.json`) |
+| `ci/` | Node tests (**`test-user-env-profile.cjs`**), bundle gate JSON |
+| `docs/` | Human-oriented guides (mirrors published npm tarball **`files`** list) |
 
-```
-<workspace>/.skillforge/
-├── orchestrator.db    # SQLite: sessions, weights, events, project_chunks (after index)
-├── policies.json      # Optional policies + overlay (or repo-root skillforge-policies.json)
-└── last_route.json    # Last CLI route snapshot (when applicable)
-```
-
-**Global default:**
-
-```
-~/.skillforge/
-├── venv/
-├── data/orchestrator.db
-├── skills/            # User skills
-└── packs/             # Pack working copies
-```
-
-| Command | Role |
-|---------|------|
-| `skillforge events` | Usage + recent **`route`** / **`feedback`** rows (`--watch`, `--project-root`, `--user`, `--verbose`). |
-| `skillforge index` | (Re)build **`project_chunks`**. |
-| `skillforge reset` | Clears learning + events in the target DB. |
-| `skillforge health` | Validates paths, catalog discovery, optional deep router load. |
-| `skillforge route-eval` | Runs JSON fixtures (CI). |
+**Tests:** **`npm test`** (Node **`--check`**) + **`cd python && pytest tests/`** in CI (**`.github/workflows/ci.yml`**).
 
 ---
 
-## Security
+## NPM package
 
-- **Redaction is best-effort.** Do not treat scrubbed output as a certified wipe of secrets.
-- **Secrets:** keep **`ANTHROPIC_API_KEY`** and workspace tokens out of VCS; inject via host or OS secret stores.
-- **Project notes** intentionally **do not apply** without **`project_root`** to reduce cross-talk from global policy config.
-- **Disclosure:** follow **[SECURITY.md](SECURITY.md)** (private channels for undisclosed issues).
+Scoped package **`@heytherevibin/skillforge`**: **`npm install -g`** or **`npx -y`** (see badges above).
 
 ---
 
-## Contributing and governance
-
-| Document | Purpose |
-|----------|---------|
-| [CONTRIBUTING.md](CONTRIBUTING.md) | Workflow and local checks. |
-| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community standards. |
-| [SECURITY.md](SECURITY.md) | Reporting vulnerabilities. |
-| [RELEASING.md](RELEASING.md) | Tags, **`NPM_TOKEN`**, npm **2FA** / granular tokens, CI vs release workflows. |
-| [CHANGELOG.md](CHANGELOG.md) | Version-by-version changes. |
-| [STRATEGY.md](STRATEGY.md) | Product direction and non-goals. |
-
-**Continuous integration:** `.github/workflows/ci.yml` (**push** / **PR** to **`main`**).
+## License
 
-**License:** [LICENSE](LICENSE) (MIT).
+[MIT License](LICENSE) © contributors.

package/RELEASING.md

@@ -5,7 +5,7 @@
 | 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.10.0`) |
+| **Skillforge release** | [.github/workflows/release.yml](.github/workflows/release.yml) | When a **`v*`** tag is **pushed** to the repository (e.g. `v0.10.1`) |
 
 In the GitHub UI, open **Actions** and look for **CI** and **Skillforge release** (not the older “publish to npm” name).
 
@@ -28,14 +28,15 @@ You need the **`NPM_TOKEN`** repository secret.
 
 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.10.0`).
-2. Match **MCP** `serverInfo.version` in `python/app/mcp_server.py` (must equal `package.json`) and add a **`CHANGELOG.md`** section for that version.
+1. On `main`, set **`version`** in **`package.json`** to the version you are releasing (must be **unused** on npm). Bump **[`CHANGELOG.md`](CHANGELOG.md)** with a **`## X.Y.Z`** section for that number. Reflect that **semver** anywhere user-facing prose names the shipping line (**[`README`](README.md)**, **[`docs/README`](docs/README.md)**, **[`getting-started`](docs/getting-started.md)**, **[`docs/mcp-integration`](docs/mcp-integration.md)**, …). Shield URLs track **published** artefacts and **`main`** automatically; only **plain-text version numbers** need a manual bump.
+2. **MCP `serverInfo.version`** matches **`package.json`** automatically (**[`python/app/npm_pkg_version.py`](python/app/npm_pkg_version.py)** **`published_package_version()`** — used from **`python/app/mcp_server.py`**). Operators can override via **`SKILLFORGE_MCP_SERVER_VERSION`**; do **not** hand-edit a second copy of semver in Python.
 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.10.0 && git push origin v0.10.0`
+4. Tag **`v` + the value of **`package.json` `version`**, push to **`origin`**, e.g.:  
+   `git tag v0.11.7 && git push origin v0.11.7`  
+   (**Replace **`v0.11.7`** with your semver** when releasing a newer number.)
 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.10.0`**) and the `.tgz` asset.
+   Confirm the **GitHub Release** exists with title **`Skillforge <tag>`** (e.g. **`Skillforge v0.11.7`**) and the `.tgz` asset.
 
 Scoped packages require a **public** publish; the workflow already runs `npm publish --access public`.
 
@@ -74,7 +75,7 @@ The **minimum** number of **`skills/**/**/SKILL.md`** files required in CI is **
 ## Local sanity checks (before push)
 
 ```bash
-node --check bin/cli.js && node --check lib/packs.js
+node --check bin/cli.js && node --check lib/packs.js && node --check lib/user-env-profile.js
 npm test
 ```
 

package/STRATEGY.md

@@ -27,8 +27,8 @@ Skillforge is a **local, MCP-first orchestration layer** that selects a **small,
 |-----------------|---------------------|
 | **Project workspace** | Pass **`project_root`** so state and optional RAG live under **`.skillforge/`**. |
 | **Strict context budgets** | Tune **`SKILLFORGE_CONTEXT_*`**, **`SKILLFORGE_ROUTE_MAX_CHARS`**, and project RAG caps. |
-| **No LLM keys on router** | Use **`SKILLFORGE_ROUTER_MODE=embedding`** (or omit **`ANTHROPIC_API_KEY`** in auto mode). |
-| **Human-in-the-loop picks** | **`SKILLFORGE_ROUTER_MODE=host`**: shortlist first, then **`picked_names`**. |
+| **No LLM keys on router** | Omit **`ANTHROPIC_API_KEY`** (**`host`** is the default when **`ROUTER_MODE`** is unset) or set **`SKILLFORGE_ROUTER_MODE=embedding`**. Legacy **auto** + key: **`SKILLFORGE_ROUTER_MODE=auto`**. |
+| **Human-in-the-loop picks** | **`SKILLFORGE_ROUTER_MODE=host`** (default when unset): shortlist first, then **`picked_names`**. |
 | **Org policy** | Central **`SKILLFORGE_ROUTE_POLICIES`** / file + per-repo **`policies.json`** with overlay keys. |
 
 ## Near-term themes