2 files changed, 48 insertions, 5 deletions

diff --git a/dev_tools/src/bin/docsify-sidebar-gen.rs b/dev_tools/src/bin/docsify-sidebar-gen.rs
index 319b2da..f45549a 100644
--- a/dev_tools/src/bin/docsify-sidebar-gen.rs
+++ b/dev_tools/src/bin/docsify-sidebar-gen.rs
@@ -93,8 +93,8 @@ fn build_sidebar_content(base_dir: &Path, pages_dir: &Path, sidebar_head: &str)
         }
     }
 
-    // Sort root files by link for stable order
-    root_files.sort_by(|a, b| a.link.cmp(&b.link));
+    // Sort root files — natural order (1, 2, ..., 10, 11)
+    root_files.sort_by(|a, b| natural_cmp(&a.link, &b.link));
 
     // Append root-level files
     for f in &root_files {
@@ -104,7 +104,7 @@ fn build_sidebar_content(base_dir: &Path, pages_dir: &Path, sidebar_head: &str)
     // Append subdirectory groups
     for (dir_name, entries) in &sub_dirs {
         let mut sorted_entries = entries.clone();
-        sorted_entries.sort_by(|a, b| a.link.cmp(&b.link));
+        sorted_entries.sort_by(|a, b| natural_cmp(&a.link, &b.link));
 
         // Directory header with 2-space indent
         let _ = writeln!(lines, "* {dir_name}");
@@ -200,3 +200,28 @@ fn find_git_repo() -> Option<std::path::PathBuf> {
 
     None
 }
+
+/// Natural (numeric-aware) comparison for sidebar links.
+///
+/// Files prefixed with a number (e.g. `1-getting-started`) are sorted by that number;
+/// files without a numeric prefix fall back to lexicographic order (after numbers).
+fn natural_cmp(a: &str, b: &str) -> std::cmp::Ordering {
+    let num_a = extract_leading_number(a);
+    let num_b = extract_leading_number(b);
+    num_a.cmp(&num_b)
+}
+
+/// Extract the leading numeric prefix from a sidebar link path.
+///
+/// Looks at the filename stem (after the last `/`) for a number before the first `-`.
+/// Returns `usize::MAX` for entries without a numeric prefix.
+fn extract_leading_number(link: &str) -> usize {
+    if let Some(file_stem) = link.rsplit('/').next() {
+        if let Some(num_end) = file_stem.find('-') {
+            if let Ok(num) = file_stem[..num_end].parse::<usize>() {
+                return num;
+            }
+        }
+    }
+    usize::MAX
+}
diff --git a/dev_tools/src/verify.rs b/dev_tools/src/verify.rs
index 834e408..2ddff0c 100644
--- a/dev_tools/src/verify.rs
+++ b/dev_tools/src/verify.rs
@@ -73,6 +73,24 @@ fn parse_single_block(lines: &[&str], start: usize, source_file: &str) -> Option
             break;
         }
 
+        // @@@ lines: strip the prefix and treat as regular Rust code
+        // These lines are hidden in the rendered docs (filtered by a docsify plugin)
+        // but must still compile.
+        if trimmed.starts_with("@@@") {
+            in_header = false;
+            // Strip @@@ and optionally one following space
+            let code = trimmed[3..].trim_start();
+            if code.contains("fn main") {
+                has_main = true;
+            }
+            if code.contains("gen_program!") {
+                has_gen_program = true;
+            }
+            code_lines.push(code.to_string());
+            idx += 1;
+            continue;
+        }
+
         // Parse header comments
         // Check for NOT VERIFIED marker
         if in_header && trimmed == "// NOT VERIFIED" {
@@ -278,8 +296,8 @@ pub fn generate_main_rs(block: &CodeBlock) -> String {
 pub fn generate_build_rs(block: &CodeBlock) -> String {
     let mut output = String::from("#![allow(dead_code)]\n#![allow(unused)]\n");
 
-    if !block.code.contains("use mingling::builds::*;") {
-        output.push_str("#[allow(unused_imports)]\nuse mingling::builds::*;\n\n");
+    if !block.code.contains("use mingling::build::*;") {
+        output.push_str("#[allow(unused_imports)]\nuse mingling::build::*;\n\n");
     }
 
     if block.has_main {