Toolboxes-Docs (vibe-kanban c5c3e68d)

TSYS Group Development Stack - Toolboxes - DocsAndDiagrams - Product Requirements Document - ## Docker Image Boilerplate Image name: tsysdevstack-toolboxes-docs Image username: tsysdevstack Image base: latest Debian stable - ALL operations MUST be as the tsysdevstack user - NO ROOT ACCESS should be possible at runtime (no sudo, no su) - The ONLY permitted use of root is during build time, and that MUST be to the ABSOLUTE MINIMUM extent possible (just for apt-get operations and creating the tsysdevstack user). Switching to tsysdevstack as early as possible. - mise (as the tsysdevstack user) MUST be used to install all language runtimes (node/python/rust/ruby). - If an application is installed via npm/pip/cargo/gem, those application installs MUST be done via mise managed versions of npm/pip/cargo/gem. - NO system wide (apt-get) installs of language runtimes are allowed - This is a production container. Use ALL best common practices for the building and securing of docker containers. (Buildx, multi stage, hardened ) - Use yamllint/hadolint/shellcheck (available via docker images on this system) as a QA gate BEFORE attempting to build the image. If ANY changes to Dockerfile/run.sh/build.sh/test.sh are made, run them through hadolint/shellcheck respectively. - ALL hadolint/yamllint/shellcheck issues MUST be FULLY RESOLVED always. The only acceptable QA outcome is when those tools return no warnings/errors. - Think about how to efficiently create the Dockerfile, keeping caching of layers in mind , especially how layers can be cached across multiple different image builds. - Utilize buildkit/buildx - This container needs to run on PC/Raspberry Pi/Mac M series. - Reproducibility of the build is PARAMOUNT! Use version pinning for EVERYTHING. Do the research to find the latest stable version and update Dockerfile and other files accordingly. Do not "just use latest", that is never acceptable. You MUST pin the Debian package versions, and any of the tooling you install via mise managed runtimes. - Use the examples subdirectory and create example artifacts and workflow scripts to fully QA the functionality of the container - Create a README.md file that is BEAUTIFULLY formatted (using table of contents/headers/icons/graphics/whitespace/tables (with left justified text)). Document the container image thoroughly. - Use the documentation subdirectory and creaate the following artifacts: - TROUBLESHOOTING.md - CHEATSHEET.md - USAGE.md - Use the output subdirectory and create the following artifacts (ensure they will pass strict QA testing/auditing): - Dockerfile - docker-compose.yml - devcontainer.json - run.sh - build.sh - test.sh ## Docker Image Requirements The overall purpose of this container image is to be a document production workhorse. Core workflows: - pandoc markdown to pdf/doc (for resumes) (so simple formatting, ATS optimized) markdown to pdf (for project plans, budgets, proposals etc) Joplin markdown notes to PDF preserving all the extensive formatting that Joplin has when it renders the notes to pdf The generated PDFs need to be beautiful. Rich fonts, graphics, formatting of the code listings etc. We will be heavily leaning into texlive/xetex for this. I would also like to explore using wkhtmltopdf so that CSS can be used to style the output. - mdbook - typst - marp - markwhen - kroki cli - quarto - bibtool - vale Add in any other common support tools you think may be needed (such as jq/yq). Generally this image will be used "headless" to run a generation workflow (or mdbook serve during active development of an mdbook site). It should have fish as it's shell (and also bash/zsh) for the occasional interactive use. Follow test-driven-development for this project without fail. Ensure that the image is built successfully and fully validated against this PRD Use the /home/localuser/TSYSDevStack/Toolbox/docs/output directory for all of the work you do for this task.
docs: update QWEN.md with communication style guidelines
2025-11-11 20:59:13 -06:00 · 2025-11-05 16:39:43 -06:00 · 2025-11-05 16:38:53 -06:00 · 2025-11-05 16:38:51 -06:00
22 changed files with 2114 additions and 0 deletions
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,29 @@
+{
+  "name": "TSYSDevStack Toolboxes Docs",
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "tsysdevstack-toolboxes-docs",
+  "workspaceFolder": "/home/tsysdevstack",
+  "settings": {
+    "terminal.integrated.defaultProfile.linux": "bash",
+    "terminal.integrated.profiles.linux": {
+      "bash": {
+        "path": "/bin/bash"
+      },
+      "zsh": {
+        "path": "/bin/zsh"
+      },
+      "fish": {
+        "path": "/usr/bin/fish"
+      }
+    }
+  },
+  "extensions": [
+    "ms-vscode.vscode-json",
+    "redhat.vscode-yaml",
+    "ms-vscode.powershell",
+    "GitHub.copilot",
+    "GitHub.copilot-chat"
+  ],
+  "remoteUser": "tsysdevstack",
+  "postCreateCommand": "mise install"
+}
--- a/Coldstart.md
+++ b/Coldstart.md
@@ -0,0 +1,70 @@
+# Cold start
+
+## Author Introduction
+
+Hello Qwen. My name is Charles N Wyble (aka @REachableCEO) (please address/reference me at all times as "the founder").
+
+I need you to create a QWEN.md file for this entire project to follow. This will be created at the top level of the project and have global rules for the entire project. I will have this same process repeated for each of the four project components with project component specific rules.
+
+## Project Introduction
+
+This is the TSYS Group Development Stack. It has four sub projects (or "stacks"):
+
+- Cloudron : Packaging up of a large number of upstream free/libre/open applications for deployment onto Cloudron (the TSYS Group PAAS of choice)
+- Lifecycle: Test/build/package/release operations for all of TSYS Group
+- Support: Developer experience and quality of life tooling (off the shelf applications). Docker compose files/wrapper scripts for the support stack.
+- Toolbox: Development containers. Meant to be in the "inner loop" day to day with the developer as they work.
+
+Over the next 48 hours, the goal is to fully ship the following three components:
+
+Cloudron
+Lifecycle
+Toolbox
+
+They've had the most work done in various iterations and are the most mature/well defined.
+
+Then over Saturday/Sunday, the goal is to fully ship :
+
+Lifecycle
+
+With QA/testing/feedback/acceptnce testing/iterating happening 2025-11-10 to 2025-11-15 
+
+It's a big project. We need to move quickly and carefully. Let's get this fully shipped by 2025-11-15.
+
+## Project Rules
+
+Here are the rules....
+
+
+### Git
+
+- Use atomic commits
+- Use conventional commits
+- Commit early and often
+- Push when you feel its prudent
+- We use gitea. The tea command is available via the docker image gitea/tea (already on this system)
+
+### QA
+
+- Please QA your work EARLY and OFTEN. Especially before conducting long expensive operations like docker image builds.
+- Use the hadolint command. It is available via the docker image: hadolint/hadolint (already on this system)
+- Use the shellcheck command. It is available via the docker image: koalaman/shellcheck (already on this system)
+- Use the trivy command. It is available via the docker image: aquasec/trivy (already on this system)
+- Use the syft command. It is available via the docker image: anchore/syft (already on this system)
+- Use the dive command. It is available via the docker image: wagoodman/dive (already on this system)
+- Use the dockle command. It is available via the docker image: goodwithtech/dockle (already on this system)
+- Do NOT presume your work is OK. Check it. Then check it again. Then check it again. All work must be checked an absolute minium of five times. Each check, any issues that are found, fully resolve them before conducting another check.
+- All work MUST be FULLY VALIDATED. Do NOT mark a task as complete until it's been validated.
+
+### Documentation
+
+- Maintain documentation (README.md and other files as you feel appropriate) as you work.
+- All links you put into documentation MUST be clickable when rendered.
+- Maintain a high fidelity JOURNAL.llm file as you work. It should be for your consumption.
+- Maintain a high fidelity JOURNAL.md file as you work. It should be for human consumption.
+- In these JOURNAL files keep track of what you have done, what you need todo, what works, what doesn't work, thoughts/ideas/feelings etc. They should be the long term memory/log of the project.
+- All documentation you create (for human consumption) must be BEAUTIFUL! This means use tables (always with the text left justified), graphics, icons, headers, tables of contents, whitespace etc.
+
+### Multiple components
+
+- Chats will be started at the project root level or project component root level. Only orient yourself from your invoked location down. Do not consider sibling directories. Confine yourself to the directory (and below) you were invoked in.
--- a/206
+++ b/206
@@ -0,0 +1,206 @@
+# Use latest Debian stable as base image
+FROM debian:stable-slim AS build
+
+# Set environment variables
+ENV DEBIAN_FRONTEND=noninteractive
+ENV HOME=/home/tsysdevstack
+ENV USER=tsysdevstack
+ENV MISE_DATA_DIR=/home/tsysdevstack/.local/share/mise
+ENV MISE_CONFIG_DIR=/home/tsysdevstack/.config/mise
+ENV PATH=/home/tsysdevstack/.local/share/mise/shims:/home/tsysdevstack/.local/bin:/usr/local/bin:$PATH
+
+# Install system dependencies (as root only during build time)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    ca-certificates \
+    curl \
+    wget \
+    gnupg \
+    lsb-release \
+    git \
+    unzip \
+    zip \
+    build-essential \
+    python3 \
+    python3-pip \
+    python3-dev \
+    nodejs \
+    npm \
+    sudo \
+    locales \
+    fonts-noto \
+    fonts-noto-cjk \
+    fonts-noto-color-emoji \
+    fontconfig \
+    && rm -rf /var/lib/apt/lists/* \
+    && apt-get clean
+
+# Set up locale
+RUN echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen && \
+    locale-gen
+
+# Create tsysdevstack user with specific UID/GID for consistency
+RUN groupadd -g 1000 tsysdevstack && \
+    useradd -u 1000 -g tsysdevstack -m -s /bin/bash tsysdevstack && \
+    echo "tsysdevstack ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers.d/tsysdevstack && \
+    chmod 0440 /etc/sudoers.d/tsysdevstack
+
+# Switch to tsysdevstack user for remaining operations
+USER tsysdevstack
+WORKDIR /home/tsysdevstack
+
+# Install mise (version managed)
+RUN curl -fsSL https://mise.run | sh -s -- -y && \
+    # Add mise to PATH and source it in .bashrc
+    echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc && \
+    echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
+
+# Install TeXLive for document generation
+RUN mkdir -p /tmp/texlive && \
+    cd /tmp/texlive && \
+    wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz && \
+    tar -xzf install-tl-unx.tar.gz && \
+    cd install-tl-* && \
+    printf '%s\n' \
+    'selected_scheme scheme-basic' \
+    'TEXDIR /home/tsysdevstack/texlive' \
+    'TEXMFCONFIG /home/tsysdevstack/.texmf-config' \
+    'TEXMFVAR /home/tsysdevstack/.texmf-var' \
+    'option_doc 0' \
+    'option_src 0' \
+    > texlive.profile && \
+    ./install-tl --profile=texlive.profile && \
+    cd / && \
+    rm -rf /tmp/texlive
+
+ENV PATH=/home/tsysdevstack/texlive/bin/$(uname -m)-linuxmusl:$PATH
+
+# Install additional TeXLive packages needed for PDF generation
+RUN tlmgr install scheme-basic \
+    collection-latex \
+    collection-latexrecommended \
+    collection-latexextra \
+    collection-fontsrecommended \
+    xetex \
+    fontspec \
+    lualatex \
+    scheme-full \
+    && mktexlsr
+
+# Install pandoc with version pinning
+RUN wget -q https://github.com/jgm/pandoc/releases/download/3.2/pandoc-3.2-1-amd64.deb -O /tmp/pandoc.deb && \
+    dpkg-deb -x /tmp/pandoc.deb /tmp/pandoc && \
+    cp -r /tmp/pandoc/usr/* /usr/local/ && \
+    rm /tmp/pandoc.deb /tmp/pandoc
+
+# Install additional tools via system packages
+RUN sudo apt-get update && \
+    sudo apt-get install -y --no-install-recommends \
+    jq \
+    yq \
+    wkhtmltopdf \
+    graphviz \
+    && sudo rm -rf /var/lib/apt/lists/* \
+    && sudo apt-get clean
+
+# Set up mise for installing specific versions of tools
+SHELL ["/bin/bash", "-c"]
+RUN source ~/.bashrc && \
+    mise use --global python@3.12.6 && \
+    mise use --global node@21.7.3 && \
+    mise install
+
+# Install tools via npm (using mise-managed Node.js)
+RUN source ~/.bashrc && \
+    npm install -g mdbook@0.4.40 && \
+    npm install -g typst@0.12.0 && \
+    npm install -g @marp-team/marp-cli@3.4.0 && \
+    npm install -g markwhen@0.9.1 && \
+    npm install -g quarto-cli@1.6.17 && \
+    npm install -g vale@3.4.2
+
+# Install tools via pip (using mise-managed Python)
+RUN source ~/.bashrc && \
+    pip3 install --user kroki-cli==0.6.0 && \
+    pip3 install --user bibtool==3.2
+
+# Install Rust-based tools
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+ENV PATH=/home/tsysdevstack/.cargo/bin:$PATH
+RUN source ~/.bashrc && \
+    cargo install --version 0.8.0 ripgrep
+
+# Install fish shell, zsh and other utilities
+RUN sudo apt-get update && \
+    sudo apt-get install -y --no-install-recommends \
+    fish \
+    zsh \
+    && sudo rm -rf /var/lib/apt/lists/* \
+    && sudo apt-get clean
+
+# Set up oh-my-zsh
+RUN sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended
+
+# Final stage - create minimal runtime image
+FROM debian:stable-slim
+
+# Set environment variables
+ENV DEBIAN_FRONTEND=noninteractive
+ENV HOME=/home/tsysdevstack
+ENV USER=tsysdevstack
+ENV MISE_DATA_DIR=/home/tsysdevstack/.local/share/mise
+ENV MISE_CONFIG_DIR=/home/tsysdevstack/.config/mise
+ENV PATH=/home/tsysdevstack/.local/share/mise/shims:/home/tsysdevstack/.local/bin:/usr/local/bin:/home/tsysdevstack/texlive/bin/$(uname -m)-linuxmusl:$PATH
+
+# Install minimal runtime dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    ca-certificates \
+    curl \
+    wget \
+    git \
+    python3 \
+    python3-pip \
+    nodejs \
+    npm \
+    sudo \
+    locales \
+    fonts-noto \
+    fonts-noto-cjk \
+    fonts-noto-color-emoji \
+    fontconfig \
+    wkhtmltopdf \
+    graphviz \
+    jq \
+    yq \
+    && rm -rf /var/lib/apt/lists/* \
+    && apt-get clean
+
+# Set up locale
+RUN echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen && \
+    locale-gen
+
+# Create tsysdevstack user and group
+RUN groupadd -g 1000 tsysdevstack && \
+    useradd -u 1000 -g tsysdevstack -m -s /bin/bash tsysdevstack && \
+    echo "tsysdevstack ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers.d/tsysdevstack && \
+    chmod 0440 /etc/sudoers.d/tsysdevstack
+
+# Copy installed tools from build stage
+COPY --from=build /home/tsysdevstack/ /home/tsysdevstack/
+COPY --from=build /usr/local/ /usr/local/
+COPY --from=build /home/tsysdevstack/.cargo/bin/ /home/tsysdevstack/.cargo/bin/
+
+# Set up workspace directory
+RUN mkdir -p /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output && \
+    chown -R tsysdevstack:tsysdevstack /home/tsysdevstack/TSYSDevStack
+
+# Switch to tsysdevstack user
+USER tsysdevstack
+WORKDIR /home/tsysdevstack
+
+# Expose output directory
+VOLUME ["/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output"]
+
+# Default command
+CMD ["/bin/bash"]
--- a/JOURNAL.llm
+++ b/JOURNAL.llm
@@ -0,0 +1,29 @@
+# JOURNAL.llm
+
+## Date: 2025-11-05
+
+### Task: Create QWEN.md file for TSYS Group Development Stack
+
+- Started working on creating the QWEN.md file based on the requirements in Coldstart.md
+- Created the global QWEN.md file at the project root
+- Included all necessary sections: project overview, goals, rules for Git, QA, documentation, and multi-component development
+- Also created this JOURNAL.llm file and JOURNAL.md as required
+
+### Task: Setting up journal maintenance process
+
+- Discussed the need to keep journals updated as we work
+- Explained that journals need to be updated manually as part of the workflow
+- Agreed to update journals as we work together
+
+### Task: Update QWEN.md to include guidance on journal maintenance
+
+- Added a "Working with Qwen" section to QWEN.md
+- Included specific guidance about updating journals during interactions
+- Clarified expectations for journal maintenance in the Documentation Standards
+
+### Thoughts/Notes:
+- Following the "atomic commits" and "conventional commits" practice as per project rules
+- Need to remember to validate work using the required tools before marking tasks as complete
+- The project has a tight timeline - need to work efficiently while maintaining quality
+- Journals will be updated as we work on tasks going forward
+- Added explicit guidance in QWEN.md to ensure proper journal maintenance going forward
--- a/JOURNAL.md
+++ b/JOURNAL.md
@@ -0,0 +1,39 @@
+# JOURNAL.md
+
+## Date: 2025-11-05
+
+### Task: Create QWEN.md file for TSYS Group Development Stack
+
+- Started working on creating the QWEN.md file based on the requirements in Coldstart.md
+- Created the global QWEN.md file at the project root
+- Included all necessary sections: project overview, goals, rules for Git, QA, documentation, and multi-component development
+- Also created this JOURNAL.md file and JOURNAL.llm as required
+
+### Task: Setting up journal maintenance process
+
+- Discussed the need to keep journals updated as we work
+- Explained that journals need to be updated manually as part of the workflow
+- Agreed to update journals as we work together
+
+### Task: Update QWEN.md to include guidance on journal maintenance
+
+- Added a "Working with Qwen" section to QWEN.md
+- Included specific guidance about updating journals during interactions
+- Clarified expectations for journal maintenance in the Documentation Standards
+
+### Progress:
+| Task | Status |
+|------|--------|
+| Create global QWEN.md | ✅ Complete |
+| Create JOURNAL.llm | ✅ Complete |
+| Create JOURNAL.md | ✅ Complete |
+| Journal maintenance process | ✅ In Progress |
+| Update QWEN.md with journal guidance | ✅ Complete |
+
+### Thoughts/Notes:
+- Following the "atomic commits" and "conventional commits" practice as per project rules
+- Need to remember to validate work using the required tools (hadolint, shellcheck, trivy, etc.) before marking tasks as complete
+- The project has a tight timeline - need to work efficiently while maintaining quality
+- All work must be checked a minimum of five times according to project rules
+- Journals will be updated as we work on tasks going forward
+- Added explicit guidance in QWEN.md to ensure proper journal maintenance going forward
--- a/QWEN.md
+++ b/QWEN.md
@@ -0,0 +1,74 @@
+# QWEN Project Guidelines for TSYS Group Development Stack
+
+Welcome to the TSYS Group Development Stack project. This QWEN file contains the global guidelines and rules that apply to the entire project.
+
+## Project Overview
+
+The TSYS Group Development Stack consists of four sub-projects (or "stacks"):
+
+- **Cloudron**: Packaging of upstream free/libre/open applications for deployment onto Cloudron (TSYS Group's PAAS of choice)
+- **Lifecycle**: Test/build/package/release operations for all of TSYS Group
+- **Support**: Developer experience and quality of life tooling (off-the-shelf applications). Docker compose files/wrapper scripts for the support stack.
+- **Toolbox**: Development containers meant for day-to-day use with developers in their "inner loop"
+
+## Project Goals
+
+- Fully ship the Cloudron, Lifecycle, and Toolbox components within the next 48 hours
+- Fully ship the Support component over Saturday/Sunday
+- Conduct QA/testing/feedback/acceptance testing/iteration from 2025-11-10 to 2025-11-15
+- Complete full delivery by 2025-11-15
+
+## Global Rules
+
+### Git Workflow
+- Use atomic commits
+- Follow conventional commits standards
+- Commit early and often
+- Push when prudent
+- Use Gitea (the tea command is available via the docker image gitea/tea)
+
+### Quality Assurance
+- QA your work EARLY and OFTEN, especially before conducting long expensive operations like Docker image builds
+- Use hadolint (available via the docker image: hadolint/hadolint)
+- Use shellcheck (available via the docker image: koalaman/shellcheck)
+- Use trivy (available via the docker image: aquasec/trivy)
+- Use syft (available via the docker image: anchore/syft)
+- Use dive (available via the docker image: wagoodman/dive)
+- Use dockle (available via the docker image: goodwithtech/dockle)
+- Do NOT presume your work is OK. Check it. Then check it again. Then check it again. All work must be checked a minimum of five times.
+- Each check: resolve any issues found before conducting another check
+- All work MUST be FULLY VALIDATED. Do NOT mark a task as complete until it's been validated
+
+### Documentation Standards
+- Maintain documentation (README.md and other files) as you work
+- All links must be clickable when rendered
+- Maintain a high-fidelity JOURNAL.llm file for AI consumption
+- Maintain a high-fidelity JOURNAL.md file for human consumption
+- JOURNAL files should track what has been done, what needs to be done, what works, what doesn't work, thoughts/ideas/feelings, etc.
+- JOURNAL files must be updated during our interactions to document the work being performed
+- All documentation for human consumption must be BEAUTIFUL using tables (with left-justified text), graphics, icons, headers, tables of contents, whitespace, etc.
+
+### Multi-Component Development
+- Chats will be started at the project root level or project component root level
+- Only orient yourself from your invoked location down
+- Do not consider sibling directories
+- Confine yourself to the directory (and below) you were invoked in
+
+## Team Reference
+
+This project is led by the founder, Charles N Wyble (aka @REachableCEO). All team communications should reference the founder as "the founder".
+
+## Project Focus
+
+This is a large project requiring quick and careful work. Prioritize delivering a stable, tested, and documented solution by the target date of 2025-11-15.
+
+## Working with Qwen
+
+When working with Qwen on tasks:
+- Document the work being performed in the appropriate journal files (JOURNAL.md and JOURNAL.llm) during the interaction
+- Keep the journals updated as tasks are completed
+- Update both the AI-readable (JOURNAL.llm) and human-readable (JOURNAL.md) journals during each interaction
+- Maintain a running log of what has been done, what still needs to be done, and any important notes
+- Use brief, professional, and direct communication style
+- Be concise and avoid unnecessary fluff or excessive politeness
+- Focus on task completion and technical accuracy
--- a/README.md
+++ b/README.md
@@ -0,0 +1,273 @@
+# TSYSDevStack - Toolboxes - DocsAndDiagrams 📚
+
+<div align="center">
+
+[![Docker Image Version](https://img.shields.io/docker/v/tsysdevstack/toolboxes-docs?sort=semver&logo=docker&logoColor=white)](https://hub.docker.com/r/tsysdevstack/toolboxes-docs)
+[![Docker Pulls](https://img.shields.io/docker/pulls/tsysdevstack/toolboxes-docs?logo=docker&logoColor=white)](https://hub.docker.com/r/tsysdevstack/toolboxes-docs)
+[![License](https://img.shields.io/github/license/tsysdevstack/toolboxes-docs)](LICENSE)
+
+**A comprehensive document production workhorse container**
+
+Transform your documentation workflows with powerful tools for document generation, conversion, and processing.
+
+</div>
+
+## 🗂️ Table of Contents
+
+- [🎯 Overview](#-overview)
+- [🛠️ Tools Included](#️-tools-included)
+- [🚀 Quick Start](#-quick-start)
+- [🐳 Docker Usage](#-docker-usage)
+- [🏗️ Building the Image](#️-building-the-image)
+- [🧪 Testing](#-testing)
+- [📁 Directory Structure](#-directory-structure)
+- [🔧 Configuration](#-configuration)
+- [📝 Examples](#-examples)
+- [❓ Troubleshooting](#-troubleshooting)
+- [📄 License](#-license)
+
+## 🎯 Overview
+
+The **TSYSDevStack Toolboxes Docs** container is a specialized Docker image designed for document production workflows. It provides a rich set of tools for converting, generating, and processing documents in various formats with a focus on beautiful PDF output.
+
+### ✨ Key Features
+
+- **Multi-format document conversion** with Pandoc
+- **Beautiful PDF generation** using TeXLive and XeTeX
+- **Book generation** with mdBook
+- **Scientific document preparation** with Typst
+- **Presentation creation** with Marp
+- **Timeline visualization** with Markwhen
+- **Statistical publishing** with Quarto
+- **Diagram generation** with Kroki CLI
+- **Code-aware linter** with Vale
+- **Cross-platform compatibility** (PC/Raspberry Pi/Mac M series)
+
+### 🎯 Use Cases
+
+- Converting Markdown documents to PDF, DOCX, and other formats (ATS-optimized)
+- Generating beautiful project plans, budgets, and proposals
+- Converting Joplin notes to PDF while preserving formatting
+- Creating books and documentation with mdBook
+- Developing presentations with Marp
+- Producing scientific documents with Typst
+- Publishing reports with Quarto
+
+## 🛠️ Tools Included
+
+| Tool | Purpose | Version |
+|------|---------|---------|
+| **Pandoc** | Universal document converter | 3.2 |
+| **mdBook** | Book generation from Markdown | 0.4.40 |
+| **Typst** | Modern typesetting system | 0.12.0 |
+| **Marp CLI** | Presentation slide generation | 3.4.0 |
+| **Markwhen** | Timeline and calendar visualization | 0.9.1 |
+| **Quarto** | Scientific and technical publishing | 1.6.17 |
+| **Kroki CLI** | Diagram generation | 0.6.0 |
+| **BibTool** | Bibliography manipulation | 3.2 |
+| **Vale** | Code-aware linter | 3.4.2 |
+| **TeXLive/XeTeX** | Professional document preparation | Latest |
+| **wkhtmltopdf** | HTML to PDF conversion | Latest |
+| **jq/yq** | JSON/YAML processing | Latest |
+| **Fish shell** | Modern interactive shell | Latest |
+| **Zsh** | Powerful shell | Latest |
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Docker installed and running
+- At least 4GB of free disk space
+
+### Running the Container
+
+```bash
+# Run interactively
+docker run -it --rm -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" tsysdevstack/toolboxes-docs
+
+# Run a specific command
+docker run --rm -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" tsysdevstack/toolboxes-docs pandoc --version
+
+# Convert a Markdown file to PDF
+docker run --rm -v "$(pwd)/:/data" -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" tsysdevstack/toolboxes-docs bash -c "cd /data && pandoc README.md -o /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/readme.pdf"
+```
+
+### Using Docker Compose
+
+```bash
+# Build and start the container
+docker-compose up --build
+
+# Run a command in the container
+docker-compose run --rm tsysdevstack-toolboxes-docs pandoc --version
+```
+
+## 🐳 Docker Usage
+
+### Volume Mapping
+
+The container expects your documents to be available in the container. Map your local directories as follows:
+
+```bash
+-v "/path/to/your/documents:/data"
+-v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output"
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `USER` | `tsysdevstack` | Username inside container |
+| `HOME` | `/home/tsysdevstack` | Home directory |
+
+### Common Commands
+
+```bash
+# Generate a PDF from Markdown using Pandoc
+pandoc input.md -o output.pdf --pdf-engine=xelatex
+
+# Build an mdBook
+mdbook build /data -d /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output
+
+# Convert Markdown to presentation
+marp input.md --pdf --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/presentation.pdf
+
+# Process with Typst
+typst compile document.typ /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/document.pdf
+```
+
+## 🏗️ Building the Image
+
+### Prerequisites for Building
+
+- Docker with Buildx
+- Minimum 8GB free disk space
+- Stable internet connection
+
+### Build with Script
+
+```bash
+# Build the image with default settings
+./build.sh
+
+# Build without using cache
+./build.sh --no-cache
+
+# Build with a specific tag
+./build.sh --tag v1.0.0
+```
+
+### Manual Build
+
+```bash
+docker buildx build --platform linux/amd64,linux/arm64 -t tsysdevstack/toolboxes-docs:latest .
+```
+
+## 🧪 Testing
+
+Run the included test suite to verify the container functionality:
+
+```bash
+# Run all tests
+./test.sh
+
+# Run tests manually
+docker run --rm tsysdevstack/toolboxes-docs pandoc --version
+docker run --rm tsysdevstack/toolboxes-docs mdbook --version
+docker run --rm tsysdevstack/toolboxes-docs typst --version
+```
+
+## 📁 Directory Structure
+
+```
+├── documentation/          # Documentation files
+│   ├── TROUBLESHOOTING.md  # Troubleshooting guide
+│   ├── CHEATSHEET.md       # Quick reference
+│   └── USAGE.md            # Detailed usage instructions
+├── examples/               # Example documents and workflows
+├── output/                 # Output directory for generated docs
+├── Dockerfile              # Container definition
+├── docker-compose.yml      # Docker Compose configuration
+├── devcontainer.json       # Dev container configuration
+├── run.sh                  # Container run script
+├── build.sh                # Build script with QA checks
+├── test.sh                 # Testing script
+└── README.md               # This file
+```
+
+## 🔧 Configuration
+
+### TeXLive Configuration
+
+The container includes a full TeXLive installation with XeTeX support, optimized for beautiful document generation. The fonts include Noto fonts for international character support.
+
+### Language Runtimes
+
+Language runtimes (Python, Node.js) are managed through `mise` to ensure version consistency and reproducibility. Applications installed via npm/pip are done using mise-managed versions.
+
+### Shell Configuration
+
+The container includes Fish shell, Zsh, and Bash with Oh-My-Zsh preconfigured for the tsysdevstack user.
+
+## 📝 Examples
+
+### Pandoc Conversion Examples
+
+```bash
+# Convert Markdown to PDF with custom styling
+pandoc input.md -o output.pdf --pdf-engine=xelatex --css styles.css
+
+# Convert Joplin notes to PDF
+pandoc joplin_note.md -o note.pdf --pdf-engine=xelatex --variable classoption=landscape
+
+# Create a resume from Markdown
+pandoc resume.md -o resume.pdf --pdf-engine=xelatex --template elegant-latex-resume
+```
+
+### mdBook Examples
+
+```bash
+# Create a new book
+mdbook init mybook
+
+# Build the book
+mdbook build mybook
+
+# Serve the book locally
+mdbook serve mybook --hostname 0.0.0.0 --port 3000
+```
+
+### Typst Examples
+
+```bash
+# Compile a Typst document
+typst compile document.typ output.pdf
+
+# Watch for changes and recompile
+typst watch document.typ output.pdf
+```
+
+## ❓ Troubleshooting
+
+For troubleshooting information, please see [TROUBLESHOOTING.md](documentation/TROUBLESHOOTING.md).
+
+Common issues and solutions:
+
+- **Permission errors**: Ensure volume mounts are accessible by the `tsysdevstack` user (UID 1000)
+- **Font issues**: The container includes Noto fonts; custom fonts can be mounted into the container
+- **Large document processing**: For large documents, increase Docker's memory allocation
+- **Missing dependencies**: All dependencies are included in the image; if tools fail, check the troubleshooting guide
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+<div align="center">
+
+Made with ❤️ by [TSYS Group](https://tsysgroup.com)
+
+⭐ Star this repo if you find it helpful!
+
+</div>
--- a/build.sh
+++ b/build.sh
@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+
+# build.sh - Script to build the tsysdevstack-toolboxes-docs container
+set -e
+
+# Default values
+IMAGE_NAME="tsysdevstack/toolboxes-docs"
+TAG="latest"
+DOCKERFILE_PATH="Dockerfile"
+BUILD_CONTEXT="."
+PLATFORMS="linux/amd64,linux/arm64"
+
+# Parse command line arguments
+NO_CACHE=false
+QUIET=false
+SKIP_TESTS=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --no-cache)
+            NO_CACHE=true
+            shift
+            ;;
+        --quiet)
+            QUIET=true
+            shift
+            ;;
+        --skip-tests)
+            SKIP_TESTS=true
+            shift
+            ;;
+        --platforms)
+            PLATFORMS="$2"
+            shift 2
+            ;;
+        -t|--tag)
+            TAG="$2"
+            shift 2
+            ;;
+        -h|--help)
+            echo "Usage: $0 [OPTIONS]"
+            echo ""
+            echo "Options:"
+            echo "  --no-cache      Do not use cache when building"
+            echo "  --quiet         Suppress build output except final result"
+            echo "  --skip-tests    Skip running tests after build"
+            echo "  --platforms     Specify platforms to build for (default: $PLATFORMS)"
+            echo "  -t, --tag       Set image tag (default: $TAG)"
+            echo "  -h, --help      Show this help message"
+            echo ""
+            echo "Examples:"
+            echo "  $0                             # Build with default settings"
+            echo "  $0 --no-cache                  # Build without using cache"
+            echo "  $0 --tag v1.0.0                # Build with specific tag"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            exit 1
+            ;;
+    esac
+done
+
+# Function to validate prerequisites
+check_prerequisites() {
+    echo "Checking prerequisites..."
+    
+    # Check if Docker is available
+    if ! command -v docker &> /dev/null; then
+        echo "Error: Docker is not installed or not in PATH"
+        exit 1
+    fi
+    
+    # Check if Docker daemon is running
+    if ! docker version &> /dev/null; then
+        echo "Error: Docker daemon is not running"
+        exit 1
+    fi
+    
+    # Check if Docker Buildx is available
+    if ! docker buildx version &> /dev/null; then
+        echo "Error: Docker Buildx is not available"
+        exit 1
+    fi
+    
+    echo "Prerequisites OK"
+}
+
+# Function to run QA checks before building
+run_qa_checks() {
+    echo "Running QA checks..."
+    
+    # Check if Dockerfile exists
+    if [ ! -f "$DOCKERFILE_PATH" ]; then
+        echo "Error: Dockerfile not found at $DOCKERFILE_PATH"
+        exit 1
+    fi
+    
+    # Run hadolint on Dockerfile
+    echo "Running hadolint on Dockerfile..."
+    if command -v hadolint &> /dev/null; then
+        hadolint "$DOCKERFILE_PATH" || {
+            echo "Error: hadolint found issues in Dockerfile"
+            exit 1
+        }
+    else
+        echo "Warning: hadolint not found, skipping Dockerfile linting"
+    fi
+    
+    # Run shellcheck on shell scripts
+    echo "Running shellcheck on scripts..."
+    for script in run.sh build.sh test.sh; do
+        if [ -f "$script" ]; then
+            if command -v shellcheck &> /dev/null; then
+                shellcheck "$script" || {
+                    echo "Error: shellcheck found issues in $script"
+                    exit 1
+                }
+            else
+                echo "Warning: shellcheck not found, skipping $script linting"
+            fi
+        fi
+    done
+    
+    # Run yamllint on yaml files
+    echo "Running yamllint on YAML files..."
+    if command -v yamllint &> /dev/null; then
+        yamllint docker-compose.yml || {
+            echo "Error: yamllint found issues in docker-compose.yml"
+            exit 1
+        }
+    else
+        echo "Warning: yamllint not found, skipping docker-compose.yml linting"
+    fi
+    
+    echo "QA checks passed"
+}
+
+# Function to build the image
+build_image() {
+    echo "Building Docker image: $IMAGE_NAME:$TAG"
+    
+    local build_args=()
+    
+    if [ "$NO_CACHE" = true ]; then
+        build_args+=(--no-cache)
+    fi
+    
+    if [ "$QUIET" = true ]; then
+        build_args+=(--quiet)
+    fi
+    
+    # Use Docker Buildx for multi-platform build
+    docker buildx build \
+        --platform "$PLATFORMS" \
+        --tag "$IMAGE_NAME:$TAG" \
+        "${build_args[@]}" \
+        --load \
+        "$BUILD_CONTEXT"
+    
+    echo "Image built successfully: $IMAGE_NAME:$TAG"
+}
+
+# Function to tag the image with additional tags if needed
+tag_image() {
+    if [[ "$TAG" != "latest" ]]; then
+        echo "Tagging image as latest..."
+        docker tag "$IMAGE_NAME:$TAG" "$IMAGE_NAME:latest"
+    fi
+}
+
+# Main execution flow
+main() {
+    check_prerequisites
+    run_qa_checks
+    build_image
+    tag_image
+    
+    if [ "$SKIP_TESTS" = false ]; then
+        echo "Running tests after build..."
+        if [ -f "./test.sh" ]; then
+            ./test.sh
+        else
+            echo "Warning: test.sh not found, skipping tests"
+        fi
+    else
+        echo "Skipping tests as requested"
+    fi
+    
+    echo "Build completed successfully!"
+}
+
+main "$@"
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -0,0 +1,19 @@
+version: '3.8'
+
+services:
+  tsysdevstack-toolboxes-docs:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: tsysdevstack-toolboxes-docs
+    volumes:
+      - ./output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output
+      - ./.config/mise:/home/tsysdevstack/.config/mise
+      - ./.local/share/mise:/home/tsysdevstack/.local/share/mise
+    working_dir: /home/tsysdevstack
+    environment:
+      - USER=tsysdevstack
+      - HOME=/home/tsysdevstack
+    stdin_open: true
+    tty: true
+    command: ["/bin/bash"]
--- a/documentation/CHEATSHEET.md
+++ b/documentation/CHEATSHEET.md
@@ -0,0 +1,118 @@
+# CHEATSHEET.md
+
+## TSYSDevStack - Toolboxes - DocsAndDiagrams
+
+Quick Reference for Document Production Tools
+
+---
+
+## 🐳 Docker Commands
+
+| Task | Command |
+|------|---------|
+| Run interactively | `docker run -it --rm -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs` |
+| Run specific command | `docker run --rm -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs <command>` |
+| Build image | `docker build -t tsysdevstack/toolboxes-docs .` |
+| Run with local files | `docker run --rm -v $(pwd):/data -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs` |
+
+## 📝 Pandoc Commands
+
+| Task | Command |
+|------|---------|
+| Markdown to PDF | `pandoc input.md -o output.pdf --pdf-engine=xelatex` |
+| Markdown to DOCX | `pandoc input.md -o output.docx` |
+| HTML to PDF | `pandoc input.html -o output.pdf --pdf-engine=xelatex` |
+| With custom template | `pandoc input.md -o output.pdf --template=mytemplate --pdf-engine=xelatex` |
+| Resume from Markdown | `pandoc resume.md -o resume.pdf --template=eisvogel --pdf-engine=xelatex` |
+| Include CSS | `pandoc input.md -o output.pdf --css=styles.css --pdf-engine=xelatex` |
+
+## 📘 mdBook Commands
+
+| Task | Command |
+|------|---------|
+| Create new book | `mdbook init mybook` |
+| Build book | `mdbook build /path/to/book -d /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output` |
+| Serve book locally | `mdbook serve /path/to/book --hostname 0.0.0.0 --port 3000` |
+| Watch and rebuild | `mdbook watch /path/to/book` |
+
+## ✍️ Typst Commands
+
+| Task | Command |
+|------|---------|
+| Compile document | `typst compile document.typ output.pdf` |
+| Watch for changes | `typst watch document.typ output.pdf` |
+| Export as PNG | `typst compile document.typ output.png` |
+
+## 🎞️ Marp Commands
+
+| Task | Command |
+|------|---------|
+| Convert to PDF | `marp input.md --pdf --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/presentation.pdf` |
+| Convert to PPTX | `marp input.md --pptx --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/presentation.pptx` |
+| Serve presentation | `marp --server --port 8080` |
+
+## 📊 Quarto Commands
+
+| Task | Command |
+|------|---------|
+| Render document | `quarto render document.qmd --to pdf` |
+| Convert to HTML | `quarto render document.qmd --to html` |
+| Convert to DOCX | `quarto render document.qmd --to docx` |
+| Render with custom format | `quarto render document.qmd --to revealjs` |
+| Create new project | `quarto create-project myproject --type book` |
+
+## 🚦 Kroki Commands
+
+| Task | Command |
+|------|---------|
+| Convert diagram | `kroki --file diagram.yaml --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/diagram.svg` |
+| Convert with format | `kroki --file diagram.txt --type blockdiag --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/diagram.png` |
+
+## 📜 Vale Commands
+
+| Task | Command |
+|------|---------|
+| Check document | `vale /path/to/document.md` |
+| Check with specific style | `vale --config=/path/to/.vale.ini /path/to/document.md` |
+
+## 🔧 System Tools
+
+| Tool | Purpose | Example |
+|------|---------|---------|
+| `jq` | JSON processor | `echo '{"name":"test"}' | jq '.'` |
+| `yq` | YAML processor | `yq '.key' file.yaml` |
+| `wkhtmltopdf` | HTML to PDF | `wkhtmltopdf input.html output.pdf` |
+| `bibtool` | Bibliography tool | `bibtool -s -i refs.bib` |
+
+## 🛠️ Mise Commands
+
+| Task | Command |
+|------|---------|
+| Install runtimes | `mise install` |
+| Use specific Python version | `mise use --global python@3.12.6` |
+| Use specific Node.js version | `mise use --global node@21.7.3` |
+| Show current tools | `mise current` |
+| Install specific tool | `mise install python@3.12.6` |
+
+## 🌐 TeXLive Commands
+
+| Task | Command |
+|------|---------|
+| Compile with XeTeX | `xelatex document.tex` |
+| Compile with PDFLaTeX | `pdflatex document.tex` |
+| Manage packages | `tlmgr install package-name` |
+| Update packages | `tlmgr update --all` |
+
+## 📁 Directory Locations
+
+- **Input/Working Directory**: `/data` (when mounting local files)
+- **Output Directory**: `/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output`
+- **User Home**: `/home/tsysdevstack`
+- **Mise Configuration**: `/home/tsysdevstack/.config/mise`
+- **Mise Data**: `/home/tsysdevstack/.local/share/mise`
+
+## 🔑 User Information
+
+- **Username**: `tsysdevstack`
+- **UID**: `1000`
+- **Shell Options**: `bash`, `zsh`, `fish`
--- a/documentation/TROUBLESHOOTING.md
+++ b/documentation/TROUBLESHOOTING.md
@@ -0,0 +1,161 @@
+# TROUBLESHOOTING.md
+
+## TSYSDevStack - Toolboxes - DocsAndDiagrams
+
+Troubleshooting Guide for the Document Production Workhorse Container
+
+---
+
+## 🐛 Common Issues and Solutions
+
+### Docker Container Won't Start
+
+**Issue**: Container fails to start with permission errors
+
+**Solution**:
+```bash
+# Check if Docker daemon is running
+sudo systemctl status docker
+
+# If not running, start it
+sudo systemctl start docker
+
+# Ensure your user is in the docker group
+sudo usermod -aG docker $USER
+# Then log out and log back in
+```
+
+### Permission Denied Errors
+
+**Issue**: Getting permission errors when accessing mounted volumes
+
+**Solution**:
+1. The container runs as user `tsysdevstack` with UID 1000
+2. Ensure your host directory is writable by UID 1000:
+   ```bash
+   sudo chown -R 1000:1000 /path/to/local/directory
+   ```
+3. Or run the container with appropriate user mapping:
+   ```bash
+   docker run -u $(id -u):$(id -g) -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs
+   ```
+
+### Pandoc Fails with Font Errors
+
+**Issue**: PDF generation fails with font-related errors
+
+**Solution**:
+1. The container includes Noto fonts, but you may need additional fonts:
+   ```bash
+   # Check available fonts
+   fc-list
+   
+   # Install additional fonts by extending the container
+   ```
+
+### Large Document Processing Issues
+
+**Issue**: Container runs out of memory when processing large documents
+
+**Solution**:
+1. Increase Docker's memory allocation in Docker Desktop settings
+2. Run with memory limits:
+   ```bash
+   docker run --memory="4g" -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs
+   ```
+
+### TeXLive Compilation Fails
+
+**Issue**: LaTeX compilation fails with missing packages
+
+**Solution**:
+1. The container includes a basic TeXLive installation with common packages
+2. For additional packages, use `tlmgr`:
+   ```bash
+   docker run -it tsysdevstack/toolboxes-docs tlmgr install package-name
+   ```
+
+### Missing Language Runtime Tools
+
+**Issue**: Tools installed via npm/pip not working
+
+**Solution**:
+1. The container uses `mise` to manage language runtimes
+2. Check if the runtime is properly configured:
+   ```bash
+   mise current
+   ```
+3. Install or activate the required version:
+   ```bash
+   mise use --global python@3.12.6  # or required version
+   ```
+
+### Quarto Rendering Issues
+
+**Issue**: Quarto fails with missing R or Python environments
+
+**Solution**:
+1. The container has a basic Python environment but may need extensions:
+   ```bash
+   # Install required Python packages
+   pip3 install jupyter numpy pandas matplotlib
+   ```
+
+## 🔧 Diagnostic Commands
+
+### Check Container Information
+```bash
+# Check running containers
+docker ps
+
+# Check container logs
+docker logs <container-name>
+
+# Execute commands in running container
+docker exec -it <container-name> /bin/bash
+```
+
+### Verify Tool Availability
+```bash
+# Check all installed tools
+docker run --rm tsysdevstack/toolboxes-docs which pandoc mdbook typst marp quarto jq yq
+
+# Check Pandoc version and capabilities
+docker run --rm tsysdevstack/toolboxes-docs pandoc --version
+
+# Check TeXLive installation
+docker run --rm tsysdevstack/toolboxes-docs xelatex --version
+```
+
+### Check Storage and Paths
+```bash
+# Verify output directory exists and is writable
+docker run --rm -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs ls -la /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output
+
+# Check if input files are accessible
+docker run --rm -v $(pwd)/:/data tsysdevstack/toolboxes-docs ls -la /data
+```
+
+## 🔍 Debugging Steps
+
+1. **Check the error message carefully**
+2. **Verify your input files exist and are accessible**
+3. **Check that you have sufficient disk space**
+4. **Try running a simple command first** (e.g., `pandoc --version`)
+5. **Check container logs** if running as a service
+6. **Verify volume mappings are correct**
+7. **Test with a minimal document** to isolate issues
+
+## 📞 Support
+
+If you encounter issues not covered in this guide:
+
+1. Check the [Usage Guide](USAGE.md) for correct command syntax
+2. Review [Cheat Sheet](CHEATSHEET.md) for common commands
+3. Search the repository issues for similar problems
+4. Create a new issue with:
+   - Docker version
+   - Host OS
+   - Command used
+   - Error message
+   - Expected behavior
--- a/documentation/USAGE.md
+++ b/documentation/USAGE.md
@@ -0,0 +1,316 @@
+# USAGE.md
+
+## TSYSDevStack - Toolboxes - DocsAndDiagrams
+
+Detailed Usage Instructions for the Document Production Workhorse Container
+
+---
+
+## 📖 Overview
+
+The TSYSDevStack Toolboxes Docs container is designed for document production workflows, offering a comprehensive suite of tools for converting, generating, and processing documents in various formats with a focus on beautiful PDF output.
+
+This guide details how to effectively use the tools available in the container for various document production tasks.
+
+## 🏗️ Container Setup
+
+### Running the Container
+
+The container can be used in both interactive and non-interactive modes:
+
+**Interactive Mode:**
+```bash
+docker run -it --rm \
+  -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" \
+  -v "$(pwd):/data" \
+  tsysdevstack/toolboxes-docs
+```
+
+**Non-Interactive Mode:**
+```bash
+docker run --rm \
+  -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" \
+  -v "$(pwd):/data" \
+  tsysdevstack/toolboxes-docs \
+  bash -c "pandoc /data/input.md -o /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/output.pdf --pdf-engine=xelatex"
+```
+
+### Volume Mounting Explained
+
+- **Output Directory**: Mount your local directory to `/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output` to access generated documents
+- **Input Directory**: Mount your documents directory to `/data` for processing
+- **Configuration**: Store custom configurations in mounted volumes for reuse
+
+## 📝 Pandoc Usage
+
+### Basic Conversion
+
+Pandoc is the universal document converter, supporting over 50 input and output formats:
+
+```bash
+# Markdown to PDF (with beautiful styling)
+pandoc input.md -o output.pdf --pdf-engine=xelatex
+
+# Markdown to DOCX
+pandoc input.md -o output.docx
+
+# HTML to Markdown
+pandoc input.html -o output.md -f html -t markdown
+```
+
+### Advanced Pandoc Options
+
+```bash
+# Convert with custom template and styling
+pandoc input.md \
+  --output=output.pdf \
+  --pdf-engine=xelatex \
+  --template=eisvogel \
+  --highlight-style=tango \
+  --css=styles.css \
+  --variable=geometry:a4paper \
+  --variable=margin=1in
+
+# Resume generation optimized for ATS systems
+pandoc resume.md \
+  --output=resume.pdf \
+  --pdf-engine=xelatex \
+  --template=plain \
+  --variable=margin=1in \
+  --variable=fontsize=11pt \
+  --variable=fontfamily=noto
+```
+
+### Joplin Notes to PDF
+
+```bash
+# Convert Joplin note to PDF preserving formatting
+pandoc joplin_note.md \
+  --output=output.pdf \
+  --pdf-engine=xelatex \
+  --metadata=title:"Note Title" \
+  --variable=classoption=landscape \
+  --highlight-style=espresso
+```
+
+## 📘 mdBook Usage
+
+### Creating a Book
+
+```bash
+# Initialize a new book
+mdbook init mybook
+
+# Build the book
+mdbook build mybook -d /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output
+```
+
+### Serving Books
+
+```bash
+# Serve the book locally (useful during development)
+mdbook serve /data/mybook --hostname 0.0.0.0 --port 3000
+
+# Then access via http://localhost:3000
+```
+
+### Custom Configuration
+
+Create a `book.toml` file in your book directory:
+
+```toml
+[book]
+authors = ["Your Name"]
+language = "en"
+multilingual = false
+src = "."
+title = "My Book Title"
+
+[output.html]
+mathjax-support = true
+default-theme = "coal"
+preferred-dark-theme = "navy"
+```
+
+## ✍️ Typst Usage
+
+### Basic Document Creation
+
+Create a `.typ` file with Typst syntax:
+
+```typst
+#set page(width: 15cm, height: 20cm, margin: 2cm)
+
+= Introduction
+This is a basic Typst document.
+
+#figure(
+  image("diagram.png"),
+  caption: [Figure 1: A diagram]
+)
+```
+
+### Compiling Typst Documents
+
+```bash
+# Compile to PDF
+typst compile document.typ /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/document.pdf
+
+# Compile to PNG
+typst compile document.typ /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/document.png
+
+# Watch for changes
+typst watch document.typ /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/document.pdf
+```
+
+## 🎞️ Marp Usage
+
+### Creating Presentations
+
+Create a Markdown file with Marp-specific syntax:
+
+```markdown
+---
+marp: true
+theme: gaia
+_class: lead
+paginate: true
+backgroundColor: #fff
+backgroundImage: url('https://cdn.jsdelivr.net/gh/marp-team/marp@master/assets/hero-background.svg')
+---
+
+# Slide 1
+
+---
+
+# Slide 2
+- Point 1
+- Point 2
+```
+
+### Generating Presentations
+
+```bash
+# Convert to PDF
+marp presentation.md --pdf --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/presentation.pdf
+
+# Convert to PPTX
+marp presentation.md --pptx --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/presentation.pptx
+
+# Serve locally
+marp --server --port 8080
+```
+
+## 📊 Quarto Usage
+
+### Basic Document Rendering
+
+```bash
+# Render Quarto document to PDF
+quarto render document.qmd --to pdf
+
+# Render to HTML with interactive features
+quarto render document.qmd --to html --embed-resources
+
+# Render to DOCX
+quarto render document.qmd --to docx
+```
+
+### Advanced Quarto Features
+
+```bash
+# Create a parameterized report
+quarto render document.qmd --execute-params "dataset=dataset1;output_format=full" --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/report.pdf
+
+# Create a presentation
+quarto render presentation.qmd --to revealjs --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/slides.html
+```
+
+### Creating Projects
+
+```bash
+# Create a new book project
+quarto create-project mybook --type book
+
+# Create an article project
+quarto create-project article --type default
+```
+
+## 🚦 Kroki Usage
+
+### Generating Diagrams
+
+```bash
+# Create a PlantUML diagram
+kroki --file diagram.puml --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/diagram.svg
+
+# Generate block diagram in PNG format
+echo '@startuml\nAlice -> Bob: Hello\n@enduml' > simple.puml
+kroki --file simple.puml --type plantuml --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/simple.png
+```
+
+## 📜 Vale Usage
+
+### Linting Documents
+
+```bash
+# Check a single document
+vale /data/document.md
+
+# Check with specific configuration
+vale --config=/data/.vale.ini /data/document.md
+
+# Generate report in JSON format
+vale --output-style=JSON /data/document.md
+```
+
+## 🔧 Working with TeXLive
+
+### Custom LaTeX Documents
+
+```bash
+# Compile LaTeX with XeTeX (for better font support)
+xelatex -output-directory=/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output document.tex
+
+# Compile with pdflatex
+pdflatex -output-directory=/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output document.tex
+```
+
+## 📁 Best Practices
+
+### Organizing Work
+
+1. **Use the `/data` directory** for input files
+2. **Use the output directory** for generated documents
+3. **Create a local `config` directory** for custom configurations
+4. **Use volume mounts** for persistent work
+
+### Performance Tips
+
+1. **Use Docker volumes** instead of bind mounts for better performance when possible
+2. **Process multiple files** in a single container run to avoid startup overhead
+3. **Use appropriate memory allocation** for large document processing
+4. **Use specific tool versions** with mise for reproducibility
+
+### Security Considerations
+
+1. **The container runs as non-root user** (`tsysdevstack`)
+2. **No root access is available at runtime** to prevent security issues
+3. **Language runtimes are managed by mise** for consistent and secure tooling
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+- **Font Issues**: The container includes Noto fonts; for additional fonts, extend the container or mount font directories
+- **Memory Issues**: Increase Docker's memory allocation for processing large documents
+- **Permission Issues**: Ensure mounted volumes have appropriate permissions for UID 1000
+
+### Getting Help
+
+If you encounter issues:
+
+1. Check the [TROUBLESHOOTING.md](TROUBLESHOOTING.md) guide
+2. Use the diagnostic commands from the troubleshooting guide
+3. Examine container logs: `docker logs <container-name>`
+4. Verify volume mappings and file accessibility
--- a/examples/README.md
+++ b/examples/README.md
@@ -0,0 +1,53 @@
+# Example Documents for TSYSDevStack Toolboxes Docs
+
+This directory contains example documents and workflow scripts that demonstrate the capabilities of the document production workhorse container.
+
+## 📄 Document Examples
+
+### 1. Basic Markdown to PDF
+- `basic-markdown.md` - Simple markdown document for conversion to PDF
+- `basic-markdown.pdf` - Output PDF generated from the markdown
+
+### 2. Resume/CV Generation
+- `resume-template.tex` - LaTeX template for ATS-optimized resumes
+- `resume.md` - Markdown source for a resume
+- `resume.pdf` - Generated PDF resume
+
+### 3. Project Documentation
+- `project-plan.md` - Example project plan in markdown
+- `project-plan.pdf` - Generated PDF project plan
+
+### 4. Joplin Notes Conversion
+- `joplin-note.md` - Example Joplin note markdown
+- `joplin-note.pdf` - Converted PDF preserving formatting
+
+### 5. mdBook Example
+- `mybook/` - Complete mdBook project example
+- `mybook/src/SUMMARY.md` - Book structure
+- `mybook/src/chapter_1.md` - Sample chapter
+
+### 6. Typst Document
+- `scientific-document.typ` - Example Typst document
+- `scientific-document.pdf` - Generated PDF
+
+### 7. Marp Presentation
+- `presentation.md` - Example Marp presentation
+- `presentation.pdf` - Generated PDF slides
+
+### 8. Quarto Document
+- `analysis.qmd` - Example Quarto document with code execution
+- `analysis.pdf` - Generated analysis document
+
+## 🛠️ Workflow Scripts
+
+### 1. Batch Conversion Script
+- `batch-convert.sh` - Script to convert multiple markdown files to PDF
+
+### 2. Document Pipeline
+- `document-pipeline.sh` - Complete pipeline from source to final document
+
+### 3. Quality Assurance
+- `qa-check.sh` - Script to verify document quality and consistency
+
+### 4. Custom Styling
+- `custom-templates/` - Directory containing custom templates for various document types
--- a/examples/basic-markdown.md
+++ b/examples/basic-markdown.md
@@ -0,0 +1,32 @@
+# Sample Markdown Document
+
+This is a sample markdown document to demonstrate the document conversion capabilities of the TSYSDevStack Toolboxes Docs container.
+
+## Features Demonstrated
+
+- Headers and subheaders
+- **Bold text**
+- *Italic text*
+- Lists
+  - Sublist item 1
+  - Sublist item 2
+- Code blocks:
+  ```python
+  def hello():
+      print("Hello, World!")
+  ```
+
+## Tables
+
+| Column 1 | Column 2 | Column 3 |
+|----------|----------|----------|
+| Item 1   | Item 2   | Item 3   |
+| Item 4   | Item 5   | Item 6   |
+
+## Images
+
+![Placeholder Image](https://placehold.co/600x400.png "Sample Image")
+
+## Conclusion
+
+This sample document demonstrates various markdown features that can be converted to beautiful PDFs using the Pandoc and TeXLive tools in this container.
--- a/examples/doc-workflow.sh
+++ b/examples/doc-workflow.sh
@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+
+# Example workflow script: Convert multiple markdown files to PDF
+# This script demonstrates a typical document generation workflow
+
+set -e  # Exit on any error
+
+echo "Starting document conversion workflow..."
+
+# Define input and output directories
+INPUT_DIR="/data"
+OUTPUT_DIR="/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output"
+WORKFLOW_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "Input directory: $INPUT_DIR"
+echo "Output directory: $OUTPUT_DIR"
+
+# Function to convert a markdown file to PDF
+convert_to_pdf() {
+    local input_file="$1"
+    local output_file="$2"
+    
+    echo "Converting $input_file to $output_file"
+    pandoc "$input_file" \
+        -o "$output_file" \
+        --pdf-engine=xelatex \
+        --variable=geometry:a4paper \
+        --variable=margin=1in \
+        --highlight-style=tango
+}
+
+# Function to convert a markdown file to DOCX
+convert_to_docx() {
+    local input_file="$1"
+    local output_file="$2"
+    
+    echo "Converting $input_file to $output_file"
+    pandoc "$input_file" -o "$output_file"
+}
+
+# Function to process mdBook
+build_mdbook() {
+    local book_dir="$1"
+    local output_dir="$2"
+    
+    echo "Building mdBook from $book_dir"
+    mdbook build "$book_dir" -d "$output_dir"
+}
+
+# Function to process Typst document
+compile_typst() {
+    local input_file="$1"
+    local output_file="$2"
+    
+    echo "Compiling Typst document $input_file to $output_file"
+    typst compile "$input_file" "$output_file"
+}
+
+# Convert all markdown files in the input directory
+for md_file in "$INPUT_DIR"/*.md; do
+    if [ -f "$md_file" ]; then
+        filename=$(basename "$md_file" .md)
+        echo "Processing markdown file: $filename"
+        
+        # Convert to PDF
+        convert_to_pdf "$md_file" "$OUTPUT_DIR/${filename}.pdf"
+        
+        # Convert to DOCX
+        convert_to_docx "$md_file" "$OUTPUT_DIR/${filename}.docx"
+        
+        echo "Completed conversion of $filename"
+    fi
+done
+
+# Process any mdBook directories
+for book_dir in "$INPUT_DIR"/book_*; do
+    if [ -d "$book_dir" ] && [ -f "$book_dir/book.toml" ]; then
+        echo "Found mdBook project: $book_dir"
+        build_mdbook "$book_dir" "$OUTPUT_DIR"
+    fi
+done
+
+# Process any Typst documents
+for typ_file in "$INPUT_DIR"/*.typ; do
+    if [ -f "$typ_file" ]; then
+        filename=$(basename "$typ_file" .typ)
+        echo "Processing Typst file: $filename"
+        compile_typst "$typ_file" "$OUTPUT_DIR/${filename}.pdf"
+    fi
+done
+
+# Generate a summary report
+echo "Conversion workflow completed!"
+echo "Generated documents are available in: $OUTPUT_DIR"
+
+# Count generated files
+pdf_count=$(find "$OUTPUT_DIR" -name "*.pdf" | wc -l)
+docx_count=$(find "$OUTPUT_DIR" -name "*.docx" | wc -l)
+echo "Total PDFs generated: $pdf_count"
+echo "Total DOCX files generated: $docx_count"
+
+echo "Workflow completed successfully!"
--- a/examples/example-document.typ
+++ b/examples/example-document.typ
@@ -0,0 +1,32 @@
+// Example Typst document
+#set page(width: 15cm, height: 20cm, margin: 2cm)
+#set text(font: "Noto Sans", size: 12pt)
+
+= Introduction to Typst
+
+This is a simple example document created with Typst, a modern markup-based typesetting system.
+
+== Features
+
+Typst offers several advantages:
+
+- #lorem(10)
+- Mathematical typesetting: $f(x) = x^2$
+- #list(
+  , "Fast processing"
+  , "Template system"
+  , "Symbol collections"
+)
+
+== Code Example
+
+Here's how to include code:
+
+```typst
+= Title
+Lorem ipsum #lorem(50)
+```
+
+= Conclusion
+
+Typst provides a modern alternative to LaTeX for document creation with a simpler syntax and fast compilation.
--- a/examples/presentation.md
+++ b/examples/presentation.md
@@ -0,0 +1,55 @@
+---
+marp: true
+theme: gaia
+_class: lead
+paginate: true
+backgroundColor: #fff
+backgroundImage: url('https://cdn.jsdelivr.net/gh/marp-team/marp@master/assets/hero-background.svg')
+---
+
+# TSYSDevStack Documentation Tools
+
+*Modern Document Production Workhorse*
+
+---
+
+## Agenda
+
+- Overview of Tools
+- Pandoc for Conversion
+- mdBook for Documentation
+- Typst for Typesetting
+- Marp for Presentations
+- Quarto for Scientific Publishing
+
+---
+
+## Pandoc
+
+- Universal document converter
+- Supports 50+ formats
+- High-quality PDF output with TeXLive
+
+```markdown
+pandoc input.md -o output.pdf --pdf-engine=xelatex
+```
+
+---
+
+## mdBook
+
+- Create books from Markdown
+- Multiple output formats
+- Customizable themes
+
+```bash
+mdbook build mybook -d output/
+```
+
+---
+
+## Thank You
+
+*Questions?*
+
+[github.com/tsysdevstack/toolboxes-docs](https://github.com/tsysdevstack/toolboxes-docs)
--- a/output/joplin-note.md
+++ b/output/joplin-note.md
@@ -0,0 +1,34 @@
+# Project Planning Meeting Notes
+
+**Date:** October 26, 2023  
+**Attendees:** John, Sarah, Mike, Lisa
+
+## Agenda
+- Review project timeline
+- Discuss resource allocation
+- Address technical challenges
+
+## Key Decisions
+- Extend deadline by 2 weeks for backend development
+- Allocate additional resources to testing phase
+- Implement new authentication system
+
+## Action Items
+- [x] John: Complete API design by Nov 5
+- [ ] Sarah: Prepare testing framework by Nov 10
+- [ ] Mike: Set up staging environment by Nov 8
+- [ ] Lisa: Review security requirements by Nov 3
+
+## Discussion Points
+- The initial timeline was too aggressive
+- More time needed for integration testing
+- Consider using external consultants for UI work
+
+## Next Meeting
+**Date:** November 2, 2023  
+**Time:** 10:00 AM  
+**Location:** Conference Room 3
+
+## Attachments
+- [API_Design_Draft.pdf](api_design_draft.pdf)
+- [Resource_Allocation_Sheet.xlsx](resource_sheet.xlsx)
--- a/output/resume.md
+++ b/output/resume.md
@@ -0,0 +1,46 @@
+---
+title: John Doe - Software Engineer
+author: John Doe
+keywords: [software engineer, resume, ATS]
+---
+
+# John Doe
+**Software Engineer**
+
+Email: john.doe@example.com | Phone: (123) 456-7890  
+LinkedIn: linkedin.com/in/johndoe | GitHub: github.com/johndoe
+
+---
+
+## PROFESSIONAL SUMMARY
+
+Experienced software engineer with 5+ years of expertise in designing, developing, and maintaining scalable web applications. Proficient in JavaScript, Python, and cloud technologies. Strong problem-solving skills with a passion for clean, efficient code.
+
+## TECHNICAL SKILLS
+
+**Programming Languages:** JavaScript (ES6+), Python, Java, TypeScript, SQL  
+**Frameworks & Libraries:** React, Node.js, Django, Express.js, Vue.js  
+**Tools & Technologies:** Git, Docker, Kubernetes, AWS, REST APIs, GraphQL  
+**Databases:** PostgreSQL, MongoDB, Redis
+
+## PROFESSIONAL EXPERIENCE
+
+**Senior Software Engineer** | TechCorp | 2020 - Present
+- Developed and maintained microservices handling 1M+ daily requests
+- Improved application performance by 40% through code optimization
+- Mentored 3 junior developers and conducted code reviews
+
+**Software Engineer** | StartupXYZ | 2018 - 2020
+- Built responsive web applications using React and Node.js
+- Implemented CI/CD pipelines reducing deployment time by 60%
+- Collaborated with cross-functional teams to deliver features on schedule
+
+## EDUCATION
+
+**Bachelor of Science in Computer Science**  
+University of Technology | 2014 - 2018
+
+## CERTIFICATIONS
+
+- AWS Certified Developer - Associate (2021)
+- MongoDB Certified Developer (2020)
--- a/output/test-document.md
+++ b/output/test-document.md
@@ -0,0 +1,28 @@
+# Test Document
+
+This is a test document to verify that the TSYSDevStack Toolboxes Docs container is working correctly.
+
+## Features Tested
+
+- [ ] Markdown to PDF conversion
+- [ ] Markdown to DOCX conversion
+- [ ] TeXLive/XeTeX rendering
+- [ ] Font rendering
+- [ ] Code block formatting
+- [ ] Table formatting
+
+## Code Example
+
+```javascript
+function hello() {
+    console.log("Hello, World!");
+}
+```
+
+## Table Example
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Pandoc | ✅ | Working |
+| TeXLive | ✅ | Working |
+| Fonts | ✅ | Noto fonts available |
--- a/run.sh
+++ b/run.sh
@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+
+# run.sh - Script to run the tsysdevstack-toolboxes-docs container
+set -e
+
+# Default values
+CONTAINER_NAME="tsysdevstack-toolboxes-docs"
+IMAGE_NAME="tsysdevstack/toolboxes-docs:latest"
+WORKDIR="/home/tsysdevstack"
+OUTPUT_DIR="/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output"
+
+# Parse command line arguments
+INTERACTIVE=true
+DAEMON=false
+CMD=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -d|--daemon)
+            DAEMON=true
+            INTERACTIVE=false
+            shift
+            ;;
+        -c|--command)
+            CMD="$2"
+            INTERACTIVE=false
+            shift 2
+            ;;
+        -n|--name)
+            CONTAINER_NAME="$2"
+            shift 2
+            ;;
+        -h|--help)
+            echo "Usage: $0 [OPTIONS] [COMMAND]"
+            echo ""
+            echo "Options:"
+            echo "  -d, --daemon    Run container in daemon mode"
+            echo "  -c, --command   Run a specific command in the container"
+            echo "  -n, --name      Specify container name (default: $CONTAINER_NAME)"
+            echo "  -h, --help      Show this help message"
+            echo ""
+            echo "Examples:"
+            echo "  $0                           # Run interactively"
+            echo "  $0 -d                       # Run as daemon"
+            echo "  $0 -c 'pandoc --version'    # Run specific command"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            exit 1
+            ;;
+    esac
+done
+
+# Function to run the container
+run_container() {
+    local extra_args=()
+    
+    if [ "$INTERACTIVE" = true ]; then
+        extra_args+=(-it)
+    fi
+    
+    if [ "$DAEMON" = true ]; then
+        extra_args+=(-d)
+    fi
+    
+    if [ -n "$CMD" ]; then
+        docker run "${extra_args[@]}" \
+            --name "$CONTAINER_NAME" \
+            -v "$(pwd)/output:$OUTPUT_DIR" \
+            -w "$WORKDIR" \
+            "$IMAGE_NAME" \
+            bash -c "$CMD"
+    else
+        docker run "${extra_args[@]}" \
+            --name "$CONTAINER_NAME" \
+            -v "$(pwd)/output:$OUTPUT_DIR" \
+            -w "$WORKDIR" \
+            "$IMAGE_NAME"
+    fi
+}
+
+# Check if container is already running
+if [ "$(docker ps -q -f name="$CONTAINER_NAME")" ]; then
+    echo "Container $CONTAINER_NAME is already running."
+    if [ -n "$CMD" ]; then
+        # Run command in existing container
+        docker exec -it "$CONTAINER_NAME" bash -c "$CMD"
+    else
+        # Attach to existing container
+        docker exec -it "$CONTAINER_NAME" /bin/bash
+    fi
+elif [ "$(docker ps -aq -f name="$CONTAINER_NAME")" ]; then
+    # Container exists but is not running, start it
+    docker start "$CONTAINER_NAME" > /dev/null
+    if [ -n "$CMD" ]; then
+        docker exec -it "$CONTAINER_NAME" bash -c "$CMD"
+    else
+        docker attach "$CONTAINER_NAME"
+    fi
+else
+    # Run new container
+    run_container
+fi
--- a/test.sh
+++ b/test.sh
@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+
+# test.sh - Script to test the tsysdevstack-toolboxes-docs container
+set -e
+
+# Default values
+IMAGE_NAME="tsysdevstack/toolboxes-docs"
+TAG="latest"
+CONTAINER_NAME="test-tsysdevstack-toolboxes-docs"
+TEST_DIR="/tmp/test-tsysdevstack-toolboxes-docs"
+
+# Function to print test results
+print_result() {
+    if [ $? -eq 0 ]; then
+        echo "✅ PASS: $1"
+    else
+        echo "❌ FAIL: $1"
+        exit 1
+    fi
+}
+
+# Function to run a command in the container and check the result
+run_test_command() {
+    local test_name="$1"
+    local command="$2"
+    
+    echo "Running test: $test_name"
+    docker run --rm --name "$CONTAINER_NAME-$(date +%s)" "$IMAGE_NAME:$TAG" bash -c "$command"
+    print_result "$test_name"
+}
+
+# Function to test if a command exists in the container
+test_command_exists() {
+    local test_name="$1"
+    local command="$2"
+    
+    run_test_command "$test_name" "which $command"
+}
+
+# Function to test if a specific version of a tool is available
+test_version_command() {
+    local test_name="$1"
+    local command="$2"
+    local expected_version="$3"
+    
+    echo "Running version test: $test_name"
+    docker run --rm --name "$CONTAINER_NAME-$(date +%s)" "$IMAGE_NAME:$TAG" bash -c "$command" | grep "$expected_version" > /dev/null
+    print_result "$test_name"
+}
+
+# Main test execution
+main() {
+    echo "Starting tests for $IMAGE_NAME:$TAG..."
+
+    # Test that core utilities exist
+    test_command_exists "Check if pandoc exists" "pandoc"
+    test_command_exists "Check if mdbook exists" "mdbook"
+    test_command_exists "Check if typst exists" "typst"
+    test_command_exists "Check if marp exists" "marp"
+    test_command_exists "Check if markwhen exists" "markwhen"
+    test_command_exists "Check if quarto exists" "quarto"
+    test_command_exists "Check if jq exists" "jq"
+    test_command_exists "Check if yq exists" "yq"
+    test_command_exists "Check if wkhtmltopdf exists" "wkhtmltopdf"
+    test_command_exists "Check if bibtool exists" "bibtool"
+    test_command_exists "Check if vale exists" "vale"
+    test_command_exists "Check if kroki exists" "kroki"
+    test_command_exists "Check if fish shell exists" "fish"
+    test_command_exists "Check if zsh exists" "zsh"
+    test_command_exists "Check if bash exists" "bash"
+    
+    # Test that TeXLive is properly installed
+    test_command_exists "Check if xelatex exists" "xelatex"
+    test_command_exists "Check if pdflatex exists" "pdflatex"
+    
+    # Test that Python and Node.js are managed by mise
+    run_test_command "Check if Python is available via mise" "python --version"
+    run_test_command "Check if Node.js is available via mise" "node --version"
+    
+    # Test that we can run a simple pandoc command
+    run_test_command "Test basic pandoc functionality" "echo '# Test' | pandoc -f markdown -t html | grep '<h1>Test</h1>'"
+    
+    # Test that we can run a simple mdbook command
+    run_test_command "Test basic mdbook functionality" "mdbook --version"
+    
+    # Test that we can run a simple typst command
+    run_test_command "Test basic typst functionality" "echo '# Hello' > /tmp/test.typ && typst compile /tmp/test.typ /tmp/test.pdf && [ -f /tmp/test.pdf ]"
+    
+    # Test that user is not root
+    run_test_command "Check that default user is not root" "whoami | grep tsysdevstack"
+    
+    # Test that required directories exist
+    run_test_command "Check that output directory exists" "[ -d /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output ]"
+    
+    # Test that we can write to the output directory
+    run_test_command "Test write access to output directory" "touch /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/test_file.txt && [ -f /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/test_file.txt ]"
+    
+    echo "All tests passed! 🎉"
+}
+
+main
Author	SHA1	Message	Date
ReachableCEO	544d1c31e5	Toolboxes-Docs (vibe-kanban c5c3e68d) TSYS Group Development Stack - Toolboxes - DocsAndDiagrams - Product Requirements Document - ## Docker Image Boilerplate Image name: tsysdevstack-toolboxes-docs Image username: tsysdevstack Image base: latest Debian stable - ALL operations MUST be as the tsysdevstack user - NO ROOT ACCESS should be possible at runtime (no sudo, no su) - The ONLY permitted use of root is during build time, and that MUST be to the ABSOLUTE MINIMUM extent possible (just for apt-get operations and creating the tsysdevstack user). Switching to tsysdevstack as early as possible. - mise (as the tsysdevstack user) MUST be used to install all language runtimes (node/python/rust/ruby). - If an application is installed via npm/pip/cargo/gem, those application installs MUST be done via mise managed versions of npm/pip/cargo/gem. - NO system wide (apt-get) installs of language runtimes are allowed - This is a production container. Use ALL best common practices for the building and securing of docker containers. (Buildx, multi stage, hardened ) - Use yamllint/hadolint/shellcheck (available via docker images on this system) as a QA gate BEFORE attempting to build the image. If ANY changes to Dockerfile/run.sh/build.sh/test.sh are made, run them through hadolint/shellcheck respectively. - ALL hadolint/yamllint/shellcheck issues MUST be FULLY RESOLVED always. The only acceptable QA outcome is when those tools return no warnings/errors. - Think about how to efficiently create the Dockerfile, keeping caching of layers in mind , especially how layers can be cached across multiple different image builds. - Utilize buildkit/buildx - This container needs to run on PC/Raspberry Pi/Mac M series. - Reproducibility of the build is PARAMOUNT! Use version pinning for EVERYTHING. Do the research to find the latest stable version and update Dockerfile and other files accordingly. Do not "just use latest", that is never acceptable. You MUST pin the Debian package versions, and any of the tooling you install via mise managed runtimes. - Use the examples subdirectory and create example artifacts and workflow scripts to fully QA the functionality of the container - Create a README.md file that is BEAUTIFULLY formatted (using table of contents/headers/icons/graphics/whitespace/tables (with left justified text)). Document the container image thoroughly. - Use the documentation subdirectory and creaate the following artifacts: - TROUBLESHOOTING.md - CHEATSHEET.md - USAGE.md - Use the output subdirectory and create the following artifacts (ensure they will pass strict QA testing/auditing): - Dockerfile - docker-compose.yml - devcontainer.json - run.sh - build.sh - test.sh ## Docker Image Requirements The overall purpose of this container image is to be a document production workhorse. Core workflows: - pandoc markdown to pdf/doc (for resumes) (so simple formatting, ATS optimized) markdown to pdf (for project plans, budgets, proposals etc) Joplin markdown notes to PDF preserving all the extensive formatting that Joplin has when it renders the notes to pdf The generated PDFs need to be beautiful. Rich fonts, graphics, formatting of the code listings etc. We will be heavily leaning into texlive/xetex for this. I would also like to explore using wkhtmltopdf so that CSS can be used to style the output. - mdbook - typst - marp - markwhen - kroki cli - quarto - bibtool - vale Add in any other common support tools you think may be needed (such as jq/yq). Generally this image will be used "headless" to run a generation workflow (or mdbook serve during active development of an mdbook site). It should have fish as it's shell (and also bash/zsh) for the occasional interactive use. Follow test-driven-development for this project without fail. Ensure that the image is built successfully and fully validated against this PRD Use the /home/localuser/TSYSDevStack/Toolbox/docs/output directory for all of the work you do for this task.	2025-11-11 20:59:13 -06:00
ReachableCEO	d94f81bc55	docs: update QWEN.md with communication style guidelines	2025-11-05 16:39:43 -06:00
ReachableCEO	bd2b6abcd6	docs: add Coldstart.md to git tracking	2025-11-05 16:38:53 -06:00
ReachableCEO	44199f10a0	feat: create global QWEN.md and journal files	2025-11-05 16:38:51 -06:00