parse_file_mentions

Extract @file mentions and return the text with resolved file paths.

Parses @file mentions from the input text and resolves them to absolute file paths. Files that do not exist or cannot be resolved are excluded with a warning printed to the console.

Email addresses (e.g., user@example.com) are automatically excluded by detecting email-like characters before the @ symbol.

Backslash-escaped spaces in paths (e.g., @my\ folder/file.txt) are unescaped before resolution. Tilde paths (e.g., @~/file.txt) are expanded via Path.expanduser(). Only regular files are returned; directories are excluded.

This function does not raise exceptions; invalid paths are handled internally with a console warning.