docs: refresh readme for directive support

Author: masterkain

README.md

@@ -1,37 +1,34 @@
 # AutoPathComment
 
-**AutoPathComment** is a Visual Studio Code extension that automatically inserts a comment at the top of your file with its **relative path** when you save. This can be useful for quickly identifying a file’s location, especially in large or multi-root workspaces.
+**AutoPathComment** is a Visual Studio Code extension that automatically inserts a comment at the top of your file with its **workspace-relative path** whenever you save. The path always lands immediately after any required shebangs or language directives so scripts keep working, while still giving you a quick breadcrumb to the file’s location.
 
 ## Features
 
 - **Auto-insertion of file path on Save**
-  Whenever you save a file in your workspace, AutoPathComment detects its relative path from the workspace root and inserts that path as a comment at the top of the file.
+  Whenever you save, AutoPathComment detects the file’s workspace-relative path and inserts it as a top-of-file comment.
 
 - **Supports Popular Languages**
-  The extension recognizes file extensions like .js, .ts, .py, .php, .java, .go, and more. It uses the appropriate comment syntax for each language (e.g., // for JavaScript, # for Python).
+  Ships with defaults for common extensions (.js, .ts, .py, .php, .java, .go, .rb, etc.) and uses the correct single-line comment token for each. You can extend or override this map in settings.
 
-- **Shebang Detection**
-  If a file has a shebang (e.g., #!/usr/bin/env python), the extension can optionally skip or insert the path comment *after* the shebang to avoid interfering with scripts.
+- **Directive-aware insertion**
+  Shebangs, Ruby magic comments (`# frozen_string_literal`, `# encoding`), Python `coding` declarations, and PHP opening tags are detected automatically. The comment is inserted right after that preamble so executables keep their required header.
 
 - **No Duplicate Comments**
-  The extension checks if the relative path comment is already present, so it doesn’t insert it again on subsequent saves.
+  The extension checks the insertion location before writing anything, so repeated saves keep the file tidy.
 
 ## Requirements
 
-- Visual Studio Code 1.104.0 or higher
+- Visual Studio Code 1.105.0 or higher
 - Node.js (for extension development, if building from source)
 
 ## Installation
 
-1. **From the VS Code Marketplace** (recommended):
-   - Search for "AutoPathComment" by publisher "icoretech" and install.
-
-2. **From a VSIX file**:
-   1. Download the `autopathcomment-<version>.vsix` file (created by `vsce package`).
+1. **From a VSIX file** (current distribution):
+   1. Download the latest `autopathcomment-<version>.vsix` from the Releases tab or build one locally with `npm run package`.
    2. In VS Code, press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS) and select **Extensions: Install from VSIX...**.
    3. Select the downloaded `.vsix` file to install.
 
-3. **From Source**:
+2. **From Source**:
    1. Clone the repository or download it.
    2. Run `npm install`.
    3. Run `npm run package` or `vsce package` to create a `.vsix`.
@@ -82,15 +79,24 @@ Examples:
 
 ## Known Issues / Limitations
 
-- **Multi-root Workspaces**: If you use multiple workspace roots, the file path is determined relative to the first matching workspace folder. If you have nested or overlapping folders, the extension may not behave as expected.
-- **Large Files**: The extension does not differentiate between text and binary files. If you open and save very large files, insertion still occurs (though typically with minimal overhead).
-- **Shebang**: Currently, if a shebang (`#!...`) is detected, the extension *skips* inserting the comment. This is to avoid breaking executable scripts.
+- **Multi-root Workspaces**: The file path is determined relative to the first workspace folder whose filesystem path prefixes the document. Nested or overlapping folders may require custom settings.
+- **Binary / Generated Files**: The extension does not discriminate between text and non-text files. Exclude generated artifacts via VS Code settings if needed.
+- **Comment Syntax**: Only single-line comment prefixes are supported. Add a custom mapping in settings if your language uses a different single-line token.
+
+## Development
+
+- Install dependencies: `npm install` (also configures the local `commit-msg` hook for Conventional Commits).
+- Build once: `npm run compile`
+- Continuous build: `npm run watch`
+- Run tests (VS Code integration via `@vscode/test-cli`): `npm test`
+- Full check (types + lint + tests): `npm run check`
 
 ## Contributing
 
 1. Fork and clone the repo.
-2. Create a new branch for your feature or bugfix.
-3. Open a pull request describing your changes.
+2. Run `npm install` (sets up commit hooks locally).
+3. Create a new branch for your feature or bugfix.
+4. Open a pull request describing your changes.
 
 ## License