Merge pull request #1670 from ousamabenyounes/fix/issue-1651

docs: add Language Support section to smart-explore/SKILL.md (#1651)

plugin/skills/smart-explore/SKILL.md

@@ -143,3 +143,48 @@ Use smart_* tools for code exploration, Read for non-code files. Mix freely.
 | Explore agent | ~39,000-59,000 | Cross-file synthesis with narrative |
 
 **4-8x savings** on file understanding (outline + unfold vs Read). **11-18x savings** on codebase exploration vs Explore agent. The narrower the query, the wider the gap — a 27-line function costs 55x less to read via unfold than via an Explore agent, because the agent still reads the entire file.
+
+## Language Support
+
+Smart-explore uses **tree-sitter AST parsing** for structural analysis. Unsupported file types fall back to text-based search.
+
+### Bundled Languages
+
+| Language | Extensions |
+|----------|-----------|
+| JavaScript | `.js`, `.mjs`, `.cjs` |
+| TypeScript | `.ts` |
+| TSX / JSX | `.tsx`, `.jsx` |
+| Python | `.py`, `.pyw` |
+| Go | `.go` |
+| Rust | `.rs` |
+| Ruby | `.rb` |
+| Java | `.java` |
+| C | `.c`, `.h` |
+| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hh` |
+
+Files with unrecognized extensions are parsed as plain text — `smart_search` still works (grep-style), but `smart_outline` and `smart_unfold` will not extract structured symbols.
+
+### Custom Grammars (`.claude-mem.json`)
+
+You can register additional tree-sitter grammars for file types not in the bundled list. Create or update `.claude-mem.json` in your project root:
+
+```json
+{
+  "grammars": {
+    ".sol": "tree-sitter-solidity",
+    ".graphql": "tree-sitter-graphql"
+  }
+}
+```
+
+Each key is a file extension; each value is the npm package name of the tree-sitter grammar. The grammar must be installed locally (`npm install tree-sitter-solidity`). Once registered, `smart_outline` and `smart_unfold` will parse those extensions structurally instead of falling back to plain text.
+
+### Markdown Special Support
+
+Markdown files (`.md`, `.mdx`) receive special handling beyond the generic plain-text fallback:
+
+- **`smart_outline`** — extracts headings (`#`, `##`, `###`) as the symbol tree. Use it to navigate long documents without reading the full file.
+- **`smart_search`** — searches within code fences as well as prose, so queries for function names inside ` ```ts ``` ` blocks work as expected.
+- **`smart_unfold`** — expands heading sections rather than function bodies; each section up to the next same-level heading is returned as a chunk.
+- **Frontmatter** — YAML frontmatter (lines between leading `---` delimiters) is included in `smart_outline` output under a synthetic `frontmatter` symbol so metadata like `title:` and `description:` is visible without reading the whole file.

tests/utils/skill-docs-placement.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Regression test for misplaced smart-explore language docs (#1651)
+ *
+ * The smart-explore language support section was missing from smart-explore/SKILL.md
+ * and had previously been in mem-search/SKILL.md (where it doesn't belong).
+ */
+import { describe, it, expect } from 'bun:test';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const SKILLS_DIR = join(import.meta.dir, '../../plugin/skills');
+
+describe('skill docs placement (#1651)', () => {
+  it('smart-explore/SKILL.md contains Language Support section', () => {
+    const path = join(SKILLS_DIR, 'smart-explore/SKILL.md');
+    expect(existsSync(path)).toBe(true);
+    const content = readFileSync(path, 'utf-8');
+
+    expect(content).toContain('Language Support');
+    expect(content).toContain('tree-sitter');
+  });
+
+  it('smart-explore/SKILL.md lists bundled languages', () => {
+    const content = readFileSync(join(SKILLS_DIR, 'smart-explore/SKILL.md'), 'utf-8');
+
+    const expectedLanguages = [
+      'JavaScript',
+      'TypeScript',
+      'TSX / JSX',
+      'Python',
+      'Go',
+      'Rust',
+      'Ruby',
+      'Java',
+      'C',
+      'C++',
+    ];
+
+    for (const language of expectedLanguages) {
+      expect(content).toContain(language);
+    }
+
+    expect(content).toContain('Files with unrecognized extensions are parsed as plain text');
+  });
+
+  it('mem-search/SKILL.md does NOT contain tree-sitter or language grammar docs', () => {
+    const path = join(SKILLS_DIR, 'mem-search/SKILL.md');
+    expect(existsSync(path)).toBe(true);
+    const content = readFileSync(path, 'utf-8');
+
+    // Language support docs belong in smart-explore, not mem-search
+    expect(content).not.toContain('tree-sitter');
+    expect(content).not.toContain('Bundled Languages');
+  });
+});