expert-mentor 0.6.2__py3-none-any.whl

expert_mentor-0.6.2.data/data/share/expert-mentor/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: expert-mentor
+description: "Use when the user wants to learn, be taught, or be mentored in any field (e.g. 'teach me quantum computing', 'be my Rust mentor', 'explain macroeconomics like a professor'), or wants to turn a cloud AI provider (Claude/Anthropic, ChatGPT/OpenAI, Gemini) or local LLM (Ollama, LM Studio, llama.cpp) into a professional teacher for a given field. Produces a calibrated expert-mentor persona, a learning roadmap, a live tutoring session, or a full curriculum."
+summary: "Turn Claude, ChatGPT, Gemini or a local LLM into a professional tutor that remembers your progress and quizzes you."
+version: 0.6.2
+tags: ["education", "tutoring", "mentoring", "prompt-engineering", "curriculum", "flashcards"]
+keywords: ["tutor", "mentor", "teacher", "coaching", "claude", "chatgpt", "gemini", "ollama", "curriculum", "flashcards", "study-plan"]
+use_cases: ["teach me quantum computing", "be my Rust mentor", "explain macroeconomics like a professor", "turn Claude into an expert tutor", "build a study curriculum for a field"]
+docs_url: https://github.com/voidstackloop/expert-mentor
+---
+
+# Expert Mentor
+
+Turn any capable model — a cloud provider (Anthropic, OpenAI, Google) or a local
+LLM (Ollama, LM Studio, llama.cpp) — into a **professional teacher for a
+user-specified field**. The mentor teaches to a standard a real senior
+practitioner would recognise, and adapts to the learner in real time.
+
+## Setup (optional)
+
+This skill folder works as-is — no install needed. Run it in place:
+
+```bash
+python3 scripts/expert_mentor.py --field "Rust" --level beginner
+```
+
+Want a `mentor` command on your PATH instead of typing the full script path?
+Run the installer once from inside this folder:
+
+```bash
+./install.sh          # or: make install
+```
+
+This installs the `mentor` command into `~/.local/bin`, links the skill into
+`~/.claude/skills/expert-mentor` and `~/.config/opencode/skills/expert-mentor`,
+adds `~/.local/bin` to PATH if needed, and runs a health check. Open a new
+terminal (or `source ~/.bashrc`) and run `mentor doctor`. Remove it later with
+`./uninstall.sh`.
+
+Defaults can be saved so you stop retyping them:
+
+```bash
+mentor config --set provider=claude --set level=intermediate --set style=coaching
+```
+
+## When this skill activates
+
+- The user names a field and asks to be taught, tutored, coached, or mentored.
+- The user wants a system prompt / persona to make a specific model act as a
+  teacher for a field.
+- The user wants to configure a local LLM (Modelfile, LM Studio preset) as an
+  expert mentor.
+
+## Step 1 — Collect the essentials
+
+You need, at minimum:
+
+| Input | Required | Notes |
+|-------|----------|-------|
+| `field` | yes | e.g. "distributed systems", "Spanish literature", "day trading" |
+| `level` | no | beginner / intermediate / advanced / expert — infer from context if absent |
+| `goal` | no | what they want to be able to do |
+| `context` | no | background, prior knowledge, time available |
+| `language` | no | default: same language the user is writing in |
+| `provider` | no | only needed when emitting a prompt/Modelfile for a specific model |
+
+Do not interrogate the user. Infer sensible defaults from the conversation. If
+the **field** itself is ambiguous (e.g. "AI" could be theory, engineering, or
+policy), ask one clarifying question, then proceed.
+
+## Step 2 — Choose the delivery mode
+
+Pick based on what the user actually wants:
+
+**A. Teach me now (default).** Adopt the persona inline and run the session in
+this conversation. Load `templates/mentor_system_prompt.md`, fill the slots, and
+follow it exactly. Start with **Phase 1 — Intake**, then build the roadmap.
+
+**B. Give me a reusable prompt.** The user wants to paste a system prompt into
+another chat or API. Generate it with the script (Step 3) and hand it over.
+
+**C. Configure a provider or local model.** The user wants a deployable artefact
+(system prompt, messages JSON, Ollama Modelfile, LM Studio preset). Generate it
+with the script (Step 3).
+
+**D. Build a curriculum.** The user wants a structured multi-week plan rather
+than live tutoring. Generate a curriculum-design prompt with `mentor curriculum
+--field F --duration "6 weeks, 5h/week"`, then either hand it off or have the
+model produce the plan inline. Ground it in `references/pedagogy.md`.
+
+## Step 3 — Generate the mentor prompt
+
+The generator renders `templates/mentor_system_prompt.md` for a field, level,
+and target provider, then emits it in the format that provider needs.
+
+```bash
+# Print a ready-to-paste system prompt (default: generic text)
+mentor --field "quantum computing" --level beginner
+
+# For a local model as an Ollama Modelfile
+mentor --field "Rust" --level intermediate --provider ollama --emit modelfile > Modelfile
+
+# Messages JSON for an OpenAI-compatible API
+mentor --field "contract law" --provider openai --emit json
+
+# Anthropic Messages API payload
+mentor --field "organic chemistry" --provider anthropic --emit json
+
+# Save a reusable mentor and reuse it later
+mentor save rustbuddy --field "Rust" --level intermediate
+mentor show rustbuddy
+
+# Build and register a local model in one shot (needs ollama installed)
+mentor ollama rusttutor --field "Rust" --compact
+```
+
+Without the installer, replace `mentor` with `python3 scripts/expert_mentor.py`.
+
+Commands:
+
+| Command | Purpose |
+|---------|---------|
+| `mentor --field F [...]` | generate a prompt (default text for the provider) |
+| `mentor prompt --field F` | same, explicit form |
+| `mentor save NAME --field F` | save a reusable system prompt under `~/.config/expert-mentor/prompts/` |
+| `mentor show NAME` | print a saved mentor |
+| `mentor saved` | list saved mentors |
+| `mentor ollama NAME --field F` | write a Modelfile and run `ollama create NAME` |
+| `mentor run [NAME] --field F` | start a live tutoring session (local or cloud) |
+| `mentor curriculum --field F` | generate a full sequenced curriculum prompt |
+| `mentor models [--provider P] [--refresh]` | list Claude/ChatGPT models (live lookup with a key) |
+| `mentor config [--set K=V] [--unset K] [--reset]` | view/edit saved defaults |
+| `mentor learners` | list persisted learner profiles |
+| `mentor progress NAME [...]` | view/update a learner's mastered/shaky/misconception lists |
+| `mentor review NAME [--apply]` | assess the latest transcript and update the learner profile |
+| `mentor cards NAME [--add "Q :: A"] [--generate]` | manage spaced-repetition flashcards |
+| `mentor quiz NAME [--all] [--n N]` | review due flashcards (again/hard/good/easy) |
+| `mentor sessions [NAME]` | list recorded sessions |
+| `mentor transcript ID` | print a session transcript |
+| `mentor fields` | list curated field profiles |
+| `mentor providers` | list providers and their defaults |
+| `mentor doctor` | check the local setup |
+| `mentor version` | print the version |
+| `mentor interactive` | build a profile by answering prompts |
+
+Useful flags:
+
+| Flag | Purpose |
+|------|---------|
+| `--field` | the field to teach (quoted) |
+| `--level` | beginner \| intermediate \| advanced \| expert |
+| `--goal` | the learner's objective |
+| `--context` | the learner's background |
+| `--language` | teaching language |
+| `--style` | socratic \| coaching \| direct \| immersive |
+| `--mentor-name` | override the generated mentor name |
+| `--provider` | generic \| anthropic \| openai \| google \| ollama \| llamacpp (aliases: `claude`, `chatgpt`, `gpt`, `gemini`) |
+| `--emit` | text \| json \| modelfile \| markdown |
+| `--compact` | short prompt for small-context local models |
+| `--out FILE` | write to a file instead of stdout |
+| `--prompt-format` | auto \| markdown \| xml (auto = XML for Claude, markdown otherwise) |
+| `--thinking` / `--thinking-budget N` | Claude extended thinking |
+| `--reasoning-effort` | OpenAI reasoning models: none \| minimal \| low \| medium \| high \| xhigh \| max |
+| `--no-cache` | Claude: disable system-prompt caching |
+| `--show-thinking` | `run`: stream the model's reasoning (dimmed, stderr) |
+
+For **local models**, always use `--compact` if the model has under ~8k context,
+and prefer the `ollama` or `llamacpp` provider so the capability notes match the
+model's real constraints.
+
+### Live sessions (`mentor run`)
+
+Run the mentor directly against a backend — no copy-paste needed:
+
+```bash
+mentor run --field "Rust" --provider ollama --model qwen2.5:7b        # local
+mentor run rustbuddy                                                  # saved mentor
+mentor run --field "contract law" --provider claude --model claude-sonnet-5
+mentor run --field "Rust" --provider chatgpt --model gpt-5.6 --reasoning-effort high
+mentor run --field "Rust" --provider claude --thinking --show-thinking
+mentor run --field "Rust" --provider ollama --once "I'm ready"        # one turn
+mentor run --field "Rust" --provider chatgpt --dry-run                # show payload, send nothing
+```
+
+- **Claude** (`--provider claude`): the system prompt is sent as a cached
+  `system` block (prompt caching), shaped with XML section tags, with optional
+  extended thinking (`--thinking`, `--thinking-budget`).
+- **ChatGPT** (`--provider chatgpt`): reasoning models automatically use the
+  `developer` role and `max_completion_tokens`, drop unsupported `temperature`,
+  and accept `--reasoning-effort`; token usage is reported per turn.
+- **Local**: Ollama (`--host` or `$OLLAMA_HOST`) and llama.cpp / LM Studio
+  (`--host` or `$LLAMACPP_HOST`, OpenAI-compatible).
+- **Credentials**: set `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`, or drop them in
+  `./.env` or `~/.config/expert-mentor/.env`. Override endpoints with
+  `$OPENAI_BASE_URL` / `$ANTHROPIC_BASE_URL`.
+- **Model discovery**: `mentor models --provider claude --refresh` lists the
+  models your key can actually call. `mentor models` shows the built-in catalog.
+- Interactive commands: `/reset` clears history, `/exit` quits. Requests retry
+  automatically on rate limits and transient errors.
+- `--dry-run` prints the exact request body (including cache/thinking/reasoning
+  fields) and is handy for debugging.
+
+### Persistent learners (`--learner` / `--remember`)
+
+Give a session a memory so the mentor adapts across days instead of starting
+over:
+
+```bash
+mentor run --field "Rust" --provider ollama --remember        # auto-name from field
+mentor run --field "Rust" --provider claude --learner rust    # explicit name
+```
+
+- The mentor's system prompt is injected with the learner's **mastered**,
+  **shaky**, **misconception**, and **open-question** lists (only once there is
+  history to report).
+- Each session transcript is written to `~/.config/expert-mentor/sessions/`.
+- Curate the model yourself:
+
+```bash
+mentor progress rust --add-mastered ownership --add-shaky lifetimes \
+    --add-misconception "Rc == Arc" --goal "write idiomatic Rust"
+mentor learners
+mentor sessions rust
+mentor transcript <id>
+```
+
+Profiles live in `~/.config/expert-mentor/learners/<name>.json` — plain JSON you
+can edit by hand.
+
+**Automatic review.** After a session, let the model assess the transcript and
+update the record for you:
+
+```bash
+mentor review rust              # show proposed changes (calls the model)
+mentor review rust --apply      # write them to the profile
+mentor review rust --dry-run    # show the review prompt, call nothing
+```
+
+The reviewer reuses the provider the session was run with, extracts a strict
+JSON assessment (mastered / shaky / misconceptions / open questions / level /
+next lesson), and merges it — promoting anything newly mastered out of *shaky*.
+This closes the loop: run → transcript → assessment → updated profile, with no
+manual bookkeeping.
+
+**Spaced repetition.** Turn a session into flashcards and review them over time:
+
+```bash
+mentor cards rust --generate                   # build cards from the latest session
+mentor cards rust --add "What is ownership? :: Each value has one owner."
+mentor cards rust                              # list, with due counts
+mentor quiz rust                               # review what is due (again/hard/good/easy)
+mentor quiz rust --all --n 20                  # review ahead
+```
+
+Cards use an SM-2-lite scheduler (interval, ease, reps) stored in
+`~/.config/expert-mentor/learners/<name>.cards.json`, so review scheduling
+carries across sessions and machines.
+
+## Step 4 — Run the session (or hand off the prompt)
+
+If teaching inline, obey the loaded prompt's **Teaching Contract** without
+exception. The non-negotiables:
+
+1. Guide with hints before giving answers.
+2. One concept at a time; verify before advancing.
+3. After each explanation, ask a retrieval question the learner must answer.
+4. Every session leaves the learner having produced something.
+5. Never fabricate facts, citations, formulas, or APIs — flag uncertainty.
+
+If handing off, tell the user exactly where to paste the output and how to set
+the temperature (the script prints a recommended value).
+
+## Files
+
+- `pyproject.toml` — packaging metadata, console entry points, tooling config.
+- `LICENSE` — MIT.
+- `.github/workflows/ci.yml` — CI: self-test matrix, health check, package build.
+- `install.sh` / `uninstall.sh` — one-command setup and teardown.
+- `bin/mentor` — the `mentor` launcher (resolves symlinks, runs the generator).
+- `Makefile` — `make install | test | doctor | fields | demo | clean`.
+- `templates/mentor_system_prompt.md` — the master mentor prompt (edit to tune).
+- `templates/compact_prompt.md` — short variant for small local models.
+- `templates/curriculum_prompt.md` — curriculum-designer prompt.
+- `templates/review_prompt.md` — session-assessment (progress review) prompt.
+- `templates/cards_prompt.md` — flashcard-generation prompt.
+- `scripts/expert_mentor.py` — the CLI: provider-aware prompt/Modelfile/JSON generator.
+- `scripts/mentor_runtime.py` — dependency-free streaming chat adapters (Ollama, llama.cpp, OpenAI, Anthropic).
+- `scripts/mentor_memory.py` — persistent learner profiles and session transcripts.
+- `scripts/mentor_cards.py` — spaced-repetition flashcards (SM-2-lite scheduler).
+- `scripts/selftest.py` — dependency-free test suite (`make test`).
+- `references/pedagogy.md` — the teaching methods the mentor draws on.
+- `references/fields.md` — curated field profiles + how to add your own.
+- `references/providers.md` — capability notes and deployment recipes per provider.
+- `examples/` — ready-made generated outputs for common cases.

expert_mentor-0.6.2.data/data/share/expert-mentor/references/fields.md

@@ -0,0 +1,64 @@
+# Field profiles
+
+A **field profile** tells the mentor what professional competence looks like in
+a specific field: the concepts, the misconceptions, the authoritative sources,
+and the capstone that proves mastery. The generator ships with curated profiles
+for a few common fields and falls back to a solid generic profile for everything
+else.
+
+## Curated profiles (built in)
+
+- **quantum computing** — `quantum-computing`
+- **Rust** — `rust`
+- **organic chemistry** — `organic-chemistry`
+- **machine learning** — `machine-learning` (also matches "AI")
+- **macroeconomics** — `macroeconomics`
+- **contract law** — `contract-law`
+
+List them anytime:
+
+```bash
+mentor fields
+```
+
+## Adding your own
+
+Create `references/fields.json`. The generator merges it over the built-ins at
+startup. Keys are arbitrary; each value uses this schema:
+
+```json
+{
+  "my-field": {
+    "key": "the Human-readable field name",
+    "aliases": ["my field", "alternate spelling", "abbreviation"],
+    "mentor_name": "Dr. Example Name",
+    "notes": "A paragraph on what professionalism in this field means: the core reasoning, the standards, the traps, and the canonical anchors.",
+    "concepts": ["concept 1", "concept 2"],
+    "misconceptions": ["wrong model A", "wrong model B"],
+    "resources": ["Author, Title", "standard/body/venue"],
+    "capstone": "One realistic project that proves competence."
+  }
+}
+```
+
+### Writing good notes
+
+The `notes` paragraph is the highest-leverage part. A strong profile:
+
+1. Names the field's **foundational reasoning** and demands it first.
+2. States the **standards** a professional is held to.
+3. Names the **classic traps** learners fall into.
+4. Points at **real authorities** (textbooks, standards bodies, journals).
+
+### Matching rules
+
+The resolver checks, in order: exact key / alias match, then substring match,
+then falls back to the generic profile. Aliases let one profile cover many
+phrasings ("ml", "deep learning", "statistical learning").
+
+## The generic fallback
+
+For fields without a profile, the generator builds notes that force the mentor
+to establish vocabulary and models first, then tools and workflows, then applied
+judgement — while distinguishing consensus from debate and attacking
+misconceptions. This is deliberately field-agnostic but pedagogically strong.

expert_mentor-0.6.2.data/data/share/expert-mentor/references/pedagogy.md

@@ -0,0 +1,90 @@
+# Pedagogy — how the Expert Mentor teaches
+
+The mentor is not a content database. It is a teacher, and its behaviour is
+grounded in established learning science. This file explains the methods baked
+into `templates/mentor_system_prompt.md` so you can tune or extend them.
+
+## Core principles
+
+### 1. Zone of proximal development (Vygotsky)
+Teach just beyond what the learner can already do alone, but within reach with
+guidance. Too easy → boredom; too hard → shutdown. The mentor continuously
+probes to find this band and adjusts step size.
+
+### 2. Cognitive load theory (Sweller)
+Working memory is small. Introduce one new element at a time, use worked
+examples early, and only remove the scaffolds once the learner is fluent. This
+is why the mentor does "one concept at a time" and fades support.
+
+### 3. Retrieval practice and testing effect (Roediger & Karpicke)
+Pulling knowledge out of memory strengthens it far more than re-reading. Every
+explanation is followed by a question the learner must answer from memory.
+
+### 4. Spacing and interleaving
+Spread practice over sessions and mix related problem types rather than
+blocking. The mentor's roadmap revisits earlier milestones and mixes review into
+new practice.
+
+### 5. Scaffolding and fading (Wood, Bruner & Ross)
+Support is temporary. The mentor models → guides → watches → steps back.
+
+### 6. Formative feedback (Hattie & Timperley)
+Effective feedback answers three questions: Where am I going? How am I going?
+Where to next? The mentor names the exact gap and the next action; it never
+offers vague praise.
+
+### 7. Metacognition (Flavell)
+Strong learners monitor their own understanding. The mentor asks the learner to
+predict, self-explain, and summarise — building the habit of self-assessment.
+
+### 8. Threshold concepts and misconceptions
+Some ideas are gateways (e.g. pointers, eigenvalues, opportunity cost) that
+unlock everything above. Others are actively wrong mental models that block
+progress. The mentor targets both deliberately.
+
+## The teach/practice cycle
+
+```
+activate prior knowledge
+        ↓
+explain + worked example
+        ↓
+retrieval check (learner answers)
+        ↓
+    correct? ── no ──→ re-teach differently (new analogy, smaller step) → check again
+        │ yes
+        ↓
+guided practice → independent exercise → precise feedback
+        ↓
+advance milestone or consolidate
+```
+
+## Question types the mentor uses
+
+| Type | Example | Purpose |
+|------|---------|---------|
+| Retrieval | "Without looking, what does X do?" | Strengthen memory |
+| Prediction | "What will happen if we change Y?" | Activate reasoning |
+| Self-explanation | "Why does that step work?" | Deepen understanding |
+| Application | "Solve this new case." | Transfer |
+| Contrast | "How is X different from Z?" | Sharpen discrimination |
+| Metacognitive | "How confident are you, and why?" | Calibrate self-assessment |
+
+## Adapting to level
+
+- **Beginner** — concrete first, heavy analogy, small steps, lots of worked
+  examples, frequent checks, no jargon without definition.
+- **Intermediate** — connect ideas into systems, pressure-test with edge cases,
+  introduce trade-offs and "why not the obvious approach".
+- **Advanced** — focus on judgement, literature, and frontier debates; the
+  learner should be arguing and the mentor should be challenging.
+- **Expert** — peer-level discussion; the mentor probes limits, counterexamples,
+  and open problems rather than explaining basics.
+
+## What the mentor must never do
+
+- Dump a full solution when a hint would teach more.
+- Say "does that make sense?" instead of testing understanding.
+- Praise vaguely ("great!") without naming what was good.
+- Fabricate a source, formula, or API to look authoritative.
+- Let a misconception stand because the learner seemed satisfied.

expert_mentor-0.6.2.data/data/share/expert-mentor/references/providers.md

@@ -0,0 +1,132 @@
+# Providers — deployment recipes
+
+The same mentor prompt is adapted per provider because cloud models and local
+models have very different capability envelopes. The generator injects the right
+**capability notes** and emits a format each provider can consume.
+
+Run `mentor providers` to see defaults, or `mentor models` for the model catalog.
+
+## Capability envelopes
+
+| Provider | Aliases | Temperature | Default model | Capability notes |
+|----------|---------|-------------|---------------|------------------|
+| `generic` | — | 0.6 | any capable model | cloud notes |
+| `anthropic` | `claude` | 0.7 | `claude-sonnet-5` | Claude notes + XML shaping |
+| `openai` | `chatgpt`, `gpt`, `oai` | 0.7 | `gpt-5.6` | ChatGPT notes + markdown |
+| `google` | `gemini` | 0.8 | `gemini-flash-latest` | cloud notes |
+| `ollama` | `local` | 0.4 | `llama3.1:8b` | local notes |
+| `llamacpp` | — | 0.4 | local-gguf | local notes |
+
+- **Cloud notes** tell the model to exploit its large context: maintain a
+  detailed learner model, use rich analogies, cite real sources when confident.
+- **Claude notes** additionally ask for structured prose / XML tags and a clean
+  separation between private deliberation and what the learner sees.
+- **ChatGPT notes** additionally ask for clear markdown structure and explicit
+  next steps.
+- **Local notes** tell the model to compensate for limited context and reasoning:
+  follow the flow strictly, keep replies short, one question per reply, never
+  invent citations, restate the goal each turn.
+
+Discover the current model line-up any time:
+
+```bash
+mentor models                      # built-in catalog for Claude + ChatGPT
+mentor models --provider claude --refresh   # live lookup with your API key
+```
+
+## Anthropic (Claude)
+
+```bash
+mentor --field "quantum computing" --provider claude --emit json
+mentor run --field "Rust" --provider claude --model claude-sonnet-5
+```
+
+The generator and runtime both produce a correct **Messages API** request:
+
+- the mentor prompt is a top-level `system` **list of blocks** marked with
+  `cache_control: {"type": "ephemeral"}` — Anthropic **prompt caching**, a large
+  cost/latency win for a long, static system prompt (`--no-cache` disables it);
+- the prompt is re-shaped into **XML section tags** (`<identity>`,
+  `<the_teaching_contract>`, …) because Claude follows XML structure well
+  (`--prompt-format markdown` opts out);
+- optional **extended thinking**: `--thinking` (`--thinking-budget` default
+  4096). When thinking is on, `temperature` is omitted (the API requires the
+  default).
+- streaming understands `text_delta` and `thinking_delta`, and reports input,
+  **cache-read**, and output tokens per turn.
+
+Recommended: `max_tokens>=2048`. Current models: `claude-sonnet-5`,
+`claude-opus-5`, `claude-fable-5-1`, `claude-haiku-4-5`.
+
+## OpenAI (ChatGPT)
+
+```bash
+mentor --field "organic chemistry" --provider chatgpt --emit json
+mentor run --field "Rust" --provider chatgpt --model gpt-5.6 --reasoning-effort high
+```
+
+The request shape is adapted automatically from the model name:
+
+| Model family | System role | Token limit field | Temperature | Reasoning |
+|--------------|-------------|-------------------|-------------|-----------|
+| `gpt-5*`, `gpt-6*`, `o1…o9*` | `developer` | `max_completion_tokens` | omitted | `reasoning_effort` supported |
+| `gpt-4o`, `gpt-4.1`, etc. | `system` | `max_tokens` | sent | not supported |
+
+- `--reasoning-effort` accepts `none|minimal|low|medium|high|xhigh|max` (values
+  the model actually supports are a subset).
+- Streaming sets `stream_options.include_usage` and reports token usage.
+- Works unchanged with any OpenAI-compatible endpoint via `$OPENAI_BASE_URL`
+  (vLLM, Together, Groq, LM Studio server, …).
+
+## Google (Gemini)
+
+```bash
+mentor --field "macroeconomics" --provider google --emit json
+```
+
+Produces a `systemInstruction` + `contents` payload for the Generative Language
+API.
+
+## Ollama (local)
+
+```bash
+mentor --field "Rust" --level intermediate \
+    --provider ollama --emit modelfile --model qwen2.5:7b --compact > Modelfile
+ollama create expert-rust -f Modelfile
+ollama run expert-rust
+```
+
+The Modelfile pins `SYSTEM`, `temperature`, `num_ctx`, and `top_p`. Use
+`--compact` for 7B-and-under models and raise `--num-ctx` to match the model.
+
+## llama.cpp / LM Studio (local)
+
+```bash
+mentor --field "music theory" --provider llamacpp --emit json --compact
+```
+
+Emits a JSON object with `system_prompt`, `temperature`, `n_ctx`, and
+`max_tokens`. In LM Studio, paste `system_prompt` into the system-prompt field
+and match the parameters. In llama.cpp server, pass it via the chat template's
+system slot or your wrapper.
+
+## Choosing `--compact`
+
+Use `--compact` when:
+
+- the model has under ~8k context,
+- the model is 7B parameters or smaller,
+- the model tends to ignore long system prompts.
+
+The compact template strips the long teaching contract down to numbered rules
+and a short flow, which small models follow far more reliably.
+
+## Tuning tips
+
+- **Mentor too passive?** Raise temperature slightly or switch `--style direct`.
+- **Mentor gives answers away?** Switch `--style socratic` and say "don't give
+  me the answer yet" in your first message.
+- **Mentor invents sources?** Append "If you are not certain a source exists,
+  say so and tell me how to find it." Local notes already include this.
+- **Long-winded local model?** Add your own `num_predict` cap and keep
+  `--compact` on.

expert_mentor-0.6.2.data/data/share/expert-mentor/templates/cards_prompt.md

@@ -0,0 +1,33 @@
+« EXPERT MENTOR — FLASHCARD GENERATOR »
+Turns a session transcript into spaced-repetition flashcards.
+
+======================================================================
+SYSTEM PROMPT
+======================================================================
+
+You are {{MENTOR_NAME}}, a senior {{FIELD}} teacher. You have just taught a
+session, and you are turning it into high-quality flashcards for spaced
+repetition. Good cards force the learner to retrieve an idea, not recognise a
+phrase.
+
+Return ONLY a single JSON object:
+
+{
+  "cards": [
+    {"front": "a question or prompt", "back": "the answer", "tags": ["topic"]}
+  ]
+}
+
+# RULES
+
+- One atomic idea per card. Never combine two facts in one card.
+- `front` is a question, problem, or cloze prompt; `back` is the concise answer.
+- Test understanding over trivia. Prefer "why / how / when" over "what is the
+  name of"; include a short worked step if the card needs it.
+- Only cover material actually in the transcript. Do not invent content.
+- Do not duplicate cards or rephrase the same idea twice.
+- Use the field's real terminology; write the answer the way a practitioner
+  would say it.
+- Produce 5-20 cards. Output valid JSON and nothing else.
+
+{{CAPABILITY_NOTES}}

expert_mentor-0.6.2.data/data/share/expert-mentor/templates/compact_prompt.md

@@ -0,0 +1,34 @@
+« EXPERT MENTOR — COMPACT »
+Short system prompt for small-context local models (under ~8k context).
+
+======================================================================
+SYSTEM PROMPT
+======================================================================
+
+You are {{MENTOR_NAME}}, a professional {{FIELD}} teacher. Your job is to make
+the learner genuinely competent, not to show off.
+
+Learner: {{LEVEL}} level. Background: {{LEARNER_CONTEXT}}
+Goal: {{SESSION_GOAL}} Language: {{LANGUAGE}}
+{{LEARNER_HISTORY}}
+
+RULES (follow every reply):
+1. Teach one idea at a time. Short steps.
+2. Give a concrete example, then the general rule.
+3. Ask the learner to answer before moving on. One question per reply.
+4. If they are wrong, explain the exact gap and re-teach differently.
+5. Never invent facts or citations. If unsure, say so.
+6. Keep replies under 200 words unless teaching one full concept.
+7. End every reply with a question or a small task for the learner.
+
+FLOW:
+1st reply: introduce yourself in one line, then ask 2 questions about their
+current knowledge and their goal. Wait.
+2nd reply: give a 3-step learning plan. Ask if it fits. Wait.
+Then: loop — explain, example, check, exercise, feedback. Raise difficulty when
+they succeed, shrink the step when they struggle.
+End of session: ask them to summarise in their own words, then assign practice.
+
+{{CAPABILITY_NOTES}}
+
+Start with the first reply.