docs: add dev-docs site with dark/light theme support

9 files changed, 1719 insertions, 35 deletions

diff --git a/dev_tools/src/bin/docsify-sidebar-gen.rs b/dev_tools/src/bin/docsify-sidebar-gen.rs
index f45549a..016afe1 100644
--- a/dev_tools/src/bin/docsify-sidebar-gen.rs
+++ b/dev_tools/src/bin/docsify-sidebar-gen.rs
@@ -1,60 +1,98 @@
 use std::collections::BTreeMap;
 use std::fmt::Write;
-use std::path::Path;
+use std::path::{Path, PathBuf};
 
 use tools::println_cargo_style;
 
-const PAGES_ROOT: &str = "./docs/pages";
-const SIDEBAR_PATH: &str = "./docs/_sidebar.md";
-
 const SIDEBAR_HEAD: &str = "- [Welcome!](README)\n";
 
 fn main() {
     println_cargo_style!("Refresh: _sidebar.md");
-    gen_sidebar();
-    gen_translation_sidebars();
+    gen_all_sidebars();
 }
 
-/// Generate _sidebar.md for the primary language
-fn gen_sidebar() {
+/// Find all README.md under docs/, treat each as a site, and generate _sidebar.md for it.
+fn gen_all_sidebars() {
     let repo_root = find_git_repo().unwrap();
-    let pages_root = repo_root.join(PAGES_ROOT);
+    let docs_root = repo_root.join("docs");
+
+    let readme_paths = find_all_readmes(&docs_root);
+
+    for readme_path in &readme_paths {
+        let site_root = readme_path.parent().unwrap();
 
-    let lines = build_sidebar_content(&repo_root.join("docs"), &pages_root, SIDEBAR_HEAD);
+        let content_dir = find_content_dir(site_root);
 
-    let sidebar_path = repo_root.join(SIDEBAR_PATH);
-    std::fs::write(&sidebar_path, lines).unwrap();
-    println_cargo_style!("Generated: {}", sidebar_path.display());
+        if let Some(content_dir) = content_dir {
+            let lines = build_sidebar_content(site_root, &content_dir, SIDEBAR_HEAD);
+
+            let sidebar_path = site_root.join("_sidebar.md");
+            std::fs::write(&sidebar_path, lines).unwrap();
+            println_cargo_style!("Generated: {}", sidebar_path.display());
+        }
+    }
 }
 
-/// Generate _sidebar.md inside translation directories
-fn gen_translation_sidebars() {
-    let repo_root = find_git_repo().unwrap();
-    let docs_root = repo_root.join("docs");
+/// Recursively find all README.md files under a directory.
+fn find_all_readmes(dir: &Path) -> Vec<PathBuf> {
+    let mut results = Vec::new();
+    if let Ok(read_dir) = std::fs::read_dir(dir) {
+        let mut entries: Vec<_> = read_dir.flatten().collect();
+        entries.sort_by_key(|e| e.path());
+        for entry in entries {
+            let path = entry.path();
+            if path.is_dir() {
+                results.extend(find_all_readmes(&path));
+            } else if path.file_name().map_or(false, |n| n == "README.md") {
+                results.push(path);
+            }
+        }
+    }
+    results
+}
 
-    if let Ok(read_dir) = std::fs::read_dir(&docs_root) {
-        for entry in read_dir.flatten() {
+/// Find the content directory for a site:
+/// 1. Prefer `pages/` if it exists (backward compatible)
+/// 2. Fall back to the first subdirectory that contains .md files
+fn find_content_dir(site_root: &Path) -> Option<PathBuf> {
+    // Try pages/ first
+    let pages_dir = site_root.join("pages");
+    if pages_dir.exists() && pages_dir.is_dir() {
+        return Some(pages_dir);
+    }
+
+    // Fall back to any subdirectory containing .md files
+    if let Ok(read_dir) = std::fs::read_dir(site_root) {
+        let mut entries: Vec<_> = read_dir.flatten().collect();
+        entries.sort_by_key(|e| e.path());
+        for entry in entries {
             let path = entry.path();
-            let file_name = entry.file_name().to_string_lossy().to_string();
-
-            // Only process entries starting with '_' that are directories
-            if file_name.starts_with('_') && path.is_dir() {
-                // Check if this directory has a 'pages' subdirectory
-                let pages_dir = path.join("pages");
-                if !pages_dir.exists() || !pages_dir.is_dir() {
-                    continue;
+            if path.is_dir() {
+                if has_markdown_files(&path) {
+                    return Some(path);
                 }
+            }
+        }
+    }
 
-                // The _sidebar.md for a translation directory is relative to that directory,
-                // so strip_prefix should use the translation directory path, removing the _zh_CN/ prefix
-                let lines = build_sidebar_content(&path, &pages_dir, "- [Welcome!](README)\n");
+    None
+}
 
-                let sidebar_path = path.join("_sidebar.md");
-                std::fs::write(&sidebar_path, lines).unwrap();
-                println_cargo_style!("Generated: {}", sidebar_path.display());
+/// Check if a directory (recursively) contains any .md files.
+fn has_markdown_files(dir: &Path) -> bool {
+    if let Ok(read_dir) = std::fs::read_dir(dir) {
+        for entry in read_dir.flatten() {
+            let path = entry.path();
+            if path.is_dir() {
+                if has_markdown_files(&path) {
+                    return true;
+                }
+            } else if path.extension().is_some_and(|ext| ext == "md") {
+                return true;
             }
         }
     }
+    false
 }
 
 /// Build sidebar content: scan .md files in `pages_dir` and return a formatted sidebar string
diff --git a/docs/css/dev-dark.css b/docs/css/dev-dark.css
new file mode 100644
index 0000000..b3d065a
--- /dev/null
+++ b/docs/css/dev-dark.css
@@ -0,0 +1,744 @@
+/*
+ * Mingling Dev Docs — Dark theme (Minimal / technical)
+ * Dark gray-blue, sans-serif body, crisp monospace code
+ */
+
+* {
+    -webkit-font-smoothing: antialiased;
+    -webkit-overflow-scrolling: touch;
+    -webkit-tap-highlight-color: rgba(0, 0, 0, 0);
+    -webkit-text-size-adjust: none;
+    -webkit-touch-callout: none;
+    box-sizing: border-box;
+}
+body:not(.ready) {
+    overflow: hidden;
+}
+body:not(.ready) [data-cloak],
+body:not(.ready) .app-nav,
+body:not(.ready) > nav {
+    display: none;
+}
+div#app {
+    font-size: 30px;
+    font-weight: lighter;
+    margin: 40vh auto;
+    text-align: center;
+}
+div#app:empty::before {
+    content: "Loading...";
+}
+img.emoji {
+    height: 1.2em;
+    vertical-align: middle;
+}
+span.emoji {
+    font-family:
+        "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol",
+        "Noto Color Emoji";
+    font-size: 1.2em;
+    vertical-align: middle;
+}
+
+/* ── Progress bar ── */
+.progress {
+    background-color: #58a6ff;
+    height: 2px;
+    left: 0;
+    position: fixed;
+    right: 0;
+    top: 0;
+    transition:
+        width 0.2s,
+        opacity 0.4s;
+    width: 0%;
+    z-index: 999999;
+}
+
+/* ── Search ── */
+.search a:hover {
+    color: #58a6ff;
+}
+.search .search-keyword {
+    color: #58a6ff;
+    font-style: normal;
+    font-weight: 600;
+}
+
+/* ── Base ── */
+html,
+body {
+    height: 100%;
+}
+body {
+    -moz-osx-font-smoothing: grayscale;
+    -webkit-font-smoothing: antialiased;
+    background-color: #0d1117;
+    color: #e6edf3;
+    font-family:
+        system-ui,
+        -apple-system,
+        "Segoe UI",
+        "Noto Sans",
+        Helvetica,
+        Arial,
+        sans-serif;
+    font-size: 15px;
+    line-height: 1.7;
+    letter-spacing: 0;
+    margin: 0;
+    overflow-x: hidden;
+}
+img {
+    max-width: 100%;
+}
+a[disabled] {
+    cursor: not-allowed;
+    opacity: 0.6;
+}
+kbd {
+    border: solid 1px #30363d;
+    border-radius: 4px;
+    display: inline-block;
+    font-size: 12px !important;
+    line-height: 14px;
+    margin-bottom: 3px;
+    padding: 3px 6px;
+    vertical-align: middle;
+}
+
+/* ── Nav bar (top) ── */
+.app-nav {
+    font-family:
+        system-ui,
+        -apple-system,
+        "Segoe UI",
+        "Noto Sans",
+        Helvetica,
+        Arial,
+        sans-serif;
+    margin: 0 0 0 auto;
+    position: fixed;
+    right: 30px;
+    top: 10px;
+    z-index: 10;
+}
+.app-nav a {
+    color: #8b949e;
+    font-size: 14px;
+    padding: 6px 14px;
+    text-decoration: none;
+    transition: color 0.15s;
+}
+.app-nav a:hover {
+    color: #58a6ff;
+}
+.app-nav a.active {
+    color: #58a6ff;
+}
+
+/* ── Top nav bar (shared class with dev-doc.html) ── */
+.dev-nav a {
+    color: #8b949e;
+}
+.dev-nav a:hover {
+    color: #58a6ff;
+}
+
+/* ── GitHub corner ── */
+.github-corner {
+    position: fixed;
+    right: 0;
+    top: 0;
+    z-index: 999;
+}
+.github-corner svg {
+    fill: #e6edf3;
+    height: 60px;
+    width: 60px;
+}
+
+/* ── Main layout ── */
+main {
+    display: block;
+    height: 100%;
+    margin-left: 300px;
+    overflow-y: auto;
+    position: relative;
+    -webkit-overflow-scrolling: touch;
+}
+
+/* ── Anchor links ── */
+.anchor {
+    display: block;
+    cursor: pointer;
+    text-decoration: none;
+    transition: all 0.15s;
+}
+.anchor span {
+    color: #e6edf3;
+}
+.anchor:hover {
+    text-decoration: underline;
+}
+
+/* ── Sidebar ── */
+.sidebar {
+    background: #161b22;
+    border-right: 1px solid #30363d;
+    bottom: 0;
+    left: 0;
+    overflow-y: auto;
+    position: fixed;
+    top: 0;
+    width: 300px;
+    z-index: 1;
+    -webkit-overflow-scrolling: touch;
+}
+.sidebar > h1 {
+    border-bottom: 1px solid #30363d;
+    font-size: 18px;
+    font-weight: 600;
+    margin: 0;
+    padding: 16px 20px;
+    line-height: 1.4;
+}
+.sidebar > h1 a {
+    color: #e6edf3;
+    text-decoration: none;
+}
+.sidebar > h1 a:hover {
+    color: #58a6ff;
+}
+.sidebar .sidebar-nav {
+    padding: 12px 0 40px;
+}
+.sidebar li.collapse .app-sub-sidebar {
+    display: none;
+}
+.sidebar ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+.sidebar li > p {
+    font-weight: 600;
+    margin: 0;
+}
+.sidebar ul,
+.sidebar ul li {
+    list-style: none;
+}
+.sidebar ul li a {
+    border-right: 2px solid transparent;
+    color: #e6edf3;
+    display: block;
+    font-size: 14px;
+    line-height: 1.6;
+    padding: 6px 20px;
+    text-decoration: none;
+    transition: all 0.1s;
+}
+.sidebar ul li a:hover {
+    color: #58a6ff;
+    background: rgba(88, 166, 255, 0.08);
+}
+.sidebar ul li ul {
+    padding-left: 16px;
+}
+.sidebar ul li.active > a {
+    border-right-color: #58a6ff;
+    color: #58a6ff;
+    font-weight: 600;
+    background: rgba(88, 166, 255, 0.12);
+}
+.sidebar::-webkit-scrollbar {
+    width: 4px;
+}
+.sidebar::-webkit-scrollbar-thumb {
+    background: transparent;
+    border-radius: 2px;
+}
+.sidebar:hover::-webkit-scrollbar-thumb {
+    background: #30363d;
+}
+.sidebar:hover::-webkit-scrollbar-track {
+    background: transparent;
+}
+
+/* ── Sidebar toggle ── */
+.sidebar-toggle {
+    background: transparent;
+    border: none;
+    bottom: 0;
+    cursor: pointer;
+    left: 0;
+    outline: none;
+    padding: 10px;
+    position: absolute;
+    text-align: center;
+    transition: opacity 0.3s;
+    width: 284px;
+    z-index: 10;
+    display: none;
+}
+.sidebar-toggle:hover .sidebar-toggle-button {
+    opacity: 0.6;
+}
+.sidebar-toggle span {
+    background: #58a6ff;
+    border-radius: 1px;
+    display: block;
+    height: 2px;
+    margin-bottom: 4px;
+    width: 16px;
+}
+body.sticky .sidebar,
+body.sticky .sidebar-toggle {
+    position: fixed;
+}
+
+/* ── Content area ── */
+.content {
+    display: block;
+    padding-bottom: 60px;
+    padding-top: 24px;
+}
+.markdown-section {
+    margin: 0 auto;
+    max-width: 880px;
+    padding: 24px 40px 40px;
+    position: relative;
+}
+.markdown-section > * {
+    box-sizing: border-box;
+}
+.markdown-section > :first-child {
+    margin-top: 0 !important;
+}
+.markdown-section hr {
+    border: none;
+    border-top: 1px solid #30363d;
+    margin: 32px 0;
+}
+.markdown-section table {
+    border-collapse: collapse;
+    border-spacing: 0;
+    display: block;
+    margin: 24px 0;
+    overflow: auto;
+    width: 100%;
+}
+.markdown-section th {
+    background: #161b22;
+    border: 1px solid #30363d;
+    font-weight: 600;
+    padding: 8px 12px;
+    text-align: left;
+}
+.markdown-section td {
+    border: 1px solid #30363d;
+    padding: 8px 12px;
+}
+.markdown-section tr:nth-child(2n) {
+    background: #161b22;
+}
+
+/* ── Headings ── */
+.markdown-section h1,
+.markdown-section h2,
+.markdown-section h3,
+.markdown-section h4,
+.markdown-section strong {
+    color: #f0f6fc;
+    font-weight: 600;
+}
+.markdown-section h1 {
+    border-bottom: 1px solid #30363d;
+    font-size: 28px;
+    margin: 0 0 20px;
+    padding-bottom: 8px;
+}
+.markdown-section h2 {
+    border-bottom: 1px solid #30363d;
+    font-size: 22px;
+    margin: 28px 0 16px;
+    padding-bottom: 6px;
+}
+.markdown-section h3 {
+    font-size: 18px;
+    margin: 24px 0 12px;
+}
+.markdown-section h4 {
+    font-size: 16px;
+    margin: 20px 0 10px;
+}
+.markdown-section h5 {
+    font-size: 15px;
+    margin: 16px 0 8px;
+}
+.markdown-section h6 {
+    color: #8b949e;
+    font-size: 14px;
+    margin: 14px 0 8px;
+}
+.markdown-section a {
+    color: #58a6ff;
+    text-decoration: none;
+}
+.markdown-section a:hover {
+    text-decoration: underline;
+}
+
+/* ── Inline code ── */
+.markdown-section code {
+    background: rgba(240, 246, 252, 0.08);
+    border-radius: 4px;
+    font-family:
+        "JetBrains Mono", "Fira Code", "Cascadia Code", "SF Mono", "Fira Mono",
+        "Source Code Pro", Menlo, Consolas, "DejaVu Sans Mono", monospace;
+    font-size: 13px;
+    margin: 0;
+    padding: 2px 6px;
+    word-break: break-word;
+}
+
+/* ── Code blocks ── */
+.markdown-section pre {
+    background: #161b22;
+    border: 1px solid #30363d;
+    border-radius: 6px;
+    font-family:
+        "JetBrains Mono", "Fira Code", "Cascadia Code", "SF Mono", "Fira Mono",
+        "Source Code Pro", Menlo, Consolas, "DejaVu Sans Mono", monospace;
+    font-size: 13px;
+    line-height: 1.6;
+    margin: 16px 0;
+    overflow: auto;
+    padding: 16px;
+    position: relative;
+    word-wrap: normal;
+}
+.markdown-section pre > code {
+    background: transparent;
+    border: none;
+    border-radius: 0;
+    font-size: 13px;
+    margin: 0;
+    padding: 0;
+    white-space: pre;
+    word-break: normal;
+}
+
+/* ── Blockquote ── */
+.markdown-section blockquote {
+    border-left: 4px solid #30363d;
+    color: #8b949e;
+    margin: 16px 0;
+    padding: 0 16px;
+}
+
+/* ── Tip / warn callouts ── */
+.markdown-section p.tip {
+    background: rgba(88, 166, 255, 0.1);
+    border-left: 4px solid #58a6ff;
+    border-radius: 4px;
+    padding: 12px 16px;
+}
+.markdown-section p.tip:before {
+    color: #58a6ff;
+    content: "💡";
+    font-weight: 600;
+    margin-right: 6px;
+}
+.markdown-section p.tip code {
+    background: rgba(88, 166, 255, 0.15);
+}
+.markdown-section p.warn {
+    background: rgba(210, 153, 34, 0.15);
+    border-left: 4px solid #d29922;
+    border-radius: 4px;
+    padding: 12px 16px;
+}
+.markdown-section ul.task-list > li {
+    list-style: none;
+}
+
+/* ── Prism token overrides (dark) ── */
+.token.cdata,
+.token.comment,
+.token.doctype,
+.token.prolog {
+    color: #8b949e;
+}
+.token.namespace {
+    opacity: 0.7;
+}
+.token.boolean,
+.token.number {
+    color: #79c0ff;
+}
+.token.punctuation {
+    color: #e6edf3;
+}
+.token.property {
+    color: #79c0ff;
+}
+.token.tag {
+    color: #7ee787;
+}
+.token.string {
+    color: #a5d6ff;
+}
+.token.selector {
+    color: #d2a8ff;
+}
+.token.attr-name {
+    color: #79c0ff;
+}
+.language-css .token.string,
+.style .token.string,
+.token.entity,
+.token.url {
+    color: #a5d6ff;
+}
+.token.attr-value,
+.token.control,
+.token.directive,
+.token.unit {
+    color: #a5d6ff;
+}
+.token.function {
+    color: #d2a8ff;
+}
+.token.keyword {
+    color: #ff7b72;
+}
+.token.atrule,
+.token.regex,
+.token.statement {
+    color: #a5d6ff;
+}
+.token.placeholder,
+.token.variable {
+    color: #ffa657;
+}
+.token.deleted {
+    text-decoration: line-through;
+}
+.token.inserted {
+    text-decoration: none;
+}
+.token.italic {
+    font-style: italic;
+}
+.token.bold,
+.token.important {
+    font-weight: 700;
+}
+.token.important {
+    color: #ff7b72;
+}
+.token.entity {
+    cursor: help;
+}
+code .token {
+    -moz-osx-font-smoothing: initial;
+    -webkit-font-smoothing: initial;
+    min-height: 24px;
+}
+
+/* ── Search panel ── */
+.search {
+    border-bottom: 1px solid #30363d;
+    padding: 12px 16px 0;
+}
+.search .input-wrap {
+    position: relative;
+}
+.search .input-wrap input[type="search"] {
+    background: #0d1117;
+    border: 1px solid #30363d;
+    border-radius: 6px;
+    color: #e6edf3;
+    font-family:
+        system-ui,
+        -apple-system,
+        "Segoe UI",
+        "Noto Sans",
+        Helvetica,
+        Arial,
+        sans-serif;
+    font-size: 14px;
+    outline: none;
+    padding: 6px 32px 6px 12px;
+    width: 100%;
+}
+.search .input-wrap input[type="search"]::placeholder {
+    color: #8b949e;
+}
+.search .input-wrap input[type="search"]:focus {
+    border-color: #58a6ff;
+    box-shadow: 0 0 0 3px rgba(88, 166, 255, 0.15);
+}
+.search .input-wrap .clear-button {
+    background: transparent;
+    border: none;
+    color: #8b949e;
+    cursor: pointer;
+    font-size: 18px;
+    line-height: 1;
+    padding: 0 8px;
+    position: absolute;
+    right: 4px;
+    top: 50%;
+    transform: translateY(-50%);
+}
+.search .input-wrap .clear-button:hover {
+    color: #e6edf3;
+}
+.search .results-panel {
+    padding: 8px 0;
+}
+.search .results-panel a {
+    color: #e6edf3;
+    display: block;
+    font-size: 14px;
+    padding: 4px 16px;
+    text-decoration: none;
+}
+.search .results-panel a:hover {
+    color: #58a6ff;
+}
+
+/* ── App name in sidebar header ── */
+.app-name-link {
+    color: #e6edf3;
+    font-size: 18px;
+    font-weight: 600;
+    text-decoration: none;
+}
+
+/* ── Iframe ── */
+.markdown-section iframe {
+    border: 1px solid #30363d;
+    border-radius: 6px;
+}
+
+/* ── Prev/Next nav ── */
+.page-nav {
+    border-top: 1px solid #30363d;
+    display: flex;
+    margin-top: 40px;
+    padding-top: 24px;
+}
+.page-nav a {
+    border: 1px solid #30363d;
+    border-radius: 6px;
+    color: #e6edf3;
+    display: inline-flex;
+    flex: 1 1 50%;
+    font-size: 14px;
+    gap: 8px;
+    max-width: 50%;
+    padding: 12px 20px;
+    text-decoration: none;
+    transition: border-color 0.15s;
+}
+.page-nav a:hover {
+    border-color: #58a6ff;
+}
+.page-nav .nav-prev {
+    justify-content: flex-start;
+    margin-right: 8px;
+}
+.page-nav .nav-next {
+    justify-content: flex-end;
+    margin-left: auto;
+}
+.page-nav a:only-child {
+    max-width: 50%;
+}
+.page-nav .nav-label {
+    font-size: 12px;
+    opacity: 0.6;
+}
+.page-nav .nav-title {
+    font-weight: 600;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+/* ── Responsive ── */
+@media screen and (max-width: 768px) {
+    .github-corner,
+    .sidebar-toggle,
+    .sidebar {
+        position: fixed;
+    }
+    .app-nav {
+        margin-top: 0;
+    }
+    .app-nav li ul {
+        background: #0d1117;
+        border: 1px solid #30363d;
+    }
+    main {
+        margin-left: 0;
+        overflow-y: auto;
+    }
+    .sidebar {
+        border-right: 1px solid #30363d;
+        left: -300px;
+        transition: left 0.25s ease;
+    }
+    .content {
+        padding-top: 20px;
+    }
+    .app-nav,
+    .github-corner {
+        opacity: 1;
+        transition: opacity 0.25s ease;
+    }
+    .sidebar-toggle {
+        background: #0d1117;
+        border: 1px solid #30363d;
+        border-radius: 0 4px 4px 0;
+        display: flex;
+        flex-direction: column;
+        left: 0;
+        padding: 8px;
+        position: fixed;
+        top: 10px;
+        width: auto;
+        z-index: 20;
+    }
+    body.close .sidebar {
+        left: 0;
+    }
+    body.close .sidebar-toggle {
+        left: 300px;
+    }
+    body.close .content {
+        opacity: 0.3;
+        pointer-events: none;
+    }
+    body.close .app-nav,
+    body.close .github-corner {
+        opacity: 0;
+        pointer-events: none;
+    }
+}
+
+@media print {
+    .github-corner,
+    .sidebar-toggle,
+    .sidebar,
+    .app-nav {
+        display: none;
+    }
+    main {
+        margin-left: 0;
+    }
+}
diff --git a/docs/css/dev-light.css b/docs/css/dev-light.css
new file mode 100644
index 0000000..4de3083
--- /dev/null
+++ b/docs/css/dev-light.css
@@ -0,0 +1,716 @@
+/*
+ * Mingling Dev Docs — Light theme (Minimal / technical)
+ * Clean white, sans-serif body, crisp monospace code
+ */
+
+* {
+    -webkit-font-smoothing: antialiased;
+    -webkit-overflow-scrolling: touch;
+    -webkit-tap-highlight-color: rgba(0, 0, 0, 0);
+    -webkit-text-size-adjust: none;
+    -webkit-touch-callout: none;
+    box-sizing: border-box;
+}
+body:not(.ready) {
+    overflow: hidden;
+}
+body:not(.ready) [data-cloak],
+body:not(.ready) .app-nav,
+body:not(.ready) > nav {
+    display: none;
+}
+div#app {
+    font-size: 30px;
+    font-weight: lighter;
+    margin: 40vh auto;
+    text-align: center;
+}
+div#app:empty::before {
+    content: "Loading...";
+}
+img.emoji {
+    height: 1.2em;
+    vertical-align: middle;
+}
+span.emoji {
+    font-family: "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol",
+        "Noto Color Emoji";
+    font-size: 1.2em;
+    vertical-align: middle;
+}
+
+/* ── Progress bar ── */
+.progress {
+    background-color: #0969da;
+    height: 2px;
+    left: 0;
+    position: fixed;
+    right: 0;
+    top: 0;
+    transition: width 0.2s, opacity 0.4s;
+    width: 0%;
+    z-index: 999999;
+}
+
+/* ── Search ── */
+.search a:hover {
+    color: #0969da;
+}
+.search .search-keyword {
+    color: #0969da;
+    font-style: normal;
+    font-weight: 600;
+}
+
+/* ── Base ── */
+html,
+body {
+    height: 100%;
+}
+body {
+    -moz-osx-font-smoothing: grayscale;
+    -webkit-font-smoothing: antialiased;
+    background-color: #ffffff;
+    color: #24292f;
+    font-family: system-ui, -apple-system, "Segoe UI", "Noto Sans",
+        Helvetica, Arial, sans-serif;
+    font-size: 15px;
+    line-height: 1.7;
+    letter-spacing: 0;
+    margin: 0;
+    overflow-x: hidden;
+}
+img {
+    max-width: 100%;
+}
+a[disabled] {
+    cursor: not-allowed;
+    opacity: 0.6;
+}
+kbd {
+    border: solid 1px #d0d7de;
+    border-radius: 4px;
+    display: inline-block;
+    font-size: 12px !important;
+    line-height: 14px;
+    margin-bottom: 3px;
+    padding: 3px 6px;
+    vertical-align: middle;
+}
+
+/* ── Nav bar (top) ── */
+.app-nav {
+    font-family: system-ui, -apple-system, "Segoe UI", "Noto Sans",
+        Helvetica, Arial, sans-serif;
+    margin: 0 0 0 auto;
+    position: fixed;
+    right: 30px;
+    top: 10px;
+    z-index: 10;
+}
+.app-nav a {
+    color: #656d76;
+    font-size: 14px;
+    padding: 6px 14px;
+    text-decoration: none;
+    transition: color 0.15s;
+}
+.app-nav a:hover {
+    color: #0969da;
+}
+.app-nav a.active {
+    color: #0969da;
+}
+
+/* ── GitHub corner ── */
+.github-corner {
+    position: fixed;
+    right: 0;
+    top: 0;
+    z-index: 999;
+}
+.github-corner svg {
+    fill: #24292f;
+    height: 60px;
+    width: 60px;
+}
+
+/* ── Main layout ── */
+main {
+    display: block;
+    height: 100%;
+    margin-left: 300px;
+    overflow-y: auto;
+    position: relative;
+    -webkit-overflow-scrolling: touch;
+}
+
+/* ── Anchor links ── */
+.anchor {
+    display: block;
+    cursor: pointer;
+    text-decoration: none;
+    transition: all 0.15s;
+}
+.anchor span {
+    color: #24292f;
+}
+.anchor:hover {
+    text-decoration: underline;
+}
+
+/* ── Sidebar ── */
+.sidebar {
+    background: #f6f8fa;
+    border-right: 1px solid #d0d7de;
+    bottom: 0;
+    left: 0;
+    overflow-y: auto;
+    position: fixed;
+    top: 0;
+    width: 300px;
+    z-index: 1;
+    -webkit-overflow-scrolling: touch;
+}
+.sidebar > h1 {
+    border-bottom: 1px solid #d0d7de;
+    font-size: 18px;
+    font-weight: 600;
+    margin: 0;
+    padding: 16px 20px;
+    line-height: 1.4;
+}
+.sidebar > h1 a {
+    color: #24292f;
+    text-decoration: none;
+}
+.sidebar > h1 a:hover {
+    color: #0969da;
+}
+
+.sidebar .sidebar-nav {
+    padding: 12px 0 40px;
+}
+.sidebar li.collapse .app-sub-sidebar {
+    display: none;
+}
+.sidebar ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+.sidebar li > p {
+    font-weight: 600;
+    margin: 0;
+}
+.sidebar ul,
+.sidebar ul li {
+    list-style: none;
+}
+.sidebar ul li a {
+    border-right: 2px solid transparent;
+    color: #24292f;
+    display: block;
+    font-size: 14px;
+    line-height: 1.6;
+    padding: 6px 20px;
+    text-decoration: none;
+    transition: all 0.1s;
+}
+.sidebar ul li a:hover {
+    color: #0969da;
+    background: rgba(9, 105, 218, 0.06);
+}
+.sidebar ul li ul {
+    padding-left: 16px;
+}
+.sidebar ul li.active > a {
+    border-right-color: #0969da;
+    color: #0969da;
+    font-weight: 600;
+    background: rgba(9, 105, 218, 0.08);
+}
+.sidebar::-webkit-scrollbar {
+    width: 4px;
+}
+.sidebar::-webkit-scrollbar-thumb {
+    background: transparent;
+    border-radius: 2px;
+}
+.sidebar:hover::-webkit-scrollbar-thumb {
+    background: #d0d7de;
+}
+.sidebar:hover::-webkit-scrollbar-track {
+    background: transparent;
+}
+
+/* ── Sidebar toggle ── */
+.sidebar-toggle {
+    background: transparent;
+    border: none;
+    bottom: 0;
+    cursor: pointer;
+    left: 0;
+    outline: none;
+    padding: 10px;
+    position: absolute;
+    text-align: center;
+    transition: opacity 0.3s;
+    width: 284px;
+    z-index: 10;
+    display: none;
+}
+.sidebar-toggle:hover .sidebar-toggle-button {
+    opacity: 0.6;
+}
+.sidebar-toggle span {
+    background: #0969da;
+    border-radius: 1px;
+    display: block;
+    height: 2px;
+    margin-bottom: 4px;
+    width: 16px;
+}
+body.sticky .sidebar,
+body.sticky .sidebar-toggle {
+    position: fixed;
+}
+
+/* ── Content area ── */
+.content {
+    display: block;
+    padding-bottom: 60px;
+    padding-top: 24px;
+}
+.markdown-section {
+    margin: 0 auto;
+    max-width: 880px;
+    padding: 24px 40px 40px;
+    position: relative;
+}
+.markdown-section > * {
+    box-sizing: border-box;
+}
+.markdown-section > :first-child {
+    margin-top: 0 !important;
+}
+.markdown-section hr {
+    border: none;
+    border-top: 1px solid #d0d7de;
+    margin: 32px 0;
+}
+.markdown-section table {
+    border-collapse: collapse;
+    border-spacing: 0;
+    display: block;
+    margin: 24px 0;
+    overflow: auto;
+    width: 100%;
+}
+.markdown-section th {
+    background: #f6f8fa;
+    border: 1px solid #d0d7de;
+    font-weight: 600;
+    padding: 8px 12px;
+    text-align: left;
+}
+.markdown-section td {
+    border: 1px solid #d0d7de;
+    padding: 8px 12px;
+}
+.markdown-section tr:nth-child(2n) {
+    background: #f6f8fa;
+}
+
+/* ── Headings ── */
+.markdown-section h1,
+.markdown-section h2,
+.markdown-section h3,
+.markdown-section h4,
+.markdown-section strong {
+    color: #1f2328;
+    font-weight: 600;
+}
+.markdown-section h1 {
+    border-bottom: 1px solid #d0d7de;
+    font-size: 28px;
+    margin: 0 0 20px;
+    padding-bottom: 8px;
+}
+.markdown-section h2 {
+    border-bottom: 1px solid #d0d7de;
+    font-size: 22px;
+    margin: 28px 0 16px;
+    padding-bottom: 6px;
+}
+.markdown-section h3 {
+    font-size: 18px;
+    margin: 24px 0 12px;
+}
+.markdown-section h4 {
+    font-size: 16px;
+    margin: 20px 0 10px;
+}
+.markdown-section h5 {
+    font-size: 15px;
+    margin: 16px 0 8px;
+}
+.markdown-section h6 {
+    color: #656d76;
+    font-size: 14px;
+    margin: 14px 0 8px;
+}
+.markdown-section a {
+    color: #0969da;
+    text-decoration: none;
+}
+.markdown-section a:hover {
+    text-decoration: underline;
+}
+
+/* ── Inline code ── */
+.markdown-section code {
+    background: rgba(27, 31, 36, 0.06);
+    border-radius: 4px;
+    font-family: "JetBrains Mono", "Fira Code", "Cascadia Code",
+        "SF Mono", "Fira Mono", "Source Code Pro", Menlo, Consolas,
+        "DejaVu Sans Mono", monospace;
+    font-size: 13px;
+    margin: 0;
+    padding: 2px 6px;
+    word-break: break-word;
+}
+
+/* ── Code blocks ── */
+.markdown-section pre {
+    background: #f6f8fa;
+    border: 1px solid #d0d7de;
+    border-radius: 6px;
+    font-family: "JetBrains Mono", "Fira Code", "Cascadia Code",
+        "SF Mono", "Fira Mono", "Source Code Pro", Menlo, Consolas,
+        "DejaVu Sans Mono", monospace;
+    font-size: 13px;
+    line-height: 1.6;
+    margin: 16px 0;
+    overflow: auto;
+    padding: 16px;
+    position: relative;
+    word-wrap: normal;
+}
+.markdown-section pre > code {
+    background: transparent;
+    border: none;
+    border-radius: 0;
+    font-size: 13px;
+    margin: 0;
+    padding: 0;
+    white-space: pre;
+    word-break: normal;
+}
+
+/* ── Blockquote ── */
+.markdown-section blockquote {
+    border-left: 4px solid #d0d7de;
+    color: #656d76;
+    margin: 16px 0;
+    padding: 0 16px;
+}
+
+/* ── Tip / warning callouts ── */
+.markdown-section p.tip {
+    background: rgba(9, 105, 218, 0.08);
+    border-left: 4px solid #0969da;
+    border-radius: 4px;
+    padding: 12px 16px;
+}
+.markdown-section p.tip:before {
+    color: #0969da;
+    content: "💡";
+    font-weight: 600;
+    margin-right: 6px;
+}
+.markdown-section p.tip code {
+    background: rgba(9, 105, 218, 0.1);
+}
+.markdown-section p.warn {
+    background: rgba(242, 211, 91, 0.15);
+    border-left: 4px solid #d29922;
+    border-radius: 4px;
+    padding: 12px 16px;
+}
+.markdown-section ul.task-list > li {
+    list-style: none;
+}
+
+/* ── Prism token overrides (light) ── */
+.token.cdata,
+.token.comment,
+.token.doctype,
+.token.prolog {
+    color: #6e7781;
+}
+.token.namespace {
+    opacity: 0.7;
+}
+.token.boolean,
+.token.number {
+    color: #0550ae;
+}
+.token.punctuation {
+    color: #24292f;
+}
+.token.property {
+    color: #0550ae;
+}
+.token.tag {
+    color: #116329;
+}
+.token.string {
+    color: #0a3069;
+}
+.token.selector {
+    color: #6f42c1;
+}
+.token.attr-name {
+    color: #0550ae;
+}
+.language-css .token.string,
+.style .token.string,
+.token.entity,
+.token.url {
+    color: #0a3069;
+}
+.token.attr-value,
+.token.control,
+.token.directive,
+.token.unit {
+    color: #0a3069;
+}
+.token.function {
+    color: #8250df;
+}
+.token.keyword {
+    color: #cf222e;
+}
+.token.atrule,
+.token.regex,
+.token.statement {
+    color: #0a3069;
+}
+.token.placeholder,
+.token.variable {
+    color: #953800;
+}
+.token.deleted {
+    text-decoration: line-through;
+}
+.token.inserted {
+    text-decoration: none;
+}
+.token.italic {
+    font-style: italic;
+}
+.token.bold,
+.token.important {
+    font-weight: 700;
+}
+.token.important {
+    color: #cf222e;
+}
+.token.entity {
+    cursor: help;
+}
+code .token {
+    -moz-osx-font-smoothing: initial;
+    -webkit-font-smoothing: initial;
+    min-height: 24px;
+}
+
+/* ── Search panel ── */
+.search {
+    border-bottom: 1px solid #d0d7de;
+    padding: 12px 16px 0;
+}
+.search .input-wrap {
+    position: relative;
+}
+.search .input-wrap input[type="search"] {
+    background: #ffffff;
+    border: 1px solid #d0d7de;
+    border-radius: 6px;
+    color: #24292f;
+    font-family: system-ui, -apple-system, "Segoe UI", "Noto Sans",
+        Helvetica, Arial, sans-serif;
+    font-size: 14px;
+    outline: none;
+    padding: 6px 32px 6px 12px;
+    width: 100%;
+}
+.search .input-wrap input[type="search"]::placeholder {
+    color: #8b949e;
+}
+.search .input-wrap input[type="search"]:focus {
+    border-color: #0969da;
+    box-shadow: 0 0 0 3px rgba(9, 105, 218, 0.15);
+}
+.search .input-wrap .clear-button {
+    background: transparent;
+    border: none;
+    color: #656d76;
+    cursor: pointer;
+    font-size: 18px;
+    line-height: 1;
+    padding: 0 8px;
+    position: absolute;
+    right: 4px;
+    top: 50%;
+    transform: translateY(-50%);
+}
+.search .input-wrap .clear-button:hover {
+    color: #24292f;
+}
+.search .results-panel {
+    padding: 8px 0;
+}
+.search .results-panel a {
+    color: #24292f;
+    display: block;
+    font-size: 14px;
+    padding: 4px 16px;
+    text-decoration: none;
+}
+.search .results-panel a:hover {
+    color: #0969da;
+}
+
+/* ── App name in sidebar header ── */
+.app-name-link {
+    color: #24292f;
+    font-size: 18px;
+    font-weight: 600;
+    text-decoration: none;
+}
+
+/* ── Iframe ── */
+.markdown-section iframe {
+    border: 1px solid #d0d7de;
+    border-radius: 6px;
+}
+
+/* ── Prev/Next nav ── */
+.page-nav {
+    border-top: 1px solid #d0d7de;
+    display: flex;
+    margin-top: 40px;
+    padding-top: 24px;
+}
+.page-nav a {
+    border: 1px solid #d0d7de;
+    border-radius: 6px;
+    color: #24292f;
+    display: inline-flex;
+    flex: 1 1 50%;
+    font-size: 14px;
+    gap: 8px;
+    max-width: 50%;
+    padding: 12px 20px;
+    text-decoration: none;
+    transition: border-color 0.15s;
+}
+.page-nav a:hover {
+    border-color: #0969da;
+}
+.page-nav .nav-prev {
+    justify-content: flex-start;
+    margin-right: 8px;
+}
+.page-nav .nav-next {
+    justify-content: flex-end;
+    margin-left: auto;
+}
+.page-nav a:only-child {
+    max-width: 50%;
+}
+.page-nav .nav-label {
+    font-size: 12px;
+    opacity: 0.6;
+}
+.page-nav .nav-title {
+    font-weight: 600;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+/* ── Responsive ── */
+@media screen and (max-width: 768px) {
+    .github-corner,
+    .sidebar-toggle,
+    .sidebar {
+        position: fixed;
+    }
+    .app-nav {
+        margin-top: 0;
+    }
+    .app-nav li ul {
+        background: #ffffff;
+        border: 1px solid #d0d7de;
+    }
+    main {
+        margin-left: 0;
+        overflow-y: auto;
+    }
+    .sidebar {
+        border-right: 1px solid #d0d7de;
+        left: -300px;
+        transition: left 0.25s ease;
+    }
+    .content {
+        padding-top: 20px;
+    }
+    .app-nav,
+    .github-corner {
+        opacity: 1;
+        transition: opacity 0.25s ease;
+    }
+    .sidebar-toggle {
+        background: #ffffff;
+        border: 1px solid #d0d7de;
+        border-radius: 0 4px 4px 0;
+        display: flex;
+        flex-direction: column;
+        left: 0;
+        padding: 8px;
+        position: fixed;
+        top: 10px;
+        width: auto;
+        z-index: 20;
+    }
+    body.close .sidebar {
+        left: 0;
+    }
+    body.close .sidebar-toggle {
+        left: 300px;
+    }
+    body.close .content {
+        opacity: 0.3;
+        pointer-events: none;
+    }
+    body.close .app-nav,
+    body.close .github-corner {
+        opacity: 0;
+        pointer-events: none;
+    }
+}
+
+@media print {
+    .github-corner,
+    .sidebar-toggle,
+    .sidebar,
+    .app-nav {
+        display: none;
+    }
+    main {
+        margin-left: 0;
+    }
+}
diff --git a/docs/dev-docs/README.md b/docs/dev-docs/README.md
new file mode 100644
index 0000000..a2eede9
--- /dev/null
+++ b/docs/dev-docs/README.md
@@ -0,0 +1,15 @@
+<h1 align="center">Mingling Dev Docs</h1>
+
+<p align="center">
+    Internal development documentation for the <b>Mingling</b> codebase — design notes, issue discussions, and architectural decisions.
+</p>
+
+This site is separate from the [main helpdoc](https://mingling-rs.github.io/mingling/docs/doc.html). The helpdoc is user-facing: tutorials, feature guides, and how-to content for developers _using_ Mingling to build CLI applications. This dev-docs site is for developers _working on_ Mingling itself — understanding internal mechanisms, tracking unresolved problems, and recording design rationale.
+
+## What's here
+
+- **Issues** — Collected notes on known pain points, unresolved trade-offs, and feature gaps in the current implementation.
+
+## How this is different from GitHub Issues
+
+Mingling is hosted on [GitHub](https://github.com/mingling-rs/mingling), and the [Issues page](https://github.com/mingling-rs/mingling/issues) there is primarily for discussion. In contrast, an issue in this document exists only when it is being planned or actively worked on.
diff --git a/docs/dev-docs/_sidebar.md b/docs/dev-docs/_sidebar.md
new file mode 100644
index 0000000..76c3649
--- /dev/null
+++ b/docs/dev-docs/_sidebar.md
@@ -0,0 +1,3 @@
+- [Welcome!](README)
+* [The Mod Pathfinder](issues/the-mod-pathfinder)
+* [Some Situations Where You'd Be Like "Shit!"](issues/the-shit-time)
diff --git a/docs/dev-docs/index.html b/docs/dev-docs/index.html
new file mode 100644
index 0000000..c3fd04a
--- /dev/null
+++ b/docs/dev-docs/index.html
@@ -0,0 +1,161 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+        <meta
+            name="viewport"
+            content="width=device-width, initial-scale=1, minimum-scale=1.0, shrink-to-fit=no, viewport-fit=cover"
+        />
+
+        <title>Mingling Dev Docs</title>
+        <meta
+            name="Mingling Dev Docs"
+            content="Internal design docs, issue discussions, and development notes for Mingling."
+        />
+
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="icon" type="image/png" href="../res/favicon_small.png" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+        <link
+            href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600&display=swap"
+            rel="stylesheet"
+        />
+
+        <link rel="stylesheet" href="../css/dev-light.css" />
+        <link
+            id="dark-style"
+            rel="stylesheet"
+            href="../css/dev-dark.css"
+            disabled
+        />
+
+        <style>
+            /* ── No sidebar header image override ── */
+            .sidebar > h1 .app-name-link {
+                font-family:
+                    "JetBrains Mono", "SF Mono", "Fira Code", "Cascadia Code",
+                    monospace;
+                font-size: 16px;
+                font-weight: 600;
+                letter-spacing: -0.3px;
+            }
+            .sidebar > h1 .app-name-link::before {
+                content: "⚙ ";
+                font-family:
+                    system-ui,
+                    -apple-system,
+                    sans-serif;
+                letter-spacing: 0;
+            }
+            .markdown-section h1,
+            .markdown-section h2,
+            .markdown-section h3,
+            .markdown-section h4 {
+                font-family:
+                    "JetBrains Mono", "SF Mono", "Fira Code", "Cascadia Code",
+                    monospace;
+                font-weight: 600;
+                letter-spacing: -0.5px;
+            }
+            .markdown-section h1 {
+                font-size: 24px;
+            }
+            .markdown-section h2 {
+                font-size: 19px;
+            }
+            .markdown-section h3 {
+                font-size: 16px;
+            }
+            .markdown-section p,
+            .markdown-section li {
+                font-family:
+                    system-ui,
+                    -apple-system,
+                    "Segoe UI",
+                    "Noto Sans",
+                    Helvetica,
+                    Arial,
+                    sans-serif;
+            }
+            .sidebar ul li a {
+                font-family:
+                    "JetBrains Mono", "SF Mono", "Fira Code", "Cascadia Code",
+                    monospace;
+                font-size: 13px;
+                letter-spacing: -0.2px;
+            }
+            .sidebar ul li ul li a {
+                font-size: 12px;
+            }
+            /* ── Top nav bar ── */
+            .dev-nav {
+                position: fixed;
+                top: 12px;
+                right: 30px;
+                z-index: 20;
+                display: flex;
+                gap: 4px;
+                align-items: center;
+            }
+            .dev-nav a {
+                font-family:
+                    "JetBrains Mono", "SF Mono", "Fira Code", "Cascadia Code",
+                    monospace;
+                font-size: 12px;
+                text-transform: uppercase;
+                letter-spacing: 0.5px;
+                color: #656d76;
+                text-decoration: none;
+                padding: 4px 10px;
+                transition: color 0.15s;
+            }
+            .dev-nav a:hover {
+                color: #0969da;
+            }
+        </style>
+    </head>
+
+    <body>
+        <nav class="dev-nav">
+            <a
+                href="#"
+                onclick="
+                    toggleTheme();
+                    return false;
+                "
+                >🌓 Theme</a
+            >
+            <a href="../doc.html">📖 Helpdoc</a>
+        </nav>
+
+        <div id="app"></div>
+
+        <script>
+            window.$docsify = {
+                name: "dev-docs",
+                repo: "true",
+                corner: {
+                    url: "https://github.com/mingling-rs/mingling",
+                    icon: "github",
+                },
+                auto2top: true,
+                loadSidebar: true,
+                maxLevel: 0,
+                subMaxLevel: 3,
+                search: {
+                    placeholder: "Search dev docs…",
+                    noData: "No matches found.",
+                    depth: 2,
+                },
+            };
+        </script>
+
+        <script src="../scripts/docsify.min.js"></script>
+        <script src="../scripts/search.js"></script>
+        <script src="../scripts/prism-bash.min.js"></script>
+        <script src="../scripts/prism-toml.min.js"></script>
+        <script src="../scripts/prism-rust.js"></script>
+        <script src="../scripts/docsify-corner.js"></script>
+        <script src="../scripts/day-night-switch.js"></script>
+    </body>
+</html>
diff --git a/docs/dev-docs/issues/.name b/docs/dev-docs/issues/.name
new file mode 100644
index 0000000..f99478d
--- /dev/null
+++ b/docs/dev-docs/issues/.name
@@ -0,0 +1 @@
+Issues
diff --git a/docs/dev-docs/issues/the-mod-pathfinder.md b/docs/dev-docs/issues/the-mod-pathfinder.md
index 5a0a4da..5f8c902 100644
--- a/docs/dev-docs/issues/the-mod-pathfinder.md
+++ b/docs/dev-docs/issues/the-mod-pathfinder.md
@@ -1,4 +1,7 @@
-# The Mod Pathfinder
+<h1 align="center">The Mod Pathfinder</h1>
+<p align="center">
+    A build-time analyzer that computes full module paths for Mingling types, resolving path ambiguity in macros.
+</p>
 
 ## Background
 
diff --git a/docs/dev-docs/issues/the-shit-time.md b/docs/dev-docs/issues/the-shit-time.md
index f830477..77a8af9 100644
--- a/docs/dev-docs/issues/the-shit-time.md
+++ b/docs/dev-docs/issues/the-shit-time.md
@@ -1,4 +1,7 @@
-# Some Situations Where You'd Be Like "Shit!"
+<h1 align="center">Some Situations Where You'd Be Like "Shit!"</h1>
+<p align="center">
+    This document collects the discomforts currently experienced while using Mingling.
+</p>
 
 This document collects the discomforts currently experienced while using Mingling.