feat!: improve file list display with User/Project terminology and better organization (#65)

* feat\!: migrate to new descriptive file type naming convention

BREAKING CHANGE: Complete migration to new ClaudeFileType values for better clarity

- Renamed all file type values to be more descriptive:
  - 'global-md' → 'user-memory'
  - 'claude-md' → 'project-memory'
  - 'claude-local-md' → 'project-memory-local'
  - 'slash-command' → 'project-command'
  - 'project-agent' → 'project-subagent'
  - 'user-agent' → 'user-subagent'
  - 'settings-json' → 'project-settings'
  - 'settings-local-json' → 'project-settings-local'
- Added new file types:
  - 'personal-command' for user's personal slash commands
  - 'user-settings' for global settings.json
- Updated UI to show more descriptive labels with path information
- Added [deprecated] badge for project-memory-local files
- Improved command display with path context
- Enhanced file detection logic to properly identify all file types

This change aligns with Anthropic's documentation terminology and provides
clearer understanding of each file's purpose in the Claude Code ecosystem.

* feat: reorder file groups to show user configs first with unified colors

- User configurations now appear before project configurations:
  User memory → User settings → User commands → User agents → Project configs
- Apply unified color scheme by category:
  - Memory files: Blue theme
  - Settings files: Cyan theme
  - Command files: Green theme
  - Agent files: Magenta theme
- Update tests to support flexible group ordering

* feat: update UI labels to use User/Project terminology with file locations

- Update FileGroup labels to show descriptive names with file locations
  e.g., "User memory (~/.claude/CLAUDE.md)"
- Update FileItem badges to use consistent USER/PROJECT prefixes
  e.g., "USER MEMORY", "PROJECT COMMAND"
- Align terminology with Anthropic's documentation conventions
- Update all related tests to match new labels

* feat: display empty file categories with count (0)

- Show all file categories even when they contain no files, displaying them as "Category name (0)"
- Empty categories are not expandable (isExpanded: false)
- Unknown type is excluded from empty group display
- Auto-select first file from the first non-empty group instead of first group

This improves discoverability by making all available file types visible to users,
even when no files of that type exist in the current project.

* feat: apply high-contrast color theme for black background

- Updated color scheme from basic colors to high-contrast hex values
- Colors optimized for better visibility on black terminal backgrounds:
  - Memory categories: Orange (#FF8A65, #FFAB91)
  - Settings categories: Cyan (#4DD0E1, #80DEEA)
  - Command categories: Green (#66BB6A)
  - Agent categories: Soft magenta (#C47FD5)
- Removed unnecessary descriptive comments per user feedback
- Fixed test to handle empty file groups correctly

* chore: remove pr.md documentation file

* docs: align file type terminology with Anthropic documentation

- Update README.md Target Files section to use User/Project terminology
- Organize files by category (Memory, Commands, Sub-agents, Settings)
- Update CLAUDE.md UI experience section to reflect latest features
- Maintain consistency with Anthropic's official documentation naming

* fix: revert package.json keywords

* refactor: address PR review comments for code cleanliness

- Remove extra blank line in CLAUDE.md
- Remove unnecessary comments in _types.ts, FileItem.test.tsx, and FileItem.tsx
- Add explicit return type annotation to getFileBadge function

All changes improve code readability by removing redundant documentation
while maintaining clear, self-documenting code structure.

* fix: support personal-command in Copy to Current Directory action

* fix: add personal-command support to claude-md-scanner getSearchPatterns

- Added USER_SLASH_COMMANDS pattern for personal-command type
- Added tests to verify personal-command pattern inclusion
- Ensures consistent handling of user-level commands across the codebase

* refactor: rename sub-agent to subagent throughout codebase

- Rename sub-agent-scanner.ts to subagent-scanner.ts
- Update all imports and references from sub-agent to subagent
- Unify terminology in labels: 'Project/User subagents'
- Maintain internal type names (project-subagent, user-subagent) for compatibility

* fix: complete subagent terminology unification

- Remove remaining hyphens from UI labels (PROJECT/USER SUBAGENT)
- Update section header in README.md to "Subagent Files"
- Change SubAgentScanner fileType from 'Sub-agent' to 'Subagent'
- Fix all Sub-agent references in CLAUDE.md documentation
- Add dedicated MAX_SUBAGENT_SIZE constant (100KB)
- Add naming conventions section following Anthropic docs

This completes the terminology unification started in 693ebeb

* fix: update icons for better visual distinction

- Change personal-command icon from 👤 to 🔹 (blue diamond)
- Change user-subagent icon from 👤 to 🧑‍💻 (technologist)
- Update test comment to use new file type terminology
- Improves visual clarity by avoiding duplicate icons

Author: nyatinte

CLAUDE.md

@@ -165,8 +165,8 @@ src/
    ```typescript
    const detectClaudeFileType = (fileName: string, dirPath: string): ClaudeFileType => {
      return match([fileName, dirPath])
-       .with(['CLAUDE.md', P._], () => 'claude-md' as const)
-       .with(['CLAUDE.local.md', P._], () => 'claude-local-md' as const)
+       .with(['CLAUDE.md', P._], () => 'project-memory' as const)
+       .with(['CLAUDE.local.md', P._], () => 'project-memory-local' as const)
        .otherwise(() => 'unknown' as const);
    };
    ```
@@ -195,18 +195,18 @@ src/
    export abstract class BaseFileScanner<T> {
      protected abstract readonly maxFileSize: number;
      protected abstract readonly fileType: string;
-     
+
      async processFile(filePath: string): Promise<T | null> {
        // Common file processing logic
      }
-     
+
      protected abstract parseContent(
        filePath: string,
        content: string,
        stats: Stats,
      ): Promise<T | null>;
    }
-   
+
    // Specialized scanners extend base
    class ClaudeMdScanner extends BaseFileScanner<ClaudeFileInfo> {
      protected readonly maxFileSize = FILE_SIZE_LIMITS.MAX_CLAUDE_MD_SIZE;
@@ -220,7 +220,7 @@ src/
   - `base-file-scanner.ts` → Abstract base class for all scanners
   - `claude-md-scanner.ts` → CLAUDE.md file discovery
   - `slash-command-scanner.ts` → Slash command discovery
-  - `sub-agent-scanner.ts` → Sub-agent definition discovery
+  - `subagent-scanner.ts` → Subagent definition discovery
   - `default-scanner.ts` → Combined scanner for all file types
   - `fast-scanner.ts` → High-performance directory traversal
 - **Type System**: `_types.ts` → branded types + zod schemas for data integrity
@@ -237,8 +237,8 @@ The tool automatically discovers these file types:
 - **CLAUDE.local.md** → Local overrides (gitignored)
 - **~/.claude/CLAUDE.md** → Global user configuration
 - **.claude/commands/**/*.md** → Slash command definitions
-- **.claude/agents/**/*.md** → Sub-agent definitions (project-level)
-- **~/.claude/agents/**/*.md** → Sub-agent definitions (user-level)
+- **.claude/agents/**/*.md** → Subagent definitions (project-level)
+- **~/.claude/agents/**/*.md** → Subagent definitions (user-level)
 - **.claude/settings.json** → Project settings (shared)
 - **.claude/settings.local.json** → Local project settings (gitignored)
 - **~/.claude/settings.json** → User settings (global)
@@ -352,12 +352,11 @@ This configuration enables:
 - **Error handling**: StatusMessage component with graceful degradation
 - **Loading states**: Spinner component during file scanning
 - **File grouping**: Organized display by file type with collapsible groups
-  - CLAUDE.md files (Project configurations)
-  - CLAUDE.local.md files (Local overrides)
-  - Global CLAUDE.md (User-wide settings)
-  - Slash commands (Custom command definitions)
-  - Sub-agents (Project and user-level agent definitions)
+  - User configurations displayed first (memory, settings, commands, agents)
+  - Project configurations follow (memory, settings, commands, agents)
+  - Groups show file count even when empty (e.g., "User memory (0)")
   - Groups can be collapsed/expanded with arrow keys
+  - High-contrast colors optimized for black terminal backgrounds
 
 ## Quality Management Rules
 
@@ -474,6 +473,23 @@ Before first release:
 
 See `VERSIONING.md` for detailed versioning strategy and commit message conventions.
 
+## Naming Conventions
+
+### Terminology from Anthropic Documentation
+
+This project follows the official terminology from https://docs.anthropic.com:
+
+- **subagent** (not sub-agent) - Specialized AI assistants for specific tasks
+- **slash command** (not slash-command) - Custom commands starting with /
+- **Claude Code** - The official CLI tool name
+- **CLAUDE.md** - Configuration file names (uppercase)
+
+### Compound Word Rules
+
+- Use single words without hyphens for established terms: `subagent`, `codebase`
+- Use hyphens for clarity when needed: `project-specific`, `user-level`
+- Follow TypeScript naming conventions for code identifiers
+
 ## CI/CD Pipeline
 
 The project uses GitHub Actions for continuous integration:

README.md

@@ -53,15 +53,23 @@
 
 ccexp (claude-code-explorer) automatically discovers these configuration files:
 
-- **CLAUDE.md** → Project-level configuration (most common)
-- **CLAUDE.local.md** → Local overrides (gitignored)
-- **~/.claude/CLAUDE.md** → Global user configuration
-- **.claude/commands/**/*.md** → Slash command definitions
-- **.claude/agents/**/*.md** → Sub-agent definitions (project-level)
-- **~/.claude/agents/**/*.md** → Sub-agent definitions (user-level)
-- **.claude/settings.json** → Project settings (shared)
-- **.claude/settings.local.json** → Local project settings (gitignored)
-- **~/.claude/settings.json** → User settings (global)
+### Memory Files
+- **CLAUDE.md** → Project memory (project configuration)
+- **CLAUDE.local.md** → Project memory local (local overrides, gitignored) (deprecated: https://docs.anthropic.com/en/docs/claude-code/memory#determine-memory-type)
+- **~/.claude/CLAUDE.md** → User memory (global configuration)
+
+### Command Files
+- **.claude/commands/**/*.md** → Project commands (project-specific slash commands)
+- **~/.claude/commands/**/*.md** → User commands (personal slash commands)
+
+### Subagent Files
+- **.claude/agents/**/*.md** → Project subagents (project-specific agents)
+- **~/.claude/agents/**/*.md** → User subagents (personal agents)
+
+### Settings Files
+- **.claude/settings.json** → Project settings (shared configuration)
+- **.claude/settings.local.json** → Project settings local (local overrides, gitignored)
+- **~/.claude/settings.json** → User settings (global configuration)
 
 ## Installation
 

src/_consts.ts

@@ -16,6 +16,7 @@ export const CLAUDE_FILE_PATTERNS = {
 export const FILE_SIZE_LIMITS = {
   MAX_CLAUDE_MD_SIZE: 1024 * 1024, // 1MB
   MAX_SLASH_COMMAND_SIZE: 512 * 1024, // 512KB
+  MAX_SUBAGENT_SIZE: 1024 * 100, // 100KB
 } as const;
 
 // CLI output configuration

src/_types.ts

@@ -9,16 +9,17 @@ export const createClaudeFilePath = (path: string): ClaudeFilePath => {
   return path;
 };
 
-// Core types as defined in requirement
 export type ClaudeFileType =
-  | 'claude-md'
-  | 'claude-local-md'
-  | 'global-md'
-  | 'slash-command'
-  | 'project-agent'
-  | 'user-agent'
-  | 'settings-json'
-  | 'settings-local-json'
+  | 'user-memory'
+  | 'project-memory'
+  | 'project-memory-local'
+  | 'project-command'
+  | 'personal-command'
+  | 'project-subagent'
+  | 'user-subagent'
+  | 'project-settings'
+  | 'project-settings-local'
+  | 'user-settings'
   | 'unknown';
 
 type _CommandInfo = {

src/_utils.ts

@@ -35,30 +35,55 @@ export const detectClaudeFileType = (filePath: string): ClaudeFileType => {
   return match([fileName, dirPath])
     .with(
       ['CLAUDE.md', P.when((dir) => dir === join(HOME_DIR, '.claude'))],
-      () => 'global-md' as const,
+      () => 'user-memory' as const,
+    )
+    .with(['CLAUDE.md', P._], () => 'project-memory' as const)
+    .with(['CLAUDE.local.md', P._], () => 'project-memory-local' as const)
+    .with(
+      [
+        P.when((name) => name.endsWith('.md')),
+        P.when((dir) => dir.includes(join(HOME_DIR, '.claude', 'commands'))),
+      ],
+      () => 'personal-command' as const,
     )
-    .with(['CLAUDE.md', P._], () => 'claude-md' as const)
-    .with(['CLAUDE.local.md', P._], () => 'claude-local-md' as const)
     .with(
       [
         P.when((name) => name.endsWith('.md')),
         P.when((dir) => dir.includes('.claude/commands')),
       ],
-      () => 'slash-command' as const,
+      () => 'project-command' as const,
+    )
+    .with(
+      [
+        P.when((name) => name.endsWith('.md')),
+        P.when((dir) => dir.includes(join(HOME_DIR, '.claude', 'agents'))),
+      ],
+      () => 'user-subagent' as const,
+    )
+    .with(
+      [
+        P.when((name) => name.endsWith('.md')),
+        P.when((dir) => dir.includes('.claude/agents')),
+      ],
+      () => 'project-subagent' as const,
+    )
+    .with(
+      ['settings.json', P.when((dir) => dir === join(HOME_DIR, '.claude'))],
+      () => 'user-settings' as const,
     )
     .with(
       [
         'settings.json',
         P.when((dir) => dir.endsWith('/.claude') || dir.includes('/.claude/')),
       ],
-      () => 'settings-json' as const,
+      () => 'project-settings' as const,
     )
     .with(
       [
         'settings.local.json',
         P.when((dir) => dir.endsWith('/.claude') || dir.includes('/.claude/')),
       ],
-      () => 'settings-local-json' as const,
+      () => 'project-settings-local' as const,
     )
     .otherwise(() => 'unknown' as const);
 };
@@ -173,35 +198,83 @@ if (import.meta.vitest != null) {
 
   describe('detectClaudeFileType', () => {
     test('should detect CLAUDE.md files', () => {
-      expect(detectClaudeFileType('/project/CLAUDE.md')).toBe('claude-md');
+      expect(detectClaudeFileType('/project/CLAUDE.md')).toBe('project-memory');
     });
 
     test('should detect CLAUDE.local.md files', () => {
       expect(detectClaudeFileType('/project/CLAUDE.local.md')).toBe(
-        'claude-local-md',
+        'project-memory-local',
       );
     });
 
     test('should detect global CLAUDE.md files', () => {
       const globalPath = join(HOME_DIR, '.claude', 'CLAUDE.md');
-      expect(detectClaudeFileType(globalPath)).toBe('global-md');
+      expect(detectClaudeFileType(globalPath)).toBe('user-memory');
     });
 
-    test('should detect slash command files', () => {
+    test('should detect project slash command files', () => {
       expect(detectClaudeFileType('/project/.claude/commands/deploy.md')).toBe(
-        'slash-command',
+        'project-command',
+      );
+      expect(detectClaudeFileType('/workspace/.claude/commands/test.md')).toBe(
+        'project-command',
+      );
+    });
+
+    test('should detect personal slash command files', () => {
+      const personalCommandPath = join(
+        HOME_DIR,
+        '.claude',
+        'commands',
+        'personal.md',
+      );
+      expect(detectClaudeFileType(personalCommandPath)).toBe(
+        'personal-command',
+      );
+
+      const nestedPersonalPath = join(
+        HOME_DIR,
+        '.claude',
+        'commands',
+        'git',
+        'commit.md',
       );
+      expect(detectClaudeFileType(nestedPersonalPath)).toBe('personal-command');
     });
 
     test.each([
-      ['/project/.claude/settings.json', 'settings-json'],
-      ['/Users/name/.claude/settings.json', 'settings-json'],
-      ['/project/.claude/settings.local.json', 'settings-local-json'],
-      ['/Users/name/.claude/settings.local.json', 'settings-local-json'],
+      ['/project/.claude/settings.json', 'project-settings'],
+      ['/workspace/.claude/settings.json', 'project-settings'],
+      ['/project/.claude/settings.local.json', 'project-settings-local'],
+      ['/workspace/.claude/settings.local.json', 'project-settings-local'],
     ] as const)('should detect %s as %s', (path, expectedType) => {
       expect(detectClaudeFileType(path)).toBe(expectedType);
     });
 
+    test('should detect user settings.json', () => {
+      const userSettingsPath = join(HOME_DIR, '.claude', 'settings.json');
+      expect(detectClaudeFileType(userSettingsPath)).toBe('user-settings');
+    });
+
+    test('should detect project subagent files', () => {
+      expect(
+        detectClaudeFileType('/project/.claude/agents/test-agent.md'),
+      ).toBe('project-subagent');
+      expect(detectClaudeFileType('/workspace/.claude/agents/helper.md')).toBe(
+        'project-subagent',
+      );
+    });
+
+    test('should detect user subagent files', () => {
+      const userAgentPath = join(
+        HOME_DIR,
+        '.claude',
+        'agents',
+        'personal-agent.md',
+      );
+      expect(detectClaudeFileType(userAgentPath)).toBe('user-subagent');
+    });
+
     test('should not detect settings files outside .claude', () => {
       expect(detectClaudeFileType('/project/settings.json')).toBe('unknown');
       expect(detectClaudeFileType('/project/settings.local.json')).toBe(