---
applyTo: "**/*.md,README.md,**/README.md,**/index.md"
---

# README Management - Quick Reference

## Four READMEs

| File | Lines | Audience | Purpose |
|------|-------|----------|---------|
| `/README.md` | 250-300 | All users | Comprehensive reference |
| `/src/ExcelMcp.McpServer/README.md` | 80-100 | .NET devs | Concise NuGet gateway |
| `/vscode-extension/README.md` | 100-120 | VS Code users | User benefits focus |
| `/gh-pages/index.md` | 450-5000 | All users | Comprehensive reference |

## Features.md

You need to make sure that the `Features.md` file is up-to-date with the latest features of the project. This file should be updated whenever a new feature is added or an existing feature is modified.

## Critical Rules

### Tool & Action Counts Must Match

**⚠️ IMPORTANT: CLI has FEWER tools/operations than MCP Server!**

**ALWAYS count tools/operations BEFORE updating any README. Never use hardcoded numbers from memory.**

Before updating counts, verify by counting:

- **MCP Server**: Count tool files (excel_batch handled via ExcelTools.cs, not separate tool file)
- **CLI**: Count command group folders (includes Session commands)
- **Operations**: Count separately for each - they differ!

Sync counts across:
  - GitHub Project About: https://github.com/sbroenne/mcp-server-excel (use the GitHub CLI to update)
  - `/README.md`
  - `/src/ExcelMcp.McpServer/README.md`
  - `/src/ExcelMcp.CLI/README.md`
  - `/vscode-extension/README.md`
  - `/gh-pages/index.md`
  - `/FEATURES.md`

### Operation Lists Must Be Complete

**⚠️ IMPORTANT: Where operation lists are documented, they MUST match the actual code!**

The `gh-pages/index.md` file contains detailed tables of all operations for each tool. When adding/removing operations:

1. **Verify section header count** matches actual operation count in code
2. **Verify each operation is listed** in the table - no missing or extra entries
3. **Verify operation names** match the code (kebab-case in docs, PascalCase in code)

**Common discrepancies found:**
- Section header says "25 actions" but code has 30
- Table lists operations that don't exist (stale documentation)
- Table is missing newly added operations

### Version Numbers
- **NEVER** manually update versions in README files
- Versions auto-managed by release workflow
- See `docs/RELEASE-STRATEGY.md`

## Verification Checklist

Before committing README changes:

- [ ] Tool counts match actual code (count, don't assume)
- [ ] Operation counts match actual code per tool
- [ ] Operation LISTS in tables match actual code (no missing/extra entries)
- [ ] All READMEs updated (not just one)
- [ ] FEATURES.md updated if applicable
- [ ] gh-pages/index.md section headers match table row counts

## Common Mistakes

## CHANGELOG.md

The project uses a **centralized changelog** at `/CHANGELOG.md` covering all components.

**When to update:**
- Before creating a `v*` tag, ensure the version section exists in CHANGELOG.md
- The release workflow extracts the specific version's changes for release notes
- Uses standard Keep a Changelog format: `## [version] - YYYY-MM-DD`

| Mistake | Fix |
|---------|-----|
| Duplicate tool entries | List each tool once |
| Unverified action counts | Count actual switch cases in code |
| Incomplete operation lists | Compare each table row against code |
| Stale operation names | Operations get renamed - verify current names |
| Overclaiming features | Use actual counts, not estimates |
| Missing safety callout | Add COM API benefits |
| Manual version updates | Let workflow handle it |
| Missing CHANGELOG entry | Add before creating release tag |
| External GitHub links in gh-pages | Use local pages (see gh-pages pattern below) |

## gh-pages Local Documentation Pattern

**CRITICAL: All documentation in gh-pages should use LOCAL pages, NOT external GitHub links.**

### Pattern: Jekyll Includes

gh-pages uses Jekyll includes to pull content from source READMEs:

1. **Source file** (e.g., `src/ExcelMcp.McpServer/README.md`)
2. **build.sh copies** to `_includes/mcp-server.md` (stripping H1, badges)
3. **Page file** (e.g., `gh-pages/mcp-server.md`) uses Jekyll include
4. **Result**: Local URL `/mcp-server/` instead of GitHub link

### Current Local Pages

| URL | Source | Page File |
|-----|--------|-----------|
| `/features/` | `/FEATURES.md` | `gh-pages/features.md` |
| `/installation/` | `/docs/INSTALLATION.md` | `gh-pages/installation.md` |
| `/changelog/` | `/CHANGELOG.md` | `gh-pages/changelog.md` |
| `/mcp-server/` | `/src/ExcelMcp.McpServer/README.md` | `gh-pages/mcp-server.md` |
| `/cli/` | `/src/ExcelMcp.CLI/README.md` | `gh-pages/cli.md` |
| `/skills/` | `/skills/README.md` | `gh-pages/skills.md` |
| `/contributing/` | `/docs/CONTRIBUTING.md` | `gh-pages/contributing.md` |

### Adding New Local Pages

1. **Update `build.sh`** - Add awk command to copy source file to `_includes/`:
   ```bash
   awk '
       BEGIN { inheader=0; headerdone=0 }
       {
           if (headerdone==0 && /^# /) { inheader=1; next }
           if (inheader==1 && /^$/) { inheader=0; headerdone=1; next }
           if (/^# /) { sub(/^# /, "## "); print; next }
           print
       }
   ' "$ROOT_DIR/path/to/SOURCE.md" > "$SCRIPT_DIR/_includes/target.md"
   ```

2. **Create page file** in `gh-pages/`:
   ```markdown
   ---
   layout: default
   title: "Page Title"
   permalink: /url-path/
   ---

   {% capture content %}{% include target.md %}{% endcapture %}
   {{ content | markdownify }}
   ```

3. **Update `.gitignore`** - Add `_includes/target.md`

4. **Update `_includes/README.md`** - Document new generated file

5. **Update `index.md`** - Use local URL `/url-path/` instead of GitHub link

### Why Local Pages

- **Consistent UX** - All docs served from same domain
- **Single source of truth** - Content auto-synced from source files
- **SEO** - Better for search engine indexing
- **Offline docs** - Works with Jekyll serve locally
