From 7973620b08975cc15aae695a5b529ecd621ab7cc Mon Sep 17 00:00:00 2001
From: Cameron Cooke <web@cameroncooke.com>
Date: Thu, 7 May 2026 20:51:43 +0100
Subject: [PATCH] docs: Document file path render style option

Explain how to configure file artifact text rendering across CLI flags,
configuration, and environment variables.

Clarify that JSON and JSONL output keep the same structured fields.
---
 app/docs/_content/cli.mdx            |  5 +++++
 app/docs/_content/configuration.mdx  |  4 ++++
 app/docs/_content/env-vars.mdx       |  1 +
 app/docs/_content/output-formats.mdx | 10 ++++++++++
 4 files changed, 20 insertions(+)

diff --git a/app/docs/_content/cli.mdx b/app/docs/_content/cli.mdx
index 9e252fa..41e68b0 100644
--- a/app/docs/_content/cli.mdx
+++ b/app/docs/_content/cli.mdx
@@ -49,8 +49,13 @@ xcodebuildmcp simulator build --json '{"scheme":"MyApp","projectPath":"./MyApp.x
 
 # Output format
 xcodebuildmcp simulator list --output json
+
+# File artifact layout in text/raw output
+xcodebuildmcp simulator build --file-path-render-style tree
 ```
 
+`--file-path-render-style list|tree` overrides the text rendering style for file artifacts on one invocation. The default CLI text style is `list`; MCP text defaults to `tree`. JSON and JSONL output are unaffected.
+
 ## Session defaults auto-fill
 
 If your project has `.xcodebuildmcp/config.yaml` with `sessionDefaults` set, the CLI fills matching flags automatically:
diff --git a/app/docs/_content/configuration.mdx b/app/docs/_content/configuration.mdx
index bf4d5cc..16c111a 100644
--- a/app/docs/_content/configuration.mdx
+++ b/app/docs/_content/configuration.mdx
@@ -81,6 +81,9 @@ sessionDefaults:
 # Build settings
 incrementalBuildsEnabled: false
 
+# Text output
+filePathRenderStyle: "list" # "list" or "tree"
+
 # Debugging and telemetry
 debug: false
 sentryDisabled: false
@@ -113,6 +116,7 @@ macosTemplateVersion: "v1.2.3"
 | `sessionDefaultsProfiles` | object | `{}` |
 | `activeSessionDefaultsProfile` | string | `global` |
 | `incrementalBuildsEnabled` | boolean | `false` |
+| `filePathRenderStyle` | `"list" \| "tree"` | CLI text: `"list"`, MCP text: `"tree"` |
 | `debug` | boolean | `false` |
 | `sentryDisabled` | boolean | `false` |
 | `debuggerBackend` | string | `"dap"` |
diff --git a/app/docs/_content/env-vars.mdx b/app/docs/_content/env-vars.mdx
index 4faded8..d9c3c35 100644
--- a/app/docs/_content/env-vars.mdx
+++ b/app/docs/_content/env-vars.mdx
@@ -26,6 +26,7 @@ Set env vars in the `env` field of your MCP client config (for example `mcp_conf
 | `disableSessionDefaults` | `XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS` |
 | `disableXcodeAutoSync` | `XCODEBUILDMCP_DISABLE_XCODE_AUTO_SYNC` |
 | `incrementalBuildsEnabled` | `INCREMENTAL_BUILDS_ENABLED` |
+| `filePathRenderStyle` | `XCODEBUILDMCP_FILE_PATH_RENDER_STYLE` (`list` or `tree`) |
 | `debug` | `XCODEBUILDMCP_DEBUG` |
 | `sentryDisabled` | `XCODEBUILDMCP_SENTRY_DISABLED` |
 | `debuggerBackend` | `XCODEBUILDMCP_DEBUGGER_BACKEND` |
diff --git a/app/docs/_content/output-formats.mdx b/app/docs/_content/output-formats.mdx
index fd35f48..01ac22d 100644
--- a/app/docs/_content/output-formats.mdx
+++ b/app/docs/_content/output-formats.mdx
@@ -50,6 +50,16 @@ Next steps:
 
 Use `text` for normal agent workflows. Agents can read summaries, diagnostics, and next-step commands without needing a JSON parser.
 
+CLI text renders file artifacts as labeled rows under `Files:` by default:
+
+```text
+Files:
+   ├ App Path: ~/Library/Developer/XcodeBuildMCP/.../MyApp.app
+   └ Build Logs: ~/Library/Developer/XcodeBuildMCP/.../build.log
+```
+
+Use `--file-path-render-style tree` for the compact grouped tree used by MCP text responses, or set `filePathRenderStyle: "tree"` / `XCODEBUILDMCP_FILE_PATH_RENDER_STYLE=tree`. This setting only affects human-readable text; `--output json` and `--output jsonl` keep the same structured fields.
+
 ## `--output json`
 
 `json` prints a structured JSON response to stdout after the tool finishes. It does not stream progress. Use it when you need stable fields for scripts or CI.