@lazyingart/agintiflow 0.15.1 → 0.16.0

package/README.md

@@ -179,7 +179,7 @@ aginti capabilities --json
 aginti doctor --capabilities
 ```
 
-The report checks the project root, command cwd, shared `.sessions/`, provider-key presence, DeepSeek routes, guarded file and shell tools, Docker status, wrappers, task profiles, TeX, Node/npm, Python, R, conda, and maintenance command policy. It never prints API key or token values.
+The report checks the project root, command cwd, shared `.sessions/`, provider-key presence, DeepSeek routes, guarded file and shell tools, OS/platform hints, Docker status, wrappers, task profiles, TeX, Node/npm, Python, R, conda, and maintenance command policy. It never prints API key or token values.
 
 Live DeepSeek verification is opt-in because it spends provider credits:
 
@@ -337,7 +337,20 @@ npm publish --access public
 
 Never publish with `npm publish` from inside an agent run. The runtime command policy blocks npm publish and npm token commands by design.
 
-## Docker Bootstrap
+## Platform And Docker Bootstrap
+
+AgInTiFlow is designed for Linux, macOS, Windows through WSL2, and best-effort native Windows use. The most portable shell/toolchain path is `docker-workspace`; native Windows host shell commands should be treated as best effort unless you run inside WSL2.
+
+Platform notes:
+
+| Platform | Recommended setup |
+| --- | --- |
+| Ubuntu/Debian | Node.js 22+, optional `scripts/install-docker-ubuntu.sh`, Docker workspace mode for broad toolchains. |
+| Red Hat/Fedora/Rocky/Alma | Node.js 22+, Docker/Podman-compatible Docker CLI from `dnf`/vendor docs; do not use the Ubuntu Docker script. |
+| macOS | Node.js 22+ from Homebrew/nvm/fnm, Docker Desktop or Colima, optional MacTeX/BasicTeX for host LaTeX. |
+| Windows | Prefer WSL2 with Docker Desktop WSL integration. Native Windows host mode is best effort; Docker/WSL is recommended for Bash, LaTeX, Python/R/Stan, and package-manager workflows. |
+
+LaTeX support first checks the active environment for `latexmk` or `pdflatex`. If your host already has MacTeX, BasicTeX, TeX Live, or MiKTeX on `PATH`, host-mode LaTeX tasks can compile directly without downloading TeX again. Docker-mode LaTeX uses the companion image; the setup script preflights an existing image and skips rebuilds when the Docker toolchain already has `latexmk` and `pdflatex`.
 
 Ubuntu helper:
 
@@ -353,14 +366,14 @@ DOCKER_TARGET_USER=lachlan ./scripts/install-docker-ubuntu.sh
 
 Open a new login shell, or run `newgrp docker`, before testing non-root Docker access.
 
-Build the companion agent toolchain sandbox:
+Build or verify the companion agent toolchain sandbox:
 
 ```bash
 ./scripts/setup-agent-toolchain-docker.sh
 npm run smoke:toolchain-docker
 ```
 
-The setup script idempotently builds `agintiflow-sandbox:latest` from `docker/sandbox.Dockerfile` and verifies Node, npm, Python, NumPy, Matplotlib, `latexmk`, and `pdflatex` inside Docker. It also creates the persistent companion folders under `~/.agintiflow/docker/`: `home/` maps to `/aginti-home`, `cache/` maps to `/aginti-cache`, and `env/` maps to `/aginti-env`. Python/conda-style toolchains should live under `/aginti-env` so they survive across agent runs. OS package changes from `apt-get` are container-ephemeral unless you rebuild the image.
+The setup script checks whether `agintiflow-sandbox:latest` already exists and runs a Docker preflight before rebuilding. If Node, npm, Python, NumPy, Matplotlib, `latexmk`, and `pdflatex` are already ready inside the image, it exits without redownloading TeX Live. Set `AGINTIFLOW_FORCE_TOOLCHAIN_REBUILD=true` only when you intentionally want a fresh image. The script also creates persistent companion folders under `~/.agintiflow/docker/`: `home/` maps to `/aginti-home`, `cache/` maps to `/aginti-cache`, and `env/` maps to `/aginti-env`. Python/conda-style toolchains should live under `/aginti-env` so they survive across agent runs. OS package changes from `apt-get` are container-ephemeral unless you rebuild the image.
 
 ## Sandbox Modes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "type": "module",
   "description": "AgInTiFlow is a resumable Playwright website-control agent with OpenAI-compatible tool calling.",
   "license": "Apache-2.0",
@@ -47,6 +47,7 @@
     "scripts/smoke-coding-tools.js",
     "scripts/smoke-capabilities.js",
     "scripts/smoke-inbox.js",
+    "scripts/smoke-platform.js",
     "scripts/smoke-skills.js",
     "scripts/smoke-toolchain-docker.js",
     "scripts/smoke-web-api.js",
@@ -71,9 +72,10 @@
     "smoke:skills": "node scripts/smoke-skills.js",
     "smoke:toolchain-docker": "node scripts/smoke-toolchain-docker.js",
     "smoke:inbox": "node scripts/smoke-inbox.js",
+    "smoke:platform": "node scripts/smoke-platform.js",
     "smoke:web-api": "node scripts/smoke-web-api.js",
     "real:deepseek": "node scripts/real-deepseek-capabilities.js",
-    "test": "npm run check && npm run smoke:web-api && npm run smoke:coding-tools && npm run smoke:auxiliary-tools && npm run smoke:auth && npm run smoke:capabilities && npm run smoke:skills && npm run smoke:cli-chat && npm run smoke:inbox",
+    "test": "npm run check && npm run smoke:web-api && npm run smoke:coding-tools && npm run smoke:auxiliary-tools && npm run smoke:auth && npm run smoke:capabilities && npm run smoke:platform && npm run smoke:skills && npm run smoke:cli-chat && npm run smoke:inbox",
     "pack:dry-run": "npm pack --dry-run",
     "smoke:capabilities": "node scripts/smoke-capabilities.js"
   },

package/public/app.js

@@ -798,6 +798,7 @@ function renderProjectStatus(info = projectInfo) {
   projectInfo = info;
   if (!projectStatusEl || !info) return;
   projectStatusEl.textContent = [
+    info.platform?.label ? `os=${info.platform.label}` : "",
     `root=${info.root || ""}`,
     `cwd=${info.commandCwd || ""}`,
     `sessions=${info.sessionsDir || ""}`,

package/scripts/setup-agent-toolchain-docker.sh

@@ -7,57 +7,106 @@ IMAGE="${AGINTIFLOW_TOOLCHAIN_IMAGE:-agintiflow-sandbox:latest}"
 WORKSPACE="${AGINTIFLOW_TOOLCHAIN_WORKSPACE:-${REPO_ROOT}}"
 DOCKERFILE="${AGINTIFLOW_TOOLCHAIN_DOCKERFILE:-${REPO_ROOT}/docker/sandbox.Dockerfile}"
 STATE_DIR="${AGINTIFLOW_DOCKER_STATE_DIR:-${HOME:-/tmp}/.agintiflow/docker}"
+FORCE_REBUILD="${AGINTIFLOW_FORCE_TOOLCHAIN_REBUILD:-false}"
+
+os_name="$(uname -s 2>/dev/null || printf unknown)"
+case "${os_name}" in
+  Darwin) platform_hint="macOS: use Docker Desktop or Colima; host LaTeX can come from MacTeX/BasicTeX." ;;
+  Linux)
+    if grep -qi microsoft /proc/version 2>/dev/null; then
+      platform_hint="WSL: use Docker Desktop WSL integration or Docker Engine inside WSL."
+    elif [ -r /etc/os-release ] && grep -Eqi '^(ID|ID_LIKE)=.*(rhel|fedora|centos|rocky|almalinux|redhat)' /etc/os-release; then
+      platform_hint="Red Hat/Fedora family: install Docker with dnf/yum or vendor docs; do not use install-docker-ubuntu.sh."
+    else
+      platform_hint="Linux: Ubuntu/Debian hosts may use scripts/install-docker-ubuntu.sh."
+    fi
+    ;;
+  MINGW*|MSYS*|CYGWIN*) platform_hint="Windows shell: prefer WSL2 for AgInTiFlow Docker/toolchain workflows." ;;
+  *) platform_hint="Use a Docker-capable environment with Node.js 22+." ;;
+esac
 
 if ! command -v docker >/dev/null 2>&1; then
-  echo "Docker is not installed or not on PATH. Run scripts/install-docker-ubuntu.sh first." >&2
+  echo "Docker is not installed or not on PATH." >&2
+  echo "${platform_hint}" >&2
   exit 1
 fi
 
 mkdir -p "${WORKSPACE}"
 mkdir -p "${STATE_DIR}/home" "${STATE_DIR}/cache" "${STATE_DIR}/env"
 
-echo "Building AgInTiFlow toolchain sandbox image:"
+host_latex="missing"
+if command -v latexmk >/dev/null 2>&1 && command -v pdflatex >/dev/null 2>&1; then
+  host_latex="complete"
+elif command -v latexmk >/dev/null 2>&1 || command -v pdflatex >/dev/null 2>&1; then
+  host_latex="partial"
+fi
+
+run_preflight() {
+  docker run --rm \
+    --network none \
+    --cap-drop ALL \
+    --security-opt no-new-privileges \
+    --pids-limit 256 \
+    --memory 2g \
+    --cpus 2 \
+    --tmpfs /tmp:rw,nosuid,nodev,size=512m \
+    -e HOME=/aginti-home \
+    -e XDG_CACHE_HOME=/aginti-cache \
+    -e PIP_CACHE_DIR=/aginti-cache/pip \
+    -e MPLCONFIGDIR=/tmp/matplotlib \
+    -e NPM_CONFIG_CACHE=/aginti-cache/npm \
+    -e CONDA_PKGS_DIRS=/aginti-cache/conda-pkgs \
+    -v "${WORKSPACE}:/workspace:rw" \
+    -v "${STATE_DIR}/home:/aginti-home:rw" \
+    -v "${STATE_DIR}/cache:/aginti-cache:rw" \
+    -v "${STATE_DIR}/env:/aginti-env:rw" \
+    -w /workspace \
+    "${IMAGE}" \
+    bash -lc 'set -Eeuo pipefail
+      mkdir -p /tmp/matplotlib
+      if [ ! -x /aginti-env/python/bin/python ]; then python3 -m venv --system-site-packages /aginti-env/python; fi
+      . /aginti-env/python/bin/activate
+      node -v
+      npm -v
+      python3 --version
+      python3 - <<PY
+import matplotlib, numpy
+print("matplotlib", matplotlib.__version__)
+print("numpy", numpy.__version__)
+PY
+      latexmk -version | head -1
+      pdflatex --version | head -1
+    '
+}
+
+echo "AgInTiFlow toolchain sandbox:"
 echo "  image=${IMAGE}"
 echo "  dockerfile=${DOCKERFILE}"
 echo "  context=${REPO_ROOT}"
 echo "  persistent=${STATE_DIR}"
+echo "  platform=${os_name}"
+echo "  hostLatex=${host_latex}"
+echo "  note=${platform_hint}"
+
+if [ "${FORCE_REBUILD}" != "true" ] && docker image inspect "${IMAGE}" >/dev/null 2>&1; then
+  echo
+  echo "Existing image found. Running preflight before rebuilding:"
+  if run_preflight; then
+    echo
+    echo "Toolchain sandbox is already ready; skipped Docker rebuild and TeX Live redownload."
+    exit 0
+  fi
+  echo
+  echo "Existing image failed preflight; rebuilding ${IMAGE}."
+fi
+
+echo
+echo "Building AgInTiFlow toolchain sandbox image:"
 docker build -t "${IMAGE}" -f "${DOCKERFILE}" "${REPO_ROOT}"
 
 echo
 echo "Running toolchain preflight inside Docker:"
-docker run --rm \
-  --network none \
-  --cap-drop ALL \
-  --security-opt no-new-privileges \
-  --pids-limit 256 \
-  --memory 2g \
-  --cpus 2 \
-  --tmpfs /tmp:rw,nosuid,nodev,size=512m \
-  -e HOME=/aginti-home \
-  -e XDG_CACHE_HOME=/aginti-cache \
-  -e PIP_CACHE_DIR=/aginti-cache/pip \
-  -e NPM_CONFIG_CACHE=/aginti-cache/npm \
-  -e CONDA_PKGS_DIRS=/aginti-cache/conda-pkgs \
-  -v "${WORKSPACE}:/workspace:rw" \
-  -v "${STATE_DIR}/home:/aginti-home:rw" \
-  -v "${STATE_DIR}/cache:/aginti-cache:rw" \
-  -v "${STATE_DIR}/env:/aginti-env:rw" \
-  -w /workspace \
-  "${IMAGE}" \
-  bash -lc 'set -Eeuo pipefail
-    if [ ! -x /aginti-env/python/bin/python ]; then python3 -m venv --system-site-packages /aginti-env/python; fi
-    . /aginti-env/python/bin/activate
-    node -v
-    npm -v
-    python3 --version
-    python3 - <<PY
-import matplotlib, numpy
-print("matplotlib", matplotlib.__version__)
-print("numpy", numpy.__version__)
-PY
-    latexmk -version | head -1
-    pdflatex --version | head -1
-  '
+run_preflight
 
 echo
 echo "Toolchain sandbox is ready."

package/scripts/smoke-capabilities.js

@@ -36,6 +36,8 @@ try {
   assert(capabilities.project.commandCwd === tempRoot, "capabilities did not default commandCwd to project root");
   assert(capabilities.project.instructionsPresent, "capabilities did not report AGINTI.md");
   assert(capabilities.project.sharedSessionFolder, "capabilities did not report shared session folder");
+  assert(capabilities.platform?.platform, "capabilities did not report platform");
+  assert(Array.isArray(capabilities.platform?.setupHints), "capabilities did not report platform setup hints");
   assert(capabilities.keys?.mock === true, "capabilities did not report mock availability");
   assert(typeof capabilities.keys?.qwen === "boolean", "capabilities did not report qwen key status");
   assert(

package/scripts/smoke-platform.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { platformInfo, platformLabel, platformSetupHints, hostShellOption } from "../src/platform.js";
+import { buildCapabilityReport } from "../src/capabilities.js";
+import { resolveRuntimeConfig } from "../src/config.js";
+
+const info = platformInfo();
+const label = platformLabel(info);
+const hints = platformSetupHints(info);
+
+assert(["linux", "darwin", "win32", "freebsd", "openbsd", "aix", "sunos"].includes(info.platform), "unknown platform shape");
+assert(label.includes(info.arch), "platform label should include architecture");
+assert(hints.length > 0, "platform hints should not be empty");
+assert(hostShellOption(), "host shell option should be defined");
+
+if (info.isMac) {
+  assert(hints.some((hint) => /Docker Desktop|Colima/i.test(hint)), "macOS hints should mention Docker Desktop or Colima");
+  assert(hints.some((hint) => /MacTeX|BasicTeX/i.test(hint)), "macOS hints should mention MacTeX or BasicTeX");
+}
+if (info.isWindows) {
+  assert(hints.some((hint) => /WSL/i.test(hint)), "Windows hints should recommend WSL");
+}
+if (info.isWsl) {
+  assert(label.includes("WSL"), "WSL platform label should mention WSL");
+}
+
+const config = resolveRuntimeConfig({ goal: "platform smoke", provider: "mock" }, { useDockerSandbox: false });
+const report = await buildCapabilityReport(process.cwd(), "0.0.0-smoke", config);
+assert.equal(report.platform.platform, info.platform, "capability report should include platform");
+assert(Array.isArray(report.platform.setupHints), "capability report should include setup hints");
+assert(typeof report.platform.hostLatexAvailable === "boolean", "capability report should include host LaTeX status");
+
+console.log(
+  JSON.stringify(
+    {
+      ok: true,
+      platform: report.platform.label,
+      linuxFamily: report.platform.linuxFamily,
+      hostLatexAvailable: report.platform.hostLatexAvailable,
+      hints: report.platform.setupHints.length,
+    },
+    null,
+    2
+  )
+);

package/src/agent-runner.js

@@ -23,6 +23,7 @@ import { searchWeb } from "./web-search.js";
 import { runParallelScouts, shouldRunParallelScouts } from "./parallel-scouts.js";
 import { readProjectInstructions } from "./project.js";
 import { formatSkillsForPrompt, selectSkillsForGoal } from "./skill-library.js";
+import { hostShellOption, platformInfo, platformLabel } from "./platform.js";
 
 const exec = promisify(execCallback);
 const BROWSER_TOOLS = new Set(["open_url", "open_workspace_file", "preview_workspace", "click", "type", "scroll", "press", "back"]);
@@ -257,6 +258,7 @@ async function createInitialState(config, sessionId) {
   const skillContext = formatSkillsForPrompt(selectedSkills);
   const projectInstructions = await readProjectInstructions(config.baseDir || config.commandCwd || process.cwd());
   const projectInstructionContext = formatProjectInstructions(projectInstructions);
+  const platform = platformInfo();
   return {
     sessionId,
     createdAt: now,
@@ -302,7 +304,7 @@ async function createInitialState(config, sessionId) {
           config.allowShellTool
             ? config.useDockerSandbox
               ? `A shell command tool is available inside Docker sandbox mode ${config.sandboxMode}. Docker workspace mode with approved package installs supports broader setup and network commands. The project is mounted at /workspace and the persistent agent toolchain is mounted at /aginti-env with caches under /aginti-cache.`
-              : "A host shell command tool is available under the configured trust policy."
+              : `A host shell command tool is available under the configured trust policy on ${platformLabel(platform)}. On native Windows, prefer PowerShell/cmd-compatible commands or switch to WSL/Docker for bash-like toolchains.`
             : "No shell command tool is available.",
           config.allowFileTools
             ? `Workspace file tools are available in ${config.commandCwd}: inspect_project, list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, and preview_workspace. For large or unfamiliar repositories, call inspect_project first, then search/read AGINTI.md/AGENTS.md/README/manifests as relevant before editing. apply_patch supports exact single-file replacements plus Codex-style/unified multi-file patches; prefer it for source edits after reading/searching the relevant context. Always use workspace-relative paths such as plot_fx.svg or docs/report.tex, never absolute host paths. Secret paths, .git internals, node_modules writes, and huge files are blocked. For generated local websites/pages, use open_workspace_file or preview_workspace instead of starting a localhost server inside Docker.`
@@ -329,6 +331,7 @@ async function createInitialState(config, sessionId) {
           "Work like a practical coding agent: orient with inspect_project/search/read, patch code with apply_patch, run safe checks when they add confidence, iterate on failures, and keep outputs inside the workspace.",
           "For large projects, decompose into useful files and milestones, identify entry points/tests/contracts first, implement a coherent minimal version, then iterate with checks rather than only describing what you would do.",
           "For website/app/code/LaTeX/Python/C/shell tasks, create or edit real workspace files, run available build/compile/test commands, and surface artifacts through the canvas when useful.",
+          "For LaTeX/PDF tasks, check existing latexmk/pdflatex first and compile with the available host or Docker TeX toolchain before installing packages or rebuilding the sandbox.",
           "For research or web-search tasks, use browser tools or safe shell network tools when the current policy allows; cite or save useful sources in workspace notes when the task needs traceability.",
           "Use the canvas tunnel for outputs the user would likely want to inspect visually, such as figures, PDFs, screenshots, images, important markdown, or generated files.",
           "For environment or system-maintenance work, use the configured sandbox and package policy; Docker workspace mode is the preferred place for installs and toolchain setup.",
@@ -476,6 +479,7 @@ async function applyContinuationPrompt(state, config, observers) {
   state.plan = "";
   state.stepsCompleted = 0;
   state.updatedAt = new Date().toISOString();
+  const platform = platformInfo();
   state.messages.push({
     role: "user",
     content: [
@@ -485,7 +489,7 @@ async function applyContinuationPrompt(state, config, observers) {
       config.allowShellTool
         ? config.useDockerSandbox
           ? `Shell working directory mounted into Docker as /workspace from ${config.commandCwd}. Use relative paths or /workspace paths. Persistent Docker env: /aginti-env, caches: /aginti-cache. Sandbox mode: ${config.sandboxMode}. Package install policy: ${config.packageInstallPolicy}.`
-          : `Shell working directory: ${config.commandCwd}`
+          : `Shell working directory: ${config.commandCwd}. Host platform: ${platformLabel(platform)}. Use OS-compatible commands; prefer WSL/Docker for bash-heavy workflows on Windows.`
         : "",
       config.allowFileTools
         ? `Workspace file tools enabled in: ${config.commandCwd}. Use inspect_project first for large or unfamiliar codebases, then search/read exact files before editing. Read AGINTI.md/AGENTS.md/README/manifests when relevant. Use workspace-relative paths. Use apply_patch for code edits; it accepts exact replacements or Codex-style/unified multi-file patches. For generated local files/sites, use open_workspace_file or preview_workspace.`
@@ -658,7 +662,7 @@ async function runShellCommand(command, config, policy = evaluateCommandPolicy(c
           cwd: config.commandCwd,
           timeout: 30000,
           maxBuffer: 200 * 1024,
-          shell: "/bin/bash",
+          shell: hostShellOption(),
           env: safeExecutionEnv(),
           signal: config.abortSignal,
         });
@@ -681,6 +685,7 @@ async function runShellCommand(command, config, policy = evaluateCommandPolicy(c
 }
 
 async function captureSyntheticSnapshot(store, step, config) {
+  const platform = platformInfo();
   const snapshot = {
     title: "No browser page open",
     url: "",
@@ -690,7 +695,7 @@ async function captureSyntheticSnapshot(store, step, config) {
       config.allowShellTool
         ? config.useDockerSandbox
           ? `Shell tool available in Docker with mounted workspace /workspace from ${config.commandCwd}. Use relative paths or /workspace paths. Persistent Docker env: /aginti-env, caches: /aginti-cache. Sandbox mode: ${config.sandboxMode}. Package install policy: ${config.packageInstallPolicy}.`
-          : `Shell tool available in: ${config.commandCwd}`
+          : `Shell tool available in: ${config.commandCwd} on ${platformLabel(platform)}. Use OS-compatible commands; prefer WSL/Docker for bash-heavy workflows on Windows.`
         : "Shell tool disabled.",
       config.allowFileTools
         ? `Workspace file tools available in: ${config.commandCwd}. Use inspect_project first for large or unfamiliar codebases, then search/read exact files before editing. Use workspace-relative paths. Use apply_patch for code edits; it supports exact single-file replacement and multi-file Codex-style/unified patches.`
@@ -700,7 +705,7 @@ async function captureSyntheticSnapshot(store, step, config) {
         : "Agent wrappers disabled.",
       "Canvas/artifacts tunnel available through send_to_canvas.",
       "For draw/plot/graph/chart/diagram/figure requests, publish a canvas artifact proactively.",
-      "For LaTeX/PDF requests, publish the source and compiled PDF artifacts when available. Keep subfolder outputs beside their source and use pdflatex-compatible figure formats.",
+      "For LaTeX/PDF requests, check latexmk/pdflatex first, publish the source and compiled PDF artifacts when available, and avoid reinstalling TeX when an existing toolchain works.",
       "Use open_url only if the task actually needs the web.",
       "For generated local HTML/SVG/PDF/site output, use open_workspace_file or preview_workspace instead of shelling a transient local server.",
     ]

package/src/capabilities.js

@@ -10,6 +10,7 @@ import { listAgentWrappers } from "./tool-wrappers.js";
 import { listAuxiliarySkills } from "./auxiliary-tools.js";
 import { readCodebaseMap } from "./codebase-map.js";
 import { listSkills } from "./skill-library.js";
+import { platformInfo, platformLabel, platformSetupHints } from "./platform.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -112,19 +113,28 @@ function trustedDockerPolicyChecks(config) {
 export async function buildCapabilityReport(projectRoot, packageVersion, config) {
   const paths = projectPaths(projectRoot);
   const keyStatus = providerKeyStatus(projectRoot);
-  const [node, npm, python, conda, r, pdflatex, latexmk, dockerStatus, sessions, instructions, codebaseMap] = await Promise.all([
+  const platform = platformInfo();
+  const commandChecks = [
     commandAvailable("node", ["--version"]),
     commandAvailable("npm", ["--version"]),
-    commandAvailable("python3", ["--version"]),
+    commandAvailable(platform.isWindows ? "python" : "python3", ["--version"]),
     commandAvailable("conda", ["--version"]),
     commandAvailable("R", ["--version"]),
     commandAvailable("pdflatex", ["--version"]),
     commandAvailable("latexmk", ["--version"]),
+  ];
+  if (platform.isMac) commandChecks.push(commandAvailable("brew", ["--version"]));
+  if (platform.isWindows) commandChecks.push(commandAvailable("wsl", ["--status"]));
+  const [commands, dockerStatus, sessions, instructions, codebaseMap] = await Promise.all([
+    Promise.all(commandChecks),
     getDockerSandboxStatus(config).catch((error) => ({ ok: false, error: error.message })),
     listProjectSessions(projectRoot, 12),
     readProjectInstructions(projectRoot, { maxBytes: 1 }),
     readCodebaseMap(projectRoot),
   ]);
+  const [node, npm, python, conda, r, pdflatex, latexmk] = commands;
+  const homebrew = platform.isMac ? commands[7] : undefined;
+  const wsl = platform.isWindows ? commands[7] : undefined;
 
   const npmPrefixPolicy = evaluateCommandPolicy("npm --prefix round9-node-app test", config);
   const cdNpmTestPolicy = evaluateCommandPolicy("cd round9-node-app && npm test", config);
@@ -144,6 +154,8 @@ export async function buildCapabilityReport(projectRoot, packageVersion, config)
     capability("R", r.available, r.available ? r : { ...r, setup: "Optional. Generate a project-local R setup plan; do not install globally from the agent." }),
     capability("pdflatex", pdflatex.available, pdflatex.available ? pdflatex : { ...pdflatex, setup: "LaTeX tasks should create .tex source and an honest setup report when TeX is unavailable." }),
     capability("latexmk", latexmk.available, latexmk.available ? latexmk : { ...latexmk, setup: "latexmk is optional if pdflatex is available." }),
+    ...(platform.isMac ? [capability("homebrew", homebrew?.available, homebrew?.available ? homebrew : { ...homebrew, setup: "Optional on macOS for host-mode tool installs." })] : []),
+    ...(platform.isWindows ? [capability("wsl", wsl?.available, wsl?.available ? wsl : { ...wsl, setup: "Recommended for Windows. Install WSL2 for the most compatible shell and Docker workflow." })] : []),
     capability("docker", Boolean(dockerStatus?.dockerAvailable), dockerStatus || {}),
     capability("deepseek-key", keyStatus.deepseek, { envVars: keyStatus.envVars.deepseek }),
     capability("openai-key", keyStatus.openai, { envVars: keyStatus.envVars.openai }),
@@ -191,6 +203,13 @@ export async function buildCapabilityReport(projectRoot, packageVersion, config)
         summary: codebaseMap.ok ? codebaseMap.map.inspection?.summary || "" : "",
       },
     },
+    platform: {
+      ...platform,
+      label: platformLabel(platform),
+      setupHints: platformSetupHints(platform),
+      hostLatexAvailable: Boolean(pdflatex.available || latexmk.available),
+      hostLatexComplete: Boolean(pdflatex.available && latexmk.available),
+    },
     routing: {
       active: {
         provider: config.provider,
@@ -256,6 +275,7 @@ export async function buildCapabilityReport(projectRoot, packageVersion, config)
 
 export function printCapabilityReport(report) {
   console.log(`AgInTiFlow capabilities ${report.package.version}`);
+  console.log(`platform=${report.platform.label} family=${report.platform.linuxFamily || report.platform.platform}`);
   console.log(`project=${report.project.root}`);
   console.log(`cwd=${report.project.commandCwd}`);
   console.log(`instructions=${report.project.instructionsPath} present=${report.project.instructionsPresent}`);
@@ -286,4 +306,8 @@ export function printCapabilityReport(report) {
       console.log(`- ${item.capability}: ${item.setup}`);
     }
   }
+  if (report.platform?.setupHints?.length) {
+    console.log("platform setup hints:");
+    for (const hint of report.platform.setupHints) console.log(`- ${hint}`);
+  }
 }

package/src/cli.js

@@ -349,6 +349,7 @@ function printInitResult(result) {
 function printDoctorReport(report) {
   console.log(`AgInTiFlow ${report.package.version} (npm latest: ${report.package.npmLatest})`);
   console.log(`node=${report.node.version} ok=${report.node.ok}`);
+  console.log(`platform=${report.platform.label} family=${report.platform.linuxFamily || report.platform.platform}`);
   console.log(`project=${report.project.root}`);
   console.log(`instructions=${report.project.instructionsPath} present=${report.project.instructionsPresent}`);
   console.log(`sessions=${report.project.sessionsDir}`);
@@ -369,6 +370,10 @@ function printDoctorReport(report) {
     `wrappers=${report.wrappers.map((wrapper) => `${wrapper.name}:${wrapper.available ? "ok" : "missing"}`).join(" ")}`
   );
   console.log(`sessions=${report.sessions.length}`);
+  if (report.platform.setupHints.length > 0) {
+    console.log("platform setup hints:");
+    for (const hint of report.platform.setupHints) console.log(`- ${hint}`);
+  }
 }
 
 async function readStdin() {

package/src/command-policy.js

@@ -84,7 +84,12 @@ const PACKAGE_INSTALL_PATTERNS = [
 const SYSTEM_PACKAGE_INSTALL_PATTERNS = [
   /^(?:sudo\s+)?apt(?:-get)?\s+update$/,
   /^(?:sudo\s+)?apt(?:-get)?\s+install(?:\s+-y)?(?:\s+[-@\w.+:=]+)+$/,
+  /^(?:sudo\s+)?(?:dnf|yum)\s+(?:makecache|check-update)(?:\s+[-\w]+)*$/,
+  /^(?:sudo\s+)?(?:dnf|yum)\s+install(?:\s+-y)?(?:\s+[-@\w.+:=]+)+$/,
   /^apk\s+add(?:\s+--no-cache)?(?:\s+[-@\w.+:=]+)+$/,
+  /^brew\s+install(?:\s+[-@\w.+:=/]+)+$/,
+  /^winget\s+install(?:\s+[-@\w.+:=/]+)+$/,
+  /^choco\s+install(?:\s+[-@\w.+:=/]+)+$/,
 ];
 
 const ENV_SETUP_PATTERNS = [

package/src/docker-sandbox.js

@@ -214,6 +214,7 @@ function dockerCommand(command, policy) {
     `export HOME=${DOCKER_HOME}`,
     `export XDG_CACHE_HOME=${DOCKER_CACHE}`,
     `export PIP_CACHE_DIR=${DOCKER_CACHE}/pip`,
+    `export MPLCONFIGDIR=/tmp/matplotlib`,
     `export UV_CACHE_DIR=${DOCKER_CACHE}/uv`,
     `export NPM_CONFIG_CACHE=${DOCKER_CACHE}/npm`,
     `export CONDA_PKGS_DIRS=${DOCKER_CACHE}/conda-pkgs`,
@@ -225,6 +226,7 @@ function dockerCommand(command, policy) {
 
   if (!policy.requiresDockerRoot) {
     envLines.push(
+      `mkdir -p /tmp/matplotlib >/dev/null 2>&1 || true`,
       `if command -v python3 >/dev/null 2>&1 && [ ! -x ${DOCKER_ENV}/python/bin/python ]; then python3 -m venv --system-site-packages ${DOCKER_ENV}/python >/dev/null 2>&1 || true; fi`,
       `if [ -f ${DOCKER_ENV}/python/bin/activate ]; then . ${DOCKER_ENV}/python/bin/activate; fi`
     );

package/src/model-client.js

@@ -4,6 +4,7 @@ import { getTaskProfile } from "./task-profiles.js";
 import { listAuxiliarySkills } from "./auxiliary-tools.js";
 import { engineeringGuidanceForTask } from "./engineering-guidance.js";
 import { formatSkillsForPrompt, selectSkillsForGoal } from "./skill-library.js";
+import { platformInfo, platformLabel } from "./platform.js";
 
 export function createClient(config) {
   if (config.provider === "mock") {
@@ -197,6 +198,7 @@ export async function createPlan(client, config, state) {
   const selectedSkills = selectSkillsForGoal(state.goal, { taskProfile: config.taskProfile, limit: 5 });
   const skillContext = formatSkillsForPrompt(selectedSkills);
   const projectInstructions = state.meta?.projectInstructions;
+  const platform = platformInfo();
   if (client.mock) {
     return [
       "1. Inspect the request and prefer the local shell when available.",
@@ -222,7 +224,7 @@ export async function createPlan(client, config, state) {
           state.startUrl ? `Suggested start URL: ${state.startUrl}` : "",
           config.allowedDomains.length > 0 ? `Allowed domains: ${config.allowedDomains.join(", ")}` : "",
           config.allowShellTool
-            ? `Shell tool is enabled in ${config.commandCwd}. In Docker, this path is mounted as /workspace with persistent /aginti-env and /aginti-cache mounts. Use relative paths or /workspace paths, not absolute host temp paths. Sandbox mode: ${config.sandboxMode}. Package install policy: ${config.packageInstallPolicy}. For npm/pip/conda/venv setup, explain the need and wait for approval unless policy is allow.`
+            ? `Shell tool is enabled in ${config.commandCwd}. Host platform: ${platformLabel(platform)}. In Docker, this path is mounted as /workspace with persistent /aginti-env and /aginti-cache mounts. Use relative paths or /workspace paths, not absolute host temp paths. Sandbox mode: ${config.sandboxMode}. Package install policy: ${config.packageInstallPolicy}. For npm/pip/conda/venv setup, explain the need and wait for approval unless policy is allow. On native Windows host mode, prefer PowerShell/cmd-compatible commands or WSL/Docker for bash-like toolchains.`
             : "",
           config.allowFileTools
             ? `Workspace file tools are enabled in ${config.commandCwd}: inspect_project, list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, preview_workspace. For large or unfamiliar repos, plan to call inspect_project first, then search/read AGINTI.md/AGENTS.md/README/manifests and exact files. apply_patch supports exact single-file replacements and Codex-style/unified multi-file patches; prefer it for edits after reading relevant context. Keep all paths workspace-relative, for example plot_fx.svg or docs/report.tex, and avoid secrets. For generated local HTML/SVG/PDF/static sites, plan to use open_workspace_file or preview_workspace rather than starting a localhost server inside Docker.`
@@ -250,6 +252,7 @@ export async function createPlan(client, config, state) {
           "A canvas/artifacts tunnel is available through send_to_canvas. Use it when an output should be highlighted visually, such as screenshots, image files, important markdown, diffs, or generated artifact paths. It is optional for ordinary text answers.",
           "Work like a practical coding agent: inspect when useful, edit with file tools, run safe checks when they add confidence, and keep outputs inside the workspace.",
           "For large apps, websites, LaTeX documents, Python/C/shell projects, or system tasks, plan a coherent minimal implementation, then use tools to create files, run checks, and publish artifacts.",
+          "For LaTeX/PDF work, first check whether latexmk or pdflatex already exists in the active host/Docker environment; compile with the existing toolchain before installing packages or rebuilding Docker.",
           "For web search or current information tasks, plan to use browser tools or safe shell network tools when allowed, then preserve useful source notes if the output depends on them.",
           "Use the canvas tunnel for outputs the user would likely want to inspect visually, such as figures, PDFs, screenshots, images, important markdown, or generated files.",
           "For environment or system-maintenance work, prefer project-local dry-run plans/scripts unless the configured policy explicitly allows stronger actions.",

package/src/platform.js

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import os from "node:os";
+
+function parseOsRelease() {
+  if (process.platform !== "linux") return {};
+  try {
+    const content = fs.readFileSync("/etc/os-release", "utf8");
+    const data = {};
+    for (const line of content.split(/\r?\n/)) {
+      const match = line.match(/^([A-Z0-9_]+)=(.*)$/);
+      if (!match) continue;
+      data[match[1].toLowerCase()] = match[2].replace(/^"|"$/g, "");
+    }
+    return data;
+  } catch {
+    return {};
+  }
+}
+
+export function platformInfo() {
+  const osRelease = parseOsRelease();
+  const release = os.release();
+  const isWsl = Boolean(process.env.WSL_DISTRO_NAME) || /microsoft|wsl/i.test(release);
+  const linuxId = osRelease.id || "";
+  const linuxLike = osRelease.id_like || "";
+  const linuxFamily = /ubuntu|debian/i.test(`${linuxId} ${linuxLike}`)
+    ? "debian"
+    : /rhel|fedora|centos|rocky|almalinux|redhat/i.test(`${linuxId} ${linuxLike}`)
+      ? "redhat"
+      : process.platform === "linux"
+        ? "linux"
+        : "";
+
+  return {
+    platform: process.platform,
+    arch: process.arch,
+    release,
+    type: os.type(),
+    distro: osRelease.pretty_name || osRelease.name || "",
+    linuxId,
+    linuxFamily,
+    isMac: process.platform === "darwin",
+    isLinux: process.platform === "linux",
+    isWindows: process.platform === "win32",
+    isWsl,
+  };
+}
+
+export function platformLabel(info = platformInfo()) {
+  if (info.isWsl) return `WSL ${info.distro || info.linuxId || "Linux"} (${info.arch})`;
+  if (info.isMac) return `macOS (${info.arch})`;
+  if (info.isWindows) return `Windows (${info.arch})`;
+  if (info.isLinux) return `${info.distro || "Linux"} (${info.arch})`;
+  return `${info.platform} (${info.arch})`;
+}
+
+export function platformSetupHints(info = platformInfo()) {
+  if (info.isWsl) {
+    return [
+      "Use the Linux/WSL shell as the primary AgInTiFlow environment; keep projects under the WSL filesystem for best file and Docker performance.",
+      "Use Docker Desktop with WSL integration or Docker Engine inside WSL for docker-workspace mode.",
+      "For LaTeX, reuse WSL latexmk/pdflatex when installed, or use the companion Docker sandbox image.",
+    ];
+  }
+  if (info.isMac) {
+    return [
+      "Use Node.js 22+ from Homebrew, nvm, fnm, or the official installer.",
+      "Use Docker Desktop or Colima for docker-workspace mode; the Ubuntu Docker installer is intentionally not used on macOS.",
+      "For LaTeX, reuse MacTeX/BasicTeX when latexmk and pdflatex are on PATH; otherwise use the companion Docker sandbox image.",
+      "Use Homebrew for optional host tools such as ripgrep, git, python, and latexmk when you choose host mode.",
+    ];
+  }
+  if (info.isWindows) {
+    return [
+      "Best supported Windows path: run AgInTiFlow inside WSL2 with Node.js 22+ and Docker Desktop WSL integration.",
+      "Native Windows host shell is best effort; prefer docker-workspace or WSL for bash-like coding, LaTeX, and package-manager tasks.",
+      "For LaTeX, use Docker/WSL, or install MiKTeX/TeX Live and ensure pdflatex/latexmk are on PATH.",
+    ];
+  }
+  if (info.linuxFamily === "debian") {
+    return [
+      "Use Node.js 22+ from nvm/fnm, NodeSource, or distro packages.",
+      "Docker can be installed with scripts/install-docker-ubuntu.sh on Ubuntu/Debian-like hosts.",
+      "For LaTeX, reuse host latexmk/pdflatex when available; otherwise use the companion Docker sandbox image.",
+    ];
+  }
+  if (info.linuxFamily === "redhat") {
+    return [
+      "Use Node.js 22+ from nvm/fnm or the Red Hat/Fedora package stream.",
+      "Install Docker/Podman-compatible Docker CLI with dnf/yum or vendor docs; do not use the Ubuntu Docker installer.",
+      "For LaTeX, reuse host latexmk/pdflatex from texlive packages when available; otherwise use the companion Docker sandbox image.",
+    ];
+  }
+  return [
+    "Use Node.js 22+ and prefer docker-workspace for portable shell/toolchain work.",
+    "For LaTeX, reuse host latexmk/pdflatex when available; otherwise use the companion Docker sandbox image.",
+  ];
+}
+
+export function hostShellOption() {
+  if (process.platform === "win32") return process.env.ComSpec || true;
+  return process.env.SHELL || "/bin/bash";
+}

package/src/project.js

@@ -5,6 +5,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { listAgentWrappers } from "./tool-wrappers.js";
 import { getDockerSandboxStatus } from "./docker-sandbox.js";
+import { platformInfo, platformLabel, platformSetupHints } from "./platform.js";
 
 const execFileAsync = promisify(execFile);
 const LOCAL_ENV_KEYS = new Set([
@@ -390,6 +391,7 @@ export async function npmLatestVersion(packageName = "@lazyingart/agintiflow") {
 export async function doctorReport(projectRoot, packageVersion, config) {
   const paths = projectPaths(projectRoot);
   const keyStatus = providerKeyStatus(projectRoot);
+  const platform = platformInfo();
   const [sessions, dockerStatus, latestVersion, instructions] = await Promise.all([
     listProjectSessions(projectRoot, 8),
     getDockerSandboxStatus(config).catch((error) => ({ ok: false, error: error.message })),
@@ -408,6 +410,11 @@ export async function doctorReport(projectRoot, packageVersion, config) {
       version: process.version,
       ok: Number(process.versions.node.split(".")[0]) >= 22,
     },
+    platform: {
+      ...platform,
+      label: platformLabel(platform),
+      setupHints: platformSetupHints(platform),
+    },
     project: {
       root: paths.root,
       instructionsPath: paths.agintiInstructionsPath,

package/src/task-profiles.js

@@ -80,7 +80,7 @@ export const TASK_PROFILES = {
     id: "latex",
     label: "LaTeX",
     prompt:
-      "Bias toward LaTeX/PDF production while still using writing, plotting, code, and web research when needed. Locate or create source and figures in a subfolder, compile when a TeX toolchain is available, run enough passes for references, and send the PDF through the canvas tunnel. In Docker, use /workspace for outputs and /aginti-env for persistent tools when setup is needed.",
+      "Bias toward LaTeX/PDF production while still using writing, plotting, code, and web research when needed. Locate or create source and figures in a subfolder, check existing latexmk/pdflatex before installing or rebuilding toolchains, compile when a TeX toolchain is available, run enough passes for references, and send the PDF through the canvas tunnel. In Docker, use /workspace for outputs and /aginti-env for persistent tools only when setup is actually needed.",
     tools: ["files", "shell", "canvas", "sandbox"],
   },
   maintenance: {

package/src/tool-wrappers.js

@@ -16,7 +16,11 @@ const BASE_ADVISORY_PROMPT = [
 
 function commandExists(command) {
   try {
-    execFileSync("bash", ["-lc", `command -v ${command}`], { stdio: "ignore" });
+    if (process.platform === "win32") {
+      execFileSync("where", [command], { stdio: "ignore" });
+    } else {
+      execFileSync("sh", ["-lc", `command -v ${command}`], { stdio: "ignore" });
+    }
     return true;
   } catch {
     return false;

package/web.js

@@ -15,6 +15,7 @@ import { listTaskProfiles, normalizeTaskProfile } from "./src/task-profiles.js";
 import { loadProjectEnv, projectPaths, providerKeyStatus, setProviderKey } from "./src/project.js";
 import { buildCapabilityReport } from "./src/capabilities.js";
 import { listSkills } from "./src/skill-library.js";
+import { platformInfo, platformLabel, platformSetupHints } from "./src/platform.js";
 import {
   buildArtifacts,
   countUnreadArtifacts,
@@ -559,6 +560,7 @@ app.get("/api/config", async (_req, res) => {
   const config = buildRunConfig({ ...preferences, goal: "" });
   const paths = projectPaths(baseDir);
   const keyStatus = publicKeyStatus(baseDir);
+  const platform = platformInfo();
   res.json({
     project: {
       root: paths.root,
@@ -567,6 +569,11 @@ app.get("/api/config", async (_req, res) => {
       sessionDbPath: paths.sessionDbPath,
       sharedSessionFolder: path.resolve(config.sessionsDir) === path.resolve(sessionsDir),
       localEnvPresent: keyStatus.localEnv,
+      platform: {
+        ...platform,
+        label: platformLabel(platform),
+        setupHints: platformSetupHints(platform),
+      },
     },
     defaults: {
       openai: publicProviderDefault("openai"),