infocyph · abmmhasan · Sep 24, 2026 · Sep 24, 2026 · Sep 24, 2026 · Sep 24, 2026
diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
@@ -49,7 +49,11 @@ jobs:
       - name: Container execution substrate contract
         run: tests/container-exec-contract.sh
 
-
+      - name: Conversion contracts
+        run: |
+          bash tests/document-convert-contract.sh
+          bash tests/image-convert-contract.sh
+          bash tests/media-convert-contract.sh
 
       - name: Environment contract
         run: tests/env-contract.sh
@@ -117,6 +121,9 @@ jobs:
       - name: Smoke direct provider on minimum Graphify
         run: bash tests/graphify-direct-provider-contract.sh
 
+      - name: Validate document merge round trip on minimum Graphify
+        run: bash tests/graphify-roundtrip-contract.sh
+
       - name: Validate latest Graphify contract
         run: |
           python -m pip install --upgrade "graphifyy[openai]"
@@ -139,6 +146,9 @@ jobs:
       - name: Smoke direct provider on latest Graphify
         run: bash tests/graphify-direct-provider-contract.sh
 
+      - name: Validate document merge round trip on latest Graphify
+        run: bash tests/graphify-roundtrip-contract.sh
+
 
   compose:
     name: Compose contract
@@ -178,6 +188,18 @@ jobs:
       - name: Validate published compatibility images
         run: tests/published-images.sh
 
+      - name: Smoke host document conversion
+        run: |
+          set -euo pipefail
+          tmp="$(mktemp -d)"
+          trap 'rm -rf "$tmp"' EXIT
+          mkdir -p "$tmp/input" "$tmp/output"
+          printf '# LocalDevStack conversion\n\nPandoc-backed host document.\n' >"$tmp/input/source.md"
+          ./lds convert docs "$tmp/input/source.md" "$tmp/output/source.html" --standalone
+          grep -Fq '<h1' "$tmp/output/source.html"
+          formats="$(./lds convert docs --list-input-formats)"
+          grep -qx markdown <<<"$formats"
+
   windows-bridge:
     name: Windows bridge
     runs-on: windows-latest

diff --git a/README.md b/README.md
@@ -224,6 +224,61 @@ lds es ...
 
 See `docs/guides/databases-and-clients.rst` for the profile/client map.
 
+## Tools and Toolset utilities
+
+The Tools image also provides developer utilities through an explicit workspace-aware
+runner:
+
+```bash
+lds tools list
+lds tools gitx status
+lds tools gitx worklog HEAD~20..HEAD
+lds tools sqlitex --db app.db tables
+cat app.log | lds tools chromacat --log
+lds tools netx route show
+lds tools ffprobe media.mkv
+lds tools mediainfo media.mkv
+lds tools soxi recording.wav
+lds tools mkvinfo media.mkv
+lds tools jq --version
+lds tools shellcheck script.sh
+lds tools ui
+```
+
+`lds tools <tool>` starts a temporary Tools container with the current host directory at
+`/workspace`, shares the running server-tools network/volumes, preserves stdin/TTY, and
+inherits the active LDS AI/Git runtime settings. Because `server-tools` owns the Docker
+socket and trusted control-plane/secret mounts, this runner is a privileged workstation
+context—not a sandbox—and should be used only with trusted commands from the Tools image.
+Use `lds tools run <tool> ...` when a tool name collides with an LDS `tools` subcommand.
+The older `tools sh/exec/file` forms continue to target the long-running control-plane
+container.
+
+## File conversion
+
+Pandoc is available from the Tools image without installing it on the host or starting
+the LocalDevStack services:
+
+```bash
+lds convert docs README.md README.html
+lds convert docs docs/guide.rst guide.docx --toc
+lds convert docs report.docx report.md --wrap=none
+lds convert docs book.md book.epub --toc
+lds convert docs --list-input-formats
+lds convert docs --list-output-formats
+lds convert image photo.jpg photo.webp -- -quality 82 -strip
+lds convert image animation.gif animation.webp
+lds convert image --formats
+lds convert audio recording.wav recording.mp3
+lds convert audio recording.wav recording.ogg -- -c:a libopus -b:a 128k
+lds convert video recording.mov recording.mp4
+lds convert video recording.mkv recording.webm -- -c:v libvpx-vp9 -crf 32 -b:v 0
+```
+
+Documents use Pandoc, images use ImageMagick, and audio/video use FFmpeg. The input mount is read-only and only the output mount is writable. The
+short-lived converter receives no Docker socket or LocalDevStack networks. Existing
+outputs require `--force`. PDF generation additionally depends on a PDF engine; the base
+Tools image ships Pandoc itself, not a TeX/PDF rendering stack.
 ## Optional local AI
 
 Enable the `ai` profile through `lds setup profile`.
@@ -286,7 +341,7 @@ lds graphify ./your-project --mode deep
 
 Nginx owns the loopback-only native route `127.0.0.1:11434 -> nginx:11434 -> llm:11434`. Provider containers do not publish host ports.
 
-`lds graphify` keeps the host Graphify CLI on `http://llm.localhost:11434/v1`, with no Graphify proxy service or Python adapter. When the Tools image supports `docstruct`, `.md/.rst/.yaml/.yml/.json/.toml/.ini/.cfg` files are extracted mechanically, optionally reviewed in bounded AI chunks, validated as a Graphify fragment, and merged into a reserved document layer; Graphify continues to own code ASTs and unsupported semantic formats. `LDS_GRAPHIFY_DOCSTRUCT=auto|on|off` and `LDS_GRAPHIFY_DOC_REVIEW=auto|on|off` control the handoff. Explicit `--code-only` remains code-only.
+`lds graphify` keeps the host Graphify CLI on `http://llm.localhost:11434/v1`, with no Graphify proxy service or Python adapter. When the Tools image supports `docstruct`, `.md/.rst/.yaml/.yml/.json/.toml/.ini/.cfg` files are extracted mechanically, optionally reviewed in bounded AI chunks, validated as a Graphify fragment, and merged into a staged reserved document layer. Before publication, LocalDevStack runs that staged graph through an isolated LLM-free `graphify cluster-only --no-label --no-viz` round trip and publishes only Graphify's canonical output; Graphify continues to own code ASTs and unsupported semantic formats. Document review retries one malformed structured response once before deterministic fallback. `LDS_GRAPHIFY_DOCSTRUCT=auto|on|off` and `LDS_GRAPHIFY_DOC_REVIEW=auto|on|off` control the handoff. Explicit `--code-only` remains code-only.
 
 The built-in Compose layout keeps both provider definitions in `docker/compose/companion.yaml`, but runtime-generated profile selectors enable exactly one. NVIDIA/ROCm hardware augmentation is generated ephemerally under `docker/.runtime/`; FastFlow's `/dev/accel/accel0` + memlock contract lives in its tracked service definition.
 

diff --git a/bin/tool-runner b/bin/tool-runner
@@ -63,7 +63,38 @@ server_tools_image() {
 server_tools_env_value() {
   local key="${1:?}"
   "$(bin_path docker)" inspect -f '{{range .Config.Env}}{{println .}}{{end}}' "$SERVER_TOOLS_CONTAINER" 2>/dev/null \
-    | awk -F= -v k="$key" '$1==k { sub(/^[^=]*=/, ""); print; exit }'
+    | awk -F= -v k="$key" '
+        $1 == k && !found {
+          sub(/^[^=]*=/, "")
+          print
+          found=1
+        }
+        END { if (!found) exit 1 }
+      '
+}
+
+stdin_has_data() {
+  [[ -p /dev/stdin || -f /dev/stdin ]]
+}
+
+append_server_tools_env() {
+  local key value
+  local -n target="${1:?}"
+
+  for key in \
+    TZ USERNAME GIT_USER_NAME GIT_USER_EMAIL GIT_CREDENTIAL_MODE \
+    LDS_AI_ENABLED LDS_AI_RUNTIME LDS_AI_MODEL LDS_AI_THINK \
+    LDS_AI_CONNECT_TIMEOUT LDS_AI_PREFLIGHT_TIMEOUT LDS_AI_TIMEOUT \
+    LDS_AI_AVAILABILITY_TTL LDS_AI_MAX_CONTEXT_BYTES \
+    LDS_AI_MAX_REQUEST_BYTES LDS_AI_MAX_RESPONSE_BYTES
+  do
+    value="$(server_tools_env_value "$key" || true)"
+    if [[ -n "$value" ]]; then
+      target+=(-e "$key=$value")
+    fi
+  done
+
+  return 0
 }
 
 resolve_workspace() {
@@ -100,15 +131,13 @@ main() {
   server_tools_running || die "$SERVER_TOOLS_CONTAINER is not running"
   server_tools_has "$cmd" || die "command '$cmd' not found in $SERVER_TOOLS_CONTAINER"
 
-  local image workspace tz username home_dir
+  local image workspace home_dir
   image="$(server_tools_image)" || die "unable to inspect $SERVER_TOOLS_CONTAINER image"
   [[ -n "$image" ]] || die "unable to resolve $SERVER_TOOLS_CONTAINER image"
 
   workspace="$(resolve_workspace)"
   [[ -n "$workspace" ]] || die "unable to resolve workspace"
 
-  tz="$(server_tools_env_value TZ || true)"
-  username="$(server_tools_env_value USERNAME || true)"
   home_dir="/home/root"
 
   local -a flags envs
@@ -120,14 +149,15 @@ main() {
     -e TERM="${TERM:-xterm-256color}"
   )
 
-  [[ -n "$tz" ]] && envs+=(-e TZ="$tz")
-  [[ -n "$username" ]] && envs+=(-e USERNAME="$username")
+  append_server_tools_env envs
   [[ -n "${COLORTERM:-}" ]] && envs+=(-e COLORTERM="$COLORTERM")
   [[ -n "${NO_COLOR:-}" ]] && envs+=(-e NO_COLOR="$NO_COLOR")
   [[ -n "${CLICOLOR_FORCE:-}" ]] && envs+=(-e CLICOLOR_FORCE="$CLICOLOR_FORCE")
   [[ -n "${FORCE_COLOR:-}" ]] && envs+=(-e FORCE_COLOR="$FORCE_COLOR")
 
-  [[ -t 0 ]] && flags+=(-i)
+  if [[ -t 0 ]] || stdin_has_data; then
+    flags+=(-i)
+  fi
   [[ -t 1 ]] && flags+=(-t)
 
   if [[ -n "${MSYSTEM:-}${CYGWIN:-}" ]]; then

diff --git a/docs/guides/conversion.rst b/docs/guides/conversion.rst
@@ -0,0 +1,131 @@
+Conversion
+==========
+
+LocalDevStack exposes Pandoc from the Tools image as a host-file conversion command.
+Pandoc does not need to be installed on the workstation and the main LocalDevStack
+services do not need to be running.
+
+Basic Usage
+-----------
+
+Convert one host file to another::
+
+   lds convert docs README.md README.html
+   lds convert docs docs/guide.rst guide.docx
+   lds convert docs report.docx report.md
+   lds convert docs book.md book.epub --toc
+
+The first path is mounted read-only. Only the output directory is mounted writable.
+The short-lived conversion container receives no Docker socket, project volumes, or
+LocalDevStack networks.
+
+Pandoc Options
+--------------
+
+Arguments after the output path are passed to Pandoc without shell flattening::
+
+   lds convert docs README.md README.html --toc --standalone
+   lds convert docs report.docx report.md --wrap=none
+   lds convert docs book.md book.epub --metadata title="Developer Guide"
+
+An optional ``--`` separator is accepted::
+
+   lds convert docs README.md README.html -- --toc --standalone
+
+``-o`` / ``--output`` is intentionally rejected because LocalDevStack owns the output
+path through the second positional argument.
+
+Relative Assets
+---------------
+
+Pandoc runs with the input directory as its working directory and with
+``--resource-path=/lds-input``. Relative images and other resources next to the input
+document therefore remain available during conversion.
+
+Auxiliary file options such as a reference document should use files below the input
+directory and refer to them with relative paths.
+
+Overwrite Safety
+----------------
+
+Existing output files are not replaced unless ``--force`` is supplied::
+
+   lds convert docs --force README.md README.html
+
+The input and output may not resolve to the same file.
+
+Format Discovery
+----------------
+
+The supported readers and writers come from the Pandoc version currently shipped by the
+Tools image::
+
+   lds convert docs --list-input-formats
+   lds convert docs --list-output-formats
+   lds convert docs --version
+
+Pandoc supports many text/document formats, but not every format can be converted to
+every other format. PDF output additionally requires a compatible PDF engine; the base
+Tools image currently provides Pandoc itself, not a TeX/PDF rendering stack.
+
+Windows and Git Bash
+--------------------
+
+The converter normalizes Windows/Git Bash host paths before creating Docker mounts and
+disables MSYS argument rewriting for the Docker invocation. Paths containing spaces are
+preserved as individual argv values.
+
+Image Conversion
+----------------
+
+Raster/image conversion uses ImageMagick from the same Tools image::
+
+   lds convert image photo.jpg photo.png
+   lds convert image photo.png photo.webp -- -quality 82 -strip
+   lds convert image animation.gif animation.webp
+   lds convert image animation.gif preview.jpg
+
+Use ``lds convert image --formats`` to inspect the delegates/formats available in the current image. Static outputs such as JPEG and PNG use the first frame of animated inputs by default; animation-capable GIF/WebP outputs preserve frames when supported.
+
+Audio and Video Conversion
+--------------------------
+
+Audio and video conversion use FFmpeg from the Tools image::
+
+   lds convert audio recording.wav recording.mp3
+   lds convert audio recording.wav recording.ogg -- -c:a libopus -b:a 128k
+   lds convert video recording.mov recording.mp4
+   lds convert video recording.mkv recording.webm -- -c:v libvpx-vp9 -crf 32 -b:v 0
+
+The first-class media converter owns one input, overwrite policy, and one output path.
+FFmpeg output options are passed after the input as exact argv. LDS reserves ``-i``,
+``-y``, and ``-n`` because it owns input/output and ``--force`` behavior.
+
+Inspect FFmpeg capabilities with::
+
+   lds convert audio --formats
+   lds convert audio --codecs
+   lds convert audio --encoders
+   lds convert video --version
+
+For multi-input, concat, capture, or complex filtergraph workflows use the raw Tools
+surface instead::
+
+   lds tools ffmpeg ...
+   lds tools ffprobe media.mkv
+
+Specialist Media Tools
+----------------------
+
+The Tools image also exposes media utilities directly::
+
+   lds tools sox ...
+   lds tools soxi recording.wav
+   lds tools mkvmerge ...
+   lds tools mkvinfo media.mkv
+   lds tools mkvextract ...
+   lds tools mkvpropedit ...
+   lds tools mediainfo media.mkv
+
+``xvidcore`` is installed as an explicit FFmpeg codec runtime dependency; it is a
+library rather than a standalone command.
diff --git a/docs/guides/local-ai.rst b/docs/guides/local-ai.rst
@@ -295,8 +295,12 @@ When the active docker-tools image exposes the docstruct Graphify handoff,
 5. optional semantic review runs in bounded chunks against the active local model;
 6. docker-tools emits a Graphify-compatible fragment;
 7. Graphify's public ``merge-chunks`` validates that fragment;
-8. docker-tools atomically replaces only the reserved ``docstruct_`` semantic layer;
-9. ``graphify label`` reclusters and relabels the final combined graph.
+8. docker-tools replaces only the reserved ``docstruct_`` semantic layer in a staged graph;
+9. LocalDevStack copies that staged graph into an isolated temporary workspace and runs
+   ``graphify cluster-only --no-label --no-viz``; only Graphify's canonical round-trip
+   output is eligible for publication;
+10. the canonical graph is atomically published to ``graphify-out/graph.json``, then
+    ``graphify label`` reclusters and relabels the final combined graph.
 
 This removes Markdown/RST/config parsing and recognized Python pip requirement manifests
 from the fragile raw LLM extraction path while preserving Graphify's existing support for
@@ -321,7 +325,8 @@ Controls
 ``LDS_GRAPHIFY_DOC_REVIEW``:
 
 - ``auto`` (default): review bounded document chunks on the built-in local provider;
-  if review fails, keep the deterministic structure and continue;
+  docker-tools retries one malformed structured response once, then LocalDevStack keeps
+  the deterministic structure and continues if review still fails;
 - ``on``: require semantic review to succeed;
 - ``off``: use deterministic document structure only.
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -28,6 +28,7 @@ LocalDevStack is designed for trusted developer workstations, not production dep
 
    guides/domain-setup
    guides/databases-and-clients
+   guides/conversion
    guides/tls-and-certificates
    guides/local-ai
    guides/operations-and-support