@heytherevibin/skillforge 0.10.1 → 0.11.7

package/docs/cli-reference.md

@@ -0,0 +1,57 @@
+# CLI reference
+
+**Entrypoint:** `bin/cli.js` (published as **`skillforge`** on npm).
+
+All Python CLIs honour the merged environment (**`buildEnv`** in **`bin/cli.js`**). Prefer **`skillforge …`** rather than invoking **`python -m app.*`** manually unless you are developing core modules.
+
+Run **`skillforge --help`** (or **`node bin/cli.js --help`**) for the condensed matrix; **`skillforge <cmd> --help`** forwards submodule help (**`route`**, **`agent`**, **`tools`**, …).
+
+## Launch surface (by concern)
+
+### Core workflows
+
+| Command | Description |
+|---------|-------------|
+| **`skillforge mcp`** | Start stdio MCP server (**forces `SKILLFORGE_TRANSPORT=mcp`**). |
+| **`skillforge route …`** | Same routing pipeline as MCP **`route_skills`** (TTY interactive **`-i`**, **`--json`**, **`--explain`**). |
+| **`skillforge tools …`** | Subcommands mirror MCP tool handlers (**`skillforge tools -h`** enumerates verbs). **`--json`** prints raw MCP-shaped envelopes for automation. |
+| **`skillforge agent …`** | Standalone OpenAI-compatible assistant loop invoking MCP-backed tool handlers (**`OPENAI_*`**, **`SKILLFORGE_AGENT_*`**). **`--help`** works before Python **`openai`** import; run **`skillforge install`** after upgrades when deps drift. |
+
+### Workspace + catalog
+
+| Command | Description |
+|---------|-------------|
+| **`skillforge index --project-root=…`** | Chunk/embed repository text · writes **`project_chunks`** per project SQLite. |
+| **`skillforge skills …`** | **`list`**, **`add`**, **`remove`**, **`init`**, **`lint`** authoring helpers (**`skills_author_cli`**). |
+| **`skillforge pack …`** | Install/list/update/remove git-hosted skill bundles (**`lib/packs.js`** bridge). |
+
+### Observability / ops
+
+| Command | Description |
+|---------|-------------|
+| **`skillforge events …`** | Tail SQLite routing / feedback events (**`--watch`**). |
+| **`skillforge replay …`** | Timeline reconstructor across stored events (**`--session-id`**). |
+| **`skillforge health …`** | Path + catalogue checks (**`--quick`** skips heavyweight embed/router load); JSON via **`--json`**. **`user_env_profile`** row notes whether **`~/.skillforge/env`** exists. |
+| **`skillforge route-eval …`** | Fixture embedding harness (CI consumes **`fixtures/route_eval/*.json`**). |
+| **`skillforge weights export|import …`** | Portable snapshots of **`skill_weights`**. |
+
+### Setup / ergonomics
+
+| Command | Description |
+|---------|-------------|
+| **`skillforge install`** | Provision **`~/.skillforge/venv`**, Python deps (**`requirements.txt`**), optional editor hooks (**`hosts init`** artefacts). |
+| **`skillforge config path|init|validate`** | Stable **`~/.skillforge/env`** profile + linter (**`validate`** exit codes documented in env guide). |
+| **`skillforge hosts init` / `skillforge cursor init`** | Write managed slash commands (**`/skillforge`**) — no Python prerequisite. |
+| **`skillforge tips`** | Human-readable MCP + terminal cheat-sheet. |
+
+## Flags worth memorising (**`skillforge route`**)
+
+| Flag / env | Behaviour |
+|------------|-----------|
+| **`-i`** or **`SKILLFORGE_ROUTE_INTERACTIVE=1`** | Prompt for ranks after **`host`** shortlists (TTY only). |
+| **`--json`** | Single envelope with **`phase`** markers for scripting (**`route_cli`**). |
+| **`--picked-names=id1,id2`** | Implements second leg of **`host`** finalize. |
+
+## Automation tip
+
+Prefer **`skillforge tools <verb> … --json`** when you want identical payloads compared to MCP (great for scripted ops + CI probes).

package/docs/environment-and-configuration.md

@@ -0,0 +1,76 @@
+# Environment & configuration
+
+## Configuration layers (in merge order)
+
+When you run **`skillforge <anything>`**, **Node `bin/cli.js`** builds a child **`process.env`** as follows:
+
+1. **`~/.skillforge/env`** (optional dotenv-style file) — **`skillforge config path`**, **`init`**, **`validate`**.
+2. **Current process env** — your shell, CI secrets, MCP host **`server.env`** / **`mcpServers.*.env`**.
+3. **Bootstrap keys always set last by Skillforge** — at minimum **`PYTHONPATH`**, **`SKILLFORGE_BUNDLED_SKILLS`**, **`SKILLFORGE_USER_SKILLS`**, **`SKILLFORGE_DB_PATH`**, **`PYTHONUNBUFFERED=1`**.
+4. **`SKILLFORGE_TRANSPORT=mcp`** is appended **only** for **`skillforge mcp`** (Python treats MCP differently from standalone CLI).
+
+Higher layers override lower ones for overlapping keys—but built-in SKILLFORGE path keys always win over accidental values in **`~/.skillforge/env`**.
+
+## ~/.skillforge/env (operator profile)
+
+| Command | Purpose |
+|---------|---------|
+| **`skillforge config path`** | Print absolute path (`~/.skillforge/env`). |
+| **`skillforge config init [--force]`** | Write commented template (`--force` overwrites). |
+| **`skillforge config validate`** | Lint; **`error`** issues exit **1**; missing file exits **0**. |
+
+**Syntax:** one **`KEY=value`** per line, optional **`export`**, **`#`** comments; variable names **`[A-Za-z_][A-Za-z0-9_]*`**; optional quotes. No shell **`${VAR}`** expansion—parser lives in **`lib/user-env-profile.js`**.
+
+## MCP **`entry.env`** vs profile
+
+If the IDE merges **`env`** into the **`skillforge mcp`** process, those vars sit in **layer 2** and **override** the same keys from **`~/.skillforge/env`**. Put **shared defaults** in the profile file; put **host-specific overrides** (or secrets the IDE injects exclusively) in **`mcp.json`**.
+
+## SKILLFORGE_TRANSPORT (**MCP** only)
+
+ **`skillforge mcp`** forces **`SKILLFORGE_TRANSPORT=mcp`**. In that mode router LLM wiring follows **Anthropic** legacy paths for MCP. Standalone CLI (no transport flag) may use **`SKILLFORGE_ROUTER_LLM_BACKEND=openai_compatible`** for OpenAI-compatible routing—see codebase **`app/main.py`** / **`app/router_llm.py`**.
+
+## Direct Python (**advanced**)
+
+If you bypass Node and run **`python -m app.mcp_server`**, **`~/.skillforge/env` is not read**. Either use **`skillforge mcp`** or replicate **`buildEnv()`** wiring yourself.
+
+## Environment variable reference (operator table)
+
+Below is reference text from the published operator docs. Defaults and parsing logic are implemented primarily in **`python/app/main.py`**, **`python/app/route_policies.py`**, **`python/app/db_paths.py`**, and MCP modules—if this table and code disagree, trust the repository.
+
+| Variable | Role |
+|----------|------|
+| `ANTHROPIC_API_KEY` | Omit when **`SKILLFORGE_ROUTER_MODE`** is **`host`** (unset default) unless **`SKILLFORGE_HAIKU_RERANK`** or other modes invoke Haiku (**`skillforge mcp config --with-anthropic`** documents **`auto` + placeholder**). |
+| `SKILLFORGE_ROUTER_MODE` | **`host`** (default when unset) · **`auto`** (legacy Haiku-if-key) · **`embedding`** · **`full`**. Empty string (**`=`** alone) normalises to **`auto`**. |
+| `SKILLFORGE_TRANSPORT` | Set **`mcp`** by **`skillforge mcp`** only. |
+| `SKILLFORGE_ROUTER_LLM_BACKEND` | Standalone/non-MCP: **`openai_compatible`** uses **`OPENAI_API_BASE`**, etc. Ignored under MCP transport. |
+| `OPENAI_API_BASE`, `SKILLFORGE_OPENAI_API_BASE`, `OPENAI_API_KEY`, `SKILLFORGE_OPENAI_ROUTER_MODEL` | OpenAI-compatible router defaults. |
+| `SKILLFORGE_AGENT_MODEL`, `SKILLFORGE_AGENT_API_KEY`, `SKILLFORGE_AGENT_API_BASE` | **`skillforge agent`** (**also **`OPENAI_*`** fallbacks). || `SKILLFORGE_EMBED_MODEL`, `SKILLFORGE_ROUTER_MODEL` | Embedding + Anthropic router model ids. |
+| `SKILLFORGE_TOP_K`, `SKILLFORGE_MAX_ACTIVE` | Shortlist size and simultaneous skills cap. |
+| `SKILLFORGE_REROUTE_THRESHOLD` | Re-route sensitivity (Jaccard distance). |
+| `SKILLFORGE_ROUTER_CONV_MAX_TURNS`, `SKILLFORGE_ROUTER_CONV_MSG_CHARS` | Conversation fused into embedding/hybrid routing query (**0** turns = prompt-only). |
+| `SKILLFORGE_ROUTER_PROMPT_HISTORY_MSGS`, `SKILLFORGE_ROUTER_PROMPT_HISTORY_CHARS` | Conversation shown into router LLM prompts. |
+| `SKILLFORGE_ROUTER_CATALOG_PREVIEW_CHARS` | Truncation in router catalog excerpts. |
+| `SKILLFORGE_ROUTER_HYBRID`, `SKILLFORGE_ROUTER_HYBRID_ALPHA` | Hybrid sparse+dense (**`off`**, **`keyword`**, **`bm25`**). |
+| `SKILLFORGE_HAIKU_RERANK`, `SKILLFORGE_HAIKU_RERANK_MAX`, `SKILLFORGE_HAIKU_RERANK_MODEL` | Optional rerank phase. |
+| `SKILLFORGE_CONTEXT_MODE`, `SKILLFORGE_ROUTE_MAX_CHARS`, `SKILLFORGE_CHUNK_MAX_CHARS`, `SKILLFORGE_CHUNK_OVERLAP` | Chunking (**`skills`** + **`index`** reuse chunk tunables). |
+| `SKILLFORGE_CONTEXT_FUSION`, `SKILLFORGE_CONTEXT_BUDGET_CHARS`, `SKILLFORGE_CONTEXT_MMR_LAMBDA`, `SKILLFORGE_FUSION_POOL_SKILL`, `SKILLFORGE_FUSION_POOL_PROJECT`, `SKILLFORGE_FUSION_FULL_BODY_PREVIEW_CHARS` | MMR fusion. |
+| `SKILLFORGE_PROJECT_RAG_MAX_CHARS`, `SKILLFORGE_PROJECT_RAG_MAX_CHUNKS` | Project chunk retrieval caps. |
+| `SKILLFORGE_PROJECT_NOTES_MAX_CHARS` | Cap **`project_notes`**. |
+| `SKILLFORGE_REDACT_CONTEXT`, `SKILLFORGE_REDACT_HOME_IN_PATHS` | Redaction knobs. |
+| `SKILLFORGE_MCP_USER_ID`, `SKILLFORGE_PROJECT_ROOT` | User scoping + DB/project resolution helpers. |
+| `SKILLFORGE_MATERIALIZE_HOSTS` | Default host resolution when **`materialize_project`** **`hosts`** is **`auto`**. |
+| `SKILLFORGE_ROUTE_POLICIES`, `SKILLFORGE_ROUTE_POLICIES_FILE` | Policies JSON (invalid JSON ⇒ stderr warning + empty rules — see Troubleshooting). |
+| `SKILLFORGE_HOST_PICK_MAX`, `SKILLFORGE_HOST_PICK_LINE_CHARS` | Host-mode shortlist formatting. |
+| `SKILLFORGE_ROUTE_AMBIGUITY_COS_MARGIN`, `SKILLFORGE_ROUTE_AMBIGUITY_ROUTE_MARGIN` | **`route_quality`** ambiguity heuristics. |
+| `SKILLFORGE_ROUTE_AMBIGUITY_DISABLE` | Disable ambiguity tier heuristics. |
+| `SKILLFORGE_PICK_DIVERSIFY`, `SKILLFORGE_PICK_MAX_PER_SOURCE` | Per-source pick thinning before policy merge. |
+| Paths | **`SKILLFORGE_BUNDLED_SKILLS`**, **`SKILLFORGE_USER_SKILLS`**, **`SKILLFORGE_DB_PATH`** (normally set by CLI). |
+| Skill manifests | **`SKILLFORGE_SKILL_MANIFEST_STRICT`** — invalid skills skipped at catalog load (**`skills lint`**). |
+| Project index | **`SKILLFORGE_INDEX_MAX_FILE_BYTES`**, **`SKILLFORGE_INDEX_IGNORE_DIRS`**. |
+| Hot reload | **`SKILLFORGE_SKILL_HOT_RELOAD`**, **`SKILLFORGE_WATCH_SKILLS_INTERVAL`**, **`SKILLFORGE_MCP_LIST_CHANGED`**. |
+| Editor hooks install | **`SKILLFORGE_SKIP_CURSOR_SETUP`**, **`SKILLFORGE_SKIP_CLAUDE_CODE_SETUP`**, **`SKILLFORGE_CURSOR_GLOBAL_COMMAND`**, **`SKILLFORGE_CLAUDE_CODE_GLOBAL_COMMAND`**. |
+| **`SKILLFORGE_MCP_SERVER_VERSION`** | Overrides **`capabilities`** / MCP reported semver (**`published_package_version()`**). |
+
+---
+
+**Related:** **[MCP integration](mcp-integration.md)** · **[Troubleshooting](troubleshooting.md)**

package/docs/getting-started.md

@@ -0,0 +1,88 @@
+# Getting started
+
+## 1. What you are installing
+
+Skillforge ships as **[@heytherevibin/skillforge](https://www.npmjs.com/package/@heytherevibin/skillforge)**. The **CLI** (`skillforge`) is a **Node.js** shim that installs a **managed Python virtualenv** under **`~/.skillforge/venv`** and runs **`python -m app.…`** with a consistent environment (`PYTHONPATH`, skill dirs, DB path). You do **not** need to activate the venv by hand.
+
+**Documentation matches this checkout’s release line:** **0.11.7** (**[`package.json` `version`](../package.json)**). On npm, **`npm view @heytherevibin/skillforge version`** is the registry truth—use **`@latest`** or **`npx -y`** to stay current.
+
+## 2. Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| **Node.js ≥ 18** | Required to run **`npx`** / **`skillforge`**. |
+| **Python ≥ 3.10** | Used on first **`skillforge install`** to create **`~/.skillforge/venv`**. |
+| **Internet (first install)** | `pip install` from **`python/requirements.txt`**; embedding model download may occur once. |
+
+## 3. Try without installing globally
+
+Run:
+
+```bash
+npx --yes @heytherevibin/skillforge --help
+```
+
+First use may invoke **`skillforge install`** implicitly when you hit a Python-backed command (`route`, `mcp`, …). Use **`skillforge install`** explicitly if you prefer a deliberate bootstrap.
+
+## 4. Global install (optional)
+
+```bash
+npm install -g @heytherevibin/skillforge
+skillforge --help
+```
+
+Verify:
+
+```bash
+skillforge config validate   # exits 0 if ~/.skillforge/env is missing (optional file)
+skillforge health --quick
+```
+
+## 5. Optional operator profile (~/.skillforge/env)
+
+Recommended for stable API keys and tunables:
+
+```bash
+skillforge config init       # ~/.skillforge/env template (chmod 600 on Unix where supported)
+skillforge config validate   # lint after edits
+```
+
+See **[Environment & configuration](environment-and-configuration.md)** for merge order versus MCP **`entry.env`**.
+
+## 6. Wire MCP (Cursor, Claude Desktop, …)
+
+Emit a snippet (stdout is JSON):
+
+```bash
+skillforge mcp config
+# Add --local for a git checkout · --with-anthropic · --with-env (see MCP guide)
+```
+
+**Instructions:**
+
+1. Copy the **`mcpServers.skillforge`** object into your host config (example: **`~/.cursor/mcp.json`**).
+2. **Fully restart** the MCP host application after edits.
+3. Confirm tools appear — start a session with **`capabilities`** once (bundle lists tool names + **router_snapshot**).
+
+**Critical:** MCP uses **stdout** only for JSON-RPC. Skillforge logs to **stderr**.
+
+## 7. Understand default routing (**host**, two-step)
+
+If **`SKILLFORGE_ROUTER_MODE`** is unset, Skillforge defaults to **`host`**:
+
+1. First **`route_skills`** → numbered **shortlist** (no **`picked_names`**).
+2. Second call → same **`prompt`** plus **`picked_names`** (`id1,id2` or enumerated picks from the listing).
+
+CLI mirrors this: **`skillforge route`** twice, or **`skillforge route -i`** on a TTY after the shortlist.
+
+Details: **[MCP integration](mcp-integration.md)**.
+
+## 8. Operational habits
+
+```bash
+skillforge tips                           # cheatsheet on stdout
+skillforge events --watch                 # routing / feedback tail
+skillforge replay --limit=20 [--json]
+```
+
+Further reading:** [CLI reference](cli-reference.md)** · **[Architecture & data](architecture-and-data.md)**.

package/docs/mcp-integration.md

@@ -0,0 +1,75 @@
+# MCP integration
+
+Skillforge speaks **stdio MCP JSON-RPC**. Tool definitions (**name**, **`inputSchema`**, descriptions) ship from **`python/app/mcp_server.py`**.
+
+## stdout discipline
+
+Anything that writes stray bytes to **stdout** breaks MCP hosts. **`skillforge mcp`** never logs JSON-RPC payloads to stdout; logs go to **stderr**.
+
+## Default routing (**host**, Skillforge ≥ 0.11.0 — use **≥ 0.11.7** if you rely on **`route-eval`** / full router init stability)
+
+Stable **`Router`** embedding + **`_by_name`** initialization ship in **[0.11.7](../CHANGELOG.md)**; stay on **`0.11.7`** or newer for CI-aligned routing.
+
+When **`SKILLFORGE_ROUTER_MODE`** is **unset**:
+
+1. First **`route_skills`** call → **numbered shortlist** (no **`picked_names`** yet).
+2. Second call → same **`prompt`** plus **`picked_names`** (**`id1,id2`** or enumerated picks returned in the listing).
+
+ **`auto`** (legacy behavior) ⇒ **`SKILLFORGE_ROUTER_MODE=auto`** or empty string (**`=`** alone). **`skillforge mcp config --with-anthropic`** emits **`SKILLFORGE_ROUTER_MODE=auto`** **and** an **`ANTHROPIC_API_KEY`** placeholder together so placeholders are not meaningless under **`host`** default routing.
+
+### Mode reference
+
+| **`SKILLFORGE_ROUTER_MODE`** | Behaviour (high level) |
+|------------------------------|------------------------|
+| **unset → treats as `host`** | Host-driven two-step routing. |
+| **`host`** | Explicit two-step **shortlist → picked_names**. |
+| **`auto`** | Embedding-first without key; in-process Haiku when **`ANTHROPIC_API_KEY`** set. |
+| **`embedding`** | Embedding-only picks / overrides via **`picked_names`**. |
+| **`full`** | Haiku-heavy paths (falls back gracefully if key absent). |
+
+## Where to declare **`env`**
+
+| Host | Typical manifest |
+|------|------------------|
+| **Cursor / VS Code MCP** | **`~/.cursor/mcp.json`** (workspace overrides possible) |
+| **Claude Desktop** | **`claude_desktop_config.json`** |
+
+Restart the MCP host whenever **`env`** or package version changes.
+
+## **`skillforge mcp config`**
+
+```bash
+skillforge mcp config
+skillforge mcp config --local
+skillforge mcp config --with-anthropic    # SKILLFORGE_ROUTER_MODE=auto + key placeholder env
+skillforge mcp config --with-env           # SKILLFORGE_ROUTER_MODE=host scaffold in entry.env
+```
+
+**Note:** Passing **`--with-anthropic`** **replaces** the emitted **`env`** object (**`--with-env`** loses); merge manually if you need both patterns.
+
+## MCP tools (quick map)
+
+Schemas + parameter docs: **`python/app/mcp_server.py`**.
+
+| Tool | Responsibility |
+|------|----------------|
+| **`route_skills`** | Embed → shortlist → policies → context assembly; honours **`picked_names`**. |
+| **`search_skills`** | Embedding shortlist for arbitrary query text. |
+| **`explain_route`** | Routing diagnostics (shortlist audit) without heavyweight session effects. |
+| **`get_skill`**, **`list_skills`** | Deterministic SKILL.md retrieval + catalog summaries. |
+| **`skill_feedback`**, **`skill_referenced`**, **`disable_skill`** | Learning loop inputs. |
+| **`materialize_project`** | Opinionated scaffolding for **`cursor`**, **`claude_code`**, or **`both`** with **`hosts`**: **`auto`**, **`both`**, **`cursor`**, **`claude_code`**. |
+| **`skillforge_bootstrap`** | Composite route + scaffold helper (mind **`host`** shortlist caveat). |
+| **`capabilities`** | Session bootstrap bundle (**semver**, MCP schema marker, **`mcp_tools`**, **`user_env_profile`** commands, **`router_snapshot`**). |
+| **`get_router_status`** | Diagnostics snapshot (modes, hybrids, rerank hints). |
+| **`project_index_status`** | Project **`project_chunks`** stats + index metadata (**`project_root`**). |
+| **`weights_snapshot`** | Portable learned weights excerpt (parity with **`weights export`** CLI). |
+| **`events_recent`** | Recent SQLite **`events`** rows (**bounded** **`limit`**). |
+
+## Response **`_meta`**
+
+Structured metadata is anchored by **`MCP_RESPONSE_SCHEMA_VERSION`** in **`app/mcp_contract.py`**. Highlights include **`route_quality`**, **`routing_overlay`**, **`feedback_effect`**, budgeting / fusion stats, **`host_pick_*`** artefacts when **`host`** mode emits shortlists.
+
+---
+
+**Related:** **[Environment & configuration](environment-and-configuration.md)** · **[CLI reference](cli-reference.md)**

package/docs/troubleshooting.md

@@ -0,0 +1,50 @@
+# Troubleshooting
+
+## MCP tools never appear / connection dies immediately
+
+**Check:**
+
+1. **Restart** Cursor / Claude / VS Code after editing **`mcp.json`** (**hot reload seldom enough**).
+2. Confirm **nothing else** wraps stdout (debug prints, rogue **`console.log`** forks); **`skillforge mcp`** forbids chatter on stdout.
+3. Bump package version (**`npm view @heytherevibin/skillforge version`** vs local git tag) — mismatched semver often means stale binary.
+4. Run **`skillforge health --quick`** locally to prove venv + skill tree viability.
+
+## **`skillforge agent` Missing `openai`**
+
+Upgrade managed deps:
+
+```bash
+skillforge install
+```
+
+(or manually **`pip install -r`** against **`~/.skillforge/venv`**).
+
+Validate env profile too:
+
+```bash
+skillforge config validate
+```
+
+## Route policies silently empty
+
+Malformed **`SKILLFORGE_ROUTE_POLICIES`** JSON or unreadable **`SKILLFORGE_ROUTE_POLICIES_FILE`** now prints **`[skillforge] …`** on **stderr** and falls back to **no regex rules**.
+
+**Instruction:** **`skillforge explain_route`** / inspect logs · fix JSON · re-run.
+
+## NPM publish / **`EOTP`** in GitHub Actions
+
+Release workflow requires a **Granular NPM token with Bypass 2FA** — see **[RELEASING.md](../RELEASING.md)**.
+
+Re-run **`Skillforge release`** after rotating **`NPM_TOKEN`**.
+
+## Tag mismatches (**`release.yml`** guard)
+
+ **`vX.Y.Z` tag must equal `package.json`** **`version`**. Bump semver, push **`main`**, then re-tag (**`git tag -d`** / **`git push :refs/tags/...`** if you need to re-cut).
+
+---
+
+Need more?
+
+- Diagnostics bundle: MCP **`capabilities`**, **`get_router_status`**.
+- Security expectations: **[SECURITY.md](../SECURITY.md)**.
+- Broader changelog context: **[CHANGELOG.md](../CHANGELOG.md)**.

package/lib/templates/claude-code-skillforge-global.md

@@ -2,8 +2,6 @@
 description: Run Skillforge MCP (route_skills) to load routed SKILL.md context. Use when the user invokes /skillforge, asks for Skillforge, or needs catalog skills for the repo.
 ---
 
-<!-- skillforge-managed vPACKAGE_VERSION — remove this line to stop auto-updates from `skillforge install` -->
-
 # Skillforge — route SKILL.md context (MCP)
 
 Global **`/skillforge`** for **Claude Code** (same mechanism as `.claude/commands/*.md`). Configure the **skillforge** MCP server (see **`skillforge mcp config`**, project **`.mcp.json`**, or `claude mcp`). Optional: **`skillforge health`**, **`skillforge route-eval`**, **`skillforge weights export|import`**. MCP **`_meta.feedback_effect`** explains learned-ranking bias for picked skills when present.
@@ -12,8 +10,10 @@ Global **`/skillforge`** for **Claude Code** (same mechanism as `.claude/command
 
 1. **`route_skills`** (MCP): pass **`project_root`** as the **current project root** (absolute path) so SQLite lives in **`<project>/.skillforge/`**. Pass the **user's task** as **`prompt`**. Reuse **`session_id`** across turns when the MCP returns it.
 
-   - **`SKILLFORGE_ROUTER_MODE=host`**: first call **without** **`picked_names`** (shortlist only); second call **with** **`picked_names`**.
+   - **`host`** routing (default when **`SKILLFORGE_ROUTER_MODE`** is unset): first call **without** **`picked_names`** (shortlist only); second call **with** **`picked_names`**.
 
 2. **Use the returned skill text** in your answer.
 
 3. **Per-repo list:** run **`materialize_project`** after **`route_skills`** to refresh **`.claude/commands/skillforge.md`** and **`CLAUDE.md`**.
+
+<!-- skillforge-managed vPACKAGE_VERSION — remove this line to stop auto-updates from `skillforge install` -->

package/lib/templates/cursor-skillforge-global.md

@@ -1,4 +1,6 @@
-<!-- skillforge-managed vPACKAGE_VERSION — remove this line to stop auto-updates from `skillforge install` -->
+---
+description: Route SKILL.md context via Skillforge MCP (/skillforge). Configure the skillforge server in ~/.cursor/mcp.json — run skillforge mcp config for JSON.
+---
 
 # Skillforge — route SKILL.md context (MCP)
 
@@ -8,9 +10,11 @@ Global **`/skillforge`** command. Use the **skillforge** MCP server (configure i
 
 1. **`route_skills`** (MCP): pass **`project_root`** as the **current workspace root** (absolute path) so SQLite lives in **`<workspace>/.skillforge/`**. Pass the **user's task** as **`prompt`**. Reuse **`session_id`** across turns when the tool returns one.
 
-   - **`SKILLFORGE_ROUTER_MODE=host`**: call once **without** **`picked_names`** (shortlist only); then call again with **`picked_names`** (exact catalog ids) to load skill context.
+   - **`host`** routing (default when **`SKILLFORGE_ROUTER_MODE`** is unset): call once **without** **`picked_names`** (shortlist only); then call again with **`picked_names`** (exact catalog ids) to load skill context.
    - Optional: **`conversation`** when recent turns should influence routing.
 
 2. **Use the returned skill text** in your answer.
 
 3. **Project-specific lists:** run **`materialize_project`** in a repo (after **`route_skills`**) to write **`.cursor/commands/skillforge.md`**, **`.cursor/rules/skillforge.mdc`**, and **`docs/SKILLFORGE-PRD.md`** with the latest **`skill_names`**.
+
+<!-- skillforge-managed vPACKAGE_VERSION — remove this line to stop auto-updates from `skillforge install` -->

package/lib/user-env-profile.js

@@ -0,0 +1,141 @@
+/**
+ * Parses Skillforge ~/.skillforge/env (dotenv-style) for merge + validation.
+ * Shell-free: no ${VAR} expansion.
+ */
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * @typedef {{ level: 'error'|'warning', line: number, message: string }} UserEnvIssue
+ */
+/**
+ * @param {string} raw
+ * @returns {{ vars: Record<string, string>, issues: UserEnvIssue[] }}
+ */
+function parseUserEnvProfileText(raw) {
+  /** @type {Record<string, string>} */
+  const vars = {};
+  /** @type {UserEnvIssue[]} */
+  const issues = [];
+
+  /** @type {Set<string>} */
+  const declared = new Set();
+
+  const lines = raw.split(/\r?\n/);
+  const keyOk = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineNum = i + 1;
+    const rawLine = lines[i];
+    const t = rawLine.trim();
+    if (!t || t.startsWith('#')) {
+      continue;
+    }
+
+    let s = t;
+    if (s.startsWith('export ')) {
+      s = s.slice(7).trim();
+    }
+
+    const ix = s.indexOf('=');
+    if (ix < 0) {
+      issues.push({
+        level: 'warning',
+        line: lineNum,
+        message:
+          'line has no "=" — expected KEY=value (dotenv syntax); skipped when loading',
+      });
+      continue;
+    }
+
+    if (ix === 0) {
+      issues.push({
+        level: 'error',
+        line: lineNum,
+        message: 'missing variable name before "="',
+      });
+      continue;
+    }
+
+    const k = s.slice(0, ix).trim();
+    let v = s.slice(ix + 1).trim();
+    if (v.startsWith('"')) {
+      if (v.length < 2 || !v.endsWith('"')) {
+        issues.push({
+          level: 'warning',
+          line: lineNum,
+          message: 'value starts with " but closing quote missing or malformed',
+        });
+      }
+    } else if (v.startsWith("'")) {
+      if (v.length < 2 || !v.endsWith("'")) {
+        issues.push({
+          level: 'warning',
+          line: lineNum,
+          message: "value starts with ' but closing quote missing or malformed",
+        });
+      }
+    }
+
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+      v = v.slice(1, -1);
+    }
+
+    if (!keyOk.test(k)) {
+      issues.push({
+        level: 'error',
+        line: lineNum,
+        message:
+          `invalid KEY "${k}" — use ASCII letters, digits, underscore (must match [A-Za-z_][A-Za-z0-9_]*)`,
+      });
+      continue;
+    }
+
+    if (declared.has(k)) {
+      issues.push({
+        level: 'warning',
+        line: lineNum,
+        message: `duplicate "${k}" — last assignment wins`,
+      });
+    }
+    declared.add(k);
+    vars[k] = v;
+  }
+
+  return { vars, issues };
+}
+
+/**
+ * Read and parse ~/.skillforge/env. Missing file ⇒ empty vars & issues only if caller treats missing.
+ * @param {string} absPath
+ * @returns {{
+ *   vars: Record<string, string>,
+ *   issues: UserEnvIssue[],
+ *   missingFile?: boolean,
+ *   readErr?: boolean,
+ * }}
+ */
+function readUserEnvProfileFromFile(absPath) {
+  if (!fs.existsSync(absPath)) {
+    return { vars: {}, issues: [], missingFile: true };
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(absPath, 'utf8');
+  } catch (e) {
+    const msg = /** @type {Error} */ (e).message;
+    return {
+      vars: {},
+      issues: [{ level: 'error', line: 0, message: `cannot read ${absPath}: ${msg}` }],
+      readErr: true,
+    };
+  }
+  const { vars, issues } = parseUserEnvProfileText(raw);
+  return { vars, issues };
+}
+
+module.exports = {
+  parseUserEnvProfileText,
+  readUserEnvProfileFromFile,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heytherevibin/skillforge",
-  "version": "0.10.1",
+  "version": "0.11.7",
   "description": "SKILL.md orchestration for AI agents: MCP-first routing with local embeddings, optional LLM stages, project RAG, policy overlays, portable learning state, and auditable telemetry.",
   "keywords": [
     "claude",
@@ -22,6 +22,7 @@
     "python/",
     "skills/",
     "README.md",
+    "docs/",
     "CHANGELOG.md",
     "STRATEGY.md",
     "LICENSE",
@@ -34,6 +35,6 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "node bin/cli.js --help"
+    "test": "node --test ci/test-user-env-profile.cjs && node bin/cli.js --help && node bin/cli.js config validate"
   }
 }