style: document include and file organization conventions

AGENTS.md

@@ -29,6 +29,11 @@
 - 内部 C API 不加 `tianole_` 前缀；这是单一内核代码库，不把项目名重复进函数名和类型名。
 - 避免 `temp` / `tmp` 这类临时语义进入函数名、类型名和长期变量名；一次性局部变量可以用具体含义命名。
 - C 代码风格参考 Linux：tabs 缩进，函数左花括号另起一行，`if/for/while` 左花括号留在行尾。
+- 公共头文件使用 `<...>` include，例如 `<tianole/boot_info.h>`；同目录私有头文件使用 `"..."` include，例如 `"file.h"`。
+- 不使用 `../foo.h` 这类相对 include；如果一个头需要跨目录使用，应先确认它是否应该成为公共接口。
+- 长文件不是问题，职责混乱才是问题；一个文件可以较长，但必须代表一个清晰子系统、算法或驱动边界。
+- 不为了降低行数拆出 `utils.c`、`helpers.c` 这类无边界文件；按职责、生命周期和调用边界拆分。
+- 注释优先解释硬件约束、ABI 决策、内存所有权、并发语义和不明显的不变量；避免重复描述简单代码正在做什么。
 - 文本文件使用 LF 行尾。
 - `.clang-format` 是当前格式化约定；如果环境有 `clang-format`，新增或大改 C/H 文件后应按它格式化。
 - 根 `Makefile` 只做总控和通用规则；架构配置放在 `arch/<arch>/Makefile`，目录自己的源文件列表放在对应目录的 `Makefile` 中。

arch/x86/boot/elf_loader.c

@@ -1,6 +1,6 @@
 #include "elf_loader.h"
 
-#include "tianole/elf.h"
+#include <tianole/elf.h>
 
 static void *mem_copy(void *dst, const void *src, uint64_t size)
 {

arch/x86/boot/elf_loader.h

@@ -2,9 +2,9 @@
 #define X86_BOOT_ELF_LOADER_H
 
 #include <stdint.h>
+#include <tianole/boot_info.h>
 
 #include "efi.h"
-#include "tianole/boot_info.h"
 
 typedef void
 	__attribute__((sysv_abi)) (*kernel_entry_fn_t)(const boot_info_t *);

arch/x86/boot/main.c

@@ -1,9 +1,10 @@
+#include <tianole/boot_info.h>
+
 #include "debug_log.h"
 #include "efi.h"
 #include "elf_loader.h"
 #include "file.h"
 #include "memory_map.h"
-#include "tianole/boot_info.h"
 
 static efi_char16_t boot_banner_text[] = u"Tianole x86 bootloader.\r\n";
 static efi_char16_t kernel_path_text[] = u"\\kernel.elf";

arch/x86/boot/memory_map.h

@@ -1,8 +1,9 @@
 #ifndef X86_BOOT_MEMORY_MAP_H
 #define X86_BOOT_MEMORY_MAP_H
 
+#include <tianole/boot_info.h>
+
 #include "efi.h"
-#include "tianole/boot_info.h"
 
 efi_status boot_exit_services_with_latest_memory_map(efi_handle image_handle,
 	efi_system_table_t *system_table,

arch/x86/kernel/early_log.c

@@ -1,6 +1,5 @@
 #include <stdint.h>
-
-#include "tianole/arch.h"
+#include <tianole/arch.h>
 
 #define X86_QEMU_DEBUG_PORT 0xe9
 

include/tianole/kernel_init.h

@@ -1,7 +1,7 @@
 #ifndef KERNEL_INIT_H
 #define KERNEL_INIT_H
 
-#include "tianole/boot_info.h"
+#include <tianole/boot_info.h>
 
 void kernel_report_boot_state(const boot_info_t *boot_info);
 

kernel/boot_report.c

@@ -1,8 +1,8 @@
 #include <stdint.h>
 
-#include "tianole/boot_info.h"
-#include "tianole/early_log.h"
-#include "tianole/kernel_init.h"
+#include <tianole/boot_info.h>
+#include <tianole/early_log.h>
+#include <tianole/kernel_init.h>
 
 static void log_memory_map_summary(const boot_info_t *boot_info)
 {

kernel/early_log.c

@@ -1,7 +1,7 @@
 #include <stdint.h>
 
-#include "tianole/arch.h"
-#include "tianole/early_log.h"
+#include <tianole/arch.h>
+#include <tianole/early_log.h>
 
 static int early_log_ready;
 

kernel/main.c

@@ -1,5 +1,5 @@
-#include "tianole/early_log.h"
-#include "tianole/kernel_init.h"
+#include <tianole/early_log.h>
+#include <tianole/kernel_init.h>
 
 void kernel_main(const boot_info_t *boot_info)
 {