Update documentation

.github/agents/extension-developer.md

@@ -41,16 +41,16 @@ You are a specialized VS Code extension developer with deep expertise in the VS
 
 - **Purpose**: Documentation file tree view with preview and editing capabilities
 - **File Types**: `.md`, `.markdown`, `.txt` by default; configurable via settings
-- **Tree Ordering**: README first, index.md as folder representative, alphabetical sorting
+- **Tree Ordering**: README first, folders display their own name with `index.md` shown as a child, alphabetical sorting
 - **Settings Namespace**: All configuration under `workspaceWiki.*`
 - **File Filtering**: Support for hidden files (`showHiddenFiles`) and ignored files (`showIgnoredFiles`)
-- **Performance**: File system caching and efficient tree updates
+- **Performance**: Front matter is read in parallel during tree building; the tree re-scans on refresh (no persistent caching)
 
 ### Key Implementation Areas
 
 - **Scanner/Indexer**: Efficient file discovery with `workspace.findFiles()`
-- **Tree Ordering Logic**: README prioritization and folder-as-index handling
-- **File System Watching**: Responding to file changes for tree updates
+- **Tree Ordering Logic**: README prioritization and folder name normalization
+- **Refresh Triggers**: Manual `workspace-wiki.refresh` command and `onDidChangeConfiguration`; the active file is revealed on editor changes (no file system watcher)
 - **Preview Integration**: Opening files in preview vs editor modes
 - **Settings Integration**: Reading and reacting to configuration changes
 

.github/agents/tester.md

@@ -98,7 +98,7 @@ describe('WikiTreeDataProvider', () => {
 - Extension activation/deactivation
 - Command registration and execution
 - Tree provider data flow
-- File system watcher behavior
+- Refresh on configuration changes and active-editor reveal behavior
 
 ### E2E Tests
 

.github/copilot-instructions.md

@@ -49,8 +49,8 @@ This guide enables AI coding agents to be immediately productive in the Workspac
 
 - **Purpose:** Presents workspace documentation files in a sidebar tree view for fast preview and editing.
 - **Main Components:**
-    - **Scanner/Indexer:** Uses `workspace.findFiles` and file system watchers to discover docs. Caches metadata for performance.
-    - **TreeDataProvider:** Implements VS Code's tree view, applies ordering rules (README/index, alphabetical, folder-as-index).
+    - **Scanner/Indexer:** Uses `workspace.findFiles` to discover docs on each scan; no caching or file watching (the tree re-scans on refresh).
+    - **TreeDataProvider:** Implements VS Code's tree view, applies ordering rules (README first, folders display their own name with `index.md` as a child, alphabetical otherwise).
     - **Preview/Open Controller:** Handles user interactions, opens files in preview/editor modes.
     - **Settings Manager:** Reads extension config from `workspaceWiki` namespace.
     - **Sync Module:** Reveals active file in the tree.
@@ -71,7 +71,7 @@ This guide enables AI coding agents to be immediately productive in the Workspac
 - Use `npm run test:jest` for Jest unit tests.
 - Use `npm run test:extension` for integration/e2e tests (via `vscode-test`).
 - Use `npm run watch-tests` for live test compilation.
-- Test files must match `**.test.ts` (unit) and `**.e2e.test.ts` (e2e) and reside in `src/test/`.
+- Test files must match `**.test.ts` (unit) and `**.e2e.test.ts` (e2e) and sit beside the file they test (e.g. `src/utils/textUtils.test.ts`). The `src/test/` directory holds only shared testing utilities (`mocks.ts`, `setupTests.ts`).
 
 **CRITICAL - Test Preservation:**
 
@@ -117,7 +117,7 @@ This guide enables AI coding agents to be immediately productive in the Workspac
 
 ## Project-Specific Conventions
 
-- **Ordering:** README at root is always top; index.md in folders replaces folder name; alphabetical sorting elsewhere.
+- **Ordering:** README at root is always top; folders display their own normalized name with any `index.md` shown as a child; alphabetical sorting elsewhere.
 - **TypeScript Config:** Use only the root `tsconfig.json`. Do not create per-purpose `tsconfig` files.
 - **Supported File Types:** `.md`, `.markdown`, `.txt` by default; `.pdf`, `.html` opt-in via settings.
 - **Settings:** All config under `workspaceWiki` namespace (see design doc for full schema).
@@ -148,9 +148,9 @@ This guide enables AI coding agents to be immediately productive in the Workspac
 - `src/extension.ts`: Main extension logic.
 - `esbuild.js`: Build pipeline.
 - `eslint.config.mjs`: Linting rules.
-- `src/test/extension.test.ts`: Example test.
+- `src/extension.test.ts`: Example test.
 - `.vscode/launch.json`, `.vscode/tasks.json`: Debug and build tasks.
-- `docs/design-doc.md`: Architecture and implementation details.
+- `docs/project/design-doc.md`: Architecture and implementation details.
 - `.github/agents/`: Specialized AI agent configurations for domain expertise.
 
 ## Examples

README.md

@@ -4,8 +4,8 @@
 [![Downloads](https://img.shields.io/visual-studio-marketplace/d/alexjsully.workspace-wiki)](https://marketplace.visualstudio.com/items?itemName=alexjsully.workspace-wiki)
 [![Open VSX Version](https://img.shields.io/open-vsx/v/alexjsully/workspace-wiki)](https://open-vsx.org/extension/alexjsully/workspace-wiki)
 [![Follow on Twitter](https://img.shields.io/twitter/follow/alexjsully?style=social)](https://twitter.com/alexjsully)
-[![GitHub repo size](https://img.shields.io/github/repo-size/AlexJSully/alexjsully-portfolio)](https://github.com/AlexJSully/alexjsully-portfolio)
-[![GitHub](https://img.shields.io/github/license/AlexJSully/alexjsully-portfolio)](https://github.com/AlexJSully/alexjsully-portfolio)
+[![GitHub repo size](https://img.shields.io/github/repo-size/AlexJSully/workspace-wiki)](https://github.com/AlexJSully/workspace-wiki)
+[![GitHub](https://img.shields.io/github/license/AlexJSully/workspace-wiki)](https://github.com/AlexJSully/workspace-wiki)
 [![Build Status](https://github.com/AlexJSully/workspace-wiki/actions/workflows/code-qa-js.yaml/badge.svg)](https://github.com/AlexJSully/workspace-wiki/actions)
 
 Workspace Wiki is a VS Code extension that scans your workspace for documentation files (Markdown and plain text by default) and presents them in a sidebar tree view for fast preview and editing. It emphasizes readability, predictable ordering (README/index handling, alphabetical directories), and fast access via preview or edit. All operations are local-first and privacy-friendly.
@@ -22,7 +22,7 @@ Workspace Wiki is a VS Code extension that scans your workspace for documentatio
 - **Acronym Case Preservation:** Technical terms like HTML, CSS, API maintain proper casing in titles.
 - **Intelligent File Exclusion:** Respects .gitignore patterns and configurable exclude globs to hide unwanted files.
 - **Preview & Edit:** Single-click to preview, double-click to edit in full editor.
-- **Live Updates:** Tree auto-refreshes when files change.
+- **Refresh:** Update the tree on demand with the Refresh action; it also re-scans automatically when `workspaceWiki` settings change.
 - **Configurable:** Supported file types, excludes, open modes, and title formatting are configurable via settings.
 - **Multi-root Support:** Works with multi-root workspaces.
 - **Privacy:** No telemetry, no cloud sync, local-only by default.
@@ -142,11 +142,7 @@ Array of acronyms to preserve proper casing in file titles.
 		"REST",
 		"SQL",
 		"CSV",
-		"FHIR",
-		"BFF",
-		"MFE",
-		"PDF",
-		"VSC"
+		"FHIR"
 	]
 }
 ```

SECURITY.MD

@@ -6,4 +6,4 @@ We are actively maintaining and developing on the latest build on the master bra
 
 ## Reporting a Vulnerability
 
-If you want to report a security vulnerability, you can do so [on the GitHub issues page](https://github.com/AlexJSully/alexjsully-portfolio/issues/new/choose).
+If you want to report a security vulnerability, you can do so [on the GitHub issues page](https://github.com/AlexJSully/workspace-wiki/issues/new/choose).

SUPPORT.md

@@ -21,7 +21,7 @@ For new features or enhancements, please [submit a feature request](https://gith
 
 ### 🔒 Security Issues
 
-For security-related issues, please see our [Security Policy](SECURITY.md) for responsible disclosure guidelines.
+For security-related issues, please see our [Security Policy](SECURITY.MD) for responsible disclosure guidelines.
 
 ### 💬 Discussions
 
@@ -33,8 +33,7 @@ For general questions, usage help, or community discussions:
 ### 📚 Documentation
 
 - Read the [README](README.md) for setup and usage instructions
-- Check the [Design Documentation](docs/design-doc.md) for technical details
-- See the [Roadmap](docs/ROADMAP.md) for planned features
+- Check the [Design Documentation](docs/project/design-doc.md) for technical details
 
 ### 🤝 Contributing
 

docs/architecture/tree-data-provider.md

@@ -12,7 +12,7 @@ The TreeDataProvider is implemented in [`src/tree/treeProvider.ts`](../../src/tr
 - Applies ordering rules:
     - `README.md` at root always first
     - Root-level docs next (alphabetical)
-    - Folders (with `index.md` as folder node)
+    - Folders (displayed by their own normalized name; an `index.md` appears as a child file, not as the folder node)
     - Files inside folders (alphabetical, with `README.md` at top)
 - Normalizes file names to human-friendly titles.
 - Handles cross-platform path compatibility by normalizing path separators
@@ -87,7 +87,7 @@ See also: [Scanner/Indexer](./scanner.md)
 ```mermaid
 flowchart TD
 	accTitle: Tree Node Ordering Logic
-	accDescr: Shows how tree nodes are sorted - README nodes always rank first, then root-level nodes are ordered by the directorySort setting (files-first, folders-first, or alphabetical), and finally alphabetically by title within each group. Folder nodes use index.md for their name when present.
+	accDescr: Shows how tree nodes are sorted - README nodes always rank first, then root-level nodes are ordered by the directorySort setting (files-first, folders-first, or alphabetical), and finally alphabetically by title within each group. Folder nodes always display their own normalized folder name; an index.md inside a folder is listed as a child file.
 	A[All Nodes] --> B{Is README?}
 	B -->|Yes| C[Rank First]
 	B -->|No| D{Root Level?}
@@ -101,10 +101,8 @@ flowchart TD
 	I --> K
 	J --> K
 	K --> L[Final Sorted List]
-	F -->|index.md Exists| M[Folder Named by index]
-	F -->|No index.md| N[Use Folder Name]
-	M --> O[Children Sorted]
-	N --> O
+	F --> N[Use Folder Name]
+	N --> O[Children Sorted]
 	O --> L
 ```
 

docs/architecture/utilities.md

@@ -71,9 +71,9 @@ The `normalizeTitle()` function performs several transformations:
 
 ```typescript
 normalizeTitle('getting-started.md'); // → 'Getting Started'
-normalizeTitle('api_reference.md'); // → 'API Reference'
+normalizeTitle('api_reference.md', ['API']); // → 'API Reference'
 normalizeTitle('userGuide.md'); // → 'User Guide'
-normalizeTitle('HTMLParser.md'); // → 'HTML Parser'
+normalizeTitle('htmlParser.md', ['HTML']); // → 'HTML Parser'
 normalizeTitle('README.md'); // → 'README'
 ```
 
@@ -114,6 +114,8 @@ See also: [Settings Manager](./settings.md)
 
 ```mermaid
 flowchart TD
+  accTitle: Utilities Module Relationships
+  accDescr: Shows how the utility functions are consumed by other modules. The title normalizer feeds the TreeDataProvider, while the file type detector feeds both the Scanner/Indexer and the Preview/Open Controller.
   A[Title Normalizer] --> B[TreeDataProvider]
   C[File Type Detector] --> D[Scanner/Indexer]
   C --> E[Preview/Open Controller]

docs/usage/publishing.md

@@ -18,7 +18,7 @@ This guide explains how to package and publish the Workspace Wiki extension to t
 1. Build the extension:
 
     ```sh
-    npm run build
+    npm run package
     ```
 
 2. Run tests and lint:

docs/usage/workflows.md

@@ -90,7 +90,7 @@ npm run lint              # ESLint validation
 npm run test:jest         # Jest unit tests
 npm run test:extension    # E2E tests
 npm run compile           # TypeScript compilation
-npm run build             # Extension bundling
+npm run package           # Production extension bundle
 ```
 
 ## Workflow Configuration

example/index-files-test/index.md

@@ -6,21 +6,21 @@ This directory tests the Workspace Wiki extension's handling of index files and
 
 This directory validates that the extension:
 
-- Recognizes `index.md` files as folder landing pages
-- Uses index file titles to replace folder names in the tree display
+- Recognizes `index.md` files within a folder
+- Lists `index.md` as a child file while the folder keeps its own name
 - Handles case variations in README files (README.md vs readme.md)
 - Correctly processes different index file extensions (index.html, index.txt)
 - Maintains proper ordering with index files present
 
 ## Expected Behavior
 
-When this directory contains an `index.md` file, the tree should display the folder using the index file's title rather than the raw directory name "index-files-test".
+When this directory contains an `index.md` file, the tree displays the folder using its own normalized name ("Index Files Test"); the `index.md` appears as a child file, flagged internally as an index file.
 
-Files within this directory should be ordered with README files at the top, followed by other files alphabetically, while the index file itself serves as the folder representation.
+Files within this directory are ordered with README files at the top, followed by other files alphabetically, including the `index.md` itself.
 
 ## Testing Scenarios
 
-- **Index file as folder node**: This index.md should be used as the folder title
+- **Index file as a child**: This index.md is listed as a child of the folder, not as the folder's title
 - **Case-insensitive README handling**: readme.md should be treated equivalently to README.md
 - **Multiple index types**: Different extensions for index files should be handled appropriately
 - **Ordering consistency**: Files should maintain alphabetical order regardless of index file presence

example/nested-structure-test/subdirectory-1/index.md

@@ -7,18 +7,18 @@ This is the index file for subdirectory-1, demonstrating index file behavior in
 This directory tests:
 
 - **Nested index files** - How index.md works in subdirectories
-- **Folder name replacement** - This title should replace "subdirectory-1" in the tree
+- **Folder naming** - The folder displays its own name "Subdirectory 1"; this index.md is shown as a child
 - **Nested ordering** - Files within this subdirectory should follow standard ordering rules
 - **Tree expansion** - Proper collapsible/expandable behavior
 
 ## Expected Behavior
 
 When this subdirectory is displayed in the Workspace Wiki tree:
 
-1. It should show as "Level One Directory" instead of "subdirectory-1"
+1. It shows as "Subdirectory 1" (its own normalized folder name)
 2. It should be expandable/collapsible
 3. Files within should be ordered alphabetically
-4. The index.md file itself should not appear as a separate child (it IS the folder node)
+4. The index.md file appears as a child of the folder (flagged internally as an index file)
 
 ## Content