diff --git a/Cargo.toml b/Cargo.toml
index b8e45c5..99ff111 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "texforge"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 rust-version = "1.75"
 description = "Self-contained LaTeX to PDF compiler CLI"
@@ -38,6 +38,10 @@ flate2 = "1.1"
 tar = "0.4"
 zip = { version = "2", default-features = false, features = ["deflate"] }
 
+# Mermaid diagram rendering
+mermaid-rs-renderer = { version = "0.2", default-features = false }
+resvg = "0.46"
+
 [dev-dependencies]
 tempfile = "3.8"
 
diff --git a/README.md b/README.md
index 0c9a6c7..db46e88 100644
--- a/README.md
+++ b/README.md
@@ -81,6 +81,9 @@ texforge fmt
 
 # Build to PDF
 texforge build
+
+# Remove build artifacts
+texforge clean
 ```
 
 ---
@@ -93,6 +96,7 @@ texforge build
 | `texforge new <name> -t <template>` | Create with specific template |
 | `texforge init` | Initialize texforge in an existing LaTeX project |
 | `texforge build` | Compile to PDF |
+| `texforge clean` | Remove build artifacts |
 | `texforge fmt` | Format .tex files |
 | `texforge fmt --check` | Check formatting without modifying |
 | `texforge check` | Lint without compiling |
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 88a297b..50f0bcf 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -15,6 +15,8 @@ pub struct Cli {
 
 #[derive(Subcommand)]
 enum Commands {
+    /// Remove build artifacts
+    Clean,
     /// Initialize a texforge project in the current directory
     Init,
     /// Create a new project from a template
@@ -61,6 +63,7 @@ enum TemplateAction {
 impl Cli {
     pub fn execute(self) -> Result<()> {
         match self.command {
+            Commands::Clean => commands::clean::execute(),
             Commands::Init => commands::init::execute(),
             Commands::New { name, template } => commands::new::execute(&name, template.as_deref()),
             Commands::Build => commands::build::execute(),
diff --git a/src/commands/build.rs b/src/commands/build.rs
index f8ac2ab..eceea9d 100644
--- a/src/commands/build.rs
+++ b/src/commands/build.rs
@@ -3,6 +3,7 @@
 use anyhow::Result;
 
 use crate::compiler;
+use crate::diagrams;
 use crate::domain::project::Project;
 
 /// Compile project to PDF.
@@ -11,10 +12,18 @@ pub fn execute() -> Result<()> {
 
     println!("Building project: {}", project.config.documento.titulo);
 
-    // Ensure build directory exists
     std::fs::create_dir_all(project.root.join("build"))?;
 
-    compiler::compile(&project.root, &project.config.compilacion.entry)?;
+    // Pre-process embedded diagrams — works on copies in build/, originals untouched
+    diagrams::process(&project.root, &project.config.compilacion.entry)?;
+
+    // Compile from build/ — all assets are mirrored there, diagrams use relative paths
+    let build_dir = project.root.join("build");
+    let entry_filename = std::path::Path::new(&project.config.compilacion.entry)
+        .file_name()
+        .map(|n| n.to_string_lossy().to_string())
+        .unwrap_or(project.config.compilacion.entry.clone());
+    compiler::compile(&build_dir, &entry_filename)?;
 
     let pdf_name = std::path::Path::new(&project.config.compilacion.entry).with_extension("pdf");
     println!("✅ build/{}", pdf_name.display());
diff --git a/src/commands/clean.rs b/src/commands/clean.rs
new file mode 100644
index 0000000..5a6d338
--- /dev/null
+++ b/src/commands/clean.rs
@@ -0,0 +1,20 @@
+//! `texforge clean` command implementation.
+
+use anyhow::Result;
+
+use crate::domain::project::Project;
+
+/// Remove the build/ directory.
+pub fn execute() -> Result<()> {
+    let project = Project::load()?;
+    let build_dir = project.root.join("build");
+
+    if !build_dir.exists() {
+        println!("Nothing to clean.");
+        return Ok(());
+    }
+
+    std::fs::remove_dir_all(&build_dir)?;
+    println!("✅ build/ removed");
+    Ok(())
+}
diff --git a/src/commands/mod.rs b/src/commands/mod.rs
index a6279fe..23f89e6 100644
--- a/src/commands/mod.rs
+++ b/src/commands/mod.rs
@@ -2,6 +2,7 @@
 
 pub mod build;
 pub mod check;
+pub mod clean;
 pub mod fmt;
 pub mod init;
 pub mod new;
diff --git a/src/commands/new.rs b/src/commands/new.rs
index 111fb7a..70143f7 100644
--- a/src/commands/new.rs
+++ b/src/commands/new.rs
@@ -64,7 +64,7 @@ bibliografia = "bib/references.bib"
 }
 
 /// Validate project name: no empty, no path traversal, no special chars.
-fn validate_project_name(name: &str) -> Result<()> {
+pub(crate) fn validate_project_name(name: &str) -> Result<()> {
     if name.is_empty() {
         anyhow::bail!("Project name cannot be empty");
     }
@@ -106,3 +106,33 @@ fn validate_project_name(name: &str) -> Result<()> {
 
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn empty_name_is_error() {
+        assert!(validate_project_name("").is_err());
+    }
+
+    #[test]
+    fn name_with_spaces_is_error() {
+        assert!(validate_project_name("my project").is_err());
+    }
+
+    #[test]
+    fn name_with_dotdot_is_error() {
+        assert!(validate_project_name("../evil").is_err());
+    }
+
+    #[test]
+    fn name_with_slash_is_error() {
+        assert!(validate_project_name("a/b").is_err());
+    }
+
+    #[test]
+    fn valid_name_is_ok() {
+        assert!(validate_project_name("mi-tesis").is_ok());
+    }
+}
diff --git a/src/compiler/mod.rs b/src/compiler/mod.rs
index 2c58f72..85f6df7 100644
--- a/src/compiler/mod.rs
+++ b/src/compiler/mod.rs
@@ -6,6 +6,7 @@ use std::process::Command;
 use anyhow::{Context, Result};
 
 /// Compile a LaTeX project to PDF using Tectonic.
+/// `root` is the working directory; output PDF goes into `root/` itself.
 pub fn compile(root: &Path, entry: &str) -> Result<()> {
     let tectonic = find_tectonic()?;
     let entry_path = root.join(entry);
@@ -13,7 +14,7 @@ pub fn compile(root: &Path, entry: &str) -> Result<()> {
     let output = Command::new(&tectonic)
         .arg(&entry_path)
         .arg("--outdir")
-        .arg(root.join("build"))
+        .arg(root)
         .arg("--keep-logs")
         .current_dir(root)
         .output()
@@ -96,7 +97,7 @@ fn parse_errors(raw: &str) -> Vec<CompileError> {
     errors
 }
 
-/// Find the tectonic binary in PATH or known locations, auto-installing if needed.
+/// Find the tectonic binary in PATH or known locations.
 fn find_tectonic() -> Result<std::path::PathBuf> {
     // Check PATH
     if let Ok(output) = Command::new("which").arg("tectonic").output() {
@@ -107,9 +108,8 @@ fn find_tectonic() -> Result<std::path::PathBuf> {
     }
 
     // Check known locations (including texforge-managed install)
-    let managed = dirs::home_dir().map(|h| h.join(".texforge/bin/tectonic"));
     for candidate in [
-        managed.clone(),
+        dirs::home_dir().map(|h| h.join(".texforge/bin/tectonic")),
         dirs::home_dir().map(|h| h.join(".cargo/bin/tectonic")),
         Some("/usr/local/bin/tectonic".into()),
         Some("/opt/homebrew/bin/tectonic".into()),
@@ -122,112 +122,9 @@ fn find_tectonic() -> Result<std::path::PathBuf> {
         }
     }
 
-    // Auto-install tectonic
-    eprintln!("Tectonic not found. Installing automatically...");
-    let dest = managed.ok_or_else(|| anyhow::anyhow!("Could not determine home directory"))?;
-    install_tectonic(&dest)?;
-    Ok(dest)
-}
-
-/// Download and install tectonic to the given path.
-fn install_tectonic(dest: &std::path::Path) -> Result<()> {
-    let target = current_target()?;
-    let version = "0.15.0";
-    let (filename, is_zip) = if target.contains("windows") {
-        (format!("tectonic-{}-{}.zip", version, target), true)
-    } else {
-        (format!("tectonic-{}-{}.tar.gz", version, target), false)
-    };
-
-    let url = format!(
-        "https://github.com/tectonic-typesetting/tectonic/releases/download/tectonic%40{}/{}",
-        version, filename
+    anyhow::bail!(
+        "Tectonic not found. Install everything with:\n\
+         \n  curl -fsSL https://raw.githubusercontent.com/JheisonMB/texforge/main/install.sh | sh\n\
+         \nor install tectonic separately: cargo install tectonic"
     );
-
-    eprintln!("Downloading tectonic {}...", version);
-
-    let response = reqwest::blocking::Client::new()
-        .get(&url)
-        .header("User-Agent", "texforge")
-        .send()
-        .context("Failed to download tectonic")?;
-
-    if !response.status().is_success() {
-        anyhow::bail!(
-            "Failed to download tectonic: HTTP {}\nURL: {}",
-            response.status(),
-            url
-        );
-    }
-
-    let bytes = response.bytes()?;
-
-    if let Some(parent) = dest.parent() {
-        std::fs::create_dir_all(parent)?;
-    }
-
-    if is_zip {
-        install_from_zip(&bytes, dest)?;
-    } else {
-        install_from_targz(&bytes, dest)?;
-    }
-
-    // Make executable on Unix
-    #[cfg(unix)]
-    {
-        use std::os::unix::fs::PermissionsExt;
-        std::fs::set_permissions(dest, std::fs::Permissions::from_mode(0o755))?;
-    }
-
-    eprintln!("✅ Tectonic installed to {}", dest.display());
-    Ok(())
-}
-
-fn install_from_targz(bytes: &[u8], dest: &std::path::Path) -> Result<()> {
-    let decoder = flate2::read::GzDecoder::new(bytes);
-    let mut archive = tar::Archive::new(decoder);
-    for entry in archive.entries()? {
-        let mut entry = entry?;
-        let path = entry.path()?.to_string_lossy().to_string();
-        if path.ends_with("tectonic") || path == "tectonic" {
-            std::io::copy(&mut entry, &mut std::fs::File::create(dest)?)?;
-            return Ok(());
-        }
-    }
-    anyhow::bail!("tectonic binary not found in archive")
-}
-
-fn install_from_zip(bytes: &[u8], dest: &std::path::Path) -> Result<()> {
-    let cursor = std::io::Cursor::new(bytes);
-    let mut archive = zip::ZipArchive::new(cursor)?;
-    for i in 0..archive.len() {
-        let mut file = archive.by_index(i)?;
-        if file.name().ends_with("tectonic.exe") || file.name() == "tectonic.exe" {
-            std::io::copy(&mut file, &mut std::fs::File::create(dest)?)?;
-            return Ok(());
-        }
-    }
-    anyhow::bail!("tectonic.exe not found in archive")
-}
-
-/// Detect the current platform target triple for tectonic releases.
-fn current_target() -> Result<&'static str> {
-    #[cfg(all(target_os = "linux", target_arch = "x86_64"))]
-    return Ok("x86_64-unknown-linux-musl");
-    #[cfg(all(target_os = "linux", target_arch = "aarch64"))]
-    return Ok("aarch64-unknown-linux-musl");
-    #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
-    return Ok("x86_64-apple-darwin");
-    #[cfg(all(target_os = "macos", target_arch = "aarch64"))]
-    return Ok("aarch64-apple-darwin");
-    #[cfg(all(target_os = "windows", target_arch = "x86_64"))]
-    return Ok("x86_64-pc-windows-msvc");
-    #[cfg(not(any(
-        all(target_os = "linux", target_arch = "x86_64"),
-        all(target_os = "linux", target_arch = "aarch64"),
-        all(target_os = "macos", target_arch = "x86_64"),
-        all(target_os = "macos", target_arch = "aarch64"),
-        all(target_os = "windows", target_arch = "x86_64"),
-    )))]
-    anyhow::bail!("Unsupported platform for automatic tectonic installation")
 }
diff --git a/src/diagrams/mod.rs b/src/diagrams/mod.rs
new file mode 100644
index 0000000..607cf5e
--- /dev/null
+++ b/src/diagrams/mod.rs
@@ -0,0 +1,290 @@
+//! Pre-processor for embedded diagram environments.
+//!
+//! Intercepts `\begin{mermaid}[opts]...\end{mermaid}` blocks, renders them
+//! to PNG, and replaces each block with a proper `figure` environment.
+//!
+//! Works on copies in `build/` — the original .tex files are never modified.
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+
+use anyhow::{Context, Result};
+
+/// Copy all .tex files to `build/`, rendering embedded diagrams in the copies.
+/// Also mirrors non-.tex assets so tectonic can resolve relative paths.
+/// Returns the path to the build copy of `entry`.
+pub fn process(root: &Path, entry: &str) -> Result<PathBuf> {
+    let build_dir = root.join("build");
+    std::fs::create_dir_all(&build_dir)?;
+
+    let diagrams_dir = build_dir.join("diagrams");
+    std::fs::create_dir_all(&diagrams_dir)?;
+
+    let mut counter = 0usize;
+
+    // Process .tex files
+    let tex_files = collect_tex_files(root, entry);
+    for src in &tex_files {
+        let rel = src.strip_prefix(root).unwrap_or(src);
+        let dest = build_dir.join(rel);
+        if let Some(parent) = dest.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        let content = std::fs::read_to_string(src)?;
+        let processed = render_diagrams(&content, &diagrams_dir, &mut counter)
+            .with_context(|| format!("Failed to render diagrams in {}", src.display()))?;
+        std::fs::write(&dest, processed)?;
+    }
+
+    // Mirror asset files (non-.tex, non-build) so tectonic resolves relative paths
+    mirror_assets(root, &build_dir)?;
+
+    Ok(build_dir.join(entry))
+}
+
+/// Replace all `\begin{mermaid}[opts]...\end{mermaid}` with figure environments.
+fn render_diagrams(content: &str, diagrams_dir: &Path, counter: &mut usize) -> Result<String> {
+    let mut result = String::new();
+    let mut remaining: &str = content;
+
+    while let Some(start) = remaining.find("\\begin{mermaid}") {
+        result.push_str(&remaining[..start]);
+
+        let after_begin = &remaining[start + "\\begin{mermaid}".len()..];
+
+        // Parse optional args: \begin{mermaid}[key=val, ...]
+        let (opts, after_opts) = parse_opts(after_begin);
+
+        let end = after_opts
+            .find("\\end{mermaid}")
+            .context("\\begin{mermaid} without matching \\end{mermaid}")?;
+
+        let diagram_src = after_opts[..end].trim();
+
+        // Render SVG → PNG
+        let svg = mermaid_rs_renderer::render(diagram_src)
+            .map_err(|e| anyhow::anyhow!("Mermaid render error: {}", e))?;
+        let png = svg_to_png(&svg).context("Failed to convert mermaid SVG to PNG")?;
+
+        *counter += 1;
+        let filename = format!("diagram-{}.png", counter);
+        std::fs::write(diagrams_dir.join(&filename), &png)?;
+
+        // Build figure environment
+        let pos = opts.get("pos").map(String::as_str).unwrap_or("H");
+        if !["H", "t", "b", "h", "p"].contains(&pos) {
+            anyhow::bail!(
+                "Invalid mermaid option pos='{}' — valid values are: H, t, b, h, p",
+                pos
+            );
+        }
+        let width = opts
+            .get("width")
+            .map(String::as_str)
+            .unwrap_or("\\linewidth");
+        let caption = opts.get("caption");
+        let rel_path = format!("diagrams/{}", filename);
+
+        let mut fig = format!(
+            "\\begin{{figure}}[{pos}]\n  \\centering\n  \\includegraphics[width={width}]{{{rel_path}}}\n"
+        );
+        if let Some(cap) = caption {
+            fig.push_str(&format!("  \\caption{{{}}}\n", cap));
+        }
+        fig.push_str("\\end{figure}");
+
+        result.push_str(&fig);
+        remaining = &after_opts[end + "\\end{mermaid}".len()..];
+    }
+
+    result.push_str(remaining);
+    Ok(result)
+}
+
+/// Parse `[key=val, key2=val2]` into a map. Returns `(map, rest_of_str)`.
+pub(crate) fn parse_opts(s: &str) -> (HashMap<String, String>, &str) {
+    let s = s.trim_start_matches('\n').trim_start_matches('\r');
+    if !s.starts_with('[') {
+        return (HashMap::new(), s);
+    }
+    let Some(end) = s.find(']') else {
+        return (HashMap::new(), s);
+    };
+    let inner = &s[1..end];
+    let rest = &s[end + 1..];
+
+    let mut map = HashMap::new();
+    for part in inner.split(',') {
+        let part = part.trim();
+        if let Some((k, v)) = part.split_once('=') {
+            map.insert(k.trim().to_string(), v.trim().to_string());
+        }
+    }
+    (map, rest)
+}
+
+/// Collect .tex files reachable from entry via \input (non-recursive for simplicity).
+fn collect_tex_files(root: &Path, entry: &str) -> Vec<PathBuf> {
+    let mut files = Vec::new();
+    collect_recursive(root, entry, &mut files);
+    files
+}
+
+fn collect_recursive(root: &Path, entry: &str, files: &mut Vec<PathBuf>) {
+    let path = resolve_tex(root, entry);
+    if !path.exists() || files.contains(&path) {
+        return;
+    }
+    files.push(path.clone());
+    if let Ok(content) = std::fs::read_to_string(&path) {
+        for line in content.lines() {
+            for input in extract_inputs(line) {
+                collect_recursive(root, input, files);
+            }
+        }
+    }
+}
+
+fn extract_inputs(line: &str) -> Vec<&str> {
+    let mut results = Vec::new();
+    let mut search = line;
+    while let Some(pos) = search.find("\\input{") {
+        let after = &search[pos + 7..];
+        if let Some(end) = after.find('}') {
+            results.push(after[..end].trim());
+            search = &after[end + 1..];
+        } else {
+            break;
+        }
+    }
+    results
+}
+
+fn resolve_tex(root: &Path, input: &str) -> PathBuf {
+    let p = root.join(input);
+    if p.extension().is_some() {
+        p
+    } else {
+        p.with_extension("tex")
+    }
+}
+
+/// Mirror asset directories into build/ using symlinks (Unix) or file copy (Windows).
+/// Skips .tex files (handled separately) and the build/ dir itself.
+fn mirror_assets(root: &Path, build_dir: &Path) -> Result<()> {
+    for entry in std::fs::read_dir(root)? {
+        let entry = entry?;
+        let path = entry.path();
+        let name = entry.file_name();
+        let name_str = name.to_string_lossy();
+
+        // Skip hidden, build/, and .tex files at root level
+        if name_str.starts_with('.') || path == build_dir {
+            continue;
+        }
+
+        let dest = build_dir.join(&name);
+
+        if path.is_dir() {
+            // Remove stale symlink/dir if it points somewhere wrong
+            if dest.exists() || dest.symlink_metadata().is_ok() {
+                continue; // already linked
+            }
+            link_or_copy_dir(&path, &dest)?;
+        }
+        // Individual root-level files (e.g. .bib at root) — skip .tex
+        else if path.is_file() {
+            let ext = path.extension().and_then(|e| e.to_str()).unwrap_or("");
+            if ext == "tex" {
+                continue;
+            }
+            if !dest.exists() {
+                std::fs::copy(&path, &dest)?;
+            }
+        }
+    }
+    Ok(())
+}
+
+#[cfg(unix)]
+fn link_or_copy_dir(src: &Path, dest: &Path) -> Result<()> {
+    // Symlink: dest -> ../dirname (relative from build/)
+    let target = std::path::Path::new("..").join(src.file_name().unwrap());
+    std::os::unix::fs::symlink(&target, dest).with_context(|| {
+        format!(
+            "Failed to symlink {} -> {}",
+            dest.display(),
+            target.display()
+        )
+    })
+}
+
+#[cfg(not(unix))]
+fn link_or_copy_dir(src: &Path, dest: &Path) -> Result<()> {
+    // Windows fallback: recursive copy
+    copy_dir_recursive(src, dest)
+}
+
+#[cfg(not(unix))]
+fn copy_dir_recursive(src: &Path, dest: &Path) -> Result<()> {
+    std::fs::create_dir_all(dest)?;
+    for entry in walkdir::WalkDir::new(src)
+        .into_iter()
+        .filter_map(|e| e.ok())
+    {
+        let rel = entry.path().strip_prefix(src).unwrap();
+        let target = dest.join(rel);
+        if entry.file_type().is_dir() {
+            std::fs::create_dir_all(&target)?;
+        } else {
+            std::fs::copy(entry.path(), &target)?;
+        }
+    }
+    Ok(())
+}
+
+/// Convert SVG string to PNG bytes at 2x scale for print quality.
+fn svg_to_png(svg: &str) -> Result<Vec<u8>> {
+    let options = resvg::usvg::Options::default();
+    let tree = resvg::usvg::Tree::from_str(svg, &options).context("Failed to parse SVG")?;
+
+    let scale = 2.0_f32;
+    let width = (tree.size().width() * scale) as u32;
+    let height = (tree.size().height() * scale) as u32;
+
+    let mut pixmap =
+        resvg::tiny_skia::Pixmap::new(width, height).context("Failed to create pixmap")?;
+
+    resvg::render(
+        &tree,
+        resvg::tiny_skia::Transform::from_scale(scale, scale),
+        &mut pixmap.as_mut(),
+    );
+
+    pixmap.encode_png().context("Failed to encode PNG")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_opts_no_brackets_returns_empty_map() {
+        let (map, rest) = parse_opts("hello");
+        assert!(map.is_empty());
+        assert_eq!(rest, "hello");
+    }
+
+    #[test]
+    fn parse_opts_width_and_pos() {
+        let (map, _) = parse_opts("[width=0.5\\linewidth, pos=t]");
+        assert_eq!(map.get("width").map(String::as_str), Some("0.5\\linewidth"));
+        assert_eq!(map.get("pos").map(String::as_str), Some("t"));
+    }
+
+    #[test]
+    fn parse_opts_caption() {
+        let (map, _) = parse_opts("[caption=My diagram]");
+        assert_eq!(map.get("caption").map(String::as_str), Some("My diagram"));
+    }
+}
diff --git a/src/formatter/mod.rs b/src/formatter/mod.rs
index 9fff0bb..a9ea0c4 100644
--- a/src/formatter/mod.rs
+++ b/src/formatter/mod.rs
@@ -117,3 +117,51 @@ fn extract_env_name(line: &str) -> Option<String> {
     let end = line[start..].find('}')?;
     Some(line[start..start + end].to_string())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn empty_input_returns_single_newline() {
+        assert_eq!(format(""), "\n");
+    }
+
+    #[test]
+    fn trailing_newline_always_present() {
+        let out = format("hello");
+        assert!(out.ends_with('\n'));
+    }
+
+    #[test]
+    fn indentation_inside_environment() {
+        let src = "\\begin{document}\nhello\n\\end{document}";
+        let out = format(src);
+        assert!(
+            out.contains("  hello"),
+            "expected indented 'hello', got:\n{}",
+            out
+        );
+    }
+
+    #[test]
+    fn multiple_blank_lines_collapsed() {
+        let src = "a\n\n\n\nb";
+        let out = format(src);
+        assert_eq!(out, "a\n\nb\n");
+    }
+
+    #[test]
+    fn structural_commands_not_indented() {
+        let src = "\\begin{document}\n\\section{Intro}\n\\end{document}";
+        let out = format(src);
+        assert!(out.contains("\n\\section{Intro}\n"), "got:\n{}", out);
+    }
+
+    #[test]
+    fn verbatim_content_preserved() {
+        let src = "\\begin{verbatim}\n  raw   content\n\\end{verbatim}";
+        let out = format(src);
+        assert!(out.contains("  raw   content"), "got:\n{}", out);
+    }
+}
diff --git a/src/linter/mod.rs b/src/linter/mod.rs
index d9675b2..3c9780f 100644
--- a/src/linter/mod.rs
+++ b/src/linter/mod.rs
@@ -80,6 +80,7 @@ pub fn lint(root: &Path, entry: &str, bib_file: Option<&str>) -> Result<Vec<Lint
             &mut errors,
         );
         check_environments(&rel, &content, &mut errors);
+        check_mermaid_blocks(&rel, &content, &mut errors);
     }
 
     Ok(errors)
@@ -123,30 +124,6 @@ fn check_references(
             }
         }
 
-        for arg in extract_commands(&line, "lstinputlisting") {
-            let path = root.join(arg);
-            if !path.exists() {
-                errors.push(LintError {
-                    file: rel.to_string(),
-                    line: line_num,
-                    message: format!("\\lstinputlisting{{{}}} — file not found", arg),
-                    suggestion: None,
-                });
-            }
-        }
-
-        for args in extract_commands_two_args(&line, "inputminted") {
-            let path = root.join(args);
-            if !path.exists() {
-                errors.push(LintError {
-                    file: rel.to_string(),
-                    line: line_num,
-                    message: format!("\\inputminted{{...}}{{{}}} — file not found", args),
-                    suggestion: None,
-                });
-            }
-        }
-
         if bib_file.is_some() {
             for arg in extract_commands(&line, "cite") {
                 for key in arg.split(',') {
@@ -173,6 +150,28 @@ fn check_references(
                 });
             }
         }
+
+        for arg in extract_commands(&line, "lstinputlisting") {
+            if !root.join(arg).exists() {
+                errors.push(LintError {
+                    file: rel.to_string(),
+                    line: line_num,
+                    message: format!("\\lstinputlisting{{{}}} — file not found", arg),
+                    suggestion: None,
+                });
+            }
+        }
+
+        for arg in extract_inputminted_files(&line) {
+            if !root.join(arg).exists() {
+                errors.push(LintError {
+                    file: rel.to_string(),
+                    line: line_num,
+                    message: format!("\\inputminted{{{}}} — file not found", arg),
+                    suggestion: None,
+                });
+            }
+        }
     }
 }
 
@@ -228,53 +227,6 @@ fn check_environments(rel: &str, content: &str, errors: &mut Vec<LintError>) {
     }
 }
 
-/// Extract the second `{arg}` from `\command{first}{second}` occurrences.
-fn extract_commands_two_args<'a>(line: &'a str, cmd: &str) -> Vec<&'a str> {
-    let mut results = Vec::new();
-    let pattern = format!("\\{}", cmd);
-    let mut search = line;
-
-    while let Some(pos) = search.find(&pattern) {
-        let after = &search[pos + pattern.len()..];
-        // Skip optional args [...]
-        let after = if after.starts_with('[') {
-            match after.find(']') {
-                Some(end) => &after[end + 1..],
-                None => break,
-            }
-        } else {
-            after
-        };
-        // Skip first {arg}
-        let after = if after.starts_with('{') {
-            match after.find('}') {
-                Some(end) => &after[end + 1..],
-                None => {
-                    search = after;
-                    continue;
-                }
-            }
-        } else {
-            search = after;
-            continue;
-        };
-        // Extract second {arg}
-        if after.starts_with('{') {
-            if let Some(end) = after.find('}') {
-                let arg = after[1..end].trim();
-                if !arg.is_empty() {
-                    results.push(arg);
-                }
-                search = &after[end + 1..];
-                continue;
-            }
-        }
-        search = after;
-    }
-
-    results
-}
-
 /// Extract arguments from `\command{arg}` and `\command[opts]{arg}` occurrences in a line.
 fn extract_commands<'a>(line: &'a str, cmd: &str) -> Vec<&'a str> {
     let mut results = Vec::new();
@@ -366,6 +318,97 @@ fn strip_comment(line: &str) -> String {
     result
 }
 
+/// Check mermaid blocks: unclosed and invalid pos option.
+fn check_mermaid_blocks(rel: &str, content: &str, errors: &mut Vec<LintError>) {
+    const VALID_POS: &[&str] = &["H", "t", "b", "h", "p"];
+
+    for (i, line) in content.lines().enumerate() {
+        let line_num = i + 1;
+        let trimmed = line.trim();
+
+        if !trimmed.starts_with("\\begin{mermaid}") {
+            continue;
+        }
+
+        // Check for unclosed block
+        let rest = &content[content.lines().take(i).map(|l| l.len() + 1).sum::<usize>()..];
+        if !rest.contains("\\end{mermaid}") {
+            errors.push(LintError {
+                file: rel.to_string(),
+                line: line_num,
+                message: "\\begin{mermaid} without matching \\end{mermaid}".into(),
+                suggestion: Some("Add \\end{mermaid}".into()),
+            });
+            continue;
+        }
+
+        // Check pos option if present
+        if let Some(opts_start) = trimmed.find('[') {
+            if let Some(opts_end) = trimmed.find(']') {
+                let opts = &trimmed[opts_start + 1..opts_end];
+                for part in opts.split(',') {
+                    if let Some((k, v)) = part.split_once('=') {
+                        if k.trim() == "pos" {
+                            let pos = v.trim();
+                            if !VALID_POS.contains(&pos) {
+                                errors.push(LintError {
+                                    file: rel.to_string(),
+                                    line: line_num,
+                                    message: format!(
+                                        "\\begin{{mermaid}} invalid pos='{}' — valid values: H, t, b, h, p",
+                                        pos
+                                    ),
+                                    suggestion: Some("Use pos=H, pos=t, pos=b, pos=h, or pos=p".into()),
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Extract the file argument from `\inputminted{lang}{file}` (second brace group).
+fn extract_inputminted_files(line: &str) -> Vec<&str> {
+    let mut results = Vec::new();
+    let mut search = line;
+    while let Some(pos) = search.find("\\inputminted") {
+        let after = &search[pos + "\\inputminted".len()..];
+        // skip optional [...]
+        let after = if after.starts_with('[') {
+            match after.find(']') {
+                Some(e) => &after[e + 1..],
+                None => break,
+            }
+        } else {
+            after
+        };
+        // skip first {lang}
+        let after = if after.starts_with('{') {
+            match after.find('}') {
+                Some(e) => &after[e + 1..],
+                None => break,
+            }
+        } else {
+            break;
+        };
+        // extract second {file}
+        if after.starts_with('{') {
+            if let Some(end) = after.find('}') {
+                let arg = after[1..end].trim();
+                if !arg.is_empty() {
+                    results.push(arg);
+                }
+                search = &after[end + 1..];
+                continue;
+            }
+        }
+        break;
+    }
+    results
+}
+
 /// Parse `@type{key, ...}` entries from a .bib file.
 fn parse_bib_keys(path: &Path) -> HashSet<String> {
     let mut keys = HashSet::new();
@@ -387,3 +430,93 @@ fn parse_bib_keys(path: &Path) -> HashSet<String> {
     }
     keys
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+    use tempfile::TempDir;
+
+    fn setup(tex: &str) -> (TempDir, String) {
+        let dir = TempDir::new().unwrap();
+        fs::write(dir.path().join("main.tex"), tex).unwrap();
+        (dir, "main.tex".to_string())
+    }
+
+    fn has_error(errors: &[LintError], fragment: &str) -> bool {
+        errors.iter().any(|e| e.message.contains(fragment))
+    }
+
+    #[test]
+    fn includegraphics_missing_file_is_error() {
+        let (dir, entry) = setup("\\includegraphics{missing.png}");
+        let errors = lint(dir.path(), &entry, None).unwrap();
+        assert!(has_error(&errors, "missing.png"));
+    }
+
+    #[test]
+    fn includegraphics_existing_file_no_error() {
+        let (dir, entry) = setup("\\includegraphics{img.png}");
+        fs::write(dir.path().join("img.png"), b"").unwrap();
+        let errors = lint(dir.path(), &entry, None).unwrap();
+        assert!(!has_error(&errors, "img.png"));
+    }
+
+    #[test]
+    fn cite_missing_key_is_error() {
+        let (dir, entry) = setup("\\cite{ghost2020}");
+        fs::write(dir.path().join("refs.bib"), "@article{real2020,}").unwrap();
+        let errors = lint(dir.path(), &entry, Some("refs.bib")).unwrap();
+        assert!(has_error(&errors, "ghost2020"));
+    }
+
+    #[test]
+    fn cite_valid_key_no_error() {
+        let (dir, entry) = setup("\\cite{real2020}");
+        fs::write(dir.path().join("refs.bib"), "@article{real2020,}").unwrap();
+        let errors = lint(dir.path(), &entry, Some("refs.bib")).unwrap();
+        assert!(!has_error(&errors, "real2020"));
+    }
+
+    #[test]
+    fn begin_without_end_is_error() {
+        let (dir, entry) = setup("\\begin{figure}");
+        let errors = lint(dir.path(), &entry, None).unwrap();
+        assert!(has_error(&errors, "never closed"));
+    }
+
+    #[test]
+    fn ref_without_label_is_error() {
+        let (dir, entry) = setup("\\ref{fig:missing}");
+        let errors = lint(dir.path(), &entry, None).unwrap();
+        assert!(has_error(&errors, "fig:missing"));
+    }
+
+    #[test]
+    fn mermaid_invalid_pos_is_error() {
+        let (dir, entry) = setup("\\begin{mermaid}[pos=x]\n\\end{mermaid}");
+        let errors = lint(dir.path(), &entry, None).unwrap();
+        assert!(has_error(&errors, "invalid pos"));
+    }
+
+    #[test]
+    fn mermaid_without_end_is_error() {
+        let (dir, entry) = setup("\\begin{mermaid}");
+        let errors = lint(dir.path(), &entry, None).unwrap();
+        assert!(has_error(&errors, "without matching \\end{mermaid}"));
+    }
+
+    #[test]
+    fn lstinputlisting_missing_file_is_error() {
+        let (dir, entry) = setup("\\lstinputlisting{code.py}");
+        let errors = lint(dir.path(), &entry, None).unwrap();
+        assert!(has_error(&errors, "code.py"));
+    }
+
+    #[test]
+    fn inputminted_missing_file_is_error() {
+        let (dir, entry) = setup("\\inputminted{python}{code.py}");
+        let errors = lint(dir.path(), &entry, None).unwrap();
+        assert!(has_error(&errors, "code.py"));
+    }
+}
diff --git a/src/main.rs b/src/main.rs
index a78c83c..39d0a57 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -6,6 +6,7 @@
 mod cli;
 mod commands;
 mod compiler;
+mod diagrams;
 mod domain;
 mod formatter;
 mod linter;
diff --git a/src/templates/general/main.tex b/src/templates/general/main.tex
index 9487ed7..c49127e 100644
--- a/src/templates/general/main.tex
+++ b/src/templates/general/main.tex
@@ -6,6 +6,7 @@
 \usepackage[T1]{fontenc}
 \usepackage[spanish]{babel}
 \usepackage{amsmath}
+\usepackage{float}
 \usepackage{graphicx}
 \usepackage{hyperref}
 \usepackage{geometry}
diff --git a/src/utils/mod.rs b/src/utils/mod.rs
index 1057cfe..37acfd1 100644
--- a/src/utils/mod.rs
+++ b/src/utils/mod.rs
@@ -18,19 +18,24 @@ pub fn templates_dir() -> anyhow::Result<std::path::PathBuf> {
     Ok(dir)
 }
 
-/// Find all .tex files in a directory
+/// Find all .tex files in a directory, excluding build/
 pub fn find_tex_files(root: &Path) -> anyhow::Result<Vec<std::path::PathBuf>> {
     let mut files = Vec::new();
+    let build_dir = root.join("build");
 
     for entry in walkdir::WalkDir::new(root)
         .follow_links(true)
         .into_iter()
         .filter_map(|e| e.ok())
     {
+        let path = entry.path();
+        if path.starts_with(&build_dir) {
+            continue;
+        }
         if entry.file_type().is_file() {
-            if let Some(ext) = entry.path().extension() {
+            if let Some(ext) = path.extension() {
                 if ext == "tex" {
-                    files.push(entry.path().to_path_buf());
+                    files.push(path.to_path_buf());
                 }
             }
         }