heraspec 0.1.13 → 0.1.15

package/dist/core/templates/skills/scripts/search.py

@@ -4,7 +4,7 @@
 UI/UX Builder Search - BM25, Vector, and Hybrid search engine for UI/UX style guides
 Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--mode <mode>] [--max-results 3]
 
-Domains: style, prompt, color, chart, landing, product, ux, typography, pages
+Domains: style, prompt, color, chart, landing, product, ux, typography, pages, design-system
 Stacks: html-tailwind, react, nextjs, vue, svelte, swiftui, react-native, flutter
 Modes: bm25 (default), vector, hybrid
 

package/dist/core/templates/skills/seo-audit/skill.md

@@ -0,0 +1,75 @@
+# Skill: SEO Audit (Cross-Cutting)
+
+## Purpose
+
+Run a comprehensive SEO audit — keyword research, on-page analysis, content gaps, technical checks, and competitor comparison to generate a prioritized SEO action plan.
+
+## When to Use
+
+- When assessing a website's overall SEO health and indexation status.
+- When researching keyword opportunities and identifying high-volume, low-difficulty search queries.
+- When identifying content gaps where competitors rank higher.
+- When reviewing technical website issues (crawlability, page speed, structured schema data).
+
+## Step-by-Step Process
+
+### Step 1: Keyword & Competitor Research
+- Extract primary and secondary keywords relevant to the business/domain.
+- Group keywords by search intent (informational, navigational, commercial, transactional).
+- Identify top 2-3 organic competitors.
+
+### Step 2: On-Page SEO Analysis
+- Verify title tag length (50-60 chars) and meta description length (150-160 chars).
+- Confirm presence of exactly one H1 tag per page.
+- Evaluate subheading hierarchy (H2/H3) and keyword usage.
+- Assess image alt text and URL clean structure.
+
+### Step 3: Content Gap & Freshness Review
+- Detect topics covered by competitors but missing on the site.
+- Identify pages with thin content (<300 words) or content older than 12 months.
+
+### Step 4: Technical SEO Audit
+- Review Robots.txt and XML sitemap configurations.
+- Check canonical tags, HTTPS mixed content, and 404 broken links.
+- Review Page Speed and Core Web Vitals (LCP, INP, CLS) markers.
+
+### Step 5: Prioritized Action Plan Formulation
+- Group recommendations into "Quick Wins" (<2h effort, high impact) and "Strategic Investments" (long-term, pillar pages).
+
+## Required Input
+
+- **Domain/URL**: The website to audit.
+- **Audit Type**: Full site audit, keyword research, content gap, or technical SEO check.
+- **Target Keywords** (Optional): Specific terms already being targeted.
+- **Competitors** (Optional): Specific competitor URLs/domains.
+
+## Expected Output
+
+- **Executive Summary**: 3-5 sentence overview of SEO health and top 3 priorities.
+- **Keyword Table**: Formatted table with Estimated Difficulty, Opportunity Score, and Intent.
+- **On-Page Issues Table**: Issues categorized by Severity (Critical, High, Medium, Low).
+- **Technical SEO Checklist**: Status (Pass, Fail, Warning) of crawlability, speed, and schema.
+- **Prioritized Action Plan**: Split into Quick Wins and Strategic Investments.
+
+## Tone & Rules
+
+- Write in a professional, marketing-focused, data-driven tone.
+- Do not make generic claims; base recommendations on specific, quantifiable SEO principles.
+- Use bullet points and markdown tables for maximum scannability.
+
+## Available Templates
+
+- None
+
+## Available Scripts
+
+- None
+
+## Examples
+
+See `examples/` directory.
+
+## Links to Other Skills
+
+- **documents**: Use to draft the final SEO audit report or content briefs.
+- **ui-ux**: Use to optimize pages for Core Web Vitals and mobile responsiveness.

package/dist/core/templates/skills/seo-audit/skill.vi.md

@@ -0,0 +1,75 @@
+# Kỹ năng: Kiểm toán SEO (SEO Audit) (Cross-Cutting)
+
+## Mục đích
+
+Thực hiện kiểm toán SEO toàn diện — nghiên cứu từ khóa, phân tích trên trang (on-page), tìm khoảng trống nội dung, kiểm tra kỹ thuật (technical SEO), và so sánh đối thủ cạnh tranh để lập kế hoạch hành động SEO tối ưu.
+
+## Khi nào sử dụng
+
+- Khi đánh giá sức khỏe SEO tổng thể và trạng thái lập chỉ mục (indexation) của một website.
+- Khi tìm kiếm cơ hội từ khóa và xác định các truy vấn tìm kiếm có lưu lượng cao nhưng độ khó thấp.
+- Khi phát hiện các khoảng trống nội dung mà đối thủ đang xếp hạng cao hơn.
+- Khi rà soát các vấn đề kỹ thuật của website (khả năng thu thập thông tin - crawlability, tốc độ trang, dữ liệu cấu trúc schema).
+
+## Quy trình từng bước
+
+### Bước 1: Nghiên cứu Từ khóa & Đối thủ cạnh tranh
+- Trích xuất từ khóa chính và phụ liên quan đến lĩnh vực kinh doanh/tên miền.
+- Phân nhóm từ khóa theo mục đích tìm kiếm (thông tin, điều hướng, thương mại, giao dịch).
+- Xác định 2-3 đối thủ cạnh tranh trực tiếp trên kết quả tìm kiếm tự nhiên.
+
+### Bước 2: Phân tích SEO On-Page
+- Kiểm tra độ dài thẻ tiêu đề (50-60 ký tự) và thẻ mô tả meta (150-160 ký tự).
+- Đảm bảo mỗi trang chỉ có duy nhất một thẻ H1.
+- Đánh giá cấu trúc phân cấp tiêu đề (H2/H3) và cách phân bổ từ khóa.
+- Đánh giá thuộc tính alt của ảnh và cấu trúc đường dẫn (URL) thân thiện.
+
+### Bước 3: Đánh giá Khoảng trống & Độ mới của Nội dung
+- Phát hiện các chủ đề đối thủ đã bao phủ nhưng trang web của bạn chưa có.
+- Xác định các trang có nội dung mỏng (<300 từ) hoặc không được cập nhật trong vòng 12 tháng qua.
+
+### Bước 4: Kiểm toán Kỹ thuật (Technical SEO)
+- Kiểm tra cấu hình file Robots.txt và sơ đồ trang XML sitemap.
+- Kiểm tra thẻ canonical, lỗi bảo mật hỗn hợp HTTPS và các liên kết gãy 404.
+- Đánh giá tốc độ tải trang và các chỉ số Core Web Vitals (LCP, INP, CLS).
+
+### Bước 5: Lập Kế hoạch Hành động Ưu tiên
+- Phân nhóm các đề xuất thành "Thành công nhanh" (Quick Wins - tốn ít hơn 2h thực hiện, hiệu quả ngay) và "Đầu tư Chiến lược" (Strategic Investments - dài hạn, xây dựng cụm chủ đề pillar page).
+
+## Input yêu cầu
+
+- **Domain/URL**: Trang web cần kiểm toán.
+- **Loại kiểm toán**: Kiểm toán toàn bộ trang, nghiên cứu từ khóa, phân tích khoảng trống nội dung, hoặc kiểm tra SEO kỹ thuật.
+- **Từ khóa mục tiêu** (Không bắt buộc): Các cụm từ cụ thể mà dự án đang muốn nhắm tới.
+- **Đối thủ cạnh tranh** (Không bắt buộc): Tên miền của các đối thủ cần so sánh.
+
+## Output mong đợi
+
+- **Tóm tắt điều hành**: Bản tóm tắt 3-5 câu về tình trạng SEO của website và 3 ưu tiên hàng đầu.
+- **Bảng Từ khóa**: Bảng định dạng rõ ràng gồm Độ khó ước tính, Điểm cơ hội và Ý định tìm kiếm.
+- **Bảng lỗi On-Page**: Danh sách các lỗi được phân loại theo mức độ nghiêm trọng (Nghiêm trọng, Cao, Trung bình, Thấp).
+- **Checklist SEO Kỹ thuật**: Trạng thái (Đạt, Lỗi, Cảnh báo) của các mục crawlability, tốc độ và dữ liệu cấu trúc schema.
+- **Kế hoạch hành động**: Được chia thành Quick Wins và Strategic Investments.
+
+## Giọng điệu & Quy tắc
+
+- Sử dụng giọng điệu chuyên nghiệp, định hướng marketing và dựa trên dữ liệu thực tế.
+- Tránh đưa ra các nhận định chung chung; các đề xuất phải dựa trên các nguyên tắc SEO cụ thể, có thể định lượng được.
+- Sử dụng các danh sách dạng dấu chấm và bảng markdown để đảm bảo dễ đọc nhất.
+
+## Templates có sẵn
+
+- Không có
+
+## Scripts có sẵn
+
+- Không có
+
+## Ví dụ
+
+Xem thư mục `examples/`.
+
+## Liên kết với các kỹ năng khác
+
+- **documents**: Dùng để viết báo cáo kiểm toán SEO cuối cùng hoặc lập dàn ý nội dung (content briefs).
+- **ui-ux**: Dùng để tối ưu hóa trang web cho Core Web Vitals và khả năng tương thích trên thiết bị di động.

package/dist/core/templates/skills/seo-audit-skill.md

@@ -0,0 +1,75 @@
+# Skill: SEO Audit (Cross-Cutting)
+
+## Purpose
+
+Run a comprehensive SEO audit — keyword research, on-page analysis, content gaps, technical checks, and competitor comparison to generate a prioritized SEO action plan.
+
+## When to Use
+
+- When assessing a website's overall SEO health and indexation status.
+- When researching keyword opportunities and identifying high-volume, low-difficulty search queries.
+- When identifying content gaps where competitors rank higher.
+- When reviewing technical website issues (crawlability, page speed, structured schema data).
+
+## Step-by-Step Process
+
+### Step 1: Keyword & Competitor Research
+- Extract primary and secondary keywords relevant to the business/domain.
+- Group keywords by search intent (informational, navigational, commercial, transactional).
+- Identify top 2-3 organic competitors.
+
+### Step 2: On-Page SEO Analysis
+- Verify title tag length (50-60 chars) and meta description length (150-160 chars).
+- Confirm presence of exactly one H1 tag per page.
+- Evaluate subheading hierarchy (H2/H3) and keyword usage.
+- Assess image alt text and URL clean structure.
+
+### Step 3: Content Gap & Freshness Review
+- Detect topics covered by competitors but missing on the site.
+- Identify pages with thin content (<300 words) or content older than 12 months.
+
+### Step 4: Technical SEO Audit
+- Review Robots.txt and XML sitemap configurations.
+- Check canonical tags, HTTPS mixed content, and 404 broken links.
+- Review Page Speed and Core Web Vitals (LCP, INP, CLS) markers.
+
+### Step 5: Prioritized Action Plan Formulation
+- Group recommendations into "Quick Wins" (<2h effort, high impact) and "Strategic Investments" (long-term, pillar pages).
+
+## Required Input
+
+- **Domain/URL**: The website to audit.
+- **Audit Type**: Full site audit, keyword research, content gap, or technical SEO check.
+- **Target Keywords** (Optional): Specific terms already being targeted.
+- **Competitors** (Optional): Specific competitor URLs/domains.
+
+## Expected Output
+
+- **Executive Summary**: 3-5 sentence overview of SEO health and top 3 priorities.
+- **Keyword Table**: Formatted table with Estimated Difficulty, Opportunity Score, and Intent.
+- **On-Page Issues Table**: Issues categorized by Severity (Critical, High, Medium, Low).
+- **Technical SEO Checklist**: Status (Pass, Fail, Warning) of crawlability, speed, and schema.
+- **Prioritized Action Plan**: Split into Quick Wins and Strategic Investments.
+
+## Tone & Rules
+
+- Write in a professional, marketing-focused, data-driven tone.
+- Do not make generic claims; base recommendations on specific, quantifiable SEO principles.
+- Use bullet points and markdown tables for maximum scannability.
+
+## Available Templates
+
+- None
+
+## Available Scripts
+
+- None
+
+## Examples
+
+See `examples/` directory.
+
+## Links to Other Skills
+
+- **documents**: Use to draft the final SEO audit report or content briefs.
+- **ui-ux**: Use to optimize pages for Core Web Vitals and mobile responsiveness.

package/dist/core/templates/skills/seo-audit-skill.vi.md

@@ -0,0 +1,75 @@
+# Kỹ năng: Kiểm toán SEO (SEO Audit) (Cross-Cutting)
+
+## Mục đích
+
+Thực hiện kiểm toán SEO toàn diện — nghiên cứu từ khóa, phân tích trên trang (on-page), tìm khoảng trống nội dung, kiểm tra kỹ thuật (technical SEO), và so sánh đối thủ cạnh tranh để lập kế hoạch hành động SEO tối ưu.
+
+## Khi nào sử dụng
+
+- Khi đánh giá sức khỏe SEO tổng thể và trạng thái lập chỉ mục (indexation) của một website.
+- Khi tìm kiếm cơ hội từ khóa và xác định các truy vấn tìm kiếm có lưu lượng cao nhưng độ khó thấp.
+- Khi phát hiện các khoảng trống nội dung mà đối thủ đang xếp hạng cao hơn.
+- Khi rà soát các vấn đề kỹ thuật của website (khả năng thu thập thông tin - crawlability, tốc độ trang, dữ liệu cấu trúc schema).
+
+## Quy trình từng bước
+
+### Bước 1: Nghiên cứu Từ khóa & Đối thủ cạnh tranh
+- Trích xuất từ khóa chính và phụ liên quan đến lĩnh vực kinh doanh/tên miền.
+- Phân nhóm từ khóa theo mục đích tìm kiếm (thông tin, điều hướng, thương mại, giao dịch).
+- Xác định 2-3 đối thủ cạnh tranh trực tiếp trên kết quả tìm kiếm tự nhiên.
+
+### Bước 2: Phân tích SEO On-Page
+- Kiểm tra độ dài thẻ tiêu đề (50-60 ký tự) và thẻ mô tả meta (150-160 ký tự).
+- Đảm bảo mỗi trang chỉ có duy nhất một thẻ H1.
+- Đánh giá cấu trúc phân cấp tiêu đề (H2/H3) và cách phân bổ từ khóa.
+- Đánh giá thuộc tính alt của ảnh và cấu trúc đường dẫn (URL) thân thiện.
+
+### Bước 3: Đánh giá Khoảng trống & Độ mới của Nội dung
+- Phát hiện các chủ đề đối thủ đã bao phủ nhưng trang web của bạn chưa có.
+- Xác định các trang có nội dung mỏng (<300 từ) hoặc không được cập nhật trong vòng 12 tháng qua.
+
+### Bước 4: Kiểm toán Kỹ thuật (Technical SEO)
+- Kiểm tra cấu hình file Robots.txt và sơ đồ trang XML sitemap.
+- Kiểm tra thẻ canonical, lỗi bảo mật hỗn hợp HTTPS và các liên kết gãy 404.
+- Đánh giá tốc độ tải trang và các chỉ số Core Web Vitals (LCP, INP, CLS).
+
+### Bước 5: Lập Kế hoạch Hành động Ưu tiên
+- Phân nhóm các đề xuất thành "Thành công nhanh" (Quick Wins - tốn ít hơn 2h thực hiện, hiệu quả ngay) và "Đầu tư Chiến lược" (Strategic Investments - dài hạn, xây dựng cụm chủ đề pillar page).
+
+## Input yêu cầu
+
+- **Domain/URL**: Trang web cần kiểm toán.
+- **Loại kiểm toán**: Kiểm toán toàn bộ trang, nghiên cứu từ khóa, phân tích khoảng trống nội dung, hoặc kiểm tra SEO kỹ thuật.
+- **Từ khóa mục tiêu** (Không bắt buộc): Các cụm từ cụ thể mà dự án đang muốn nhắm tới.
+- **Đối thủ cạnh tranh** (Không bắt buộc): Tên miền của các đối thủ cần so sánh.
+
+## Output mong đợi
+
+- **Tóm tắt điều hành**: Bản tóm tắt 3-5 câu về tình trạng SEO của website và 3 ưu tiên hàng đầu.
+- **Bảng Từ khóa**: Bảng định dạng rõ ràng gồm Độ khó ước tính, Điểm cơ hội và Ý định tìm kiếm.
+- **Bảng lỗi On-Page**: Danh sách các lỗi được phân loại theo mức độ nghiêm trọng (Nghiêm trọng, Cao, Trung bình, Thấp).
+- **Checklist SEO Kỹ thuật**: Trạng thái (Đạt, Lỗi, Cảnh báo) của các mục crawlability, tốc độ và dữ liệu cấu trúc schema.
+- **Kế hoạch hành động**: Được chia thành Quick Wins và Strategic Investments.
+
+## Giọng điệu & Quy tắc
+
+- Sử dụng giọng điệu chuyên nghiệp, định hướng marketing và dựa trên dữ liệu thực tế.
+- Tránh đưa ra các nhận định chung chung; các đề xuất phải dựa trên các nguyên tắc SEO cụ thể, có thể định lượng được.
+- Sử dụng các danh sách dạng dấu chấm và bảng markdown để đảm bảo dễ đọc nhất.
+
+## Templates có sẵn
+
+- Không có
+
+## Scripts có sẵn
+
+- Không có
+
+## Ví dụ
+
+Xem thư mục `examples/`.
+
+## Liên kết với các kỹ năng khác
+
+- **documents**: Dùng để viết báo cáo kiểm toán SEO cuối cùng hoặc lập dàn ý nội dung (content briefs).
+- **ui-ux**: Dùng để tối ưu hóa trang web cho Core Web Vitals và khả năng tương thích trên thiết bị di động.

package/dist/core/templates/skills/smart-explore/skill.md

@@ -0,0 +1,141 @@
+---
+name: smart-explore
+description: Token-efficient code exploration — view file structure, search symbols, and read specific implementations without loading full files. Reduces token usage by 4-18x compared to reading entire files.
+projectType: all
+---
+
+# Smart Explore Skill
+
+## Purpose
+
+Enable AI agents to **explore codebases efficiently** by viewing structural outlines, searching for symbols, and extracting specific implementations — without reading entire files. This dramatically reduces token consumption when navigating large projects.
+
+## When to Use
+
+- **Understanding a new file**: Use `outline` instead of reading the full file
+- **Finding where something is defined**: Use `search` to locate symbols across the project
+- **Reading a specific function**: Use `unfold` to extract just that function's code
+
+## Token Savings
+
+| Method | Typical Token Cost | Notes |
+|--------|-------------------|-------|
+| Read full file | ~12,000+ | All content, most irrelevant |
+| **Outline** | ~1,000-2,000 | Structural skeleton only |
+| **Search** | ~2,000-6,000 | Symbol locations across codebase |
+| **Unfold** | ~400-2,100 | Exact function/class source |
+
+**Savings: 4-18x** compared to reading full files.
+
+## Available Commands
+
+### 1. Outline — Structural Skeleton
+
+View all symbols (functions, classes, interfaces, exports) in a file without reading the full source:
+
+```bash
+heraspec explore outline src/core/memory/memory-store.ts
+```
+
+**Output example:**
+```
+## 📄 src/core/memory/memory-store.ts
+*typescript | 285 lines | ~71250 tokens*
+
+🏛️ export class MemoryStore (L20-285)
+  ↳ open() (L32-58)
+  ↳ close() (L63-68)
+  ↳ addObservation(input) (L88-120)
+  ↳ getObservationById(id) (L125-132)
+  ↳ getRecentObservations(project, limit) (L140-160)
+  ↳ addSummary(input) (L165-195)
+  ↳ getStatus(project) (L200-260)
+```
+
+### 2. Search — Find Symbols Across Codebase
+
+Search for functions, classes, interfaces by name across the project:
+
+```bash
+heraspec explore search "MemoryStore" src/
+heraspec explore search "addObservation" src/ --limit 10
+```
+
+**Output example:**
+```
+## Symbol Search: "MemoryStore" (3 results)
+
+| Rel | Type | Name | File | Lines |
+|-----|------|------|------|-------|
+| 100% | 🏛️ class | MemoryStore | src/core/memory/memory-store.ts | L20-285 |
+| 60% | ⚡ function | MemoryStoreFactory | src/core/memory/index.ts | L10-15 |
+| 40% | 📌 variable | memoryStore | src/commands/memory.ts | L25-25 |
+```
+
+### 3. Unfold — Extract Specific Symbol Source
+
+Read just the implementation of a specific function or class:
+
+```bash
+heraspec explore unfold src/core/memory/memory-store.ts addObservation
+```
+
+**Output example:**
+```
+## method: addObservation
+*src/core/memory/memory-store.ts:L88-120 | ~800 tokens (vs ~71250 full file)*
+
+  addObservation(input: ObservationInput): Observation {
+    this.ensureOpen();
+    // ... full implementation
+  }
+```
+
+## Supported Languages
+
+| Language | Extensions | Symbols Detected |
+|----------|-----------|-----------------|
+| TypeScript | `.ts`, `.tsx` | class, interface, type, enum, function, method, variable |
+| JavaScript | `.js`, `.jsx`, `.mjs` | class, function, method, variable |
+| Python | `.py` | class, function, method, variable |
+| PHP | `.php` | class, interface, function |
+| Go | `.go` | struct, interface, func |
+| Rust | `.rs` | struct, trait, enum, fn |
+| Java | `.java` | class, interface, method |
+| C# | `.cs` | class, interface, method |
+| Vue | `.vue` | Same as TypeScript |
+| Svelte | `.svelte` | Same as TypeScript |
+
+## Workflow for AI Agents
+
+### Exploration Strategy
+
+```
+Need to understand a file?
+├── Step 1: heraspec explore outline <file>
+│   → See all functions, classes, interfaces (~1K tokens)
+├── Step 2: Identify relevant symbols from outline
+├── Step 3: heraspec explore unfold <file> <symbol>
+│   → Read just the relevant function (~400-2K tokens)
+└── Only read full file if you need comprehensive understanding
+
+Need to find where something is?
+├── heraspec explore search "<name>" <path>
+│   → Find symbol locations across codebase
+├── Then use unfold to read specific implementations
+└── Avoid grep-like full-text search when possible
+```
+
+### Key Principles
+
+1. **Outline first, read later**: Always check the outline before reading full files
+2. **Unfold specific symbols**: Don't read entire files when you only need one function
+3. **Search before browsing**: Find what you need by name rather than scanning directories
+4. **Skip node_modules, dist, .git**: Automatically excluded from search
+
+## Limitations
+
+- Uses regex-based parsing (not AST) — may miss some complex patterns
+- Symbol end-line detection is approximate (brace/indent counting)
+- Method detection within classes requires proper indentation
+- Does not handle dynamically generated code or macros

package/dist/core/templates/skills/smart-explore-skill.md

@@ -0,0 +1,141 @@
+---
+name: smart-explore
+description: Token-efficient code exploration — view file structure, search symbols, and read specific implementations without loading full files. Reduces token usage by 4-18x compared to reading entire files.
+projectType: all
+---
+
+# Smart Explore Skill
+
+## Purpose
+
+Enable AI agents to **explore codebases efficiently** by viewing structural outlines, searching for symbols, and extracting specific implementations — without reading entire files. This dramatically reduces token consumption when navigating large projects.
+
+## When to Use
+
+- **Understanding a new file**: Use `outline` instead of reading the full file
+- **Finding where something is defined**: Use `search` to locate symbols across the project
+- **Reading a specific function**: Use `unfold` to extract just that function's code
+
+## Token Savings
+
+| Method | Typical Token Cost | Notes |
+|--------|-------------------|-------|
+| Read full file | ~12,000+ | All content, most irrelevant |
+| **Outline** | ~1,000-2,000 | Structural skeleton only |
+| **Search** | ~2,000-6,000 | Symbol locations across codebase |
+| **Unfold** | ~400-2,100 | Exact function/class source |
+
+**Savings: 4-18x** compared to reading full files.
+
+## Available Commands
+
+### 1. Outline — Structural Skeleton
+
+View all symbols (functions, classes, interfaces, exports) in a file without reading the full source:
+
+```bash
+heraspec explore outline src/core/memory/memory-store.ts
+```
+
+**Output example:**
+```
+## 📄 src/core/memory/memory-store.ts
+*typescript | 285 lines | ~71250 tokens*
+
+🏛️ export class MemoryStore (L20-285)
+  ↳ open() (L32-58)
+  ↳ close() (L63-68)
+  ↳ addObservation(input) (L88-120)
+  ↳ getObservationById(id) (L125-132)
+  ↳ getRecentObservations(project, limit) (L140-160)
+  ↳ addSummary(input) (L165-195)
+  ↳ getStatus(project) (L200-260)
+```
+
+### 2. Search — Find Symbols Across Codebase
+
+Search for functions, classes, interfaces by name across the project:
+
+```bash
+heraspec explore search "MemoryStore" src/
+heraspec explore search "addObservation" src/ --limit 10
+```
+
+**Output example:**
+```
+## Symbol Search: "MemoryStore" (3 results)
+
+| Rel | Type | Name | File | Lines |
+|-----|------|------|------|-------|
+| 100% | 🏛️ class | MemoryStore | src/core/memory/memory-store.ts | L20-285 |
+| 60% | ⚡ function | MemoryStoreFactory | src/core/memory/index.ts | L10-15 |
+| 40% | 📌 variable | memoryStore | src/commands/memory.ts | L25-25 |
+```
+
+### 3. Unfold — Extract Specific Symbol Source
+
+Read just the implementation of a specific function or class:
+
+```bash
+heraspec explore unfold src/core/memory/memory-store.ts addObservation
+```
+
+**Output example:**
+```
+## method: addObservation
+*src/core/memory/memory-store.ts:L88-120 | ~800 tokens (vs ~71250 full file)*
+
+  addObservation(input: ObservationInput): Observation {
+    this.ensureOpen();
+    // ... full implementation
+  }
+```
+
+## Supported Languages
+
+| Language | Extensions | Symbols Detected |
+|----------|-----------|-----------------|
+| TypeScript | `.ts`, `.tsx` | class, interface, type, enum, function, method, variable |
+| JavaScript | `.js`, `.jsx`, `.mjs` | class, function, method, variable |
+| Python | `.py` | class, function, method, variable |
+| PHP | `.php` | class, interface, function |
+| Go | `.go` | struct, interface, func |
+| Rust | `.rs` | struct, trait, enum, fn |
+| Java | `.java` | class, interface, method |
+| C# | `.cs` | class, interface, method |
+| Vue | `.vue` | Same as TypeScript |
+| Svelte | `.svelte` | Same as TypeScript |
+
+## Workflow for AI Agents
+
+### Exploration Strategy
+
+```
+Need to understand a file?
+├── Step 1: heraspec explore outline <file>
+│   → See all functions, classes, interfaces (~1K tokens)
+├── Step 2: Identify relevant symbols from outline
+├── Step 3: heraspec explore unfold <file> <symbol>
+│   → Read just the relevant function (~400-2K tokens)
+└── Only read full file if you need comprehensive understanding
+
+Need to find where something is?
+├── heraspec explore search "<name>" <path>
+│   → Find symbol locations across codebase
+├── Then use unfold to read specific implementations
+└── Avoid grep-like full-text search when possible
+```
+
+### Key Principles
+
+1. **Outline first, read later**: Always check the outline before reading full files
+2. **Unfold specific symbols**: Don't read entire files when you only need one function
+3. **Search before browsing**: Find what you need by name rather than scanning directories
+4. **Skip node_modules, dist, .git**: Automatically excluded from search
+
+## Limitations
+
+- Uses regex-based parsing (not AST) — may miss some complex patterns
+- Symbol end-line detection is approximate (brace/indent counting)
+- Method detection within classes requires proper indentation
+- Does not handle dynamically generated code or macros