docs: revise thesis narrative, diagrams, and build layout

docs/thesis/.gitignore

@@ -4,3 +4,5 @@
 *.typ
 !figures/*.svg
 !title-pages.tex
+!header-includes.tex
+!header-includes.html

docs/thesis/evidence-index.md

@@ -1,14 +1,19 @@
 # Thesis Evidence Index
 
 The claim-to-evidence map now lives inline in
-[`system-design-implementation.md`](system-design-implementation.md), Appendix B:
+[`system-design-implementation.md`](system-design-implementation.md), Appendix A:
 Evidence Index.
 
 This file remains as a stable pointer for older roadmap and project-map links.
 
-For the external-agent challenge evaluation workflow, including trial profiles,
-manual audits, and report interpretation, see
+The earlier CLI campaign is retired from the active thesis. Its preserved
+text and supporting data are indexed in the
+[historical evaluation](../historical/thesis/2026-09-07-retired-agent-evaluation.md).
+No replacement shell-backed agent results are claimed yet.
+
+For the retained challenge harness, including trial profiles, manual audits,
+and report interpretation, see
 [`../runbooks/agent-challenge-evaluation.md`](../runbooks/agent-challenge-evaluation.md).
-The primary checked cohort and generated aggregate are
+The historical cohort and generated aggregate remain at
 [`agent-challenge-cohort.json`](agent-challenge-cohort.json) and
 [`agent-challenge-results.md`](agent-challenge-results.md).

docs/thesis/generate.ps1

@@ -2,8 +2,16 @@
 # use pandoc -M to change the key: diagram:engine:mermaid:outputFormat to svg or pdf if output is html or pdf.
 # use the script at stuff/pandoc-diagram.ps1 to set the env vars and pass the filter to pandoc.
 param(
+    [Parameter(Mandatory = $true, HelpMessage = "The output type to generate. Must be either 'html' or 'pdf'.")]
     [string]$type,
-    [Parameter(ValueFromRemainingArguments = $true)]
+    [Parameter(Mandatory = $true, HelpMessage = "The input Markdown file to process.")]
+    [string]$InputFile = (Join-Path $PSScriptRoot "system-design-implementation.md"),
+    [string]$OutputFile = (Join-Path $PSScriptRoot "system-design-implementation.$type"),
+    [Parameter(ValueFromRemainingArguments = $true, HelpMessage = "Additional arguments to pass to pandoc.
+    
+    Notable use: 
+    - passing --resource-path to specify the directory where images and other resources are located,
+    - passing --pdf-engine=xelatex to specify the PDF engine for PDF output.")]
     [string[]]$RemainingArgs
 )
 function New-PandocDiagramMetadata([string] $outputFormat) {
@@ -100,24 +108,61 @@ if ($type -eq "pdf") {
     $title_pages_args = @("--include-in-header", $title_pages_header)
 }
 
+$tex_preamble_header = Join-Path $PSScriptRoot "header-includes.tex"
+if (-not (Test-Path $tex_preamble_header)) {
+    Write-Error "header-includes.tex is missing. Make sure the thesis preamble header exists."
+    exit 1
+}
+$html_preamble_header = Join-Path $PSScriptRoot "header-includes.html"
+if (-not (Test-Path $html_preamble_header)) {
+    Write-Error "header-includes.html is missing. Make sure the thesis preamble header exists."
+    exit 1
+}
+
+$preamble_args = @()
+if ($type -eq "pdf") {
+    $preamble_args += @("--include-in-header", $tex_preamble_header)
+}
+elseif ($type -eq "html") {
+    $preamble_args += @("--include-in-header", $html_preamble_header)
+}
+
+$info_md = Join-Path $PSScriptRoot "info.md"
+if (-not (Test-Path $info_md)) {
+    Write-Error "info.md is missing. Make sure the thesis info.md file exists."
+    exit 1
+}
+
+$input_files = @($info_md, $InputFile)
 
 $metatempfile = New-TemporaryFile
 $pandocExitCode = 0
 
+$pandoc_args = $(
+    @(
+        "--lua-filter", $include_markdown_filter,
+        "--lua-filter", $diagram_filter,
+        "--lua-filter", $figure_format_filter,
+        "--filter=pandoc-crossref",
+        "--pdf-engine=xelatex"
+    ) + 
+    $title_pages_args + 
+    $preamble_args + 
+    @(
+        "--metadata", "thesisFigureFormat=$outputFormat",
+        "--metadata", "thesisAgentResults=$agent_results",
+        "--metadata-file", $metatempfile,
+        "--embed-resources", "--standalone", "--citeproc"
+    ) +
+    $input_files + 
+    @("--output", $OutputFile) + 
+    $RemainingArgs
+).Where({ [string]::IsNullOrWhiteSpace($_) -eq $false })
+
 try {
     Set-Content -Path $metatempfile -Value $metadata
-    pandoc `
-        --lua-filter $include_markdown_filter `
-        --lua-filter $diagram_filter `
-        --lua-filter $figure_format_filter `
-        --filter=pandoc-crossref `
-        --pdf-engine=xelatex `
-        @title_pages_args `
-        --metadata thesisFigureFormat=$outputFormat `
-        --metadata thesisAgentResults=$agent_results `
-        --metadata-file=$metatempfile `
-        --embed-resources --standalone --citeproc `
-        @RemainingArgs
+    Write-Host "Running pandoc for file $($InputFile | Split-Path -Leaf) to generate $($OutputFile | Split-Path -Leaf)..."
+    pandoc @pandoc_args
     $pandocExitCode = $LASTEXITCODE
 }
 finally {

docs/thesis/gengen.ps1

@@ -1,6 +1,6 @@
 # Generate both HTML and PDF outputs for one Markdown file.
 param(
-    [string]$file = $(throw "File is required."),
+    [string]$file = (Join-Path $PSScriptRoot "system-design-implementation.md"),
     [Parameter(ValueFromRemainingArguments = $true)]
     [string[]]$RemainingArgs = @()
 )
@@ -37,6 +37,6 @@ function Get-OutputFilenames([string] $file, [string] $type) {
 Write-Host "Generating HTML and PDF for $file..."
 Write-Debug "Remaining args: $($RemainingArgs | Format-List)"
 
-& $PSScriptRoot\generate.ps1 -type html -- -i $file -o (Get-OutputFilenames $file "html") --resource-path $resourcePath @RemainingArgs
+& $PSScriptRoot\generate.ps1 -type html -i $file -o (Get-OutputFilenames $file "html") -- --resource-path $resourcePath @RemainingArgs
 
-& $PSScriptRoot\generate.ps1 -type pdf -- -i $file -o (Get-OutputFilenames $file "pdf") --resource-path $resourcePath @RemainingArgs
+& $PSScriptRoot\generate.ps1 -type pdf -i $file -o (Get-OutputFilenames $file "pdf") -- --resource-path $resourcePath @RemainingArgs

docs/thesis/header-includes.html

@@ -0,0 +1,6 @@
+<style>
+    code {
+        white-space: pre-wrap;
+        word-break: break-word;
+    }
+</style>

docs/thesis/header-includes.tex

@@ -0,0 +1,29 @@
+\usepackage{graphicx}
+% \usepackage{booktabs} % exists in the template
+\usepackage{tabulary}
+\usepackage{hyperref}
+\usepackage{hyperxmp}
+\usepackage[dvipsnames]{xcolor}
+\usepackage{fancyhdr}
+\usepackage{float}
+\pagestyle{fancy}
+\usepackage{seqsplit}
+
+% Pandoc emits inline code as \texttt{...}. This blunt wrapper keeps long
+% paths and commands from overflowing PDF table cells.
+\let\origtexttt\texttt
+\renewcommand{\texttt}[1]{{\origtexttt{\seqsplit{#1}}}}
+
+\usepackage{fvextra}
+\fvset{breaklines=true, breaknonspaceingroup=true, breakanywhere=true}
+\fancyhead[L]{\small lda.chat}
+\fancyhead[R]{\small\leftmark}
+\fancyfoot[C]{\thepage}
+\setlength{\parskip}{0.6em}
+\setlength{\parindent}{0pt}
+\setkeys{Gin}{width=\linewidth,height=0.55\textheight,keepaspectratio}
+\renewcommand{\arraystretch}{1.3}
+
+% \hypersetup{pdfauthor={lda.chat}, pdftitle={Design and Implementation of lda.chat}}
+\usepackage{newfloat}
+\DeclareFloatingEnvironment{none}

docs/thesis/info.md

@@ -0,0 +1,15 @@
+---
+# this file supplies info, and it is prepend(!) into the other file.
+author: "Lương Đức Anh"
+student-id: "23BI14021"
+---
+
+# Acknowledgements {.unnumbered}
+
+I would like to express my sincere gratitude to **Eng. Trần Văn Trường** at **Dicom Technology Co. Ltd.** for the trust, autonomy, and practical space to pursue this project and develop its technical direction independently. His thoughtful input, critical perspective, and support throughout the development process helped shape the project into a concrete and technically grounded engineering project.
+
+I am also grateful to **Dr. Nghiêm Thị Phương** at the **University of Science and Technology of Hanoi** for coordinating the university--company requirements of the thesis, providing academic guidance on the submission process, and helping ensure that the final report met the university's formal academic requirements.
+
+I would also like to thank the **University of Science and Technology of Hanoi**, the **Department of Information and Communication Technology**, and **Dicom Technology Co. Ltd.** for providing the academic and professional environment in which this thesis could be carried out.
+
+Finally, I am deeply thankful to my family and friends for their encouragement, patience, and support during the development and writing of this thesis.

docs/thesis/references.bib

@@ -1,3 +1,27 @@
+@online{n8n-merge-2026,
+  title   = {Merge},
+  author  = {{n8n}},
+  year    = {2026},
+  url     = {https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.merge/},
+  urldate = {2026-09-07}
+}
+
+@online{zapier-paths-2026,
+  title   = {Add branching logic to Zap workflows with Paths},
+  author  = {{Zapier}},
+  year    = {2026},
+  url     = {https://help.zapier.com/hc/en-us/articles/8496288555917-Add-branching-logic-to-Zap-workflows-with-Paths},
+  urldate = {2026-09-07}
+}
+
+@online{langgraph-graph-api-2026,
+  title   = {Graph API overview},
+  author  = {{LangChain}},
+  year    = {2026},
+  url     = {https://docs.langchain.com/oss/python/langgraph/graph-api},
+  urldate = {2026-09-07}
+}
+
 @online{mcp-tools-2025,
   title   = {Tools},
   author  = {{Model Context Protocol}},