---

name: install-putior locale: caveman-ultra source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-24" description: > Install and configure the putior R package for workflow visualization. Covers CRAN and GitHub installation, optional dependencies (mcptools, ellmer, shiny, shinyAce, logger, plumber2), and verification of the complete annotation-to-diagram pipeline. Use when setting up putior for the first time, preparing a machine for workflow visualization tasks, when a downstream skill requires putior to be installed, or restoring an environment after an R version upgrade or renv wipe. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: workflow-visualization complexity: basic language: R tags: putior, install, workflow, mermaid, visualization, R

Install putior

Install putior R pkg + optional deps → annotation-to-diagram pipeline ready.

Use When

• First-time setup in project/env
• Prep machine for workflow viz
• Downstream skill (analyze-codebase-workflow, generate-workflow-diagram) needs it
• Restore after R ver upgrade / renv wipe

In

• Required: R install (≥4.1.0)
• Optional: CRAN (default) or GitHub dev ver
• Optional: opt deps: MCP (mcptools, ellmer), interactive (shiny, shinyAce), logging (logger), ACP (plumber2)

Do

Step 1: Verify R install

R.Version()$version.string
# Must be >= 4.1.0

# From WSL with Windows R
"/mnt/c/Program Files/R/R-4.5.2/bin/Rscript.exe" -e "cat(R.version.string)"

→ R version printed, ≥4.1.0.

If err: install/upgrade R. Windows → https://cran.r-project.org/bin/windows/base/. Linux → sudo apt install r-base.

Step 2: Install putior

# CRAN (recommended)
install.packages("putior")

# GitHub dev version (if latest features needed)
remotes::install_github("pjt222/putior")

→ Installs no errors. library(putior) loads silently.

If err: CRAN fails "not available for R ver" → use GitHub. GitHub fails → check remotes installed: install.packages("remotes").

Step 3: Optional deps

# MCP server integration (for AI assistant access)
remotes::install_github("posit-dev/mcptools")
install.packages("ellmer")

# Interactive sandbox
install.packages("shiny")
install.packages("shinyAce")

# Structured logging
install.packages("logger")

# ACP server (agent-to-agent communication)
install.packages("plumber2")

→ Each installs no errors.

If err: mcptools → remotes first. Linux system dep errs → install libs (e.g., sudo apt install libcurl4-openssl-dev for httr2).

Step 4: Verify

library(putior)

# Check package version
packageVersion("putior")

# Verify core functions are available
stopifnot(
  is.function(put),
  is.function(put_auto),
  is.function(put_diagram),
  is.function(put_generate),
  is.function(put_merge),
  is.function(put_theme)
)

# Test basic pipeline with a temp file
tmp <- tempfile(fileext = ".R")
writeLines("# put id:'test', label:'Hello putior'", tmp)
cat(put_diagram(put(tmp)))

→ Mermaid flowchart w/ test + Hello putior.

Key defaults: All scan fns (put(), put_auto(), put_generate(), put_merge()) default recursive = TRUE, scan subdirs auto. Breaking change from pre-0.2.0 where default was FALSE. All accept exclude param for regex file filtering (e.g., put("./src/", exclude = "test_")).

If shiny installed → interactive sandbox:

putior::run_sandbox()

Browser-based editor for PUT annotation syntax + real-time diagrams.

If err: put not found → pkg didn't install correctly. Reinstall install.packages("putior", dependencies = TRUE). Empty diagram → verify temp file + annotation uses single quotes inside double.

Check

• library(putior) loads no errors
• packageVersion("putior") valid version
• put() on valid PUT annotation → DF w/ 1 row
• put_diagram() → Mermaid starting flowchart
• All requested opt deps load no errors

Traps

• Wrong quote nesting: PUT uses single quotes inside annotation: id:'name' not id:"name" (conflicts w/ comment string delim).
• Missing Pandoc for vignettes: build local → set RSTUDIO_PANDOC in .Renviron.
• renv isolation: renv project → install inside renv lib: renv::install("putior") not install.packages().
• GitHub rate limits: mcptools from GitHub may fail w/o GITHUB_PAT. Set via usethis::create_github_token().

→

• analyze-codebase-workflow — next step post-install
• configure-putior-mcp — MCP server after opt deps
• manage-renv-dependencies — putior within renv env
• configure-mcp-server — general MCP config