feat(skills): update media-delivery

media-delivery/SKILL.md

@@ -502,6 +502,11 @@ If MEDIA delivery fails, check in this order:
    ```
    ```
    Helps if cache dirs were created mid-session
    Helps if cache dirs were created mid-session
 
 
+8. **Check workspace security policy**: 
+   - Markdown links only work for files in `~/.hermes/workspace/`
+   - Files in `~/.hermes/cache/` will fail with "File is outside the session"
+   - See: `references/workspace-security-policy.md` for details
+
 ---
 ---
 
 
 ## Related Skills
 ## Related Skills

media-delivery/references/macos-workspace-security-restriction.md → media-delivery/references/workspace-security-policy.md

-# macOS File Delivery — Workspace Security Restriction
+# Hermes Workspace Security Policy — File Delivery Restrictions
 
 
 > **Source**: Conversation 2026-07-22 (session `mrvqi0lwbwg569`)  
 > **Source**: Conversation 2026-07-22 (session `mrvqi0lwbwg569`)  
 > **Symptom**: Files in `~/.hermes/cache/documents/` cannot be accessed via Markdown links, even with angle brackets
 > **Symptom**: Files in `~/.hermes/cache/documents/` cannot be accessed via Markdown links, even with angle brackets
 
 
 ## Problem Description
 ## Problem Description
 
 
-When attempting to send files with long Chinese filenames from `~/.hermes/cache/documents/` directory on macOS:
+When attempting to send files with long Chinese filenames from `~/.hermes/cache/documents/` directory:
 
 
 1. File exists and is readable: `ls -la` confirms it
 1. File exists and is readable: `ls -la` confirms it
 2. File is in an "allowed" cache directory
 2. File is in an "allowed" cache directory
@@ -14,11 +14,14 @@ When attempting to send files with long Chinese filenames from `~/.hermes/cache/
 
 
 ## Root Cause
 ## Root Cause
 
 
-Hermes security policy enforces that files must be within the **session workspace** (`~/.hermes/workspace/`) or explicitly allowed directories. Even though `~/.hermes/cache/` directories are listed as "safe roots" for MEDIA protocol, the **Markdown link delivery** path has stricter restrictions that only allow files within the active workspace.
+**This is a Hermes security policy restriction, NOT a platform-specific issue.**
 
 
-This is a **platform-specific behavior on macOS** where:
-- MEDIA protocol may work for some file types in cache dirs
-- Markdown links **always require** files to be in `~/.hermes/workspace/`
+Hermes enforces that files must be within the **session workspace** (`~/.hermes/workspace/`) for Markdown link delivery. Even though `~/.hermes/cache/` directories are listed as "safe roots" for MEDIA protocol, the **Markdown link delivery** path has stricter restrictions that only allow files within the active workspace.
+
+**Applies to all deployment scenarios:**
+- Hermes running locally on macOS/Linux/Windows
+- Hermes running on remote server accessed via Gateway
+- Cross-platform access (macOS client → Linux server, etc.)
 
 
 ## Reproduction Steps
 ## Reproduction Steps
 
 
@@ -57,10 +60,7 @@ Then send:
 When file cannot be moved to workspace (e.g., large files, read-only locations):
 When file cannot be moved to workspace (e.g., large files, read-only locations):
 
 
 ```bash
 ```bash
-# Encode (macOS)
-base64 -i "/path/to/文件.md"
-
-# Encode (Linux)
+# Encode (macOS/Linux)
 base64 "/path/to/文件.md"
 base64 "/path/to/文件.md"
 ```
 ```
 
 
@@ -108,16 +108,17 @@ When encountering `File is outside the session and Hermes workspaces`:
 
 
 4. **If copy fails or not desirable, use base64**:
 4. **If copy fails or not desirable, use base64**:
    ```bash
    ```bash
-   base64 -i "/path/to/file"
+   base64 "/path/to/file"
    ```
    ```
 
 
-## Platform Differences
+## Platform Independence
 
 
-| Platform | Cache Dir Links | Workspace Links | Base64 |
-|----------|----------------|-----------------|--------|
-| macOS    | ❌ Fails       | ✅ Works        | ✅ Works |
-| Linux    | ⚠️ Sometimes   | ✅ Works        | ✅ Works |
-| Windows  | ⚠️ Sometimes   | ✅ Works        | ✅ Works |
+| Hermes Deployment | Markdown Cache Links | Markdown Workspace Links | Base64 |
+|-------------------|---------------------|-------------------------|--------|
+| Local macOS       | ❌ Fails            | ✅ Works                | ✅ Works |
+| Local Linux       | ❌ Fails            | ✅ Works                | ✅ Works |
+| Local Windows     | ❌ Fails            | ✅ Works                | ✅ Works |
+| Remote (any)      | ❌ Fails            | ✅ Works                | ✅ Works |
 
 
 ## Best Practices
 ## Best Practices
 
 
@@ -125,18 +126,18 @@ When encountering `File is outside the session and Hermes workspaces`:
 2. **For Chinese filenames, always use angle brackets**: `](</path/文件.md>)`
 2. **For Chinese filenames, always use angle brackets**: `](</path/文件.md>)`
 3. **When in doubt, use base64** — it works everywhere and bypasses all path restrictions
 3. **When in doubt, use base64** — it works everywhere and bypasses all path restrictions
 4. **For large files**, consider base64 or direct content display
 4. **For large files**, consider base64 or direct content display
-5. **Test file delivery early** in a session to confirm platform behavior
+5. **Test file delivery early** in a session to confirm behavior
 
 
 ## Related Issues
 ## Related Issues
 
 
-- Windows path format: Use `C:/...` not `/c/...`
+- Windows path format: Use `C:/...` not `/c/...` (see `windows-media-path-debugging.md`)
 - Chinese filename parsing: Always use angle brackets
 - Chinese filename parsing: Always use angle brackets
-- MEDIA protocol initialization: May require gateway restart on macOS
+- MEDIA protocol initialization: May require gateway restart (see `macos-gateway-media-issue.md`)
 - Cache directory restrictions: Not all "safe roots" work for Markdown links
 - Cache directory restrictions: Not all "safe roots" work for Markdown links
 
 
 ## Key Takeaway
 ## Key Takeaway
 
 
-**On macOS, Markdown file links only work for files in `~/.hermes/workspace/`. Files in `~/.hermes/cache/` directories will fail with "File is outside the session and Hermes workspaces" error.**
+**Hermes security policy restricts Markdown file links to `~/.hermes/workspace/` only. Files in `~/.hermes/cache/` directories will fail with "File is outside the session and Hermes workspaces" error, regardless of deployment platform.**
 
 
 Use one of these alternatives:
 Use one of these alternatives:
 1. Copy file to workspace (preferred for small/medium files)
 1. Copy file to workspace (preferred for small/medium files)