claude-code-arcane 1.0.0

package/skills/docx-generator/scripts/dotnet/MiniMaxAIDocx.Core/Validation/BusinessRuleValidator.cs

@@ -0,0 +1,224 @@
+using System.IO.Compression;
+using System.Xml.Linq;
+
+namespace MiniMaxAIDocx.Core.Validation;
+
+public class BusinessRuleValidator
+{
+    private static readonly XNamespace W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+    private static readonly XNamespace R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+    private static readonly XNamespace WP = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
+    private static readonly XNamespace A = "http://schemas.openxmlformats.org/drawingml/2006/main";
+
+    private const int MinMarginDxa = 360;   // 0.25 inch
+    private const int MaxMarginDxa = 4320;  // 3 inches
+    private const int MinBodyFontHps = 16;  // 8pt
+    private const int MaxBodyFontHps = 144; // 72pt
+    private const int MinHeadingFontHps = 20; // 10pt
+    private const int MaxHeadingFontHps = 192; // 96pt
+
+    public ValidationResult Validate(string docxPath)
+    {
+        var result = new ValidationResult();
+
+        using var zip = ZipFile.OpenRead(docxPath);
+        var docEntry = zip.GetEntry("word/document.xml")
+            ?? throw new InvalidOperationException("Missing word/document.xml");
+
+        var doc = LoadXml(docEntry);
+        var body = doc.Root?.Element(W + "body");
+        if (body == null)
+        {
+            result.Errors.Add(Error("Document has no body element"));
+            return result;
+        }
+
+        ValidateMargins(body, result);
+        ValidateFontSizes(body, result);
+        ValidateHeadingHierarchy(body, result);
+        ValidateTableColumnWidths(body, result);
+        ValidateRelationships(zip, doc, result);
+        ValidateComments(zip, result);
+
+        return result;
+    }
+
+    private void ValidateMargins(XElement body, ValidationResult result)
+    {
+        foreach (var sectPr in body.Descendants(W + "sectPr"))
+        {
+            var pgMar = sectPr.Element(W + "pgMar");
+            if (pgMar == null) continue;
+
+            foreach (var attr in new[] { "top", "bottom", "left", "right" })
+            {
+                var val = (string?)pgMar.Attribute(W + attr);
+                if (val != null && int.TryParse(val, out var dxa))
+                {
+                    var absDxa = Math.Abs(dxa);
+                    if (absDxa < MinMarginDxa)
+                        result.Errors.Add(Error($"Margin '{attr}' is {absDxa} DXA ({absDxa / 1440.0:F2}\"), below minimum {MinMarginDxa} DXA"));
+                    if (absDxa > MaxMarginDxa)
+                        result.Warnings.Add(Warning($"Margin '{attr}' is {absDxa} DXA ({absDxa / 1440.0:F2}\"), above maximum {MaxMarginDxa} DXA"));
+                }
+            }
+        }
+    }
+
+    private void ValidateFontSizes(XElement body, ValidationResult result)
+    {
+        foreach (var p in body.Descendants(W + "p"))
+        {
+            var pStyle = p.Element(W + "pPr")?.Element(W + "pStyle")?.Attribute(W + "val")?.Value;
+            bool isHeading = pStyle?.StartsWith("Heading", StringComparison.OrdinalIgnoreCase) == true;
+
+            foreach (var rPr in p.Descendants(W + "rPr"))
+            {
+                var szEl = rPr.Element(W + "sz");
+                var val = (string?)szEl?.Attribute(W + "val");
+                if (val != null && int.TryParse(val, out var hps))
+                {
+                    int min = isHeading ? MinHeadingFontHps : MinBodyFontHps;
+                    int max = isHeading ? MaxHeadingFontHps : MaxBodyFontHps;
+                    if (hps < min || hps > max)
+                        result.Warnings.Add(Warning($"Font size {hps / 2.0}pt is outside {(isHeading ? "heading" : "body")} range ({min / 2}-{max / 2}pt)"));
+                }
+            }
+        }
+    }
+
+    private void ValidateHeadingHierarchy(XElement body, ValidationResult result)
+    {
+        int lastLevel = 0;
+        foreach (var p in body.Descendants(W + "p"))
+        {
+            var pStyle = p.Element(W + "pPr")?.Element(W + "pStyle")?.Attribute(W + "val")?.Value;
+            if (pStyle == null) continue;
+
+            int level = 0;
+            if (pStyle.StartsWith("Heading", StringComparison.OrdinalIgnoreCase))
+            {
+                var numPart = pStyle.AsSpan(7);
+                if (int.TryParse(numPart, out var parsed)) level = parsed;
+            }
+
+            if (level > 0)
+            {
+                if (lastLevel > 0 && level > lastLevel + 1)
+                    result.Warnings.Add(Warning($"Heading level skips from {lastLevel} to {level} (missing Heading{lastLevel + 1})"));
+                lastLevel = level;
+            }
+        }
+    }
+
+    private void ValidateTableColumnWidths(XElement body, ValidationResult result)
+    {
+        var sectPr = body.Element(W + "sectPr");
+        if (sectPr == null) return;
+
+        var pgSz = sectPr.Element(W + "pgSz");
+        var pgMar = sectPr.Element(W + "pgMar");
+        if (pgSz == null || pgMar == null) return;
+
+        if (!int.TryParse((string?)pgSz.Attribute(W + "w"), out var pageWidth)) return;
+        int.TryParse((string?)pgMar.Attribute(W + "left"), out var marginLeft);
+        int.TryParse((string?)pgMar.Attribute(W + "right"), out var marginRight);
+        var contentWidth = pageWidth - marginLeft - marginRight;
+
+        int tableIndex = 0;
+        foreach (var tbl in body.Descendants(W + "tbl"))
+        {
+            tableIndex++;
+            var firstRow = tbl.Element(W + "tr");
+            if (firstRow == null) continue;
+
+            int totalWidth = 0;
+            foreach (var tc in firstRow.Elements(W + "tc"))
+            {
+                var tcW = tc.Element(W + "tcPr")?.Element(W + "tcW");
+                var w = (string?)tcW?.Attribute(W + "w");
+                if (w != null && int.TryParse(w, out var cellWidth))
+                    totalWidth += cellWidth;
+            }
+
+            if (totalWidth > 0)
+            {
+                var tolerance = contentWidth * 0.02;
+                if (Math.Abs(totalWidth - contentWidth) > tolerance)
+                    result.Warnings.Add(Warning($"Table {tableIndex}: column widths sum to {totalWidth} DXA but content width is {contentWidth} DXA"));
+            }
+        }
+    }
+
+    private void ValidateRelationships(ZipArchive zip, XDocument doc, ValidationResult result)
+    {
+        var relsEntry = zip.GetEntry("word/_rels/document.xml.rels");
+        if (relsEntry == null) return;
+
+        var relDoc = LoadXml(relsEntry);
+        var ns = relDoc.Root?.Name.Namespace ?? XNamespace.None;
+        var definedIds = new HashSet<string>();
+
+        foreach (var rel in relDoc.Descendants(ns + "Relationship"))
+        {
+            var id = (string?)rel.Attribute("Id");
+            if (id != null) definedIds.Add(id);
+        }
+
+        var referencedIds = new HashSet<string>();
+        foreach (var el in doc.Descendants())
+        {
+            var rid = (string?)el.Attribute(R + "id") ?? (string?)el.Attribute(R + "embed");
+            if (rid != null) referencedIds.Add(rid);
+        }
+
+        foreach (var id in referencedIds.Except(definedIds))
+            result.Errors.Add(Error($"Reference r:id='{id}' has no matching relationship"));
+
+        foreach (var id in definedIds.Except(referencedIds))
+            result.Warnings.Add(Warning($"Orphaned relationship: Id='{id}' is defined but never referenced"));
+    }
+
+    private void ValidateComments(ZipArchive zip, ValidationResult result)
+    {
+        var commentFiles = new[] { "word/comments.xml", "word/commentsExtended.xml", "word/commentsIds.xml", "word/commentsExtensible.xml" };
+        var existing = commentFiles.Where(f => zip.GetEntry(f) != null).ToList();
+
+        if (existing.Count > 0 && existing.Count < 4)
+        {
+            var missing = commentFiles.Except(existing);
+            result.Warnings.Add(Warning($"Comments partially present. Missing: {string.Join(", ", missing)}"));
+        }
+
+        if (zip.GetEntry("word/comments.xml") is { } commentsEntry)
+        {
+            var commentsDoc = LoadXml(commentsEntry);
+            var commentIds = commentsDoc.Descendants(W + "comment")
+                .Select(c => (string?)c.Attribute(W + "id"))
+                .Where(id => id != null)
+                .ToHashSet();
+
+            if (zip.GetEntry("word/commentsExtended.xml") is { } extEntry)
+            {
+                var W15 = XNamespace.Get("http://schemas.microsoft.com/office/word/2012/wordml");
+                var extDoc = LoadXml(extEntry);
+                var extIds = extDoc.Descendants(W15 + "commentEx")
+                    .Select(c => (string?)c.Attribute(W15 + "paraId"))
+                    .Where(id => id != null)
+                    .ToHashSet();
+
+                if (commentIds.Count > 0 && extIds.Count == 0)
+                    result.Warnings.Add(Warning("comments.xml has entries but commentsExtended.xml has none"));
+            }
+        }
+    }
+
+    private static XDocument LoadXml(ZipArchiveEntry entry)
+    {
+        using var stream = entry.Open();
+        return XDocument.Load(stream);
+    }
+
+    private static ValidationError Error(string msg) => new() { Message = msg, Severity = "Error" };
+    private static ValidationError Warning(string msg) => new() { Message = msg, Severity = "Warning" };
+}

package/skills/docx-generator/scripts/dotnet/MiniMaxAIDocx.Core/Validation/GateCheckValidator.cs

@@ -0,0 +1,148 @@
+using System.IO.Compression;
+using System.Xml.Linq;
+
+namespace MiniMaxAIDocx.Core.Validation;
+
+public class GateCheckResult
+{
+    public bool Passed => Violations.Count == 0;
+    public List<string> Violations { get; set; } = new();
+}
+
+public class GateCheckValidator
+{
+    private static readonly XNamespace W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+
+    public GateCheckResult Validate(string outputDocxPath, string templateDocxPath)
+    {
+        var result = new GateCheckResult();
+
+        var templateStyles = ExtractStyles(templateDocxPath);
+        var outputStyles = ExtractStyles(outputDocxPath);
+        var templateSectPr = ExtractSectionProperties(templateDocxPath);
+        var outputSectPr = ExtractSectionProperties(outputDocxPath);
+
+        // All template styles must exist in output
+        foreach (var style in templateStyles)
+        {
+            if (!outputStyles.Contains(style))
+                result.Violations.Add($"Missing style: '{style}' defined in template but absent from output");
+        }
+
+        // Page margins must match
+        if (templateSectPr.Margins != null && outputSectPr.Margins != null)
+        {
+            var tm = templateSectPr.Margins;
+            var om = outputSectPr.Margins;
+            if (tm.Top != om.Top || tm.Bottom != om.Bottom || tm.Left != om.Left || tm.Right != om.Right)
+                result.Violations.Add($"Page margins mismatch: template=({tm.Top},{tm.Bottom},{tm.Left},{tm.Right}) output=({om.Top},{om.Bottom},{om.Left},{om.Right})");
+        }
+
+        // Page size must match
+        if (templateSectPr.PageWidth != outputSectPr.PageWidth || templateSectPr.PageHeight != outputSectPr.PageHeight)
+            result.Violations.Add($"Page size mismatch: template=({templateSectPr.PageWidth}x{templateSectPr.PageHeight}) output=({outputSectPr.PageWidth}x{outputSectPr.PageHeight})");
+
+        // Default font must match
+        var templateFont = ExtractDefaultFont(templateDocxPath);
+        var outputFont = ExtractDefaultFont(outputDocxPath);
+        if (templateFont != null && outputFont != null && templateFont != outputFont)
+            result.Violations.Add($"Default font mismatch: template='{templateFont}' output='{outputFont}'");
+
+        // Heading font hierarchy consistency
+        ValidateHeadingFontHierarchy(outputDocxPath, result);
+
+        return result;
+    }
+
+    private HashSet<string> ExtractStyles(string docxPath)
+    {
+        using var zip = ZipFile.OpenRead(docxPath);
+        var entry = zip.GetEntry("word/styles.xml");
+        if (entry == null) return new();
+
+        using var stream = entry.Open();
+        var doc = XDocument.Load(stream);
+        return doc.Descendants(W + "style")
+            .Select(s => (string?)s.Attribute(W + "styleId"))
+            .Where(id => id != null)
+            .ToHashSet()!;
+    }
+
+    private record SectionProps(int PageWidth, int PageHeight, MarginInfo? Margins);
+    private record MarginInfo(int Top, int Bottom, int Left, int Right);
+
+    private SectionProps ExtractSectionProperties(string docxPath)
+    {
+        using var zip = ZipFile.OpenRead(docxPath);
+        var entry = zip.GetEntry("word/document.xml")!;
+        using var stream = entry.Open();
+        var doc = XDocument.Load(stream);
+
+        var sectPr = doc.Descendants(W + "sectPr").LastOrDefault();
+        if (sectPr == null) return new(0, 0, null);
+
+        int.TryParse((string?)sectPr.Element(W + "pgSz")?.Attribute(W + "w"), out var pw);
+        int.TryParse((string?)sectPr.Element(W + "pgSz")?.Attribute(W + "h"), out var ph);
+
+        var pgMar = sectPr.Element(W + "pgMar");
+        MarginInfo? margins = null;
+        if (pgMar != null)
+        {
+            int.TryParse((string?)pgMar.Attribute(W + "top"), out var t);
+            int.TryParse((string?)pgMar.Attribute(W + "bottom"), out var b);
+            int.TryParse((string?)pgMar.Attribute(W + "left"), out var l);
+            int.TryParse((string?)pgMar.Attribute(W + "right"), out var r);
+            margins = new(t, b, l, r);
+        }
+
+        return new(pw, ph, margins);
+    }
+
+    private string? ExtractDefaultFont(string docxPath)
+    {
+        using var zip = ZipFile.OpenRead(docxPath);
+        var entry = zip.GetEntry("word/styles.xml");
+        if (entry == null) return null;
+
+        using var stream = entry.Open();
+        var doc = XDocument.Load(stream);
+
+        var defaultStyle = doc.Descendants(W + "style")
+            .FirstOrDefault(s => (string?)s.Attribute(W + "type") == "paragraph"
+                && (string?)s.Attribute(W + "default") == "1");
+
+        return (string?)defaultStyle?.Descendants(W + "rFonts").FirstOrDefault()?.Attribute(W + "ascii");
+    }
+
+    private void ValidateHeadingFontHierarchy(string docxPath, GateCheckResult result)
+    {
+        using var zip = ZipFile.OpenRead(docxPath);
+        var entry = zip.GetEntry("word/styles.xml");
+        if (entry == null) return;
+
+        using var stream = entry.Open();
+        var doc = XDocument.Load(stream);
+
+        var headingSizes = new SortedDictionary<int, int>();
+        foreach (var style in doc.Descendants(W + "style"))
+        {
+            var id = (string?)style.Attribute(W + "styleId");
+            if (id == null || !id.StartsWith("Heading", StringComparison.OrdinalIgnoreCase)) continue;
+
+            var numPart = id.AsSpan(7);
+            if (!int.TryParse(numPart, out var level)) continue;
+
+            var sz = (string?)style.Descendants(W + "sz").FirstOrDefault()?.Attribute(W + "val");
+            if (sz != null && int.TryParse(sz, out var hps))
+                headingSizes[level] = hps;
+        }
+
+        int prevSize = int.MaxValue;
+        foreach (var (level, size) in headingSizes)
+        {
+            if (size > prevSize)
+                result.Violations.Add($"Heading{level} ({size / 2}pt) is larger than a higher-level heading ({prevSize / 2}pt)");
+            prevSize = size;
+        }
+    }
+}

package/skills/docx-generator/scripts/dotnet/MiniMaxAIDocx.Core/Validation/ValidationResult.cs

@@ -0,0 +1,23 @@
+namespace MiniMaxAIDocx.Core.Validation;
+
+public class ValidationResult
+{
+    public bool IsValid => Errors.Count == 0;
+    public List<ValidationError> Errors { get; set; } = new();
+    public List<ValidationError> Warnings { get; set; } = new();
+
+    public void Merge(ValidationResult other)
+    {
+        Errors.AddRange(other.Errors);
+        Warnings.AddRange(other.Warnings);
+    }
+}
+
+public class ValidationError
+{
+    public int LineNumber { get; set; }
+    public int LinePosition { get; set; }
+    public string Element { get; set; } = "";
+    public string Message { get; set; } = "";
+    public string Severity { get; set; } = "Error";
+}

package/skills/docx-generator/scripts/dotnet/MiniMaxAIDocx.Core/Validation/XsdValidator.cs

@@ -0,0 +1,69 @@
+using System.IO.Compression;
+using System.Xml;
+using System.Xml.Schema;
+
+namespace MiniMaxAIDocx.Core.Validation;
+
+public class XsdValidator
+{
+    public ValidationResult Validate(string docxPath, string xsdPath)
+    {
+        using var zip = ZipFile.OpenRead(docxPath);
+        var entry = zip.GetEntry("word/document.xml")
+            ?? throw new InvalidOperationException("DOCX does not contain word/document.xml");
+
+        using var stream = entry.Open();
+        using var reader = new StreamReader(stream);
+        var xmlContent = reader.ReadToEnd();
+
+        return ValidateXml(xmlContent, xsdPath);
+    }
+
+    public ValidationResult ValidateXml(string xmlContent, string xsdPath)
+    {
+        var result = new ValidationResult();
+        var settings = new XmlReaderSettings();
+
+        var schemaSet = new XmlSchemaSet();
+        schemaSet.Add(null, xsdPath);
+        settings.Schemas = schemaSet;
+        settings.ValidationType = ValidationType.Schema;
+        settings.ValidationFlags |= XmlSchemaValidationFlags.ReportValidationWarnings;
+
+        settings.ValidationEventHandler += (sender, e) =>
+        {
+            var error = new ValidationError
+            {
+                LineNumber = e.Exception?.LineNumber ?? 0,
+                LinePosition = e.Exception?.LinePosition ?? 0,
+                Message = e.Message,
+                Severity = e.Severity == XmlSeverityType.Warning ? "Warning" : "Error"
+            };
+
+            if (e.Severity == XmlSeverityType.Warning)
+                result.Warnings.Add(error);
+            else
+                result.Errors.Add(error);
+        };
+
+        using var stringReader = new StringReader(xmlContent);
+        using var xmlReader = XmlReader.Create(stringReader, settings);
+
+        try
+        {
+            while (xmlReader.Read()) { }
+        }
+        catch (XmlException ex)
+        {
+            result.Errors.Add(new ValidationError
+            {
+                LineNumber = ex.LineNumber,
+                LinePosition = ex.LinePosition,
+                Message = $"XML parse error: {ex.Message}",
+                Severity = "Error"
+            });
+        }
+
+        return result;
+    }
+}

package/skills/docx-generator/scripts/dotnet/MiniMaxAIDocx.slnx

@@ -0,0 +1,4 @@
+<Solution>
+  <Project Path="MiniMaxAIDocx.Cli/MiniMaxAIDocx.Cli.csproj" />
+  <Project Path="MiniMaxAIDocx.Core/MiniMaxAIDocx.Core.csproj" />
+</Solution>

package/skills/docx-generator/scripts/env_check.sh

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+# minimax-docx Quick Environment Check
+# Cross-platform: macOS, Linux, WSL, Git Bash
+# Run this BEFORE any minimax-docx operation. Use setup.sh for initial installation.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+DOTNET_DIR="$SCRIPT_DIR/dotnet"
+
+# Force English output for dotnet CLI
+export DOTNET_CLI_UI_LANGUAGE=en
+
+echo "=== minimax-docx Environment Check ==="
+echo ""
+
+STATUS="READY"
+WARNINGS=0
+
+# --- Detect platform ---
+OS="unknown"
+case "$(uname -s)" in
+    Darwin)  OS="macos" ;;
+    Linux)
+        OS="linux"
+        grep -qi microsoft /proc/version 2>/dev/null && OS="wsl"
+        ;;
+    MINGW*|MSYS*|CYGWIN*) OS="windows-shell" ;;
+esac
+
+# --- Critical: .NET SDK ---
+if ! command -v dotnet &>/dev/null; then
+    printf "[FAIL]    %-14s not found\n" "dotnet"
+    echo ""
+    echo "  .NET SDK is REQUIRED. Install it:"
+    case "$OS" in
+        macos)   echo "    brew install --cask dotnet-sdk" ;;
+        linux|wsl)
+            echo "    # Option 1: Microsoft install script"
+            echo "    wget https://dot.net/v1/dotnet-install.sh -O /tmp/dotnet-install.sh"
+            echo "    chmod +x /tmp/dotnet-install.sh && /tmp/dotnet-install.sh --channel 8.0"
+            echo "    # Option 2 (Ubuntu/Debian): sudo apt-get install -y dotnet-sdk-8.0"
+            ;;
+        windows-shell) echo "    winget install Microsoft.DotNet.SDK.8" ;;
+        *) echo "    https://dotnet.microsoft.com/download" ;;
+    esac
+    echo ""
+    echo "  Or run the full setup: bash scripts/setup.sh"
+    echo ""
+    STATUS="NOT READY"
+else
+    local_ver=$(dotnet --version 2>/dev/null || echo "0.0.0")
+    local_major="${local_ver%%.*}"
+    if [ "$local_major" -ge 8 ] 2>/dev/null; then
+        printf "[OK]      %-14s %s (>= 8.0)\n" "dotnet" "$local_ver"
+    else
+        printf "[FAIL]    %-14s %s (requires >= 8.0)\n" "dotnet" "$local_ver"
+        STATUS="NOT READY"
+    fi
+fi
+
+# --- Critical: NuGet packages ---
+if [ -d "$DOTNET_DIR" ]; then
+    if [ -f "$DOTNET_DIR/MiniMaxAIDocx.Cli/bin/Debug/net10.0/MiniMaxAIDocx.Cli.dll" ] || \
+       [ -f "$DOTNET_DIR/MiniMaxAIDocx.Cli/bin/Debug/net8.0/MiniMaxAIDocx.Cli.dll" ]; then
+        printf "[OK]      %-14s built\n" "project"
+    else
+        # Try restore + build
+        if dotnet restore "$DOTNET_DIR" --verbosity quiet &>/dev/null; then
+            printf "[OK]      %-14s packages restored\n" "nuget"
+            if dotnet build "$DOTNET_DIR" --verbosity quiet --no-restore &>/dev/null; then
+                printf "[OK]      %-14s build succeeded\n" "project"
+            else
+                printf "[FAIL]    %-14s build failed (run: dotnet build %s)\n" "project" "$DOTNET_DIR"
+                STATUS="NOT READY"
+            fi
+        else
+            printf "[FAIL]    %-14s restore failed\n" "nuget"
+            echo ""
+            echo "  Common causes:"
+            echo "    - No internet access (NuGet needs to download packages)"
+            echo "    - Corporate proxy blocking nuget.org"
+            echo "    - SSL certificate issues (try: dotnet nuget list source)"
+            echo ""
+            STATUS="NOT READY"
+        fi
+    fi
+else
+    printf "[FAIL]    %-14s directory not found: %s\n" "project" "$DOTNET_DIR"
+    STATUS="NOT READY"
+fi
+
+# --- Optional: pandoc ---
+if command -v pandoc &>/dev/null; then
+    pandoc_ver=$(pandoc --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1 || echo "?")
+    printf "[OK]      %-14s %s (content preview)\n" "pandoc" "$pandoc_ver"
+else
+    printf "[WARN]    %-14s not found — docx_preview.sh will use fallback\n" "pandoc"
+    WARNINGS=$((WARNINGS + 1))
+    case "$OS" in
+        macos)        echo "           Install: brew install pandoc" ;;
+        linux|wsl)    echo "           Install: sudo apt-get install pandoc  # or dnf/pacman" ;;
+        windows-shell) echo "           Install: winget install JohnMacFarlane.Pandoc" ;;
+    esac
+fi
+
+# --- Optional: LibreOffice ---
+if command -v soffice &>/dev/null; then
+    soffice_ver=$(soffice --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1 || echo "?")
+    printf "[OK]      %-14s %s (.doc conversion)\n" "soffice" "$soffice_ver"
+else
+    # Check common paths
+    soffice_found=false
+    for p in \
+        "/Applications/LibreOffice.app/Contents/MacOS/soffice" \
+        "/usr/lib/libreoffice/program/soffice" \
+        "/snap/bin/libreoffice" \
+        "/opt/libreoffice/program/soffice"; do
+        if [ -x "$p" ]; then
+            printf "[OK]      %-14s found at %s (.doc conversion)\n" "soffice" "$p"
+            soffice_found=true
+            break
+        fi
+    done
+    if ! $soffice_found; then
+        printf "[WARN]    %-14s not found — .doc files cannot be converted\n" "soffice"
+        WARNINGS=$((WARNINGS + 1))
+        case "$OS" in
+            macos)        echo "           Install: brew install --cask libreoffice" ;;
+            linux|wsl)    echo "           Install: sudo apt-get install libreoffice-core" ;;
+            windows-shell) echo "           Install: winget install TheDocumentFoundation.LibreOffice" ;;
+        esac
+    fi
+fi
+
+# --- Optional: zip/unzip ---
+zip_ok=true
+if ! command -v zip &>/dev/null; then
+    printf "[WARN]    %-14s not found (optional, .NET handles DOCX natively)\n" "zip"
+    zip_ok=false
+    WARNINGS=$((WARNINGS + 1))
+fi
+if ! command -v unzip &>/dev/null; then
+    printf "[WARN]    %-14s not found (optional, .NET handles DOCX natively)\n" "unzip"
+    zip_ok=false
+    WARNINGS=$((WARNINGS + 1))
+fi
+if $zip_ok; then
+    printf "[OK]      %-14s available\n" "zip/unzip"
+fi
+
+# --- Encoding check ---
+current_lang="${LANG:-}"
+if [ -n "$current_lang" ] && echo "$current_lang" | grep -qi "utf-8\|utf8"; then
+    printf "[OK]      %-14s %s\n" "locale" "$current_lang"
+else
+    if [ -z "$current_lang" ]; then
+        printf "[WARN]    %-14s LANG not set (CJK text may have issues)\n" "locale"
+    else
+        printf "[WARN]    %-14s %s (not UTF-8, CJK text may have issues)\n" "locale" "$current_lang"
+    fi
+    WARNINGS=$((WARNINGS + 1))
+    echo "           Fix: export LANG=en_US.UTF-8"
+fi
+
+# --- Shell script permissions ---
+perm_issues=0
+for s in "$SCRIPT_DIR"/*.sh; do
+    if [ -f "$s" ] && [ ! -x "$s" ]; then
+        perm_issues=$((perm_issues + 1))
+    fi
+done
+if [ "$perm_issues" -gt 0 ]; then
+    printf "[WARN]    %-14s %d script(s) not executable\n" "permissions" "$perm_issues"
+    echo "           Fix: chmod +x scripts/*.sh"
+    WARNINGS=$((WARNINGS + 1))
+else
+    printf "[OK]      %-14s all scripts executable\n" "permissions"
+fi
+
+# --- Result ---
+echo ""
+if [ "$STATUS" = "READY" ]; then
+    if [ "$WARNINGS" -gt 0 ]; then
+        echo "Status: READY (with $WARNINGS warning(s) — optional features may be limited)"
+    else
+        echo "Status: READY"
+    fi
+else
+    echo "Status: NOT READY"
+    echo ""
+    echo "Critical dependencies missing. Run the full setup:"
+    echo "  bash scripts/setup.sh          # macOS / Linux / WSL"
+    echo "  powershell scripts/setup.ps1   # Windows PowerShell"
+    exit 1
+fi