codewhale.history 2.8.0 → 2.8.2

package/README.md

@@ -38,10 +38,74 @@ codewhale-tools-install -p <target-path>        # specific workspace
 ```
 
 ## After install
-- **`//tools`** — lists every tool available in the current session
-- **`//history`** — lists all chat sessions for the current workspace with cost totals
-- **`//snapshot`** — toggle pre-edit file backups (`on`, `off`, `status`)
-- **`//teach-me`** — interactive code quiz that tests your knowledge of the current codebase
+
+### `//tools`
+Lists every tool available in the current session, grouped by category (File I/O,
+Search, Git, Sub-agents, Shell, Planning, etc.), with a brief description of what
+each tool does. Read-only — no files touched.
+
+### `//history`
+Lists all chat sessions for the current workspace. Each session row shows:
+
+- **Date/time** — when the session was created
+- **Title** — session title
+- **Messages** — message count for that session
+- **Tokens** — tokens consumed (with thousands separators)
+- **Cost** — session cost in USD (to 4 decimal places)
+- **Model** — which model was used
+
+A **TOTAL** row at the bottom summarizes the number of sessions, total messages,
+total tokens, and total cost across all sessions.
+
+### `//snapshot`
+Toggle pre-edit file backups: `//snapshot on`, `//snapshot off`,
+`//snapshot status`.
+
+**Why you'll want this:** Snapshot is designed for folders that are **not** Git
+repos — especially folders full of Office documents (`.docx`, `.pptx`, `.xlsx`,
+`.pdf`) that an AI agent is about to edit. Before every file modification,
+snapshot saves a timestamped copy into `_snapshots/` so you can always get back
+to the pre-AI version:
+
+```
+report.docx  →  _snapshots/report.2026-06-21_14-30-00.docx
+```
+
+If the workspace already has a `.git` directory, snapshot politely declines —
+Git already has your back.
+
+### `//teach-me`
+An interactive code-teaching quiz that randomly selects real snippets from your
+current project and quizzes you on what they do and how they work. Great for
+onboarding to a new codebase or sharpening your language skills.
+
+**Triggers:** `teach me` · `quiz me` · `test my knowledge` · `code quiz` ·
+`drill me`
+
+**Modifiers (combine freely):**
+
+| Modifier | Example | What it does |
+|----------|---------|-------------|
+| Language | `teach me python` | Restrict to Python, TypeScript, Rust, Go, Java… |
+| Level | `teach me level 3` or `teach me l3` | Set difficulty 1–5 (default: 3) |
+| Scope | `teach me services/` | Narrow to a specific file or folder |
+| Concept | `teach me decorators` | Target: decorators, async, generators, context managers, comprehensions, error handling, type hints, threading |
+
+**Difficulty levels:**
+
+| Level | Line range | What you'll face |
+|-------|-----------|------------------|
+| 1 | 5–15 | Straight-line logic, `if`/`else`, basic function calls |
+| 2 | 8–20 | Loops, list/dict operations, simple `try`/`except` |
+| 3 | 12–30 | Comprehensions, decorators, `with` statements, multiple branches |
+| 4 | 18–45 | Generators, `async`/`await`, descriptors, threading, closures |
+| 5 | 25–55 | Metaclasses, complex async patterns, multi-threading, architectural glue |
+
+**Mid-round commands:** `hint` (get a nudge) · `skip` (see the answer) ·
+`next` (draw a new snippet) · `level N` · `easier` · `harder` · `stop`
+
+**At the end** you get a session summary: rounds completed, files covered, what
+you're strong on, what to review, and a suggested next level.
 
 ## Requirements
 - Node.js (for the `codewhale-history` command)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codewhale.history",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "description": "CodeWhale utility commands: session history, tool listing, file snapshot, interactive code quiz — global install",
   "bin": {
     "codewhale-history": "./_list_sessions.js",

package/skills/teach-me/SKILL.md

@@ -26,6 +26,13 @@ Optionally followed by modifiers:
 - `teach me python` — restrict to a specific language
 - `teach me level 3` / `teach me l3` — set difficulty (1–5)
 - `teach me <file or module>` — narrow scope to a specific file, directory, or module
+- `teach me <concept>` — target a specific language concept. Examples:
+  `teach me decorators`, `teach me async`, `teach me generators`,
+  `teach me context managers`, `teach me comprehensions`,
+  `teach me error handling`, `teach me type hints`, `teach me threading`
+
+Modifiers combine freely: `teach me decorators level 4`,
+`teach me async services/`, `teach me generators l2`
 
 If no level is specified, default to **level 3** and adjust based on
 performance across rounds.
@@ -84,13 +91,32 @@ Do not repeat a snippet unless the user explicitly asks or all candidates
 are exhausted. Prefer cycling through files before returning to the same
 file.
 
+#### Concept Targeting
+
+When the user targets a specific concept, filter snippets to ensure they
+contain that concept. After selecting a random candidate, verify it with
+`grep_files` on the file for the concept signal. If the candidate doesn't
+match, pick another random snippet (retry up to 10 times; if still no
+match, relax the filter and note the fallback to the user).
+
+| Trigger phrase | Signal to verify in the snippet |
+|---|---|
+| `decorators` | `@` immediately above a `def` line |
+| `async` | `async def` or `await` |
+| `generators` | `yield` |
+| `context managers` | `with` statement or `__enter__`/`__exit__` |
+| `comprehensions` | `for ... in` inside `[`, `{`, or `(` |
+| `error handling` | `try:`, `except`, or `finally` |
+| `type hints` | `:` type annotation in function signatures or variable assignments |
+| `threading` | `Thread(`, `Lock(`, `Queue(`, or `threading.` |
+
 ### 3. Presentation — Show the Snippet
 
 For each round, present the snippet with its filename:
 
 ```
 ---
-## Round N — Level X | `path/to/file.py` (lines A–B)
+## Round N — Level X · concept | `path/to/file.py` (lines A–B)
 
 ```python
  42  def calculate_position_size(
@@ -119,6 +145,7 @@ Guidelines:
 - Strip only excessive blank lines; keep natural spacing
 - Show the function/class signature with its decorators
 - Show the filename and line range in the header
+- The `· concept` portion only appears when a concept is targeted; omit it during free-play rounds
 - If the snippet depends on one obvious external type or constant, include a
   brief inline note
 - **Before presenting, scan for secrets.** Redact API keys, tokens, passwords,
@@ -149,6 +176,20 @@ Evaluate across two dimensions, scaled to the current difficulty level.
 | 4 | Generator mechanics (`yield`), `async`/`await` internals, descriptor protocol, closures, threading primitives |
 | 5 | Coroutine internals, metaclass programming, GIL implications, memory model, `__slots__`, MRO, weak references |
 
+#### Weighted Evaluation for Targeted Concepts
+
+When a concept is targeted (e.g., `teach me decorators`), bias the
+evaluation toward that concept:
+
+- **Mechanics axis:** The targeted concept carries extra weight. Missing
+  it is a significant gap even if other mechanics are handled well.
+- **Strike hints:** Always steer strike 1 toward the targeted concept
+  before hinting about any other missed item.
+- **Feedback ordering:** List the targeted concept first under "What you
+  missed" or "What you could sharpen."
+- **Success bar:** To "meet expectations," the user must correctly
+  explain the targeted concept at the current level's depth.
+
 #### The Three-Strikes Rule
 
 If the user's answer does **not** meet the expectations for the current