---
title: "Quick Start"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Quick Start}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```

## Your First Diagram in 2 Minutes

### Step 1: Install

```{r eval=FALSE}
install.packages("putior")
```
```{r}
library(putior)
```

### Step 2: Add Annotations to Your Code

Add `# put` comments to your R scripts:

```r
# my_analysis.R
# put label:"Load Data", output:"raw_data"
data <- read.csv("sales.csv")

# put label:"Clean Data", input:"raw_data", output:"clean_data"
clean <- data[complete.cases(data), ]

# put label:"Generate Report", input:"clean_data", output:"report.html"
rmarkdown::render("report.Rmd")
```

### Step 3: Generate Diagram

```{r eval=FALSE}
workflow <- put("my_analysis.R")
put_diagram(workflow)
```

That's it! You'll see a flowchart like this:

```{r first-diagram, echo=FALSE, results='asis', eval=TRUE}
library(putior)
demo_workflow <- data.frame(
  file_name = "my_analysis.R",
  id = c("load", "clean", "report"),
  label = c("Load Data", "Clean Data", "Generate Report"),
  node_type = c("input", "process", "output"),
  input = c(NA, "raw_data", "clean_data"),
  output = c("raw_data", "clean_data", "report.html"),
  stringsAsFactors = FALSE
)
cat("```mermaid\n")
cat(put_diagram(demo_workflow, theme = "github", output = "raw"))
cat("\n```\n")
```

---

## Try It Now

```{r try-it-now, results='asis', eval=TRUE}
# Create a temporary file with annotations
temp_file <- tempfile(fileext = ".R")
writeLines(c(
  '# put label:"Extract", output:"raw.csv"',
  'data <- read.csv("source.csv")',
  '',
  '# put label:"Transform", input:"raw.csv", output:"clean.csv"',
  'clean <- transform(data)',
  '',
  '# put label:"Load", input:"clean.csv", output:"database"',
  'write_to_db(clean)'
), temp_file)

# Scan and visualize
workflow <- put(temp_file)
cat("```mermaid\n")
cat(put_diagram(workflow, output = "raw"))
cat("\n```\n")

# Cleanup
unlink(temp_file)
```

---
## Annotation Syntax at a Glance

```
# put label:"Step Name", input:"file.csv", output:"result.csv"
```

| Field | Purpose | Required |
|-------|---------|----------|
| `label` | Human-readable name | Yes |
| `input` | Files/data consumed | No |
| `output` | Files/data produced | No |
| `id` | Unique identifier | No (auto-generated) |
| `node_type` | `input`, `process`, `output`, `decision`, `start`, `end` | No (defaults to `process`) |

**Multiple inputs/outputs:** Use commas: `input:"a.csv, b.csv"`

---

## Multi-Language Support

putior works with 30+ languages. Comment prefix is auto-detected:

| Language | Annotation |
|----------|------------|
| R, Python, Shell | `# put label:"..."` |
| SQL, Lua | `-- put label:"..."` |
| JavaScript, Go, Rust | `// put label:"..."` |
| MATLAB | `% put label:"..."` |

---

## Common Patterns

### Scan a Directory
```{r eval=FALSE}
workflow <- put("./src/")
put_diagram(workflow)
```

### Include Subdirectories
```{r eval=FALSE}
workflow <- put("./project/", recursive = TRUE)
```

### Auto-Detect Workflow (No Annotations!)
```{r eval=FALSE}
# Automatically detect file I/O from code
workflow <- put_auto("./src/")
put_diagram(workflow)
```

### Choose a Theme
```{r eval=FALSE}
put_diagram(workflow, theme = "github")  # or: light, dark, minimal, viridis
```

### Save to File
```{r eval=FALSE}
put_diagram(workflow, output = "file", file = "workflow.md")
```

---

## Interactive Sandbox

Experiment without creating files:

```{r eval=FALSE}
run_sandbox()  # Opens Shiny app
```

---

## Quick Reference

```r
# Core functions
put(path)                    # Extract annotations
put_diagram(workflow)        # Generate Mermaid diagram
put_auto(path)               # Auto-detect workflow (no annotations)
put_generate(path)           # Generate annotation suggestions

# Useful options
put("./", recursive = TRUE)  # Include subdirectories
put_diagram(wf, theme = "github", direction = "LR")
put_diagram(wf, show_artifacts = FALSE)  # Hide data files
```

**Need help?** Run `?put` or `?put_diagram` for full documentation.

---

## See Also

| Guide | Description |
|-------|-------------|
| [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 |
| [AI Integration](ai-integration.html) | MCP/ACP integration guide |