---
title: "AI Integration Guide"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{AI Integration Guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## About This Vignette

This vignette documents putior's capabilities for **AI assistants** (like Claude, ChatGPT, or GitHub Copilot). It's designed to be read by language models to understand how to use putior effectively.

### For Humans

If you're a human reader, you probably want one of these instead:

| Guide | Description |
|-------|-------------|
| [Quick Start](quick-start.html) | Create your first diagram in 2 minutes |
| [Annotation Guide](annotation-guide.html) | Complete syntax reference |
| [Quick Reference](quick-reference.html) | Printable cheat sheet |
| [API Reference](api-reference.html) | Full function documentation |
| [Troubleshooting](troubleshooting.html) | Common issues and solutions |

### For AI Assistants

This content is automatically available via:

- **`putior_guide()`** - Returns this documentation as a string
- **MCP server** - Exposed as a tool via `putior_mcp_server()`
- **ACP server** - Available via `/runs` endpoint from `putior_acp_server()`

### Programmatic Access

```r
# Get guide documentation as a string
guide_text <- putior_guide()

# Use in prompt engineering
prompt <- paste("You have access to putior:", guide_text)

# Or access via MCP tools
tools <- putior_mcp_tools()
```

### MCP/ACP Integration

When running as an MCP or ACP server, AI assistants can:

1. **Discover capabilities** via `putior_guide` tool
2. **Extract annotations** via `put` tool
3. **Generate diagrams** via `put_diagram` tool
4. **Auto-detect workflows** via `put_auto` tool

See the [MCP Server section in CLAUDE.md](https://github.com/pjt222/putior/blob/main/CLAUDE.md#mcp-server-integration) for setup instructions.

## Agent-Almanac Integration

putior's procedural documentation lives in the
[agent-almanac](https://github.com/pjt222/agent-almanac) repository,
which provides 6 skills for the complete putior workflow:

| Skill | Purpose |
|-------|---------|
| [`install-putior`](https://github.com/pjt222/agent-almanac/blob/main/skills/install-putior/SKILL.md) | Installation and dependency setup |
| [`analyze-codebase-workflow`](https://github.com/pjt222/agent-almanac/blob/main/skills/analyze-codebase-workflow/SKILL.md) | Auto-detect workflows in arbitrary codebases |
| [`annotate-source-files`](https://github.com/pjt222/agent-almanac/blob/main/skills/annotate-source-files/SKILL.md) | Add PUT annotations to source files |
| [`generate-workflow-diagram`](https://github.com/pjt222/agent-almanac/blob/main/skills/generate-workflow-diagram/SKILL.md) | Generate themed Mermaid diagrams |
| [`configure-putior-mcp`](https://github.com/pjt222/agent-almanac/blob/main/skills/configure-putior-mcp/SKILL.md) | Set up MCP/ACP server for AI assistants |
| [`setup-putior-ci`](https://github.com/pjt222/agent-almanac/blob/main/skills/setup-putior-ci/SKILL.md) | GitHub Actions CI/CD for diagram auto-refresh |

---

## Guide Documentation

The content below is the same as returned by `putior_guide()`:

```{r, echo=FALSE, results='asis'}
guide_path <- system.file("GUIDE.md", package = "putior")
if (guide_path == "") {

  # Fallback for when building vignette before installation
  guide_path <- file.path("..", "inst", "GUIDE.md")
}
if (file.exists(guide_path)) {
  lines <- readLines(guide_path, warn = FALSE)
  # Skip YAML frontmatter (lines between --- markers)
  if (length(lines) > 0 && lines[1] == "---") {
    yaml_end <- which(lines[-1] == "---")[1] + 1
    if (!is.na(yaml_end)) {
      lines <- lines[(yaml_end + 1):length(lines)]
    }
  }
  cat(lines, sep = "\n")
} else {
  cat("Guide file not found. See `putior_guide()` for the full reference.")
}
```

---

## See Also

| Guide | Description |
|-------|-------------|
| [Quick Start](quick-start.html) | First diagram in 2 minutes |
| [Annotation Guide](annotation-guide.html) | Complete syntax reference |
| [Features Tour](features-tour.html) | Auto-detection, themes, logging |
| [API Reference](api-reference.html) | Function documentation |
| [Showcase](showcase.html) | Real-world examples |
| [Quick Reference](quick-reference.html) | At-a-glance reference card |
| [Troubleshooting](troubleshooting.html) | Common issues and solutions |