---
title: "Getting Started with tutorizeR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with tutorizeR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## User goal

This vignette helps an instructor convert one existing `.qmd` or `.Rmd` lesson into an interactive tutorial. The pedagogical goal is to keep one source document while generating student-facing practice material.

## Minimal example

```{r eval=FALSE}
library(tutorizeR)

work_dir <- file.path(tempdir(), "tutorizeR-minimal")

report <- tutorize(
  input = file.path(work_dir, "lesson.qmd"),
  output_dir = work_dir,
  format = "learnr",
  assessment = "both",
  overwrite = TRUE
)

print(report)
```

The report records the input file, output file, format, assessment mode, generated exercises, MCQs, warnings, lint results, and render status.

## Realistic installed example

```{r eval=FALSE}
library(tutorizeR)

example_dir <- system.file("examples", "example_course_module", package = "tutorizeR")
work_dir <- file.path(tempdir(), "tutorizeR-example")
dir.create(work_dir, recursive = TRUE, showWarnings = FALSE)

file.copy(file.path(example_dir, "lesson-source.qmd"), work_dir, overwrite = TRUE)
file.copy(file.path(example_dir, "student_activity.csv"), work_dir, overwrite = TRUE)

question_bank <- load_question_bank(file.path(example_dir, "question-bank"))

report <- tutorize(
  input = file.path(work_dir, "lesson-source.qmd"),
  output_dir = work_dir,
  format = "learnr",
  assessment = "both",
  question_bank = question_bank,
  mcq_source = "mixed",
  overwrite = TRUE,
  verbose = FALSE
)

print(report)
```

## Batch conversion

```{r eval=FALSE}
library(tutorizeR)

course_dir <- file.path(tempdir(), "course_material")
output_dir <- file.path(course_dir, "tutorials")

folder_report <- convert_folder(
  dir = course_dir,
  recursive = TRUE,
  output_dir = output_dir,
  format = "learnr",
  assessment = "both",
  overwrite = TRUE
)

print(folder_report)
```

## Source annotation tags

Use comments inside R chunks:

- `# tutorizeR: skip`
- `# tutorizeR: exercise-only`
- `# tutorizeR: solution-only`
- `# tutorizeR: mcq`
- `# tutorizeR: narrative-only`
- `# tutorizeR: locked`
- `# tutorizeR: hints=Hint 1|Hint 2`

## Limits

Generated tutorials should be reviewed before release. The package can scaffold exercises, solutions, MCQs, and reports, but it does not decide whether a prompt is pedagogically appropriate for a course. Formal learning-outcome evaluation: Not verifiable from repository contents.

## Reproducibility checklist

```{r eval=FALSE}
library(tutorizeR)

example_dir <- system.file("examples", "example_course_module", package = "tutorizeR")
source(file.path(example_dir, "run-example.R"))
```