codewhale.history 2.8.1 → 2.8.3

package/README.md

@@ -38,10 +38,78 @@ 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.
+
+**`//tools help`** or **`//tools readme`** — displays this full README inside any
+CodeWhale session, so you can always reference the command docs without leaving
+the terminal.
+
+### `//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.1",
+  "version": "2.8.3",
   "description": "CodeWhale utility commands: session history, tool listing, file snapshot, interactive code quiz — global install",
   "bin": {
     "codewhale-history": "./_list_sessions.js",

package/skills/tools/tools-skill/SKILL.md

@@ -13,6 +13,9 @@ When the user types `//tools`, enumerate every tool available to the model in th
 3. For each tool, provide the name and a one-line description of what it does
 4. Present as a readable terminal-friendly list
 
+### `//tools help` / `//tools readme`
+When the user types `//tools help` or `//tools readme`, read and display the full tools README from `~/.codewhale/tools-readme.md`. This file is copied during install and contains detailed docs for all four commands: `//tools`, `//history`, `//snapshot`, and `//teach-me`.
+
 ## Notes
 - Read-only — no files modified or state changed
 - The tool list is dynamic per-session — do not hardcode it

package/tools-install.js

@@ -70,6 +70,17 @@ if (fs.existsSync(instructionsSource)) {
   console.log('  WARNING: instructions.md not found.');
 }
 
+// ── 2b. Copy README for //tools help ───────────────────
+const readmeSource = path.join(sourceDir, 'README.md');
+const readmeDest = path.join(os.homedir(), '.codewhale', 'tools-readme.md');
+
+if (fs.existsSync(readmeSource)) {
+  fs.copyFileSync(readmeSource, readmeDest);
+  console.log('  Copied README.md for //tools help.');
+} else {
+  console.log('  WARNING: README.md not found.');
+}
+
 // ── 3. Verify ──────────────────────────────────────────
 console.log('[3/3] Verifying installation...');
 let errors = 0;
@@ -79,7 +90,8 @@ const checklist = {
   'tools skill': path.join(skillsDest, 'tools', 'tools-skill', 'SKILL.md'),
   'snapshot skill': path.join(skillsDest, 'snapshot', 'SKILL.md'),
   'teach-me skill': path.join(skillsDest, 'teach-me', 'SKILL.md'),
-  'workspace instructions': instructionsDest
+  'workspace instructions': instructionsDest,
+  'tools readme': readmeDest
 };
 
 for (const [name, filePath] of Object.entries(checklist)) {