From e7bf2ac65ad63f8ab706dd5982bbcad30338e29c Mon Sep 17 00:00:00 2001
From: Ousama Ben Younes <benyounes.ousama@gmail.com>
Date: Fri, 10 Apr 2026 10:52:31 +0000
Subject: [PATCH] docs: add custom grammar and markdown special support
 sections to smart-explore/SKILL.md

- Add Custom Grammars (.claude-mem.json) section explaining how to register
  additional tree-sitter parsers for unsupported file extensions
- Add Markdown Special Support section documenting heading-based outline,
  code-fence search, section unfold, and frontmatter extraction behaviors
- Expand bundled language test to cover all 10 documented languages plus
  the plain-text fallback sentence to prevent partial doc regressions

Co-Authored-By: Claude <noreply@anthropic.com>
---
 plugin/skills/smart-explore/SKILL.md     | 24 ++++++++++++++++++++++++
 tests/utils/skill-docs-placement.test.ts | 24 ++++++++++++++++++------
 2 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/plugin/skills/smart-explore/SKILL.md b/plugin/skills/smart-explore/SKILL.md
index 19799d86..3bfda66f 100644
--- a/plugin/skills/smart-explore/SKILL.md
+++ b/plugin/skills/smart-explore/SKILL.md
@@ -164,3 +164,27 @@ Smart-explore uses **tree-sitter AST parsing** for structural analysis. Unsuppor
 | 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.
diff --git a/tests/utils/skill-docs-placement.test.ts b/tests/utils/skill-docs-placement.test.ts
index f3b46d6c..d3035195 100644
--- a/tests/utils/skill-docs-placement.test.ts
+++ b/tests/utils/skill-docs-placement.test.ts
@@ -23,12 +23,24 @@ describe('skill docs placement (#1651)', () => {
   it('smart-explore/SKILL.md lists bundled languages', () => {
     const content = readFileSync(join(SKILLS_DIR, 'smart-explore/SKILL.md'), 'utf-8');
 
-    // Core languages must be documented
-    expect(content).toContain('JavaScript');
-    expect(content).toContain('TypeScript');
-    expect(content).toContain('Python');
-    expect(content).toContain('Go');
-    expect(content).toContain('Rust');
+    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', () => {