From 763790d739afd743c0ccb8c6182b3c40f23edccc Mon Sep 17 00:00:00 2001
From: Richard Adleta <radleta@gmail.com>
Date: Fri, 24 Oct 2025 20:43:53 +0000
Subject: [PATCH 1/7] fix(ci): restrict release workflow to main branch only

- Add branch filter to workflow trigger (only main branch)
- Add verification step to check tag is on main branch
- Fetch full git history for branch verification
- Prevents accidental releases from feature/develop branches

This ensures npm releases only happen from the main branch,
protecting against accidental releases from other branches.
---
 .github/workflows/release.yml | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index d671cad..ee9fcf6 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -4,6 +4,8 @@ on:
   push:
     tags:
       - 'v*'
+    branches:
+      - main
 
 jobs:
   publish:
@@ -16,6 +18,21 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all history for all branches and tags
+
+      - name: Verify tag is on main branch
+        run: |
+          # Get the commit SHA for the tag
+          TAG_COMMIT=$(git rev-parse ${{ github.ref }})
+
+          # Check if the commit is on the main branch
+          if ! git branch -r --contains $TAG_COMMIT | grep -q 'origin/main'; then
+            echo "Error: Tag ${{ github.ref_name }} is not on the main branch"
+            exit 1
+          fi
+
+          echo "✓ Tag ${{ github.ref_name }} is on main branch"
 
       - name: Setup Node.js
         uses: actions/setup-node@v4

From b03c9705274e7ee22ad0dff8aba510be02bfb983 Mon Sep 17 00:00:00 2001
From: Richard Adleta <radleta@gmail.com>
Date: Mon, 3 Nov 2025 21:01:57 +0000
Subject: [PATCH 2/7] feat(lint): add literal path error reporting with grep
 format

Add literal link text and resolved path reporting to mdite lint errors,
enabling automated fix scripts with grep/sed without reverse-engineering paths.

## What Changed

### Error Type Enhancement
- Extended LintError interface with three new optional fields:
  - literal: The literal link text from source files (e.g., '../../../docs/file.md')
  - endColumn: End column position for range extraction
  - resolvedPath: Resolved path relative to basePath (e.g., 'features/docs/file.md')
- All fields optional for backward compatibility

### Link Validator Updates
- Capture literal text and position from markdown AST (remark/unified)
- Create complete error messages at source: "Dead link: 'literal' resolves to 'resolved'"
- Pass literal, endColumn, resolvedPath to all error objects
- Applies to dead-link, dead-anchor, and external-link errors

### Reporter Enhancements
- Text format: Shows 'literal' resolves to 'resolved' inline (uses error.message directly)
- JSON format: Includes literal, endColumn, resolvedPath fields (flat structure)
- **NEW grep format**: Tab-delimited output for Unix tool parsing
  - Field order: file, line, column, endColumn, severity, ruleId, literal, resolvedPath
  - Parseable with cut/awk/sed for automated fixes
  - Example: `mdite lint --format grep | cut -d$'\t' -f7` extracts all literal paths
- Clean architecture: LinkValidator creates messages, Reporter presents them (no parsing)

### CLI Updates
- Added 'grep' as valid format option: --format text|json|grep
- Auto-disables colors for grep format (machine-readable)

### Testing
- Added 11 new integration tests (tests/integration/lint-literal-paths.test.ts)
  - Text format literal display
  - JSON format field structure
  - Grep format tab-delimited parsing
  - Backward compatibility
  - Complex scenarios (multiple errors, anchors)
- Fixed 1 existing test updated for new format
- All 625 tests passing (614 existing + 11 new)
- All 38 smoke tests passing

### Documentation
- Updated CHANGELOG.md with feature details and examples
- Added README.md workflow 7: "Automated Link Fixing with Grep Format"
- Updated lint command documentation with grep format examples

## Use Cases

**Automated fix scripts**:
```bash
# Extract all literal paths
mdite lint --format grep | cut -d$'\t' -f7

# Process dead links
mdite lint --format grep | awk -F'\t' '$6=="dead-link" {print $1, $7}'

# Automated fix workflow
mdite lint --format grep | while IFS=$'\t' read file line col endCol severity rule literal resolved; do
  if [ "$rule" = "dead-link" ]; then
    sed -i "${line}s|$literal|correct-path|" "$file"
  fi
done
```

## Architecture

Clean separation of concerns achieved through iterative refinement:
1. LinkValidator creates complete error messages with literal/resolved at source
2. Reporter presents messages without any parsing or manipulation
3. Error type carries all necessary fields (literal, resolvedPath, endColumn)
4. All formats use error object fields directly (no regex, no brittleness)

## Breaking Changes

None - all new fields are optional and formats are additive.
---
 CHANGELOG.md                                 |  10 +
 README.md                                    |  42 +++-
 src/commands/lint.ts                         |   5 +-
 src/core/link-validator.ts                   |  71 +++++-
 src/core/reporter.ts                         |  25 +-
 src/types/errors.ts                          |   6 +
 tests/integration/lint-literal-paths.test.ts | 247 +++++++++++++++++++
 tests/integration/lint-multi-files.test.ts   |   9 +-
 8 files changed, 397 insertions(+), 18 deletions(-)
 create mode 100644 tests/integration/lint-literal-paths.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2df4c62..f32e550 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Enhanced
+
+- **Literal path error reporting**: mdite lint now reports literal link text from source files alongside resolved paths
+  - Text format: Shows `'literal' resolves to 'resolved'` inline for clear understanding
+  - JSON format: Includes `literal`, `endColumn` fields (flat structure, backward compatible)
+  - New grep format: `--format grep` outputs tab-delimited for Unix tool parsing (cut/awk/sed)
+  - Enables automated fix scripts with grep/sed without reverse-engineering paths
+  - Example: `mdite lint --format grep | cut -d$'\t' -f7` extracts all literal paths
+  - All formats maintain backward compatibility with existing parsers
+
 ## [1.0.2] - 2025-10-24
 
 ### Fixed
diff --git a/README.md b/README.md
index d2e1688..47580bb 100644
--- a/README.md
+++ b/README.md
@@ -449,7 +449,36 @@ mdite deps README.md --format json | jq -r '.outgoing[] | [.file, .depth] | @csv
 
 **Benefit:** Full integration with Unix ecosystem (grep, jq, awk, sed, mail, etc.)
 
-### 7. Progressive Validation
+### 7. Automated Link Fixing with Grep Format
+
+```bash
+# Find all dead links with literal paths (grep format)
+mdite lint --format grep > dead-links.tsv
+
+# Extract just the literal link text (field 7)
+mdite lint --format grep | cut -d$'\t' -f7
+
+# Extract file, line, and literal for manual fixing
+mdite lint --format grep | awk -F'\t' '{print $1 ":" $2 " → " $7}'
+
+# Automated fix workflow example
+mdite lint --format grep | while IFS=$'\t' read file line col endCol severity rule literal resolved; do
+  if [ "$rule" = "dead-link" ]; then
+    echo "Fix: $file:$line - Replace '$literal' with correct path"
+    # Add your automated fix logic here (sed, etc.)
+  fi
+done
+
+# Extract broken links by file
+mdite lint --format grep | awk -F'\t' '$6=="dead-link" {print $1, $7}' | sort
+
+# Count broken links by type
+mdite lint --format grep | cut -d$'\t' -f6 | sort | uniq -c
+```
+
+**Benefit:** Automated fix scripts can locate and replace broken links using exact text from source files, no path reverse-engineering needed.
+
+### 8. Progressive Validation
 
 ```bash
 # Start with core docs only
@@ -568,6 +597,15 @@ mdite lint ./docs
 # JSON output for CI/CD (auto-disables colors)
 mdite lint --format json
 
+# Grep format for automated fixes (tab-delimited)
+mdite lint --format grep
+
+# Extract all literal paths
+mdite lint --format grep | cut -d$'\t' -f7
+
+# Extract file and literal for processing
+mdite lint --format grep | awk -F'\t' '{print $1, $7}'
+
 # Pipe JSON to jq for analysis
 mdite lint --format json | jq '.[] | select(.severity=="error")'
 
@@ -614,7 +652,7 @@ mdite lint $(git diff --cached --name-only | grep '\.md$') --depth 1
 
 **Options:**
 
-- `--format <type>` - Output: `text` (default) or `json`
+- `--format <type>` - Output: `text` (default), `json`, or `grep`
 - `--entrypoint <file>` - Entrypoint file (overrides config, cannot be used with multiple files)
 - `--depth <n>` - Maximum depth of traversal (default: unlimited, applies to all files)
 - `-q, --quiet` - Suppress informational output (only show errors)
diff --git a/src/commands/lint.ts b/src/commands/lint.ts
index cf22ec5..023d657 100644
--- a/src/commands/lint.ts
+++ b/src/commands/lint.ts
@@ -87,7 +87,7 @@ export function lintCommand(): Command {
     .description('Lint documentation files')
     .addHelpText('after', DESCRIPTION)
     .argument('[paths...]', 'Documentation files or directory', ['.'])
-    .option('--format <type>', 'Output format (text|json)', 'text')
+    .option('--format <type>', 'Output format (text|json|grep)', 'text')
     .option('--entrypoint <file>', 'Entrypoint file (overrides config)')
     .option('--depth <n>', 'Maximum depth of traversal (default: unlimited)', 'unlimited')
     .option(
@@ -114,10 +114,11 @@ export function lintCommand(): Command {
     .action(async (pathsArg: string[], options, command) => {
       const globalOpts = command.optsWithGlobals();
       const isJsonFormat = options.format === 'json';
+      const isGrepFormat = options.format === 'grep';
 
       // Determine colors setting
       const colors = (() => {
-        if (isJsonFormat) return false; // JSON never uses colors
+        if (isJsonFormat || isGrepFormat) return false; // JSON and grep never use colors
         if (globalOpts.colors === true) return true; // Forced on
         if (globalOpts.colors === false) return false; // Forced off
         return shouldUseColors(); // Auto-detect
diff --git a/src/core/link-validator.ts b/src/core/link-validator.ts
index 64e5205..2891b1c 100644
--- a/src/core/link-validator.ts
+++ b/src/core/link-validator.ts
@@ -121,6 +121,8 @@ export class LinkValidator {
     visit(ast, 'link', (node: Link) => {
       const url = node.url;
       const position = node.position?.start || { line: 0, column: 0 };
+      const endColumn = node.position?.end?.column;
+      const literal = url; // The URL is the literal text from source
 
       // Skip external links
       if (url.startsWith('http://') || url.startsWith('https://')) {
@@ -129,7 +131,9 @@ export class LinkValidator {
 
       // Check anchor-only links
       if (url.startsWith('#')) {
-        linkChecks.push(this.validateAnchor(url.slice(1), filePath, filePath, position));
+        linkChecks.push(
+          this.validateAnchor(url.slice(1), filePath, filePath, position, literal, endColumn)
+        );
         return;
       }
 
@@ -140,10 +144,17 @@ export class LinkValidator {
         const targetPath = path.resolve(path.dirname(filePath), filePart);
 
         linkChecks.push(
-          this.validateFileLink(targetPath, filePath, position).then(error => {
+          this.validateFileLink(targetPath, filePath, position, literal, endColumn).then(error => {
             // If file link is valid and there's an anchor, check it
             if (!error && anchor) {
-              return this.validateAnchor(anchor, targetPath, filePath, position);
+              return this.validateAnchor(
+                anchor,
+                targetPath,
+                filePath,
+                position,
+                literal,
+                endColumn
+              );
             }
             return error;
           })
@@ -167,13 +178,17 @@ export class LinkValidator {
    * @param targetPath - Absolute path to target file
    * @param sourceFile - Source file containing the link
    * @param position - Line/column position of link in source
+   * @param literal - Literal link text from source file (for error reporting)
+   * @param endColumn - End column position for range extraction
    * @returns LintError if file doesn't exist or external link policy violated, null if valid
    * @private
    */
   private async validateFileLink(
     targetPath: string,
     sourceFile: string,
-    position: { line: number; column: number }
+    position: { line: number; column: number },
+    literal?: string,
+    endColumn?: number
   ): Promise<LintError | null> {
     const targetInScope = this.isWithinScope(targetPath);
 
@@ -187,13 +202,20 @@ export class LinkValidator {
     }
 
     if (!exists) {
+      const resolvedPath = path.relative(this.basePath, targetPath);
+      const message = literal
+        ? `Dead link: '${literal}' resolves to '${resolvedPath}'`
+        : `Dead link: ${resolvedPath}`;
       return {
         rule: 'dead-link',
         severity: 'error',
         file: sourceFile,
         line: position.line,
         column: position.column,
-        message: `Dead link: ${path.relative(this.basePath, targetPath)}`,
+        endColumn,
+        message,
+        literal,
+        resolvedPath,
       };
     }
 
@@ -206,25 +228,41 @@ export class LinkValidator {
         case 'validate':
           return null; // Already validated existence, no warning
 
-        case 'warn':
+        case 'warn': {
+          const resolvedPath = path.relative(this.basePath, targetPath);
+          const message = literal
+            ? `External link (outside scope): '${literal}' resolves to '${resolvedPath}'`
+            : `External link (outside scope): ${resolvedPath}`;
           return {
             rule: 'external-link',
             severity: 'warning',
             file: sourceFile,
             line: position.line,
             column: position.column,
-            message: `External link (outside scope): ${path.relative(this.basePath, targetPath)}`,
+            endColumn,
+            message,
+            literal,
+            resolvedPath,
           };
+        }
 
-        case 'error':
+        case 'error': {
+          const resolvedPath = path.relative(this.basePath, targetPath);
+          const message = literal
+            ? `External link not allowed: '${literal}' resolves to '${resolvedPath}'`
+            : `External link not allowed: ${resolvedPath}`;
           return {
             rule: 'external-link',
             severity: 'error',
             file: sourceFile,
             line: position.line,
             column: position.column,
-            message: `External link not allowed: ${path.relative(this.basePath, targetPath)}`,
+            endColumn,
+            message,
+            literal,
+            resolvedPath,
           };
+        }
       }
     }
 
@@ -241,6 +279,8 @@ export class LinkValidator {
    * @param targetFile - File containing the heading
    * @param sourceFile - Source file containing the link
    * @param position - Line/column position of link in source
+   * @param literal - Literal link text from source file (for error reporting)
+   * @param endColumn - End column position for range extraction
    * @returns LintError if anchor doesn't exist, null if valid
    * @private
    *
@@ -255,7 +295,9 @@ export class LinkValidator {
     anchor: string,
     targetFile: string,
     sourceFile: string,
-    position: { line: number; column: number }
+    position: { line: number; column: number },
+    literal?: string,
+    endColumn?: number
   ): Promise<LintError | null> {
     try {
       // Use cache to get headings
@@ -263,13 +305,20 @@ export class LinkValidator {
       const anchorSlug = slugify(anchor);
 
       if (!headings.includes(anchorSlug)) {
+        const resolvedPath = `#${anchor} in ${path.relative(this.basePath, targetFile)}`;
+        const message = literal
+          ? `Dead anchor: '${literal}' resolves to '${resolvedPath}'`
+          : `Dead anchor: ${resolvedPath}`;
         return {
           rule: 'dead-anchor',
           severity: 'error',
           file: sourceFile,
           line: position.line,
           column: position.column,
-          message: `Dead anchor: #${anchor} in ${path.relative(this.basePath, targetFile)}`,
+          endColumn,
+          message,
+          literal,
+          resolvedPath,
         };
       }
 
diff --git a/src/core/reporter.ts b/src/core/reporter.ts
index 43232d6..2d8c905 100644
--- a/src/core/reporter.ts
+++ b/src/core/reporter.ts
@@ -4,13 +4,15 @@ import { Logger } from '../utils/logger.js';
 
 export class Reporter {
   constructor(
-    private format: 'text' | 'json',
+    private format: 'text' | 'json' | 'grep',
     private logger: Logger
   ) {}
 
   report(results: LintResults): void {
     if (this.format === 'json') {
       this.reportJson(results);
+    } else if (this.format === 'grep') {
+      this.reportGrep(results);
     } else {
       this.reportText(results);
     }
@@ -45,6 +47,7 @@ export class Reporter {
         const severity = error.severity === 'error' ? chalk.red('error') : chalk.yellow('warn');
         const rule = chalk.gray(`[${error.rule}]`);
 
+        // Message already includes literal/resolved formatting if available
         this.logger.log(`  ${location} ${severity} ${error.message} ${rule}`);
       }
       this.logger.log('');
@@ -60,4 +63,24 @@ export class Reporter {
   private reportJson(results: LintResults): void {
     console.log(JSON.stringify(results.getAllErrors(), null, 2));
   }
+
+  private reportGrep(results: LintResults): void {
+    const errors = results.getAllErrors();
+
+    // Grep format: tab-delimited fields (file, line, column, endColumn, severity, ruleId, literal, resolvedPath)
+    for (const error of errors) {
+      const file = error.file;
+      const line = error.line.toString();
+      const column = error.column.toString();
+      const endColumn = error.endColumn?.toString() || '';
+      const severity = error.severity;
+      const ruleId = error.rule;
+      const literal = error.literal || '';
+      const resolvedPath = error.resolvedPath || '';
+
+      // Tab-delimited output (ensure all fields are strings)
+      const fields = [file, line, column, endColumn, severity, ruleId, literal, resolvedPath];
+      console.log(fields.join('\t'));
+    }
+  }
 }
diff --git a/src/types/errors.ts b/src/types/errors.ts
index 2819b51..90c58e3 100644
--- a/src/types/errors.ts
+++ b/src/types/errors.ts
@@ -6,5 +6,11 @@ export interface LintError {
   file: string;
   line: number;
   column: number;
+  /** End column position for range extraction */
+  endColumn?: number;
   message: string;
+  /** Literal link text from source file (for automated fixes) */
+  literal?: string;
+  /** Resolved path that the literal resolves to (for error context) */
+  resolvedPath?: string;
 }
diff --git a/tests/integration/lint-literal-paths.test.ts b/tests/integration/lint-literal-paths.test.ts
new file mode 100644
index 0000000..59b1f37
--- /dev/null
+++ b/tests/integration/lint-literal-paths.test.ts
@@ -0,0 +1,247 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createTestDir, writeTestFile } from '../setup.js';
+import { join } from 'path';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+describe('lint command - literal path reporting (integration)', () => {
+  let testDir: string;
+  let cliPath: string;
+
+  beforeEach(async () => {
+    testDir = await createTestDir();
+    cliPath = path.resolve(process.cwd(), 'dist/src/index.js');
+  });
+
+  afterEach(async () => {
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  function runCli(args: string[]): {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+  } {
+    const { spawnSync } = require('child_process');
+    const result = spawnSync('node', [cliPath, ...args], {
+      cwd: testDir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      maxBuffer: 10 * 1024 * 1024, // 10MB
+    });
+
+    return {
+      stdout: result.stdout || '',
+      stderr: result.stderr || '',
+      exitCode: result.status || 0,
+    };
+  }
+
+  describe('text format with literal inline display', () => {
+    it('should show literal and resolved paths inline with "resolves to"', async () => {
+      await writeTestFile(join(testDir, 'README.md'), '# Main\n\n[Broken](./missing.md)');
+
+      const result = runCli(['lint', '--format', 'text']);
+
+      expect(result.exitCode).toBe(1);
+      expect(result.stdout).toContain('resolves to');
+      expect(result.stdout).toContain('./missing.md');
+    });
+
+    it('should handle relative paths correctly', async () => {
+      // Create deep directory structure
+      await fs.mkdir(join(testDir, 'docs/deep/nested'), { recursive: true });
+      await writeTestFile(
+        join(testDir, 'docs/deep/nested/file.md'),
+        '# File\n\n[Link](../../../missing.md)'
+      );
+      await writeTestFile(
+        join(testDir, 'README.md'),
+        '# Main\n\n[Link](./docs/deep/nested/file.md)'
+      );
+
+      const result = runCli(['lint', '--format', 'text']);
+
+      expect(result.exitCode).toBe(1);
+      expect(result.stdout).toContain('../../../missing.md');
+      expect(result.stdout).toContain('resolves to');
+    });
+
+    it('should handle anchor-only links with literal text', async () => {
+      await writeTestFile(join(testDir, 'README.md'), '# Main\n\n[Broken](#nonexistent-heading)');
+
+      const result = runCli(['lint', '--format', 'text']);
+
+      expect(result.exitCode).toBe(1);
+      expect(result.stdout).toContain('#nonexistent-heading');
+    });
+  });
+
+  describe('JSON format with literal/resolvedPath/endColumn fields', () => {
+    it('should include literal, resolvedPath, and endColumn in JSON output', async () => {
+      await writeTestFile(join(testDir, 'README.md'), '# Main\n\n[Broken](./missing.md)');
+
+      const result = runCli(['lint', '--format', 'json']);
+
+      expect(result.exitCode).toBe(1);
+      const errors = JSON.parse(result.stdout);
+      expect(Array.isArray(errors)).toBe(true);
+      expect(errors.length).toBeGreaterThan(0);
+
+      const deadLinkError = errors.find((e: any) => e.rule === 'dead-link');
+      expect(deadLinkError).toBeDefined();
+      expect(deadLinkError.literal).toBe('./missing.md');
+      expect(deadLinkError.endColumn).toBeDefined();
+      expect(typeof deadLinkError.endColumn).toBe('number');
+    });
+
+    it('should have flat structure with all new fields', async () => {
+      await writeTestFile(join(testDir, 'README.md'), '# Main\n\n[Link](./broken.md)');
+
+      const result = runCli(['lint', '--format', 'json']);
+
+      const errors = JSON.parse(result.stdout);
+      const error = errors.find((e: any) => e.rule === 'dead-link');
+
+      // Verify flat structure (all fields at top level)
+      expect(error).toHaveProperty('literal');
+      expect(error).toHaveProperty('endColumn');
+      expect(error).toHaveProperty('line');
+      expect(error).toHaveProperty('column');
+      expect(error).toHaveProperty('file');
+      expect(error).toHaveProperty('severity');
+      expect(error).toHaveProperty('message');
+      expect(error).toHaveProperty('rule');
+    });
+  });
+
+  describe('grep format tab-delimited output', () => {
+    it('should output tab-delimited format with 8 fields', async () => {
+      await writeTestFile(join(testDir, 'README.md'), '# Main\n\n[Broken](./missing.md)');
+
+      const result = runCli(['lint', '--format', 'grep']);
+
+      expect(result.exitCode).toBe(1);
+      const lines = result.stdout.trim().split('\n');
+      expect(lines.length).toBeGreaterThan(0);
+
+      // Check tab-delimited format
+      const firstLine = lines.find((line: string) => line.includes('dead-link'));
+      expect(firstLine).toBeDefined();
+      const fields = firstLine!.split('\t');
+      expect(fields.length).toBe(8);
+
+      // Field order: file, line, column, endColumn, severity, ruleId, literal, resolvedPath
+      expect(fields[0]).toContain('README.md'); // file
+      expect(fields[1]).toMatch(/^\d+$/); // line number
+      expect(fields[2]).toMatch(/^\d+$/); // column number
+      expect(fields[3]).toMatch(/^\d*$/); // endColumn (may be empty)
+      expect(['error', 'warning']).toContain(fields[4]); // severity
+      expect(fields[5]).toBeTruthy(); // ruleId
+      expect(fields[6]).toBeTruthy(); // literal
+      expect(fields[7]).toBeTruthy(); // resolvedPath
+    });
+
+    it('should be parseable with cut command (field 7 = literal)', async () => {
+      await writeTestFile(
+        join(testDir, 'README.md'),
+        '# Main\n\n[Link1](./missing1.md)\n[Link2](./missing2.md)'
+      );
+
+      const result = runCli(['lint', '--format', 'grep']);
+
+      expect(result.exitCode).toBe(1);
+      const lines = result.stdout.trim().split('\n');
+
+      // Extract field 7 (literal) from each line
+      const literals = lines
+        .filter((line: string) => line.trim())
+        .map((line: string) => line.split('\t')[6]);
+
+      expect(literals).toContain('./missing1.md');
+      expect(literals).toContain('./missing2.md');
+    });
+
+    it('should handle empty fields gracefully', async () => {
+      await writeTestFile(join(testDir, 'README.md'), '# Main\n\nOrphan file test');
+      await writeTestFile(join(testDir, 'orphan.md'), '# Orphan');
+
+      const result = runCli(['lint', '--format', 'grep']);
+
+      expect(result.exitCode).toBe(1);
+      const lines = result.stdout.trim().split('\n');
+      const orphanLine = lines.find((line: string) => line.includes('orphan-files'));
+
+      if (orphanLine) {
+        const fields = orphanLine.split('\t');
+        // Orphan files don't have literal/resolved paths, so fewer fields
+        expect(fields.length).toBeGreaterThan(0);
+        // But still has core fields: file, line, column, endColumn (empty), severity, ruleId
+        expect(fields[0]).toContain('orphan.md'); // file
+        expect(fields[4]).toBe('error'); // severity
+        expect(fields[5]).toBe('orphan-files'); // ruleId
+      }
+    });
+  });
+
+  describe('backward compatibility', () => {
+    it('should not crash when error has no literal field', async () => {
+      // Create scenario where literal might be unavailable
+      await writeTestFile(join(testDir, 'README.md'), '# Main\n\nSimple test');
+      await writeTestFile(join(testDir, 'orphan.md'), '# Orphan');
+
+      // All three formats should work
+      const textResult = runCli(['lint', '--format', 'text']);
+      expect(textResult.exitCode).toBe(1);
+      expect(textResult.stdout).toBeTruthy();
+
+      const jsonResult = runCli(['lint', '--format', 'json']);
+      expect(jsonResult.exitCode).toBe(1);
+      const errors = JSON.parse(jsonResult.stdout);
+      expect(Array.isArray(errors)).toBe(true);
+
+      const grepResult = runCli(['lint', '--format', 'grep']);
+      expect(grepResult.exitCode).toBe(1);
+      expect(grepResult.stdout).toBeTruthy();
+    });
+  });
+
+  describe('complex scenarios', () => {
+    it('should handle multiple dead links in same file', async () => {
+      await writeTestFile(
+        join(testDir, 'README.md'),
+        `# Main
+
+[Link1](./missing1.md)
+[Link2](./missing2.md)
+[Link3](./missing3.md)`
+      );
+
+      const result = runCli(['lint', '--format', 'json']);
+
+      expect(result.exitCode).toBe(1);
+      const errors = JSON.parse(result.stdout);
+      const deadLinks = errors.filter((e: any) => e.rule === 'dead-link');
+      expect(deadLinks.length).toBe(3);
+
+      deadLinks.forEach((error: any) => {
+        expect(error.literal).toBeDefined();
+        expect(error.literal).toMatch(/\.\/missing\d\.md/);
+        expect(error.endColumn).toBeGreaterThan(error.column);
+      });
+    });
+
+    it('should handle dead link with dead anchor', async () => {
+      await writeTestFile(join(testDir, 'README.md'), '# Main\n\n[Link](./missing.md#anchor)');
+
+      const result = runCli(['lint', '--format', 'json']);
+
+      expect(result.exitCode).toBe(1);
+      const errors = JSON.parse(result.stdout);
+      const deadLinkError = errors.find((e: any) => e.rule === 'dead-link');
+
+      expect(deadLinkError).toBeDefined();
+      expect(deadLinkError.literal).toContain('./missing.md');
+    });
+  });
+});
diff --git a/tests/integration/lint-multi-files.test.ts b/tests/integration/lint-multi-files.test.ts
index 8ef3248..be6b6b5 100644
--- a/tests/integration/lint-multi-files.test.ts
+++ b/tests/integration/lint-multi-files.test.ts
@@ -181,9 +181,14 @@ describe('mdite lint [paths...] (multi-file)', () => {
       const result = runLint(['A.md', 'B.md']);
 
       expect(result.exitCode).toBe(1);
-      // Should report broken.md error only once, not twice
+      // Should report broken.md error once per file (A.md and B.md)
+      // With literal/resolved format, "broken.md" appears twice per error line (literal + resolved)
+      // So we expect 2 errors * 2 occurrences = 4 total mentions
       const brokenCount = (result.stdout.match(/broken\.md/g) || []).length;
-      expect(brokenCount).toBeLessThanOrEqual(2); // Once in each file's context
+      expect(brokenCount).toBeGreaterThan(0); // At least some errors reported
+      // Count actual error lines instead
+      const errorLines = result.stdout.split('\n').filter(line => line.includes('dead-link'));
+      expect(errorLines.length).toBe(2); // One error per file
     });
   });
 

From 38da5b04f8286dc207a3e5e95fbf4e099b5c7c0b Mon Sep 17 00:00:00 2001
From: Richard Adleta <radleta@gmail.com>
Date: Tue, 4 Nov 2025 02:49:41 +0000
Subject: [PATCH 3/7] docs(help): add comprehensive CLI help standards and
 enhance all commands
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add CLI help text standards section to CONTRIBUTING.md
  • Documents hybrid architecture (shared vs command-specific)
  • Provides templates for DESCRIPTION, EXAMPLES, OUTPUT, SEE_ALSO
  • Includes formatting guidelines and checklists
  • References industry best practices (git, docker, npm, ripgrep)

- Enhance help text across all commands
  • Add detailed OUTPUT sections (8-10 bullets each)
  • Improve SEE_ALSO organization (Core workflow, Configuration, Global tiers)
  • Standardize cross-references between related commands

- Improve shared help text (help-text.ts)
  • Expand ENVIRONMENT_VARS with detailed descriptions
  • Add context for NO_COLOR, FORCE_COLOR, CI usage
  • Document precedence and equivalents

- Update tests to match new help structure
  • Fix JMESPath reference check for new External tier
  • Maintain all existing coverage
---
 CONTRIBUTING.md                    | 213 +++++++++++++++++++++++++++++
 src/commands/cat.ts                |  30 +++-
 src/commands/config.ts             |  30 +++-
 src/commands/deps.ts               |  30 +++-
 src/commands/files.ts              |  35 ++++-
 src/commands/init.ts               |  41 +++++-
 src/commands/lint.ts               |  34 +++--
 src/utils/help-text.ts             |  17 ++-
 tests/integration/cli-help.test.ts |   3 +-
 9 files changed, 403 insertions(+), 30 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6f00a53..7087463 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -525,6 +525,219 @@ Add an example if:
 
 See [examples/README.md](./examples/README.md) for existing examples and detailed documentation.
 
+## CLI Help Text Standards
+
+mdite follows industry best practices from established CLI tools (git, docker, npm, ripgrep) to provide comprehensive, agent-optimized help text. This section documents patterns for maintaining and extending CLI help.
+
+### Hybrid Architecture
+
+**Shared Content** (`src/utils/help-text.ts`):
+
+- Content identical across all commands
+- Examples: EXIT_CODES, ENVIRONMENT_VARS, CONFIG_PRECEDENCE
+- Export as constants, import where needed
+
+**Command-Specific Content** (colocated with command files):
+
+- DESCRIPTION, EXAMPLES, OUTPUT, SEE_ALSO constants
+- Defined at top of command file (e.g., `src/commands/lint.ts`)
+- Registered via `.addHelpText('after', CONSTANT)`
+
+### Help Text Components
+
+Every command should include these sections in order:
+
+#### 1. DESCRIPTION Constant
+
+```typescript
+const DESCRIPTION = `
+DESCRIPTION:
+  Brief explanation of what command does (1-2 sentences).
+
+  Use cases:
+    - Use case 1
+    - Use case 2
+    - Use case 3
+
+  Key features or behaviors:
+    - Feature 1
+    - Feature 2
+`;
+```
+
+**Guidelines:**
+
+- Start with high-level purpose
+- Include 3-4 use cases showing when to use the command
+- List key features or special behaviors
+- Keep concise but informative
+
+#### 2. EXAMPLES Constant
+
+```typescript
+const EXAMPLES = `
+EXAMPLES:
+  Basic usage:
+      $ mdite command
+
+  With common option:
+      $ mdite command --option value
+
+  Advanced scenario:
+      $ mdite command --flag1 --flag2 value
+
+  Piping to other tools:
+      $ mdite command | grep "pattern"
+
+  JSON output for tooling:
+      $ mdite command --format json | jq '.field'
+
+  CI/CD integration:
+      $ mdite command --quiet || exit 1
+
+  Complex workflow:
+      $ mdite command --multiple --flags | xargs other-tool
+
+  Edge case:
+      $ mdite command --special-case
+`;
+```
+
+**Guidelines:**
+
+- Aim for 8-10 examples covering all use cases
+- Use 6-space indentation for consistency
+- Prefix commands with `$` for clarity
+- Add blank line between examples
+- Include: basic usage, common options, advanced scenarios, piping, CI/CD, edge cases
+- Show Unix tool composition (grep, jq, xargs, etc.)
+
+#### 3. OUTPUT Constant
+
+```typescript
+const OUTPUT = `
+OUTPUT:
+  - Data to stdout (pipeable): What data goes to stdout
+  - Messages to stderr (suppressible): What messages go to stderr
+  - Quiet mode (--quiet): Suppresses stderr, keeps stdout data
+  - Format options (--format):
+      • format1: Description of format
+      • format2: Description of format
+      • format3: Description of format
+  - Color handling: Auto-disabled for JSON and when piped, respects NO_COLOR/FORCE_COLOR
+  - Exit codes: 0=success, 1=validation errors, 2=invalid arguments, 130=interrupted
+  - TTY detection: Colors auto-disable when piped to other tools
+  - Error output: Where errors appear (stdout vs stderr)
+  - Pipe-friendly: Works with grep, jq, awk - clean stdout for processing
+  - Additional behavior: Any other relevant output behavior
+`;
+```
+
+**Guidelines:**
+
+- Aim for 8-10 bullet points covering all output behaviors
+- Document stdout/stderr separation (critical for Unix composition)
+- Explain --quiet mode behavior
+- List all --format options with descriptions
+- Document color handling (TTY detection, NO_COLOR, FORCE_COLOR)
+- List exit codes
+- Explain piping behavior
+- Mention tools that work well with the command
+
+#### 4. SEE_ALSO Constant
+
+```typescript
+const SEE_ALSO = `
+SEE ALSO:
+  Core workflow:
+    mdite lint               Validate documentation structure
+    mdite deps               Analyze file dependencies
+
+  Configuration:
+    mdite config             View current configuration
+    mdite init               Create config file
+
+  Global:
+    mdite --help             Main help with exit codes and environment variables
+`;
+```
+
+**Guidelines:**
+
+- Organize by tier (Core workflow, Configuration, Global)
+- Include 3-5 references per command
+- Brief description per reference (2-5 words)
+- Bidirectional links (lint ↔ deps, init ↔ config)
+- All commands reference global help
+
+**Tier Structure:**
+
+- **Core workflow**: lint → deps → files → cat (main feature workflow)
+- **Configuration**: init ↔ config (configuration management)
+- **Global**: All commands reference `mdite --help`
+
+### Registration Pattern
+
+```typescript
+export function myCommand(): Command {
+  return new Command('my-command')
+    .description('Brief one-line description')
+    .addHelpText('after', DESCRIPTION)
+    .argument('<arg>', 'Argument description')
+    .option('--flag', 'Flag description')
+    .addHelpText('after', EXAMPLES)
+    .addHelpText('after', OUTPUT)
+    .addHelpText('after', SEE_ALSO)
+    .action(async (arg, options, command) => {
+      // Implementation
+    });
+}
+```
+
+**Registration order:**
+
+1. DESCRIPTION (after command definition)
+2. Arguments and options
+3. EXAMPLES (after options)
+4. OUTPUT (after examples)
+5. SEE_ALSO (after output)
+
+### Formatting Conventions
+
+- **Indentation**: 6 spaces for examples, 4 spaces for bullet sub-items
+- **Command prefix**: `$` before all command examples
+- **Blank lines**: Between examples, between tier groups in SEE_ALSO
+- **Bullet format**: `-` for main bullets, `•` for sub-items (format options)
+- **Line length**: Aim for 80 characters, wrap longer lines
+- **Escape sequences**: Support `\n`, `\t` in examples (e.g., --separator)
+
+### Checklist for Adding Help Text
+
+When adding or updating command help, verify:
+
+- [ ] DESCRIPTION constant present (1-2 sentences + use cases + features)
+- [ ] EXAMPLES constant present (8-10 examples covering all use cases)
+- [ ] OUTPUT constant present (8-10 bullets covering all output behaviors)
+- [ ] SEE_ALSO constant present (3-5 references organized by tier)
+- [ ] All constants registered via `.addHelpText('after', CONSTANT)`
+- [ ] Registration order correct (DESCRIPTION → args/opts → EXAMPLES → OUTPUT → SEE_ALSO)
+- [ ] Formatting consistent (6-space indent, $ prefix, blank lines)
+- [ ] Cross-references bidirectional (if command references another, that command references back)
+- [ ] Manual test: `mdite [command] --help` displays correctly
+- [ ] Integration test added to `tests/integration/cli-help.test.ts`
+
+### Reference Implementations
+
+**Simple**: `src/commands/init.ts` (~80 lines)
+**Medium**: `src/commands/config.ts` (~90 lines)
+**Complex**: `src/commands/files.ts` (~120 lines)
+
+### Related Documentation
+
+- **Industry patterns**: `scratch/cli-help-improvements/patterns.md` - Analysis of git, docker, npm, ripgrep
+- **Architecture**: `ARCHITECTURE.md` - Unix CLI Integration Patterns section
+- **User docs**: `README.md` - Commands section (keep aligned with help text)
+
 ## Documentation
 
 - Update README.md for user-facing features
diff --git a/src/commands/cat.ts b/src/commands/cat.ts
index c1c1a07..ab37405 100644
--- a/src/commands/cat.ts
+++ b/src/commands/cat.ts
@@ -62,10 +62,35 @@ EXAMPLES:
       $ mdite cat | pandoc -s -o documentation.html
 `;
 
+const OUTPUT = `
+OUTPUT:
+  - Data to stdout (pipeable): File content (markdown) or JSON with metadata
+  - Messages to stderr (suppressible): Progress messages, file counts, errors
+  - Quiet mode (--quiet): Suppresses stderr progress, keeps only content on stdout
+  - Format options (--format):
+      • markdown: Raw file content concatenated with separators (default)
+      • json: Array with {file, depth, content, wordCount, lineCount} per file
+  - Separator handling: --separator supports escape sequences (\\n, \\t, etc.)
+  - Order options: --order deps (respects document relationships), --order alpha (predictable)
+  - Color handling: Never uses colors (content must be parseable)
+  - Exit codes: 0=success, 1=error, 2=invalid arguments, 130=interrupted
+  - TTY detection: Output always pipe-friendly regardless of terminal
+  - Stream efficiency: Outputs files sequentially for memory efficiency on large docs
+  - Pipe compatibility: Works with pandoc, grep, awk, sed, jq - clean stdout for processing
+`;
+
 const SEE_ALSO = `
 SEE ALSO:
-  mdite files   List files for selective output
-  mdite deps    Understand dependency order
+  Core workflow:
+    mdite files              List files for selective output
+    mdite deps               Understand dependency order
+
+  Configuration:
+    mdite config             View current configuration
+    mdite init               Create config file
+
+  Global:
+    mdite --help             Main help with exit codes and environment variables
 `;
 
 // ============================================================================
@@ -91,6 +116,7 @@ export function catCommand(): Command {
     .option('--respect-gitignore', 'Respect .gitignore patterns')
     .option('--no-exclude-hidden', "Don't exclude hidden directories")
     .addHelpText('after', EXAMPLES)
+    .addHelpText('after', OUTPUT)
     .addHelpText('after', SEE_ALSO)
     .action(async (files: string[], options, command) => {
       const globalOpts = command.optsWithGlobals();
diff --git a/src/commands/config.ts b/src/commands/config.ts
index 6b7649f..d6bb113 100644
--- a/src/commands/config.ts
+++ b/src/commands/config.ts
@@ -23,7 +23,7 @@ DESCRIPTION:
   Without flags: Shows merged configuration from all sources
   With --schema: Shows all available configuration options
   With --explain: Shows detailed docs for specific option
-  With --sources: Shows which layer provides each value
+  With --sources: Shows which layer provides each value (Phase 2, currently shows placeholder)
   With --template: Generates comprehensive config template
 
   Configuration layers (highest to lowest priority):
@@ -57,9 +57,34 @@ EXAMPLES:
       $ mdite config --quiet | jq '.entrypoint'
 `;
 
+const OUTPUT = `
+OUTPUT:
+  - Data to stdout (pipeable): Configuration JSON or formatted text
+  - Messages to stderr (suppressible): Headers, prompts, help text
+  - Quiet mode (--quiet): Suppresses stderr messages, outputs only config data
+  - Format options (--format):
+      • text: Human-readable with colors (default, --schema and no-flag modes)
+      • json: Structured data for programmatic processing (pipeable to jq)
+      • js/yaml/md: Template formats (only with --template flag)
+  - Schema output: All options with descriptions, types, defaults, examples
+  - Explain output: Detailed help for specific option with fuzzy matching
+  - Color handling: Auto-disabled for JSON and when piped, respects NO_COLOR/FORCE_COLOR
+  - Exit codes: 0=success, 1=error, 2=invalid arguments (unknown option), 130=interrupted
+  - TTY detection: Colors auto-disable when piped to other tools (jq, grep, less)
+  - Template output: Can write to file with --output or stdout for piping
+`;
+
 const SEE_ALSO = `
 SEE ALSO:
-  mdite init  Create configuration file
+  Configuration:
+    mdite init               Create config file with defaults
+
+  Core workflow:
+    mdite lint               Use config for validation
+    mdite deps               Use config for graph traversal
+
+  Global:
+    mdite --help             Main help with exit codes and environment variables
 `;
 
 // ============================================================================
@@ -77,6 +102,7 @@ export function configCommand(): Command {
     .option('--output <file>', 'Write template to file (for --template)')
     .addHelpText('after', DESCRIPTION)
     .addHelpText('after', EXAMPLES)
+    .addHelpText('after', OUTPUT)
     .addHelpText('after', SEE_ALSO)
     .action(async (options, command) => {
       const globalOpts = command.optsWithGlobals();
diff --git a/src/commands/deps.ts b/src/commands/deps.ts
index b06b742..7f4d762 100644
--- a/src/commands/deps.ts
+++ b/src/commands/deps.ts
@@ -55,10 +55,35 @@ EXAMPLES:
       $ mdite deps docs/orphan.md --outgoing && echo "Has dependencies"
 `;
 
+const OUTPUT = `
+OUTPUT:
+  - Data to stdout (pipeable): Tree structure, list of files, or JSON data
+  - Messages to stderr (suppressible): Progress messages, errors, summaries
+  - Quiet mode (--quiet): Suppresses stderr progress, keeps stdout data
+  - Format options (--format):
+      • tree: Hierarchical view with indentation and branch characters
+      • list: One file per line (perfect for piping to grep, xargs, etc.)
+      • json: Structured data with stats, incoming, outgoing arrays
+  - Color handling: Auto-disabled for JSON and when piped, respects NO_COLOR/FORCE_COLOR
+  - Exit codes: 0=success, 1=file not found, 2=invalid arguments, 130=interrupted
+  - TTY detection: Colors auto-disable when piped to other tools (grep, jq, less)
+  - Error output: Errors go to stderr, never mixed with data on stdout
+  - Pipe-friendly: Works with grep, jq, awk, xargs - clean stdout for processing
+  - JSON structure: {file, stats, incoming[], outgoing[], cycles[]} for programmatic use
+`;
+
 const SEE_ALSO = `
 SEE ALSO:
-  mdite lint    Validate all links
-  mdite files   List files in graph
+  Core workflow:
+    mdite lint               Validate all links in dependency graph
+    mdite files              List files in graph with filtering options
+
+  Configuration:
+    mdite config             View current configuration
+    mdite init               Create config file
+
+  Global:
+    mdite --help             Main help with exit codes and environment variables
 `;
 
 // ============================================================================
@@ -81,6 +106,7 @@ export function depsCommand(): Command {
     .option('--respect-gitignore', 'Respect .gitignore patterns')
     .option('--no-exclude-hidden', "Don't exclude hidden directories")
     .addHelpText('after', EXAMPLES)
+    .addHelpText('after', OUTPUT)
     .addHelpText('after', SEE_ALSO)
     .action(async (file: string, options, command) => {
       const globalOpts = command.optsWithGlobals();
diff --git a/src/commands/files.ts b/src/commands/files.ts
index 8e91862..f0dea79 100644
--- a/src/commands/files.ts
+++ b/src/commands/files.ts
@@ -78,14 +78,38 @@ EXAMPLES:
       $ mdite files --format json | jq '.[] | select(.depth > 3)'
 `;
 
+const OUTPUT = `
+OUTPUT:
+  - Data to stdout (pipeable): File paths (one per line) or JSON array
+  - Messages to stderr (suppressible): Progress messages, errors, file counts
+  - Quiet mode (--quiet): Suppresses stderr messages, keeps only file paths on stdout
+  - Format options (--format):
+      • list: One file path per line (default, perfect for piping)
+      • json: Array of objects with {file, depth, orphan} metadata
+  - Path format: Relative paths by default, use --absolute for full paths
+  - Separator: Newline by default, use --print0 for null-separated (xargs -0)
+  - Color handling: Never uses colors (file paths must be parseable)
+  - Exit codes: 0=success, 1=error, 2=invalid arguments, 130=interrupted
+  - TTY detection: Output always pipe-friendly regardless of terminal
+  - Sorting: --sort alpha/depth/incoming/outgoing controls output order
+  - Frontmatter queries: JMESPath syntax for powerful metadata filtering
+`;
+
 const SEE_ALSO = `
 SEE ALSO:
-  mdite cat     Output file content
-  mdite deps    Analyze dependencies
-  mdite lint    Validate documentation
+  Core workflow:
+    mdite lint               Validate documentation structure
+    mdite deps               Analyze file dependencies
+
+  Configuration:
+    mdite config             View current configuration
+    mdite init               Create config file
+
+  Global:
+    mdite --help             Main help with exit codes and environment variables
 
-  JMESPath query syntax:
-      https://jmespath.org/
+  External:
+    JMESPath query syntax    https://jmespath.org/ (for --frontmatter queries)
 `;
 
 // ============================================================================
@@ -116,6 +140,7 @@ export function filesCommand(): Command {
     .option('--respect-gitignore', 'Respect .gitignore patterns')
     .option('--no-exclude-hidden', "Don't exclude hidden directories")
     .addHelpText('after', EXAMPLES)
+    .addHelpText('after', OUTPUT)
     .addHelpText('after', SEE_ALSO)
     .action(async (options, command) => {
       const globalOpts = command.optsWithGlobals();
diff --git a/src/commands/init.ts b/src/commands/init.ts
index 7b4712c..f700697 100644
--- a/src/commands/init.ts
+++ b/src/commands/init.ts
@@ -27,19 +27,52 @@ DESCRIPTION:
 
 const EXAMPLES = `
 EXAMPLES:
-  Create default config file:
+  Create default config file (mdite.config.js):
       $ mdite init
 
-  Create config with custom path:
+  Create JSON config:
       $ mdite init --config .mditerc.json
 
-  View current configuration:
+  Create YAML config:
+      $ mdite init --config .mditerc.yaml
+
+  Create config in package.json (manual edit required):
+      $ mdite init --config mdite.config.js
+      # Then move config to package.json "mdite": {} section
+
+  Initialize config in monorepo workspace root:
+      $ cd workspace-root
+      $ mdite init
+
+  Override global config with project-specific settings:
+      $ mdite init
+      # Edit mdite.config.js to customize rules, depth, excludes
+
+  CI/CD configuration (restrictive rules):
+      $ mdite init
+      # Edit rules to: orphan-files: 'error', dead-link: 'error'
+
+  Verify config creation and view merged settings:
+      $ mdite init
       $ mdite config
+
+  Development workflow (create, customize, test):
+      $ mdite init
+      $ vim mdite.config.js  # Edit entrypoint, depth, excludes
+      $ mdite lint           # Test configuration
 `;
 
 const SEE_ALSO = `
 SEE ALSO:
-  mdite config  View current configuration
+  Configuration:
+    mdite config --schema    Show all available config options
+    mdite config             View current merged configuration
+
+  Core workflow:
+    mdite lint               Validate documentation with your config
+
+  Global:
+    mdite --help             Main help with exit codes and environment variables
 `;
 
 // ============================================================================
diff --git a/src/commands/lint.ts b/src/commands/lint.ts
index 023d657..01bcf61 100644
--- a/src/commands/lint.ts
+++ b/src/commands/lint.ts
@@ -61,21 +61,33 @@ EXAMPLES:
 
 const OUTPUT = `
 OUTPUT:
-  Text format (default):
-    - Data (errors/warnings) → stdout (pipeable)
-    - Messages (progress/info) → stderr (suppressible with --quiet)
-
-  JSON format:
-    - Structured JSON → stdout
-    - Errors → stderr
-    - Colors auto-disabled
+  - Data to stdout (pipeable): Validation errors and warnings
+  - Messages to stderr (suppressible): Progress updates, summaries, headers
+  - Quiet mode (--quiet): Suppresses stderr messages, keeps only errors on stdout
+  - Format options (--format):
+      • text: Human-readable with colors, file:line:col format (default)
+      • json: Structured array [{file, line, column, severity, rule, message, endColumn?, literal?, resolvedPath?}]
+      • grep: Tab-delimited with 8 fields: file, line, column, endColumn, severity, rule, literal, resolvedPath
+  - Color handling: Auto-disabled for JSON/grep and when piped, respects NO_COLOR/FORCE_COLOR
+  - Exit codes: 0=no errors, 1=validation errors, 2=invalid arguments, 130=interrupted
+  - TTY detection: Colors auto-disable when piped to other tools (grep, jq, less)
+  - Error output: Validation errors go to stdout, system errors to stderr
+  - Pipe-friendly: Works with grep, jq, awk, cut - clean stdout for processing
+  - Grep format: Tab-delimited for easy extraction with cut/awk, includes literal link text
 `;
 
 const SEE_ALSO = `
 SEE ALSO:
-  mdite deps    Analyze dependencies before refactoring
-  mdite files   List files in documentation graph
-  mdite config  View configuration
+  Core workflow:
+    mdite deps               Analyze dependencies before refactoring
+    mdite files              List files in documentation graph
+
+  Configuration:
+    mdite config             View current configuration
+    mdite init               Create config file
+
+  Global:
+    mdite --help             Main help with exit codes and environment variables
 `;
 
 // ============================================================================
diff --git a/src/utils/help-text.ts b/src/utils/help-text.ts
index bbca826..5b3ca78 100644
--- a/src/utils/help-text.ts
+++ b/src/utils/help-text.ts
@@ -18,9 +18,20 @@ EXIT CODES:
 
 export const ENVIRONMENT_VARS = `
 ENVIRONMENT:
-  NO_COLOR        Disable colored output (respects no-color.org standard)
-  FORCE_COLOR     Force colored output even when piped
-  CI=true         Auto-disable colors in CI environments
+  NO_COLOR
+      Disable colored output globally (respects no-color.org standard).
+      When set to any value, colors are disabled regardless of TTY detection.
+      Equivalent to --no-colors flag. Takes precedence over FORCE_COLOR.
+
+  FORCE_COLOR
+      Force colored output even when piped to other tools.
+      Useful for debugging or when piping to color-aware tools.
+      Equivalent to --colors flag. Overridden by NO_COLOR.
+
+  CI=true
+      Automatically disables colors in CI/CD environments.
+      Prevents color escape codes in build logs and CI output.
+      Can be overridden with FORCE_COLOR if needed.
 `;
 
 export const CONFIG_PRECEDENCE = `
diff --git a/tests/integration/cli-help.test.ts b/tests/integration/cli-help.test.ts
index 21ae7b1..2ecb12a 100644
--- a/tests/integration/cli-help.test.ts
+++ b/tests/integration/cli-help.test.ts
@@ -126,7 +126,8 @@ describe('CLI Help Enhancement', () => {
     it('should include see also with JMESPath link', () => {
       const help = getHelp(['files', '--help']);
       expect(help).toContain('SEE ALSO:');
-      expect(help).toContain('JMESPath query syntax:');
+      expect(help).toContain('External:');
+      expect(help).toContain('JMESPath query syntax');
       expect(help).toContain('https://jmespath.org/');
     });
   });

From aec6baed8d43daee35772258c8d71c76d5b76209 Mon Sep 17 00:00:00 2001
From: Richard Adleta <radleta@gmail.com>
Date: Tue, 4 Nov 2025 14:24:08 +0000
Subject: [PATCH 4/7] chore: remove redundant .npmignore (files field takes
 precedence)

The .npmignore file was redundant because the 'files' field in package.json
takes absolute precedence according to npm documentation. When a 'files' field
is present, .npmignore is completely ignored.

This change:
- Eliminates technical debt and maintainer confusion
- Establishes package.json 'files' as single source of truth
- No impact on package contents (verified with npm pack --dry-run)

Package size remains: 87.6 kB
Files included remain unchanged: dist/src/, README.md, CHANGELOG.md, LICENSE

Resolves: scratch/release-ready-20251104-140123/ISSUE-npmignore-conflicts-with-files.md
---
 .npmignore | 59 ------------------------------------------------------
 1 file changed, 59 deletions(-)
 delete mode 100644 .npmignore

diff --git a/.npmignore b/.npmignore
deleted file mode 100644
index 31f86bf..0000000
--- a/.npmignore
+++ /dev/null
@@ -1,59 +0,0 @@
-# Source files (we ship compiled dist/)
-src/
-tests/
-dist/tests/
-scripts/
-
-# Config files
-tsconfig.json
-vitest.config.ts
-eslint.config.js
-.prettierrc
-
-# Development
-.github/
-.githooks/
-.git/
-.gitignore
-.gitattributes
-coverage/
-scratch/
-*.test.ts
-*.test.js
-*.spec.ts
-*.spec.js
-
-# Documentation (keep README, CHANGELOG, LICENSE)
-docs/
-*.md
-!README.md
-!CHANGELOG.md
-
-# Build artifacts
-*.tsbuildinfo
-.DS_Store
-Thumbs.db
-.vscode/
-.idea/
-
-# Logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-
-# Dependencies
-node_modules/
-
-# Environment
-.env
-.env.local
-.env.*.local
-
-# Temporary
-tmp/
-temp/
-*.tmp
-
-# CI/CD and iteration workspaces
-claude-iterate/

From 5808aab582f76abf82013782bf3d5b3d7df708f4 Mon Sep 17 00:00:00 2001
From: Richard Adleta <radleta@gmail.com>
Date: Tue, 4 Nov 2025 14:44:44 +0000
Subject: [PATCH 5/7] docs(changelog): prepare v1.1.0 release notes

- Move unreleased changes to v1.1.0 section dated 2025-11-04
- Reorganize from "Enhanced" to proper "Added" section
- Add grep format as headline feature (new machine-parseable output)
- Document literal path error reporting enhancements
- Include CLI help system improvements across all commands
- Add Fixed section for CI/CD branch restriction
- Add Changed section for .npmignore removal
- Comprehensive release notes covering all 5 commits since v1.0.2
---
 CHANGELOG.md | 52 +++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 45 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f32e550..cf49b05 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,15 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Enhanced
+### Added
+
+- **Grep format for lint output**: New `--format grep` option for machine-parseable, tab-delimited output
+  - Field order: file, line, column, endColumn, severity, ruleId, literal, resolvedPath
+  - Enables automated link fixing with standard Unix tools (cut, awk, sed)
+  - Example: `mdite lint --format grep | cut -d$'\t' -f7` extracts all literal link texts
+  - Colors auto-disabled for machine readability
+  - Fully backward compatible with existing text and JSON formats
 
-- **Literal path error reporting**: mdite lint now reports literal link text from source files alongside resolved paths
+- **Literal path error reporting**: mdite lint now captures and reports literal link text from source files
+  - Extended `LintError` interface with three optional fields: `literal`, `endColumn`, `resolvedPath`
   - Text format: Shows `'literal' resolves to 'resolved'` inline for clear understanding
-  - JSON format: Includes `literal`, `endColumn` fields (flat structure, backward compatible)
-  - New grep format: `--format grep` outputs tab-delimited for Unix tool parsing (cut/awk/sed)
-  - Enables automated fix scripts with grep/sed without reverse-engineering paths
-  - Example: `mdite lint --format grep | cut -d$'\t' -f7` extracts all literal paths
-  - All formats maintain backward compatibility with existing parsers
+  - JSON format: Includes all three new fields (flat structure, backward compatible)
+  - LinkValidator captures literal text and position from markdown AST during validation
+  - Enables automated fix scripts without reverse-engineering paths from error messages
+  - Added new workflow section to README.md: "Automated Link Fixing with Grep Format"
+  - Added 11 new integration tests in `tests/integration/lint-literal-paths.test.ts`
+
+- **Enhanced CLI help system**: Comprehensive help documentation following Unix CLI best practices
+  - Added CLI Help Text Standards section to CONTRIBUTING.md (213 lines)
+    - Documents hybrid architecture (shared vs command-specific help)
+    - Provides templates for DESCRIPTION, EXAMPLES, OUTPUT, SEE_ALSO sections
+    - Includes formatting guidelines and pre-merge checklist
+    - References industry patterns from git, docker, npm, and ripgrep
+  - Enhanced help text across all 6 commands with detailed OUTPUT sections (8-10 bullets each)
+  - Improved SEE_ALSO organization using three tiers: Core workflow, Configuration, Global
+  - Expanded ENVIRONMENT_VARS in shared help with detailed descriptions
+  - Added context for NO_COLOR, FORCE_COLOR, CI usage and precedence
+  - Updated integration tests to verify new help structure
+  - Modified 9 files with 403 insertions, maintaining 100% test coverage
+
+### Fixed
+
+- **CI/CD**: Restricted release workflow to main branch only
+  - Added branch filter to workflow trigger (only main branch)
+  - Added verification step to check tag is on main branch
+  - Fetches full git history for branch verification
+  - Prevents accidental releases from feature/develop branches
+
+### Changed
+
+- **Package publishing**: Removed redundant .npmignore file
+  - The .npmignore file was redundant because 'files' field in package.json takes absolute precedence per npm documentation
+  - Establishes package.json 'files' field as single source of truth
+  - Eliminates technical debt and maintainer confusion
+  - No impact on package contents (verified with `npm pack --dry-run`)
+  - Package size remains: 87.6 kB with unchanged file list
 
 ## [1.0.2] - 2025-10-24
 

From 33c89bbd452afc1eb8d66fab14ef5e4d3deaf0ba Mon Sep 17 00:00:00 2001
From: Richard Adleta <radleta@gmail.com>
Date: Tue, 4 Nov 2025 15:13:23 +0000
Subject: [PATCH 6/7] test(lint): fix TypeScript type warnings in literal path
 tests

- Replace 5 instances of `any` type with proper `LintError` type
- Add import for LintError interface
- Improves type safety and eliminates ESLint warnings
---
 tests/integration/lint-literal-paths.test.ts | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/tests/integration/lint-literal-paths.test.ts b/tests/integration/lint-literal-paths.test.ts
index 59b1f37..85a2a3e 100644
--- a/tests/integration/lint-literal-paths.test.ts
+++ b/tests/integration/lint-literal-paths.test.ts
@@ -3,6 +3,7 @@ import { createTestDir, writeTestFile } from '../setup.js';
 import { join } from 'path';
 import * as fs from 'fs/promises';
 import * as path from 'path';
+import type { LintError } from '../../src/types/errors.js';
 
 describe('lint command - literal path reporting (integration)', () => {
   let testDir: string;
@@ -88,7 +89,7 @@ describe('lint command - literal path reporting (integration)', () => {
       expect(Array.isArray(errors)).toBe(true);
       expect(errors.length).toBeGreaterThan(0);
 
-      const deadLinkError = errors.find((e: any) => e.rule === 'dead-link');
+      const deadLinkError = errors.find((e: LintError) => e.rule === 'dead-link');
       expect(deadLinkError).toBeDefined();
       expect(deadLinkError.literal).toBe('./missing.md');
       expect(deadLinkError.endColumn).toBeDefined();
@@ -101,7 +102,7 @@ describe('lint command - literal path reporting (integration)', () => {
       const result = runCli(['lint', '--format', 'json']);
 
       const errors = JSON.parse(result.stdout);
-      const error = errors.find((e: any) => e.rule === 'dead-link');
+      const error = errors.find((e: LintError) => e.rule === 'dead-link');
 
       // Verify flat structure (all fields at top level)
       expect(error).toHaveProperty('literal');
@@ -221,10 +222,10 @@ describe('lint command - literal path reporting (integration)', () => {
 
       expect(result.exitCode).toBe(1);
       const errors = JSON.parse(result.stdout);
-      const deadLinks = errors.filter((e: any) => e.rule === 'dead-link');
+      const deadLinks = errors.filter((e: LintError) => e.rule === 'dead-link');
       expect(deadLinks.length).toBe(3);
 
-      deadLinks.forEach((error: any) => {
+      deadLinks.forEach((error: LintError) => {
         expect(error.literal).toBeDefined();
         expect(error.literal).toMatch(/\.\/missing\d\.md/);
         expect(error.endColumn).toBeGreaterThan(error.column);
@@ -238,7 +239,7 @@ describe('lint command - literal path reporting (integration)', () => {
 
       expect(result.exitCode).toBe(1);
       const errors = JSON.parse(result.stdout);
-      const deadLinkError = errors.find((e: any) => e.rule === 'dead-link');
+      const deadLinkError = errors.find((e: LintError) => e.rule === 'dead-link');
 
       expect(deadLinkError).toBeDefined();
       expect(deadLinkError.literal).toContain('./missing.md');

From adacae367cc461cc18f67340376d5116cb6afd0e Mon Sep 17 00:00:00 2001
From: Richard Adleta <radleta@gmail.com>
Date: Tue, 4 Nov 2025 15:17:22 +0000
Subject: [PATCH 7/7] 1.1.0

---
 CHANGELOG.md      | 2 ++
 package-lock.json | 4 ++--
 package.json      | 2 +-
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cf49b05..01a672d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2025-11-04
+
 ### Added
 
 - **Grep format for lint output**: New `--format grep` option for machine-parseable, tab-delimited output
diff --git a/package-lock.json b/package-lock.json
index 95468d6..d9227a4 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "mdite",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "mdite",
-      "version": "1.0.2",
+      "version": "1.1.0",
       "license": "MIT",
       "dependencies": {
         "chalk": "^5.4.1",
diff --git a/package.json b/package.json
index 42f4c0b..ae64200 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "mdite",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Markdown documentation toolkit - work with documentation as a connected system: validate, analyze dependencies, search, and output",
   "type": "module",
   "main": "dist/src/index.js",