NOISSUE Project Tick Handbook is Released!

Assisted-by: Claude:Opus-4.6-High
Signed-off-by: Mehmet Samet Duman <yongdohyun@projecttick.org>

27 files changed, 7579 insertions, 0 deletions

diff --git a/docs/handbook/corebinutils/architecture.md b/docs/handbook/corebinutils/architecture.md
new file mode 100644
index 0000000000..7f6342c9f0
--- /dev/null
+++ b/docs/handbook/corebinutils/architecture.md
@@ -0,0 +1,665 @@
+# Corebinutils — Architecture
+
+## Repository Layout
+
+The corebinutils tree follows a straightforward directory-per-utility layout
+with a top-level orchestrator build system:
+
+```
+corebinutils/
+├── configure               # POSIX sh configure script
+├── README.md               # Top-level build instructions
+├── .gitattributes
+├── .gitignore
+│
+├── config.mk               # [generated] feature detection results
+├── GNUmakefile              # [generated] top-level build orchestrator
+│
+├── build/                   # [generated] intermediate object files
+│   ├── configure/           # Configure test artifacts and logs
+│   ├── cat/                 # Per-utility build intermediates
+│   ├── chmod/
+│   ├── ...
+│   └── sh/
+│
+├── out/                     # [generated] final binaries
+│   └── bin/                 # Staged executables (after `make stage`)
+│
+├── contrib/                 # Shared library sources
+│   ├── libc-vis/            # vis(3)/unvis(3) implementation
+│   ├── libedit/             # editline(3) library
+│   └── printf/              # Shared printf format helpers
+│
+├── cat/                     # Utility: cat
+│   ├── cat.c                # Main source
+│   ├── cat.1                # Manual page (groff)
+│   ├── GNUmakefile          # Per-utility build rules
+│   └── README.md            # Port notes and differences
+│
+├── chmod/                   # Utility: chmod
+│   ├── chmod.c              # Main implementation
+│   ├── mode.c               # Mode parsing library (shared with mkdir)
+│   ├── mode.h               # Mode parsing header
+│   ├── GNUmakefile
+│   └── chmod.1
+│
+├── dd/                      # Utility: dd (multi-file)
+│   ├── dd.c                 # Main control flow
+│   ├── dd.h                 # Shared types (IO, STAT, flags)
+│   ├── extern.h             # Function declarations
+│   ├── args.c               # JCL argument parser
+│   ├── conv.c               # Conversion functions (block/unblock/def)
+│   ├── conv_tab.c           # ASCII/EBCDIC conversion tables
+│   ├── gen.c                # Signal handling helpers
+│   ├── misc.c               # Summary, progress, timing
+│   ├── position.c           # Input/output seek positioning
+│   └── GNUmakefile
+│
+├── ed/                      # Utility: ed (multi-file)
+│   ├── main.c               # Command dispatch and main loop
+│   ├── ed.h                 # Types (line_t, undo_t, constants)
+│   ├── compat.c / compat.h  # Portability shims
+│   ├── buf.c                # Buffer management (scratch file)
+│   ├── glbl.c               # Global command (g/re/cmd)
+│   ├── io.c                 # File I/O (read_file, write_file)
+│   ├── re.c                 # Regular expression handling
+│   ├── sub.c                # Substitution command
+│   └── undo.c               # Undo stack management
+│
+├── ls/                      # Utility: ls (multi-file)
+│   ├── ls.c                 # Main logic, option parsing, directory traversal
+│   ├── ls.h                 # Types (entry, context, enums)
+│   ├── extern.h             # Cross-module declarations
+│   ├── print.c              # Output formatting (columns, long, stream)
+│   ├── cmp.c                # Sort comparison functions
+│   └── util.c               # Helper functions
+│
+├── ps/                      # Utility: ps (multi-file)
+│   ├── ps.c                 # Main logic, /proc scanning
+│   ├── ps.h                 # Types (kinfo_proc, KINFO, VAR)
+│   ├── extern.h             # Cross-module declarations
+│   ├── fmt.c                # Format string parsing
+│   ├── keyword.c            # Output keyword definitions
+│   ├── print.c              # Field value formatting
+│   └── nlist.c              # Name list handling
+│
+└── sh/                      # Utility: POSIX shell
+    ├── main.c               # Shell entry point
+    ├── parser.c / parser.h  # Command parser
+    ├── eval.c               # Command evaluator
+    ├── exec.c               # Command execution
+    ├── jobs.c               # Job control
+    ├── var.c                # Variable management
+    ├── trap.c               # Signal/trap handling
+    ├── expand.c             # Parameter expansion
+    ├── redir.c              # I/O redirection
+    └── ...                  # (60+ additional files)
+```
+
+## Build System Architecture
+
+### Two-Level Build Organization
+
+The build system has two distinct levels:
+
+1. **Top-level orchestrator** — Generated `GNUmakefile` and `config.mk` that
+   coordinate all subdirectories.
+2. **Per-utility `GNUmakefile`** — Each utility directory has its own build
+   rules. These are the source of truth and are never overwritten by
+   `configure`.
+
+The top-level `GNUmakefile` invokes subdirectory builds via recursive make:
+
+```makefile
+build-%: prepare-%
+	+env CPPFLAGS="$(CPPFLAGS)" CFLAGS="$(CFLAGS)" LDFLAGS="$(LDFLAGS)" \
+		$(MAKE) -C "$*" -f GNUmakefile $(SUBMAKE_OVERRIDES) all
+```
+
+### Shared Output Directories
+
+All utilities share centralized output directories to simplify packaging:
+
+```
+build/    # Object files, organized per-utility: build/cat/, build/chmod/, ...
+out/      # Final linked binaries
+out/bin/  # Staged binaries (after `make stage`)
+```
+
+Subdirectories get symbolic links (`build -> ../build/<util>`,
+`out -> ../out`) created by the `prepare-%` target:
+
+```makefile
+prepare-%:
+	@mkdir -p "$(MONO_BUILDDIR)/$*" "$(MONO_OUTDIR)"
+	@ln -sfn "../build/$*" "$*/build"
+	@ln -sfn "../out" "$*/out"
+```
+
+### Variable Propagation
+
+The top-level Makefile passes all detected toolchain variables to
+subdirectory builds via `SUBMAKE_OVERRIDES`:
+
+```makefile
+SUBMAKE_OVERRIDES = \
+	CC="$(CC)" \
+	AR="$(AR)" \
+	AWK="$(AWK)" \
+	RANLIB="$(RANLIB)" \
+	NM="$(NM)" \
+	SH="$(SH)" \
+	CRYPTO_LIBS="$(CRYPTO_LIBS)" \
+	EDITLINE_CPPFLAGS="$(EDITLINE_CPPFLAGS)" \
+	EDITLINE_LIBS="$(EDITLINE_LIBS)" \
+	PREFIX="$(PREFIX)" \
+	BINDIR="$(BINDIR)" \
+	DESTDIR="$(DESTDIR)" \
+	CROSS_COMPILING="$(CROSS_COMPILING)" \
+	EXEEXT="$(EXEEXT)"
+```
+
+This ensures every utility builds with the same compiler, flags, and
+library configuration.
+
+### Generated vs. Maintained Files
+
+| File             | Generated? | Purpose                              |
+|------------------|------------|--------------------------------------|
+| `configure`      | No         | POSIX sh configure script            |
+| `config.mk`     | Yes        | Feature detection macros              |
+| `GNUmakefile`    | Yes        | Top-level orchestrator                |
+| `*/GNUmakefile`  | No         | Per-utility build rules               |
+| `build/`         | Yes        | Object file directory tree            |
+| `out/`           | Yes        | Binary output directory               |
+
+## Configure Script Architecture
+
+### Script Structure
+
+The `configure` script is a single POSIX shell file (no autoconf) organized
+into these phases:
+
+```
+1. Initialization       — Set defaults, parse CLI arguments
+2. Compiler Detection   — Find musl-first C compiler
+3. Tool Detection       — Find make, ar, ranlib, nm, awk, sh, pkg-config
+4. Libc Identification  — Determine musl vs glibc via binary inspection
+5. Header Probing       — Check for ~40 system headers
+6. Function Probing     — Check for ~20 C library functions
+7. Library Probing      — Check for optional libraries (crypt, dl, pthread, rt)
+8. File Generation      — Write config.mk and GNUmakefile
+```
+
+### Compiler Probing
+
+The compiler detection uses three progressive tests:
+
+```sh
+# Can it compile a simple program?
+can_compile_with() { ... }
+
+# Can it compile AND run? (native builds only)
+can_run_with() { ... }
+
+# Does it support C11 stdatomic.h?
+can_compile_stdatomic_with() { ... }
+```
+
+All three must pass. For cross-compilation (`--host != --build`), the
+run test is skipped.
+
+### Feature Detection Pattern
+
+Headers and functions are probed with a consistent pattern that records
+results as Make variables and C preprocessor defines:
+
+```sh
+check_header() {
+    hdr=$1
+    macro="HAVE_$(to_macro "$hdr")"    # e.g., HAVE_SYS_ACL_H
+    if try_cc "#include <$hdr>
+    int main(void) { return 0; }"; then
+        record_cpp_define "$macro" 1
+    else
+        record_cpp_define "$macro" 0
+    fi
+}
+
+check_func() {
+    func=$1
+    includes=$2
+    macro="HAVE_$(to_macro "$func")"   # e.g., HAVE_COPY_FILE_RANGE
+    if try_cc "$includes
+    int main(void) { void *p = (void *)(uintptr_t)&$func; return p == 0; }"; then
+        record_cpp_define "$macro" 1
+    else
+        record_cpp_define "$macro" 0
+    fi
+}
+```
+
+### Headers Probed
+
+The configure script checks for the following headers:
+
+```
+stdlib.h  stdio.h  stdint.h  inttypes.h  stdbool.h  stddef.h
+string.h  strings.h  unistd.h  errno.h  fcntl.h  signal.h
+sys/types.h  sys/stat.h  sys/time.h  sys/resource.h  sys/wait.h
+sys/select.h  sys/ioctl.h  sys/param.h  sys/socket.h  netdb.h
+poll.h  sys/poll.h  termios.h  stropts.h  pthread.h
+sys/event.h  sys/timerfd.h  sys/acl.h  attr/xattr.h  linux/xattr.h
+dlfcn.h  langinfo.h  locale.h  wchar.h  wctype.h
+```
+
+### Functions Probed
+
+```
+getcwd  realpath  fchdir  fstatat  openat  copy_file_range
+memmove  strlcpy  strlcat  explicit_bzero  getline  getentropy
+posix_spawn  clock_gettime  poll  kqueue  timerfd_create
+pipe2  closefrom  getrandom
+```
+
+### Libraries Probed
+
+| Library  | Symbol              | Usage                              |
+|----------|---------------------|------------------------------------|
+| crypt    | `crypt()`           | Password hashing (`ed -x` legacy)  |
+| dl       | `dlopen()`          | Dynamic loading                    |
+| pthread  | `pthread_create()`  | Threading support                  |
+| rt       | `clock_gettime()`   | High-resolution timing             |
+| util     | `openpty()`         | Pseudo-terminal support            |
+| attr     | `setxattr()`        | Extended attributes (`mv`, `cp`)   |
+| selinux  | `is_selinux_enabled()` | SELinux label support           |
+
+## Code Organization Patterns
+
+### Single-File Utility Pattern
+
+Most simple utilities follow this structure:
+
+```c
+/* SPDX license header */
+
+#include <system-headers.h>
+
+struct options { ... };
+
+static const char *progname;
+
+static void usage(void) __attribute__((__noreturn__));
+static void error_errno(const char *, ...);
+static void error_msg(const char *, ...);
+
+int main(int argc, char *argv[])
+{
+    struct options opt;
+    int ch;
+
+    progname = program_name(argv[0]);
+
+    while ((ch = getopt(argc, argv, "...")) != -1) {
+        switch (ch) {
+        case 'f': opt.force = true; break;
+        /* ... */
+        default:  usage();
+        }
+    }
+    argc -= optind;
+    argv += optind;
+
+    /* Perform main operation */
+    for (int i = 0; i < argc; i++) {
+        if (process(argv[i], &opt) != 0)
+            exitval = 1;
+    }
+    return exitval;
+}
+```
+
+### Multi-File Utility Pattern
+
+Complex utilities split across files with a shared header:
+
+```
+utility/
+├── utility.c     # main(), option parsing, top-level dispatch
+├── utility.h     # Shared types, constants, macros
+├── extern.h      # Function declarations for cross-module calls
+├── sub1.c        # Functional subsystem (e.g., args.c, conv.c)
+├── sub2.c        # Another subsystem (e.g., print.c, fmt.c)
+└── GNUmakefile   # Build rules listing all .c files
+```
+
+### Header Guard Convention
+
+Headers use the BSD `_FILENAME_H_` pattern:
+
+```c
+#ifndef _PS_H_
+#define _PS_H_
+/* ... */
+#endif
+```
+
+### Portability Macros
+
+Common compatibility macros appear across multiple utilities:
+
+```c
+#ifndef __unused
+#define __unused __attribute__((__unused__))
+#endif
+
+#ifndef __dead2
+#define __dead2  __attribute__((__noreturn__))
+#endif
+
+#ifndef nitems
+#define nitems(array) (sizeof(array) / sizeof((array)[0]))
+#endif
+
+#ifndef MIN
+#define MIN(a, b) ((a) < (b) ? (a) : (b))
+#endif
+
+#ifndef MAX
+#define MAX(a, b) ((a) > (b) ? (a) : (b))
+#endif
+```
+
+### POSIX Feature Test Macros
+
+Many utilities define feature test macros at the top of their main source
+file:
+
+```c
+#define _POSIX_C_SOURCE 200809L
+```
+
+Or rely on the configure-injected flags:
+
+```
+-D_DEFAULT_SOURCE -D_XOPEN_SOURCE=700
+```
+
+## Shared Code Reuse
+
+### `mode.c` / `mode.h`
+
+The mode parsing library is shared between `chmod` and `mkdir`. It provides:
+
+- `mode_compile()` — Parse a mode string (numeric or symbolic) into a
+  compiled command array (`bitcmd_t`)
+- `mode_apply()` — Apply a compiled mode to an existing `mode_t`
+- `mode_free()` — Release compiled mode memory
+- `strmode()` — Convert `mode_t` to display string like `"drwxr-xr-x "`
+
+### `fts.c` / `fts.h`
+
+An in-tree FTS (File Tree Walk) implementation used by `cp`, `chflags`, and
+other utilities that do recursive directory traversal. This avoids depending
+on glibc's FTS implementation or `nftw(3)`.
+
+### `contrib/libc-vis/`
+
+BSD `vis(3)` / `unvis(3)` character encoding used by `ls` for safe
+display of filenames containing control characters or non-printable bytes.
+
+### Signal Name Tables
+
+`kill` and `timeout` both maintain identical `struct signal_entry` tables
+mapping signal names to numbers:
+
+```c
+struct signal_entry {
+    const char *name;
+    int number;
+};
+
+#define SIGNAL_ENTRY(name) { #name, SIG##name }
+
+static const struct signal_entry canonical_signals[] = {
+    SIGNAL_ENTRY(HUP),
+    SIGNAL_ENTRY(INT),
+    SIGNAL_ENTRY(QUIT),
+    /* ... ~30 standard signals ... */
+};
+```
+
+Both also share the same `normalize_signal_name()` function pattern that
+strips "SIG" prefixes and uppercases input.
+
+## Data Structures
+
+### Process Information (`ps`)
+
+The `ps` utility defines a Linux-compatible replacement for FreeBSD's
+`kinfo_proc`:
+
+```c
+struct kinfo_proc {
+    pid_t    ki_pid, ki_ppid, ki_pgid, ki_sid;
+    dev_t    ki_tdev;
+    uid_t    ki_uid, ki_ruid, ki_svuid;
+    gid_t    ki_groups[KI_NGROUPS];
+    char     ki_comm[COMMLEN];        // 256 bytes
+    struct timeval ki_start;
+    uint64_t ki_runtime;              // microseconds
+    uint64_t ki_size;                 // VSZ in bytes
+    uint64_t ki_rssize;               // RSS in pages
+    int      ki_nice;
+    char     ki_stat;                 // BSD-like state (S,R,T,Z,D)
+    int      ki_numthreads;
+    struct rusage ki_rusage;
+    /* ... */
+};
+```
+
+This struct is populated by reading `/proc/[pid]/stat` and
+`/proc/[pid]/status` files.
+
+### I/O State (`dd`)
+
+The `dd` utility uses two key structures for its I/O engine:
+
+```c
+typedef struct {
+    u_char *db;         // Buffer address
+    u_char *dbp;        // Current buffer I/O position
+    ssize_t dbcnt;      // Current byte count in buffer
+    ssize_t dbrcnt;     // Last read byte count
+    ssize_t dbsz;       // Block size
+    u_int   flags;      // ISCHR | ISPIPE | ISTAPE | ISSEEK | NOREAD | ISTRUNC
+    const char *name;   // Filename
+    int     fd;         // File descriptor
+    off_t   offset;     // Block count to skip
+    off_t   seek_offset;// Sparse output seek offset
+} IO;
+
+typedef struct {
+    uintmax_t in_full, in_part;    // Full/partial input blocks
+    uintmax_t out_full, out_part;  // Full/partial output blocks
+    uintmax_t trunc;               // Truncated records
+    uintmax_t swab;                // Odd-length swab blocks
+    uintmax_t bytes;               // Total bytes written
+    struct timespec start;         // Start timestamp
+} STAT;
+```
+
+### Line Buffer (`ed`)
+
+The `ed` editor uses a doubly-linked list of line nodes with a scratch
+file backing store:
+
+```c
+typedef struct line {
+    struct line *q_forw;   // Next line
+    struct line *q_back;   // Previous line
+    off_t        seek;     // Offset in scratch file
+    int          len;      // Line length
+} line_t;
+```
+
+### File Entry (`ls`)
+
+The `ls` utility represents each directory entry with:
+
+```c
+struct entry {
+    struct stat sb;
+    struct file_time btime;    // Birth time (via statx)
+    char *name;                // Display name
+    char *link_target;         // Symlink target (if applicable)
+    /* color, type classification, etc. */
+};
+```
+
+## Makefile Targets Reference
+
+### Top-Level Targets
+
+| Target             | Description                                           |
+|--------------------|-------------------------------------------------------|
+| `all`              | Build all utilities                                   |
+| `clean`            | Remove `build/` and `out/` directories                |
+| `distclean`        | `clean` + remove generated `GNUmakefile`, `config.mk` |
+| `rebuild`          | `clean` then `all`                                    |
+| `reconfigure`      | Re-run `./configure`                                  |
+| `check` / `test`   | Run all utility test suites                           |
+| `stage`            | Copy binaries to `out/bin/`                           |
+| `install`          | Copy binaries to `$DESTDIR$BINDIR`                    |
+| `status`           | Show `out/` directory contents                        |
+| `list`             | Print all subdirectory names                          |
+| `print-config`     | Show active compiler and flags                        |
+| `help`             | List available targets                                |
+
+### Per-Utility Targets
+
+Individual utilities can be built, cleaned, or tested:
+
+```sh
+make -f GNUmakefile build-cat      # Build only cat
+make -f GNUmakefile clean-cat      # Clean only cat
+make -f GNUmakefile check-cat      # Test only cat
+make -f GNUmakefile cat            # Alias for build-cat
+```
+
+### Target Dependencies
+
+```
+all
+ └── build-<util> (for each utility)
+      └── prepare-<util>
+           ├── mkdir -p build/<util> out/
+           ├── ln -sfn ../build/<util> <util>/build
+           └── ln -sfn ../out <util>/out
+
+stage
+ └── all
+      └── copy executables to out/bin/
+
+install
+ └── stage
+      └── copy out/bin/* to $DESTDIR$BINDIR/
+
+distclean
+ └── clean
+      └── remove build/ out/
+ └── unprepare
+      └── remove build/out symlinks from subdirs
+ └── remove GNUmakefile config.mk
+```
+
+## Cross-Compilation Support
+
+The configure script supports cross-compilation via `--host` and `--build`
+triples:
+
+```sh
+./configure --host=aarch64-linux-musl --build=x86_64-linux-musl \
+            --cc=aarch64-linux-musl-gcc
+```
+
+When `--host` differs from `--build`:
+- The executable run test (`can_run_with`) is skipped
+- `CROSS_COMPILING=1` is recorded in `config.mk`
+- The value propagates to all subdirectory builds
+
+## Typical Per-Utility GNUmakefile
+
+Each utility has a `GNUmakefile` following this general pattern:
+
+```makefile
+# cat/GNUmakefile
+
+PROG = cat
+SRCS = cat.c
+
+BUILDDIR ?= build
+OUTDIR ?= out
+
+CC ?= cc
+CPPFLAGS += -D_DEFAULT_SOURCE -D_XOPEN_SOURCE=700
+CFLAGS ?= -O2 -g -pipe
+LDFLAGS ?=
+
+OBJS = $(SRCS:.c=.o)
+OBJS := $(addprefix $(BUILDDIR)/,$(OBJS))
+
+all: $(OUTDIR)/$(PROG)
+
+$(OUTDIR)/$(PROG): $(OBJS)
+	$(CC) $(LDFLAGS) -o $@ $(OBJS) $(LDLIBS)
+
+$(BUILDDIR)/%.o: %.c
+	@mkdir -p $(dir $@)
+	$(CC) $(CPPFLAGS) $(CFLAGS) -c -o $@ $<
+
+clean:
+	rm -f $(OBJS) $(OUTDIR)/$(PROG)
+
+test:
+	@echo "SKIP: no tests for $(PROG)"
+
+.PHONY: all clean test
+```
+
+Multi-file utilities list all sources in `SRCS` and may link additional
+libraries:
+
+```makefile
+# dd/GNUmakefile
+SRCS = dd.c args.c conv.c conv_tab.c gen.c misc.c position.c
+LDLIBS += -lm    # For dd's speed calculations
+```
+
+## Security Considerations
+
+### Input Validation Boundaries
+
+- **File paths**: Validated against `PATH_MAX` limits. Utilities like `rm`
+  explicitly reject `/`, `.`, and `..` as arguments.
+- **Numeric arguments**: Parsed with `strtoimax()` or `strtol()` with
+  explicit overflow checking.
+- **Signal numbers**: Validated against the compiled signal table, not
+  unchecked `atoi()`.
+- **Mode strings**: `mode_compile()` validates syntax before any filesystem
+  modification occurs.
+
+### Privilege Handling
+
+- `hostname` and `domainname` require root for set operations; they validate
+  the hostname length against the kernel's UTS namespace limit first.
+- `rm` refuses to delete `/` unless explicitly overridden.
+- `chmod -R` includes cycle detection to prevent infinite loops from symlink
+  chains.
+
+### Temporary File Safety
+
+- `ed` creates temporary scratch files in `$TMPDIR` (or `/tmp`) using
+  `mkstemp(3)`.
+- `dd` does not create temporary files — it operates on explicit input/output
+  file descriptors.
diff --git a/docs/handbook/corebinutils/building.md b/docs/handbook/corebinutils/building.md
new file mode 100644
index 0000000000..48ad098712
--- /dev/null
+++ b/docs/handbook/corebinutils/building.md
@@ -0,0 +1,429 @@
+# Corebinutils — Building
+
+## Prerequisites
+
+### Required Tools
+
+| Tool       | Minimum Version | Purpose                                 |
+|------------|----------------|-----------------------------------------|
+| C compiler | C11 support    | Must support `<stdatomic.h>`            |
+| `make`     | GNU Make 4.x   | Build orchestration                     |
+| `ar`       | Any            | Archive tool for static libraries       |
+| `ranlib`   | Any            | Library index generation                |
+| `awk`      | POSIX          | Build-time text processing              |
+| `sh`       | POSIX          | Shell for scripts and tests             |
+
+### Preferred Compiler: musl-based
+
+The configure script searches for musl-based compilers in this priority
+order:
+
+1. `musl-clang` — musl's Clang wrapper
+2. `clang --target=<arch>-linux-musl` — Clang targeting musl
+3. `clang --target=<arch>-unknown-linux-musl` — Clang with full triple
+4. `musl-gcc` — musl's GCC wrapper
+5. `clang` — Generic Clang (libc detected from output binary)
+6. `cc` — System default
+7. `gcc` — GNU CC
+
+If a glibc toolchain is detected, configure fails with:
+
+```
+configure: error: glibc toolchain detected; refusing by default
+                  (use --allow-glibc to override)
+```
+
+### Libc Detection
+
+The configure script identifies the libc implementation through three
+methods (tried in order):
+
+1. **Binary inspection**: Compiles a test program, runs `file(1)` on it,
+   looks for `ld-musl` or `ld-linux` in the interpreter path
+2. **Preprocessor macros**: Checks for `__GLIBC__` or `__MUSL__` in the
+   compiler's predefined macros
+3. **Target triple**: Inspects the compiler's `-dumpmachine` output for
+   `musl` or `gnu`/`glibc` substrings
+
+### Optional Dependencies
+
+| Library    | Symbol           | Required By         | Fallback             |
+|------------|------------------|---------------------|----------------------|
+| `libcrypt` | `crypt()`        | `ed` (legacy `-x`)  | Feature disabled     |
+| `libdl`    | `dlopen()`       | `sh` (loadable)     | Feature disabled     |
+| `libpthread`| `pthread_create()` | Various           | Single-threaded      |
+| `librt`    | `clock_gettime()`| `dd`, `timeout`     | Linked if needed     |
+| `libutil`  | `openpty()`      | `sh`, `csh`         | Pty feature disabled |
+| `libattr`  | `setxattr()`     | `mv`, `cp`          | xattr not preserved  |
+| `libselinux`| `is_selinux_enabled()` | SELinux labels | Labels not set     |
+| `libedit`  | editline(3)      | `sh`, `csh`         | No line editing      |
+
+## Quick Build
+
+```sh
+cd corebinutils/
+
+# Step 1: Configure
+./configure
+
+# Step 2: Build all utilities
+make -f GNUmakefile -j$(nproc) all
+
+# Step 3: (Optional) Run tests
+make -f GNUmakefile test
+
+# Step 4: (Optional) Stage binaries
+make -f GNUmakefile stage
+```
+
+After a successful build, binaries appear in `out/` and staged copies in
+`out/bin/`.
+
+## Configure Script Reference
+
+### Usage
+
+```
+./configure [options]
+```
+
+### General Options
+
+| Option                    | Default          | Description                    |
+|---------------------------|------------------|--------------------------------|
+| `--help`                  |                  | Show help and exit             |
+| `--prefix=PATH`           | `/usr/local`     | Install prefix                 |
+| `--bindir=PATH`           | `<prefix>/bin`   | Install binary directory       |
+| `--host=TRIPLE`           | Auto-detected    | Target host triple             |
+| `--build=TRIPLE`          | Auto-detected    | Build system triple            |
+
+### Toolchain Options
+
+| Option                    | Default          | Description                    |
+|---------------------------|------------------|--------------------------------|
+| `--cc=COMMAND`            | Auto-detected    | Force specific compiler        |
+| `--allow-glibc`           | Off              | Allow glibc toolchain          |
+
+### Flag Options
+
+| Option                    | Default          | Description                    |
+|---------------------------|------------------|--------------------------------|
+| `--extra-cppflags=FLAGS`  | Empty            | Extra preprocessor flags       |
+| `--extra-cflags=FLAGS`    | Empty            | Extra compilation flags        |
+| `--extra-ldflags=FLAGS`   | Empty            | Extra linker flags             |
+
+### Local Path Options
+
+| Option                    | Default          | Description                    |
+|---------------------------|------------------|--------------------------------|
+| `--with-local-dir=PATH`   | `/usr/local`     | Add `PATH/include` and `PATH/lib` |
+| `--without-local-dir`     |                  | Disable local path probing     |
+
+### Policy Options
+
+| Option                       | Default | Description                        |
+|------------------------------|---------|-----------------------------------|
+| `--enable-fail-if-missing`   | Off     | Fail on missing optional probes   |
+
+### Environment Variables
+
+The configure script respects standard environment variables:
+
+| Variable    | Purpose                                        |
+|-------------|------------------------------------------------|
+| `CC`        | C compiler (overridden by probing if unusable) |
+| `CPPFLAGS`  | Preprocessor flags from environment            |
+| `CFLAGS`    | Compilation flags from environment             |
+| `LDFLAGS`   | Linker flags from environment                  |
+
+### Default Flags
+
+The configure script applies these base flags:
+
+```
+CPPFLAGS: -D_DEFAULT_SOURCE -D_XOPEN_SOURCE=700 $env $extra
+CFLAGS:   -O2 -g -pipe $env $extra
+LDFLAGS:  $env $extra
+```
+
+## Configure Output
+
+### `config.mk`
+
+A Make include file with feature detection results:
+
+```makefile
+# Auto-generated by ./configure on 2026-04-05T12:00:00Z
+CONF_CPPFLAGS :=
+CONF_LDFLAGS :=
+CONF_LIBS :=
+CONFIGURE_TIMESTAMP := 2026-04-05T12:00:00Z
+CONFIGURE_HOST := x86_64-unknown-Linux
+CONFIGURE_BUILD := x86_64-unknown-Linux
+CONFIGURE_CC_MACHINE := x86_64-linux-musl
+CONFIGURE_LIBC := musl
+CROSS_COMPILING := 0
+EXEEXT :=
+HAVE_STDLIB_H := 1
+HAVE_COPY_FILE_RANGE := 1
+HAVE_STRLCPY := 1
+# ... (one entry per probed header/function)
+CONF_CPPFLAGS += -DHAVE_STDLIB_H=1 -DHAVE_COPY_FILE_RANGE=1 ...
+CONF_LIBS += -lcrypt -ldl -lpthread -lrt
+```
+
+### `GNUmakefile`
+
+The generated top-level Makefile contains:
+
+- Toolchain variables (`CC`, `AR`, `RANLIB`, etc.)
+- Flag variables (`CPPFLAGS`, `CFLAGS`, `LDFLAGS`)
+- Library variables (`CRYPTO_LIBS`, `EDITLINE_LIBS`)
+- Path variables (`PREFIX`, `BINDIR`, `MONO_BUILDDIR`, `MONO_OUTDIR`)
+- Subdirectory list (`SUBDIRS := cat chflags chmod cp ...`)
+- Build, clean, test, install, and utility targets
+
+### `build/configure/config.log`
+
+Detailed log of every compiler test and probe result. Useful for debugging
+configure failures:
+
+```
+$ musl-clang -x c build/configure/conftest.c -o build/configure/conftest
+$ build/configure/conftest
+checking for sys/acl.h... no
+checking for copy_file_range... yes
+```
+
+## Makefile Targets
+
+### Build Targets
+
+```sh
+make -f GNUmakefile all             # Build all utilities
+make -f GNUmakefile cat             # Build only cat (alias for build-cat)
+make -f GNUmakefile build-cat       # Build only cat
+make -f GNUmakefile build-ls        # Build only ls
+```
+
+### Clean Targets
+
+```sh
+make -f GNUmakefile clean           # Remove build/ and out/
+make -f GNUmakefile clean-cat       # Clean only cat's objects
+make -f GNUmakefile distclean       # clean + remove GNUmakefile, config.mk
+make -f GNUmakefile maintainer-clean # Same as distclean
+```
+
+### Test Targets
+
+```sh
+make -f GNUmakefile test            # Run all test suites
+make -f GNUmakefile check           # Same as test
+make -f GNUmakefile check-cat       # Test only cat
+make -f GNUmakefile check-ls        # Test only ls
+```
+
+### Install Targets
+
+```sh
+make -f GNUmakefile stage           # Copy binaries to out/bin/
+make -f GNUmakefile install         # Install to $DESTDIR$PREFIX/bin
+make -f GNUmakefile install DESTDIR=/tmp/pkg  # Staged install
+```
+
+### Information Targets
+
+```sh
+make -f GNUmakefile status          # Show output directory contents
+make -f GNUmakefile list            # List all utility subdirectories
+make -f GNUmakefile print-config    # Show compiler and flags
+make -f GNUmakefile print-subdirs   # List subdirectories
+make -f GNUmakefile help            # Show available targets
+```
+
+### Rebuild and Reconfigure
+
+```sh
+make -f GNUmakefile rebuild         # clean + all
+make -f GNUmakefile reconfigure     # Re-run ./configure
+```
+
+## Cross-Compilation
+
+### Basic Cross-Compilation
+
+```sh
+./configure \
+    --host=aarch64-linux-musl \
+    --build=x86_64-linux-musl \
+    --cc=aarch64-linux-musl-gcc
+
+make -f GNUmakefile -j$(nproc) all
+```
+
+### Cross-Compilation with Clang
+
+```sh
+./configure \
+    --host=aarch64-linux-musl \
+    --cc="clang --target=aarch64-linux-musl --sysroot=/path/to/musl-sysroot"
+
+make -f GNUmakefile -j$(nproc) all
+```
+
+### Cross vs. Native Detection
+
+When `--host` matches `--build` (or both are auto-detected to the same
+value), `REQUIRE_RUNNABLE_CC=1` and the configure script verifies the
+compiler produces executables that can actually run. For cross-compilation,
+only compilation (not execution) is tested.
+
+## Build Customization
+
+### Custom Compiler Flags
+
+```sh
+# Debug build
+./configure --extra-cflags="-O0 -g3 -fsanitize=address,undefined"
+
+# Release build
+./configure --extra-cflags="-O3 -DNDEBUG -flto" --extra-ldflags="-flto"
+
+# With warnings
+./configure --extra-cflags="-Wall -Wextra -Werror"
+```
+
+### Custom Install Prefix
+
+```sh
+./configure --prefix=/opt/project-tick --bindir=/opt/project-tick/sbin
+make -f GNUmakefile -j$(nproc) all
+make -f GNUmakefile install
+```
+
+### Building Individual Utilities
+
+```sh
+# Configure once
+./configure
+
+# Build only what you need
+make -f GNUmakefile cat ls cp mv rm mkdir
+```
+
+### Forcing glibc
+
+```sh
+./configure --allow-glibc --cc=gcc
+```
+
+Note: The primary test target for corebinutils is musl. Building with glibc
+may expose minor differences in header availability or function signatures.
+
+## Troubleshooting
+
+### "no usable compiler found"
+
+The configure script could not find any C compiler that:
+1. Produces working executables
+2. Supports `<stdatomic.h>` (C11)
+3. Can run the output (native builds only)
+
+**Fix**: Install `musl-gcc` or `musl-clang`, or specify a compiler
+explicitly with `--cc=...`.
+
+### "glibc toolchain detected; refusing by default"
+
+The detected compiler links against glibc instead of musl.
+
+**Fix**: Install musl development tools or pass `--allow-glibc`.
+
+### Missing header warnings
+
+The configure log (`build/configure/config.log`) shows which headers were
+not found. Missing optional headers (e.g., `sys/acl.h`) disable related
+features but don't prevent building.
+
+### Linker errors for `-lcrypt` or `-lrt`
+
+Some utilities use optional libraries. If they're not found at configure
+time, the corresponding features are disabled. If you see linker errors:
+
+```sh
+# Check what was detected
+cat config.mk | grep CONF_LIBS
+```
+
+### Parallel build failures
+
+If `make -j$(nproc)` fails but `make -j1` succeeds, a subdirectory
+`GNUmakefile` may have missing dependencies. File a bug report.
+
+### Cleaning stale state
+
+```sh
+make -f GNUmakefile distclean
+./configure
+make -f GNUmakefile -j$(nproc) all
+```
+
+## Build Output Structure
+
+After a successful `make all && make stage`:
+
+```
+out/
+├── cat
+├── chmod
+├── cp
+├── csh
+├── date
+├── dd
+├── df
+├── echo
+├── ed
+├── expr
+├── hostname
+├── kill
+├── ln
+├── ls
+├── mkdir
+├── mv
+├── nproc
+├── pax
+├── ps
+├── pwd
+├── realpath
+├── rm
+├── rmdir
+├── sh
+├── sleep
+├── sync
+├── test
+├── timeout
+├── [              # Symlink or hardlink to test
+└── bin/           # Staged binaries (copies)
+```
+
+## CI Integration
+
+For CI pipelines, use the non-interactive build sequence:
+
+```sh
+#!/bin/sh
+set -eu
+
+cd corebinutils/
+./configure --prefix=/usr
+
+# Build with parallelism hinted by configure
+JOBS=$(grep -o 'JOBS_HINT := [0-9]*' GNUmakefile | cut -d' ' -f3)
+make -f GNUmakefile -j"${JOBS:-1}" all
+
+# Run tests (SKIP is OK, failures are not)
+make -f GNUmakefile test
+
+# Package
+make -f GNUmakefile install DESTDIR="$PWD/pkg"
+```
diff --git a/docs/handbook/corebinutils/cat.md b/docs/handbook/corebinutils/cat.md
new file mode 100644
index 0000000000..ddc2b842c5
--- /dev/null
+++ b/docs/handbook/corebinutils/cat.md
@@ -0,0 +1,211 @@
+# cat — Concatenate and Display Files
+
+## Overview
+
+`cat` reads files sequentially and writes their contents to standard output.
+It supports line numbering, non-printable character visualization, blank
+line squeezing, and efficient in-kernel copying.
+
+**Source**: `cat/cat.c` (single file)
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+cat [-belnstuv] [file ...]
+```
+
+## Options
+
+| Flag | Long Form | Description |
+|------|-----------|-------------|
+| `-b` | — | Number non-blank output lines (starting at 1) |
+| `-e` | — | Display `$` at end of each line (implies `-v`) |
+| `-l` | — | Set exclusive advisory lock on stdout via `flock(2)` |
+| `-n` | — | Number all output lines |
+| `-s` | — | Squeeze multiple adjacent blank lines into one |
+| `-t` | — | Display TAB as `^I` (implies `-v`) |
+| `-u` | — | Disable output buffering (write immediately) |
+| `-v` | — | Visualize non-printing characters using `^X` and `M-X` notation |
+
+## Source Analysis
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Option parsing via `getopt(3)`, dispatch to `scanfiles()` |
+| `usage()` | Print usage message and exit |
+| `scanfiles()` | Iterate over file arguments, handle `-` as stdin |
+| `cook_cat()` | Process input with formatting (numbering, visualization, squeezing) |
+| `raw_cat()` | Fast buffer-based copy without formatting |
+| `in_kernel_copy()` | Zero-copy via `copy_file_range(2)` syscall |
+| `init_casper()` | BSD Capsicum sandbox init (disabled on Linux) |
+| `init_casper_net()` | BSD Casper network service (disabled on Linux) |
+| `udom_open()` | Unix domain socket support (disabled on Linux) |
+
+### Option Processing
+
+```c
+while ((ch = getopt(argc, argv, "belnstuv")) != -1)
+    switch (ch) {
+    case 'b': bflag = nflag = 1; break;  /* implies -n */
+    case 'e': eflag = vflag = 1; break;  /* implies -v */
+    case 'l': lflag = 1; break;
+    case 'n': nflag = 1; break;
+    case 's': sflag = 1; break;
+    case 't': tflag = vflag = 1; break;  /* implies -v */
+    case 'u': setbuf(stdout, NULL); break;
+    case 'v': vflag = 1; break;
+    default:  usage();
+    }
+```
+
+### I/O Strategy: Three Modes
+
+`cat` selects among three output strategies based on which flags are active:
+
+1. **`in_kernel_copy()`** — When no formatting flags are set and the output
+   supports `copy_file_range(2)`, data moves directly between file
+   descriptors inside the kernel, never entering user space.
+
+2. **`raw_cat()`** — When no formatting is needed but `copy_file_range` is
+   unavailable (e.g., stdin is a pipe). Uses an adaptive read buffer.
+
+3. **`cook_cat()`** — When any formatting flag (`-b`, `-e`, `-n`, `-s`,
+   `-t`, `-v`) is active. Processes each character individually.
+
+### Adaptive Buffer Sizing
+
+`raw_cat()` dynamically sizes its read buffer based on available physical
+memory:
+
+```c
+#define PHYSPAGES_THRESHOLD (32*1024)
+#define BUFSIZE_MAX         (2*1024*1024)   /* 2 MB */
+#define BUFSIZE_SMALL       (128*1024)      /* 128 KB */
+
+if (sysconf(_SC_PHYS_PAGES) > PHYSPAGES_THRESHOLD)
+    bsize = MIN(BUFSIZE_MAX, MAXPHYS * 8);
+else
+    bsize = BUFSIZE_SMALL;
+```
+
+On systems with more than 128 MB of RAM (`32K × 4K pages`), cat uses up
+to 2 MB buffers. On constrained systems, it falls back to 128 KB.
+
+### In-Kernel Copy
+
+When possible, `cat` uses the Linux `copy_file_range(2)` syscall for
+zero-copy I/O:
+
+```c
+static int
+in_kernel_copy(int from_fd, int to_fd)
+{
+    ssize_t ret;
+
+    do {
+        ret = copy_file_range(from_fd, NULL, to_fd, NULL, SSIZE_MAX, 0);
+    } while (ret > 0);
+
+    return (ret == 0) ? 0 : -1;
+}
+```
+
+This avoids two context switches per block (kernel→user for read,
+user→kernel for write) and can be significantly faster for large files.
+
+### Character Visualization
+
+When `-v` is active, `cook_cat()` renders non-printable characters:
+
+| Character Range | Rendering | Example |
+|----------------|-----------|---------|
+| `0x00–0x1F`    | `^@` to `^_` | `^C` for ETX |
+| `0x7F`         | `^?`      | DEL character |
+| `0x80–0x9F`    | `M-^@` to `M-^_` | Meta-control |
+| `0xA0–0xFE`    | `M- ` to `M-~` | Meta-printable |
+| `0xFF`         | `M-^?`    | Meta-DEL |
+| TAB (`0x09`)   | `^I` (with `-t`) or literal | |
+| Newline        | `$\n` (with `-e`) or `\n` | |
+
+### Locale Support
+
+`cat` calls `setlocale(LC_CTYPE, "")` for wide character handling. In
+multibyte locales, the `-v` flag considers locale-specific printability
+via `iswprint(3)`. In the C locale, only ASCII printable characters
+pass through unmodified.
+
+### Lock Mode
+
+The `-l` flag acquires an exclusive advisory lock on stdout before
+writing:
+
+```c
+if (lflag)
+    flock(STDOUT_FILENO, LOCK_EX);
+```
+
+This prevents interleaved output when multiple `cat` processes write to
+the same file simultaneously. The lock is held for the entire duration
+of the program.
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `open(2)` | Open input files |
+| `read(2)` | Read file data into buffer |
+| `write(2)` | Write processed data to stdout |
+| `copy_file_range(2)` | Zero-copy kernel-to-kernel transfer |
+| `flock(2)` | Advisory locking (with `-l`) |
+| `fstat(2)` | Get file type for I/O strategy selection |
+| `sysconf(3)` | Query physical page count for buffer sizing |
+
+## BSD Features Disabled on Linux
+
+Several BSD-specific features are compiled out on Linux:
+
+- **Capsicum sandbox** (`cap_enter`, `cap_rights_limit`): The
+  `init_casper()` function is a no-op stub on Linux.
+- **Unix domain socket reading** (`udom_open()`): BSD `cat` can read
+  from Unix sockets via `connect(2)`. Disabled on Linux.
+- **`O_RESOLVE_BENEATH`**: BSD sandbox path resolution flag. Defined to 0
+  on Linux.
+
+## Examples
+
+```sh
+# Concatenate files
+cat file1.txt file2.txt > combined.txt
+
+# Number non-blank lines
+cat -b source.c
+
+# Show invisible characters
+cat -vet binary_file
+
+# Squeeze blank lines and number
+cat -sn logfile.txt
+
+# Lock stdout for atomic output
+cat -l data.csv >> shared_output.csv
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | All files read successfully |
+| 1    | Error opening or reading a file |
+
+## Edge Cases
+
+- Reading from stdin: When no files are specified or `-` is given, cat
+  reads from standard input.
+- Empty files: Produce no output but are not errors.
+- Binary files: Processed byte-by-byte; `-v` makes them viewable.
+- Named pipes and devices: `raw_cat()` handles them with buffered reads.
+  `copy_file_range` is not attempted on non-regular files.
diff --git a/docs/handbook/corebinutils/chmod.md b/docs/handbook/corebinutils/chmod.md
new file mode 100644
index 0000000000..b5f8a22886
--- /dev/null
+++ b/docs/handbook/corebinutils/chmod.md
@@ -0,0 +1,296 @@
+# chmod — Change File Permissions
+
+## Overview
+
+`chmod` changes the file mode (permission) bits of specified files. It supports
+both symbolic and numeric (octal) mode specifications, recursive directory
+traversal, symlink handling policies, ACL awareness, and verbose operation.
+
+**Source**: `chmod/chmod.c`, `chmod/mode.c`, `chmod/mode.h`
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+chmod [-fhvR [-H | -L | -P]] mode file ...
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-R` | Recursive: change files and directories recursively |
+| `-H` | Follow symlinks on the command line (with `-R` only) |
+| `-L` | Follow all symbolic links (with `-R` only) |
+| `-P` | Do not follow symbolic links (default with `-R`) |
+| `-f` | Force: suppress most error messages |
+| `-h` | Affect symlinks themselves, not their targets |
+| `-v` | Verbose: print changed files |
+| `-vv` | Very verbose: print all files, whether changed or not |
+
+## Source Analysis
+
+### chmod.c — Main Implementation
+
+#### Key Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Parse options via `getopt(3)`, compile mode, dispatch traversal |
+| `walk_path()` | Stat a path and decide how to process it |
+| `walk_dir()` | Enumerate directory contents for recursive processing |
+| `apply_mode()` | Compile mode, apply via `fchmodat(2)`, report changes |
+| `stat_path()` | Wrapper choosing between `stat(2)` and `lstat(2)` |
+| `should_skip_acl_check()` | Cache per-filesystem ACL support detection |
+| `visited_push()` / `visited_check()` | Cycle detection via device/inode tracking |
+| `siginfo_handler()` | Handle SIGINFO/SIGUSR1 for progress reporting |
+| `join_path()` | Safe path concatenation with separator handling |
+
+#### Option Processing
+
+```c
+while ((ch = getopt(argc, argv, "HLPRfhv")) != -1)
+    switch (ch) {
+    case 'H': Hflag = 1; Lflag = 0; break;
+    case 'L': Lflag = 1; Hflag = 0; break;
+    case 'P': Hflag = Lflag = 0; break;
+    case 'R': Rflag = 1; break;
+    case 'f': fflag = 1; break;
+    case 'h': hflag = 1; break;
+    case 'v': vflag++; break;  /* -v increments, -vv = 2 */
+    default:  usage();
+    }
+```
+
+#### Recursive Traversal
+
+The `-R` flag triggers recursive directory traversal. `chmod` implements its
+own traversal with cycle detection rather than using `fts(3)`:
+
+```c
+static int
+walk_dir(const char *dir_path, const struct chmod_options *opts)
+{
+    DIR *dp;
+    struct dirent *de;
+    char *child_path;
+    int ret = 0;
+
+    dp = opendir(dir_path);
+    while ((de = readdir(dp)) != NULL) {
+        if (strcmp(de->d_name, ".") == 0 || strcmp(de->d_name, "..") == 0)
+            continue;
+        child_path = join_path(dir_path, de->d_name);
+        ret |= walk_path(child_path, opts, false);
+        free(child_path);
+    }
+    closedir(dp);
+    return ret;
+}
+```
+
+#### Cycle Detection
+
+To prevent infinite traversal through symlink loops or bind mounts, `chmod`
+maintains a visited-path stack keyed on `(dev, ino)` pairs:
+
+```c
+static int visited_check(dev_t dev, ino_t ino);   /* returns 1 if seen */
+static void visited_push(dev_t dev, ino_t ino);   /* record as visited */
+```
+
+### mode.c — Mode Parsing Library
+
+#### Data Types
+
+```c
+typedef struct {
+    int cmd;     /* '+', '-', '=', 'X', 'u', 'g', 'o' */
+    mode_t bits; /* Permission bits to modify */
+    mode_t who;  /* Scope mask (user/group/other/all) */
+} bitcmd_t;
+```
+
+#### Key Functions
+
+| Function | Purpose |
+|----------|---------|
+| `mode_compile()` | Parse mode string into array of `bitcmd_t` operations |
+| `mode_apply()` | Apply compiled mode to an existing `mode_t` value |
+| `mode_free()` | Free compiled mode array |
+| `strmode()` | Convert `mode_t` to display string like `"drwxr-xr-x "` |
+| `get_current_umask()` | Atomically read process umask |
+
+#### Numeric Mode Parsing
+
+Numeric modes are parsed as octal:
+
+```c
+if (isdigit(*mode_string)) {
+    /* Parse octal: 755 → rwxr-xr-x, 0644 → rw-r--r-- */
+    val = strtol(mode_string, &ep, 8);
+    /* Set bits directly, clearing old permission bits */
+}
+```
+
+#### Symbolic Mode Parsing
+
+Symbolic modes follow the grammar:
+
+```
+mode    ::= clause [, clause ...]
+clause  ::= [who ...] [action ...] action
+who     ::= 'u' | 'g' | 'o' | 'a'
+action  ::= op [perm ...]
+op      ::= '+' | '-' | '='
+perm    ::= 'r' | 'w' | 'x' | 'X' | 's' | 't' | 'u' | 'g' | 'o'
+```
+
+Examples:
+- `u+rwx` — Add read/write/execute for user
+- `go-w` — Remove write for group and other
+- `a=rx` — Set all to read+execute only
+- `u=g` — Copy group permissions to user
+- `+X` — Add execute only if already executable or is a directory
+- `u+s` — Set SUID bit
+- `g+s` — Set SGID bit
+- `+t` — Set sticky bit
+
+#### The 'X' Permission
+
+The conditional execute permission `X` is a special case:
+
+```c
+/* 'X' only adds execute if:
+ *   - The file is a directory, OR
+ *   - Any execute bit is already set */
+if (cmd == 'X') {
+    if (S_ISDIR(old_mode) || (old_mode & (S_IXUSR|S_IXGRP|S_IXOTH)))
+        /* apply execute bits */
+}
+```
+
+This is commonly used with `-R` to make directories traversable without
+making regular files executable: `chmod -R u+rwX,go+rX dir/`
+
+#### Mode Compilation
+
+The `mode_compile()` function translates a mode string into an array of
+`bitcmd_t` instructions that can be applied to any `mode_t`:
+
+```c
+bitcmd_t *mode_compile(const char *mode_string);
+
+/* Usage: */
+bitcmd_t *set = mode_compile("u+rw,go+r");
+mode_t new_mode = mode_apply(set, old_mode);
+mode_free(set);
+```
+
+This two-phase approach lets the mode be parsed once and applied to many
+files during recursive traversal.
+
+#### strmode() Function
+
+Converts a numeric `mode_t` into a human-readable string:
+
+```c
+char buf[12];
+strmode(0100755, buf);  /* "drwxr-xr-x " → for directories */
+strmode(0100644, buf);  /* "-rw-r--r-- " → for regular files */
+```
+
+The output is always 11 characters: type + 9 permission chars + space.
+
+### Umask Interaction
+
+When no scope (`u`, `g`, `o`, `a`) is specified in a symbolic mode, the
+umask determines which bits are affected. The umask is read atomically:
+
+```c
+static mode_t
+get_current_umask(void)
+{
+    mode_t mask;
+    sigset_t set, oset;
+
+    sigfillset(&set);
+    sigprocmask(SIG_BLOCK, &set, &oset);
+    mask = umask(0);
+    umask(mask);
+    sigprocmask(SIG_SETMASK, &oset, NULL);
+    return mask;
+}
+```
+
+Signals are blocked during the read-restore cycle to prevent another
+thread or signal handler from seeing a zero umask.
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `fchmodat(2)` | Apply permission changes |
+| `fstatat(2)` | Get current file mode |
+| `lstat(2)` | Stat without following symlinks |
+| `opendir(3)` / `readdir(3)` | Directory traversal |
+| `sigaction(2)` | Install SIGINFO handler |
+| `umask(2)` | Read current umask |
+
+## ACL Integration
+
+`chmod` is aware of POSIX ACLs. When changing permissions on a file with
+ACLs, the ACL mask entry may need updating. The `should_skip_acl_check()`
+function caches whether a filesystem supports ACLs to avoid repeated
+`pathconf()` calls:
+
+```c
+static bool
+should_skip_acl_check(const char *path)
+{
+    /* Cache per-device ACL support to avoid pathconf() on every file */
+}
+```
+
+## Examples
+
+```sh
+# Set exact permissions
+chmod 755 script.sh
+chmod 0644 config.txt
+
+# Add execute for user
+chmod u+x program
+
+# Recursive: directories traversable, files not executable
+chmod -R u+rwX,go+rX project/
+
+# Remove write for everyone except owner
+chmod go-w important.txt
+
+# Copy group permissions to other
+chmod o=g shared_file
+
+# Set SUID
+chmod u+s /usr/local/bin/helper
+
+# Verbose mode
+chmod -Rv 755 bin/
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | All files changed successfully |
+| 1    | Error changing one or more files (partial failure) |
+
+## Differences from GNU chmod
+
+- No `--reference=FILE` option
+- No `--changes` (use `-v`)
+- `-h` flag affects symlinks (GNU uses `--no-dereference`)
+- `-vv` for very verbose (GNU only has one `-v` level)
+- ACL awareness is filesystem-dependent
+- Mode compiler supports `u=g` (copy from group to user)
diff --git a/docs/handbook/corebinutils/code-style.md b/docs/handbook/corebinutils/code-style.md
new file mode 100644
index 0000000000..2461903725
--- /dev/null
+++ b/docs/handbook/corebinutils/code-style.md
@@ -0,0 +1,351 @@
+# Code Style — Corebinutils Conventions
+
+## Overview
+
+The corebinutils codebase follows FreeBSD kernel style (KNF) with
+Linux-specific adaptations. This document catalogs the coding
+conventions observed across all utilities.
+
+## File Organization
+
+### Standard File Layout
+
+```c
+/*-
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ * Copyright (c) YYYY Project Tick
+ * Copyright (c) YYYY The Regents of the University of California.
+ * All rights reserved.
+ *
+ * Redistribution notice ...
+ */
+
+/* System headers (alphabetical) */
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <errno.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+/* Local headers */
+#include "utility.h"
+
+/* Macros */
+#define BUFSIZE  (128 * 1024)
+
+/* Types and structs */
+struct options { ... };
+
+/* Static function prototypes */
+static void usage(void);
+
+/* Static globals */
+static const char *progname;
+
+/* Functions (main last or first, utility-dependent) */
+```
+
+### Header Guard Style
+
+```c
+/* No #pragma once — uses traditional guards */
+#ifndef _DD_H_
+#define _DD_H_
+/* ... */
+#endif /* !_DD_H_ */
+```
+
+## Naming Conventions
+
+### Functions
+
+- **Lowercase with underscores**: `parse_args()`, `copy_file_data()`
+- **Static for file-scope**: All non-`main` functions are `static` unless
+  needed by other translation units
+- **Verb-first**: `read_file()`, `write_output()`, `parse_duration()`
+- **Predicate prefix**: `is_directory()`, `should_recurse()`, `has_flag()`
+
+### Variables
+
+- **Short names in small scopes**: `n`, `p`, `ch`, `sb`, `dp`
+- **Descriptive names in structs**: `suppress_newline`, `follow_mode`
+- **Constants as macros**: `BUFSIZE`, `EXIT_TIMEOUT`, `COMMLEN`
+- **Global flags**: Single-word or abbreviated: `verbose`, `force`, `rflag`
+
+### Struct Naming
+
+```c
+/* Tagged structs (no typedef for most) */
+struct options { ... };
+struct mount_entry { ... };
+
+/* Typedefs only for opaque or complex types */
+typedef struct line line_t;
+typedef struct { ... } bitcmd_t;
+typedef regex_t pattern_t;
+```
+
+## Option Processing
+
+### getopt(3) Pattern
+
+```c
+while ((ch = getopt(argc, argv, "fhilnRsvwx")) != -1) {
+    switch (ch) {
+    case 'f':
+        opts.force = true;
+        break;
+    case 'v':
+        opts.verbose = true;
+        break;
+    /* ... */
+    default:
+        usage();
+    }
+}
+argc -= optind;
+argv += optind;
+```
+
+### getopt_long(3) Pattern
+
+```c
+static const struct option long_options[] = {
+    {"color",                optional_argument, NULL, 'G'},
+    {"group-directories-first", no_argument,    NULL, OPT_GROUPDIRS},
+    {NULL, 0, NULL, 0},
+};
+
+while ((ch = getopt_long(argc, argv, optstring,
+                         long_options, NULL)) != -1) { ... }
+```
+
+### Manual Parsing (echo)
+
+```c
+/* When getopt is too heavy */
+while (*argv && strcmp(*argv, "-n") == 0) {
+    suppress_newline = true;
+    argv++;
+}
+```
+
+## Error Handling
+
+### BSD err(3) Family
+
+```c
+#include <err.h>
+
+err(1, "open '%s'", path);      /* perror-style with exit */
+errx(2, "invalid mode: %s", s); /* No errno, with exit */
+warn("stat '%s'", path);        /* perror-style, no exit */
+warnx("skipping '%s'", path);   /* No errno, no exit */
+```
+
+### Custom Error Functions
+
+Many utilities define their own for consistency:
+
+```c
+static void
+error_errno(const char *fmt, ...)
+{
+    int saved = errno;
+    va_list ap;
+    fprintf(stderr, "%s: ", progname);
+    va_start(ap, fmt);
+    vfprintf(stderr, fmt, ap);
+    va_end(ap);
+    fprintf(stderr, ": %s\n", strerror(saved));
+}
+
+static void
+error_msg(const char *fmt, ...)
+{
+    va_list ap;
+    fprintf(stderr, "%s: ", progname);
+    va_start(ap, fmt);
+    vfprintf(stderr, fmt, ap);
+    va_end(ap);
+    fputc('\n', stderr);
+}
+```
+
+### Usage Functions
+
+```c
+static void __dead2   /* noreturn attribute */
+usage(void)
+{
+    fprintf(stderr, "usage: %s [-fiv] source target\n", progname);
+    exit(2);
+}
+```
+
+## Memory Management
+
+### Dynamic Allocation Patterns
+
+```c
+/* Always check allocation */
+char *buf = malloc(size);
+if (buf == NULL)
+    err(1, "malloc");
+
+/* strdup with check */
+char *copy = strdup(str);
+if (copy == NULL)
+    err(1, "strdup");
+
+/* Adaptive buffer sizing */
+size_t bufsize = BUFSIZE_MAX;
+while (bufsize >= BUFSIZE_MIN) {
+    buf = malloc(bufsize);
+    if (buf) break;
+    bufsize /= 2;
+}
+```
+
+### No Global malloc/free Tracking
+
+Utilities that process-exit after completion do not free final
+allocations — the OS reclaims all memory. Early-exit utilities
+(cat, echo, pwd) rely on this.
+
+## Portability Patterns
+
+### Conditional Compilation
+
+```c
+/* Feature detection from configure */
+#ifdef HAVE_SYS_XATTR_H
+#include <sys/xattr.h>
+#endif
+
+/* BSD vs Linux */
+#ifdef __linux__
+    /* Linux-specific path */
+#else
+    /* BSD fallback (rarely used) */
+#endif
+
+/* musl compatibility */
+#ifndef STAILQ_HEAD
+#define STAILQ_HEAD(name, type) ...
+#endif
+```
+
+### Inline Syscall Wrappers
+
+```c
+/* For syscalls not in musl headers */
+static int
+linux_statx(int dirfd, const char *path, int flags,
+            unsigned int mask, struct statx *stx)
+{
+    return syscall(__NR_statx, dirfd, path, flags, mask, stx);
+}
+```
+
+## Formatting
+
+### Indentation
+
+- **Tabs** for indentation (KNF style)
+- **8-space tab stops** (standard)
+- Continuation lines indented 4 spaces from operator
+
+### Braces
+
+```c
+/* K&R for functions */
+static void
+function_name(int arg)
+{
+    /* body */
+}
+
+/* Same-line for control flow */
+if (condition) {
+    /* body */
+} else {
+    /* body */
+}
+
+/* No braces for single statements */
+if (error)
+    return -1;
+```
+
+### Line Length
+
+- Target 80 columns
+- Long function signatures wrap at parameter boundaries
+- Long strings use concatenation
+
+### Switch Statements
+
+```c
+switch (ch) {
+case 'f':
+    force = true;
+    break;
+case 'v':
+    verbose++;
+    break;
+default:
+    usage();
+    /* NOTREACHED */
+}
+```
+
+## Common Macros
+
+```c
+/* Array size */
+#define nitems(x) (sizeof(x) / sizeof((x)[0]))
+
+/* Min/Max */
+#ifndef MIN
+#define MIN(a, b) ((a) < (b) ? (a) : (b))
+#endif
+
+/* Noreturn */
+#define __dead2 __attribute__((__noreturn__))
+
+/* Unused parameter */
+#define __unused __attribute__((__unused__))
+```
+
+## Signal Handling Conventions
+
+```c
+/* Volatile sig_atomic_t for signal flags */
+static volatile sig_atomic_t info_requested;
+
+/* Minimal signal handlers (set flag only) */
+static void
+handler(int sig)
+{
+    (void)sig;
+    info_requested = 1;
+}
+
+/* Check flag in main loop */
+if (info_requested) {
+    report_progress();
+    info_requested = 0;
+}
+```
+
+## Build System Conventions
+
+- Per-utility `GNUmakefile` is the source of truth
+- Top-level `GNUmakefile` generated by `configure`
+- All object files go to `build/<utility>/`
+- Final binaries go to `out/bin/`
+- `CFLAGS` include `-Wall -Wextra -Werror` by default
diff --git a/docs/handbook/corebinutils/cp.md b/docs/handbook/corebinutils/cp.md
new file mode 100644
index 0000000000..b15bb01a2d
--- /dev/null
+++ b/docs/handbook/corebinutils/cp.md
@@ -0,0 +1,270 @@
+# cp — Copy Files and Directories
+
+## Overview
+
+`cp` copies files and directory trees. It supports recursive copying, archive
+mode (preserving metadata), symlink handling policies, sparse file detection,
+and interactive/forced overwrite modes.
+
+**Source**: `cp/cp.c`, `cp/utils.c`, `cp/extern.h`, `cp/fts.c`, `cp/fts.h`
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+cp [-HLPRafilnpsvx] [--sort] [-N mode] source_file target_file
+cp [-HLPRafilnpsvx] [--sort] [-N mode] source_file ... target_directory
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-R` / `-r` | Recursive: copy directories and their contents |
+| `-a` | Archive mode: equivalent to `-R -P -p` |
+| `-f` | Force: remove existing target before copying |
+| `-i` | Interactive: prompt before overwriting |
+| `-l` | Create hard links instead of copying |
+| `-n` | No-clobber: do not overwrite existing files |
+| `-p` | Preserve: maintain mode, ownership, timestamps |
+| `-s` | Create symbolic links instead of copying |
+| `-v` | Verbose: print each file as it is copied |
+| `-x` | One-filesystem: do not cross mount points |
+| `-H` | Follow symlinks on command line (with `-R`) |
+| `-L` | Follow all symbolic links (with `-R`) |
+| `-P` | Do not follow symbolic links (default with `-R`) |
+| `--sort` | Sort entries numerically during recursive copy |
+| `-N mode` | Apply negated permissions to regular files |
+
+## Source Analysis
+
+### cp.c — Main Logic
+
+#### Key Data Structures
+
+```c
+typedef struct {
+    char *p_end;           /* Pointer to NULL at end of path */
+    char *target_end;      /* Pointer to end of target base */
+    char p_path[PATH_MAX]; /* Current target path buffer */
+    int  p_fd;             /* Directory file descriptor */
+} PATH_T;
+
+struct options {
+    bool recursive;
+    bool force;
+    bool interactive;
+    bool no_clobber;
+    bool preserve;
+    bool hard_link;
+    bool symbolic_link;
+    bool verbose;
+    bool one_filesystem;
+    /* ... */
+};
+```
+
+#### Key Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Parse options, stat destination, determine copy mode |
+| `copy()` | Main recursive copy driver using FTS traversal |
+| `ftscmp()` | qsort comparator for `--sort` numeric ordering |
+| `local_strlcpy()` | Portability wrapper for `strlcpy` |
+| `local_asprintf()` | Portability wrapper for `asprintf` |
+
+#### Copy Mode Detection
+
+`cp` determines the operation mode from the arguments:
+
+```c
+/* Three cases:
+ * 1. cp file1 file2           → file-to-file copy
+ * 2. cp file1 file2 dir/      → files into directory
+ * 3. cp -R dir1 dir2          → directory to new directory
+ */
+if (stat(target, &sb) == 0 && S_ISDIR(sb.st_mode))
+    type = DIR_TO_DIR;
+else if (argc == 2)
+    type = FILE_TO_FILE;
+else
+    usage();  /* Multiple sources require directory target */
+```
+
+### utils.c — Copy Engine
+
+#### Adaptive Buffer Sizing
+
+Like `cat`, `cp` adapts its I/O buffer to available memory:
+
+```c
+#define PHYSPAGES_THRESHOLD (32*1024)
+#define BUFSIZE_MAX         (2*1024*1024)
+#define BUFSIZE_SMALL       (MAXPHYS)        /* 128 KB */
+
+static ssize_t
+copy_fallback(int from_fd, int to_fd)
+{
+    if (buf == NULL) {
+        if (sysconf(_SC_PHYS_PAGES) > PHYSPAGES_THRESHOLD)
+            bufsize = MIN(BUFSIZE_MAX, MAXPHYS * 8);
+        else
+            bufsize = BUFSIZE_SMALL;
+        buf = malloc(bufsize);
+    }
+    /* read/write loop */
+}
+```
+
+#### Key Functions in utils.c
+
+| Function | Purpose |
+|----------|---------|
+| `copy_fallback()` | Buffer-based file copy with adaptive sizing |
+| `copy_file()` | Copy regular file, potentially using `copy_file_range(2)` |
+| `copy_link()` | Copy symbolic link (read target, create new symlink) |
+| `copy_fifo()` | Copy FIFO via `mkfifo(2)` |
+| `copy_special()` | Copy device nodes via `mknod(2)` |
+| `setfile()` | Set timestamps, ownership, permissions on target |
+| `preserve_fd_acls()` | Copy POSIX ACLs between file descriptors |
+
+### FTS Traversal
+
+`cp -R` uses an in-tree FTS (File Traversal Stream) implementation:
+
+```c
+FTS *ftsp;
+FTSENT *curr;
+int fts_options = FTS_NOCHDIR | FTS_PHYSICAL;
+
+if (Lflag)
+    fts_options &= ~FTS_PHYSICAL;
+    fts_options |= FTS_LOGICAL;
+
+ftsp = fts_open(argv, fts_options, NULL);
+while ((curr = fts_read(ftsp)) != NULL) {
+    switch (curr->fts_info) {
+    case FTS_D:     /* Directory pre-visit */
+        mkdir(target_path, curr->fts_statp->st_mode);
+        break;
+    case FTS_F:     /* Regular file */
+        copy_file(curr->fts_path, target_path);
+        break;
+    case FTS_SL:    /* Symbolic link */
+        copy_link(curr->fts_path, target_path);
+        break;
+    case FTS_DP:    /* Directory post-visit */
+        setfile(curr->fts_statp, target_path);
+        break;
+    }
+}
+```
+
+### Symlink Handling Modes
+
+| Mode | Flag | Behavior |
+|------|------|----------|
+| Physical | `-P` (default) | Copy symlinks as symlinks |
+| Command-line follow | `-H` | Follow symlinks named on command line |
+| Logical | `-L` | Follow all symlinks, copy targets |
+
+### Archive Mode
+
+The `-a` flag combines three flags for complete archival:
+
+```sh
+cp -a source/ dest/
+# Equivalent to:
+cp -R -P -p source/ dest/
+```
+
+- `-R` — Recursive copy
+- `-P` — Don't follow symlinks (preserve them as-is)
+- `-p` — Preserve timestamps, ownership, and permissions
+
+### Metadata Preservation (`-p`)
+
+When `-p` is specified, `cp` preserves:
+
+| Metadata | System Call |
+|----------|-------------|
+| Access time | `utimensat(2)` |
+| Modification time | `utimensat(2)` |
+| File mode | `fchmod(2)` / `chmod(2)` |
+| Owner/group | `fchown(2)` / `lchown(2)` |
+| ACLs | `acl_get_fd()` / `acl_set_fd()` (if available) |
+
+### Cycle Detection
+
+During recursive copy, `cp` tracks visited directories by `(dev, ino)`
+pairs to detect filesystem cycles created by symlinks or bind mounts:
+
+```c
+/* If we've already visited this inode on this device, skip it */
+if (cycle_check(curr->fts_statp->st_dev, curr->fts_statp->st_ino)) {
+    warnx("%s: directory causes a cycle", curr->fts_path);
+    fts_set(ftsp, curr, FTS_SKIP);
+    continue;
+}
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `open(2)` | Open source and target files |
+| `read(2)` / `write(2)` | Buffer-based data copy |
+| `copy_file_range(2)` | Zero-copy in-kernel transfer |
+| `mkdir(2)` | Create target directories |
+| `mkfifo(2)` | Create FIFO copies |
+| `mknod(2)` | Create device node copies |
+| `symlink(2)` | Create symbolic links |
+| `link(2)` | Create hard links (with `-l`) |
+| `readlink(2)` | Read symlink target |
+| `fchmod(2)` | Set permissions on target |
+| `fchown(2)` | Set ownership on target |
+| `utimensat(2)` | Set timestamps on target |
+| `fstat(2)` | Check file type and metadata |
+
+## Examples
+
+```sh
+# Simple file copy
+cp source.txt dest.txt
+
+# Recursive directory copy
+cp -R src/ dest/
+
+# Archive mode (preserve everything)
+cp -a project/ backup/project/
+
+# Interactive overwrite
+cp -i newfile.txt existing.txt
+
+# Create hard links instead of copies
+cp -l large_file.dat link_to_large_file.dat
+
+# Don't cross filesystem boundaries
+cp -Rx /home/user/ /backup/home/user/
+
+# Verbose recursive copy
+cp -Rv config/ /etc/myapp/
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | All files copied successfully |
+| 1    | Error copying one or more files |
+
+## Differences from GNU cp
+
+- No `--reflink` option for CoW copies
+- No `--sparse=auto/always/never` (sparse handling is automatic)
+- `--sort` flag for sorted recursive output (not in GNU)
+- `-N` flag for negated permissions (not in GNU)
+- Uses in-tree FTS instead of gnulib
+- No SELinux context preservation (use `--preserve=context` in GNU)
diff --git a/docs/handbook/corebinutils/date.md b/docs/handbook/corebinutils/date.md
new file mode 100644
index 0000000000..d498f406a5
--- /dev/null
+++ b/docs/handbook/corebinutils/date.md
@@ -0,0 +1,352 @@
+# date — Display and Set System Date
+
+## Overview
+
+`date` displays the current date and time, or sets the system clock. It
+supports strftime-based format strings, ISO 8601 output, RFC 2822 output,
+timezone overrides, date arithmetic via "vary" adjustments, and input
+date parsing.
+
+**Source**: `date/date.c`, `date/vary.c`, `date/vary.h`
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause / BSD-2-Clause (vary.c)
+
+## Synopsis
+
+```
+date [-jnRu] [-r seconds | filename] [-I[date|hours|minutes|seconds|ns]]
+     [-f input_fmt] [-v [+|-]val[ymwdHMS]] [-z output_zone]
+     [+output_format] [[[[[cc]yy]mm]dd]HH]MM[.ss]]
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-j` | Do not try to set the system clock |
+| `-n` | Same as `-j` (compatibility) |
+| `-R` | RFC 2822 format output |
+| `-u` | Use UTC instead of local time |
+| `-r seconds` | Display time from epoch seconds |
+| `-r filename` | Display modification time of file |
+| `-I[precision]` | ISO 8601 format output |
+| `-f input_fmt` | Parse input date using strptime format |
+| `-v adjustment` | Adjust date components (can be repeated) |
+| `-z timezone` | Use specified timezone for output |
+
+## Source Analysis
+
+### date.c — Main Implementation
+
+#### Key Data Structures
+
+```c
+struct iso8601_fmt {
+    const char *refname;        /* "date", "hours", "minutes", etc. */
+    const char *format_string;  /* strftime format */
+    bool include_zone;          /* Whether to append timezone */
+};
+
+struct strbuf {
+    char *data;
+    size_t len;
+    size_t cap;
+};
+
+struct options {
+    const char *input_format;       /* -f format string */
+    const char *output_zone;        /* -z timezone */
+    const char *reference_arg;      /* -r argument */
+    const char *time_operand;       /* MMDDhhmm... or parsed date */
+    const char *format_operand;     /* +format string */
+    struct vary *vary_chain;        /* -v adjustments */
+    const struct iso8601_fmt *iso8601_selected;
+    bool no_set;                    /* -j flag */
+    bool rfc2822;                   /* -R flag */
+    bool use_utc;                   /* -u flag */
+};
+```
+
+#### ISO 8601 Formats
+
+```c
+static const struct iso8601_fmt iso8601_fmts[] = {
+    { "date",    "%Y-%m-%d",              false },
+    { "hours",   "%Y-%m-%dT%H",           true  },
+    { "minutes", "%Y-%m-%dT%H:%M",        true  },
+    { "seconds", "%Y-%m-%dT%H:%M:%S",     true  },
+    { "ns",      "%Y-%m-%dT%H:%M:%S,%N",  true  },
+};
+```
+
+#### Key Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Parse options, resolve time, format output |
+| `parse_args()` | Option-by-option argument processing |
+| `validate_options()` | Check for conflicting options |
+| `set_timezone_or_die()` | Apply timezone via `setenv("TZ", ...)` |
+| `read_reference_time()` | Get time from `-r` argument (epoch or file mtime) |
+| `read_current_time()` | Get current time via `clock_gettime(2)` |
+| `parse_legacy_time()` | Parse `[[[[cc]yy]mm]dd]HH]MM[.ss]` format |
+| `parse_formatted_time()` | Parse via `strptime(3)` with `-f` format |
+| `parse_time_operand()` | Dispatch to legacy or formatted parser |
+| `set_system_time()` | Set clock via `clock_settime(2)` |
+| `apply_variations()` | Apply `-v` adjustments to broken-down time |
+| `expand_format_string()` | Expand `%N` (nanoseconds) in format strings |
+| `render_format()` | Format via `strftime(3)` with extensions |
+| `render_iso8601()` | Generate ISO 8601 output with timezone |
+| `render_numeric_timezone()` | Format `+HHMM` timezone offset |
+| `print_line_and_exit()` | Write output and exit |
+
+#### Main Flow
+
+```c
+int main(int argc, char **argv)
+{
+    parse_args(argc, argv, &options);
+    validate_options(&options);
+    setlocale(LC_TIME, "");
+
+    if (options.use_utc)
+        set_timezone_or_die("UTC0", "TZ=UTC0");
+
+    if (options.reference_arg != NULL)
+        read_reference_time(options.reference_arg, &ts);
+    else
+        read_current_time(&ts, &resolution);
+
+    if (options.time_operand != NULL) {
+        parse_time_operand(&options, &ts, &ts);
+        if (!options.no_set)
+            set_system_time(&ts);
+    }
+
+    localtime_or_die(ts.tv_sec, &tm);
+    apply_variations(&options, &tm);
+
+    /* Render output based on -I, -R, or +format */
+    output = render_format(format, &tm, ts.tv_nsec, resolution.tv_nsec);
+    print_line_and_exit(output);
+}
+```
+
+#### String Buffer Implementation
+
+`date.c` includes a custom growable string buffer for format expansion:
+
+```c
+static void strbuf_init(struct strbuf *buf);
+static void strbuf_reserve(struct strbuf *buf, size_t extra);
+static void strbuf_append_mem(struct strbuf *buf, const char *data, size_t len);
+static void strbuf_append_char(struct strbuf *buf, char ch);
+static void strbuf_append_str(struct strbuf *buf, const char *text);
+static char *strbuf_finish(struct strbuf *buf);
+```
+
+#### Nanosecond Format Extension
+
+The `%N` format specifier (not in standard `strftime`) is expanded
+manually before passing to `strftime(3)`:
+
+```c
+static void
+append_nsec_digits(struct strbuf *buf, const char *pending, size_t len,
+    long nsec, long resolution)
+{
+    /* Format nanoseconds with appropriate precision based on resolution */
+}
+```
+
+### vary.c — Date Arithmetic
+
+The `-v` flag enables relative date adjustments. Multiple `-v` flags can
+be chained to build complex date expressions.
+
+#### Adjustment Types
+
+| Code | Unit | Example |
+|------|------|---------|
+| `y` | Years | `-v +1y` (next year) |
+| `m` | Months | `-v -3m` (3 months ago) |
+| `w` | Weeks | `-v +2w` (2 weeks forward) |
+| `d` | Days | `-v +1d` (tomorrow) |
+| `H` | Hours | `-v -6H` (6 hours ago) |
+| `M` | Minutes | `-v +30M` (30 minutes forward) |
+| `S` | Seconds | `-v -10S` (10 seconds ago) |
+
+#### Named Values
+
+Month names and weekday names can be used with `=`:
+
+```sh
+date -v =monday     # Next Monday
+date -v =january    # Set month to January
+```
+
+#### Implementation
+
+```c
+struct trans {
+    int64_t value;
+    const char *name;
+};
+
+static const struct trans trans_mon[] = {
+    { 1, "january" }, { 2, "february" }, { 3, "march" },
+    { 4, "april" },   { 5, "may" },      { 6, "june" },
+    { 7, "july" },    { 8, "august" },    { 9, "september" },
+    { 10, "october" },{ 11, "november" }, { 12, "december" },
+    { -1, NULL }
+};
+
+static const struct trans trans_wday[] = {
+    { 0, "sunday" },   { 1, "monday" },  { 2, "tuesday" },
+    { 3, "wednesday" },{ 4, "thursday" },{ 5, "friday" },
+    { 6, "saturday" }, { -1, NULL }
+};
+```
+
+The `vary_apply()` function processes each adjustment in the chain,
+calling specific adjuster functions:
+
+```c
+static int adjyear(struct tm *tm, char type, int64_t value, bool normalize);
+static int adjmon(struct tm *tm, char type, int64_t value, bool is_text, bool normalize);
+static int adjday(struct tm *tm, char type, int64_t value, bool normalize);
+static int adjwday(struct tm *tm, char type, int64_t value, bool is_text, bool normalize);
+static int adjhour(struct tm *tm, char type, int64_t value, bool normalize);
+static int adjmin(struct tm *tm, char type, int64_t value, bool normalize);
+static int adjsec(struct tm *tm, char type, int64_t value, bool normalize);
+```
+
+Each adjuster modifies the broken-down `struct tm` and calls
+`normalize_tm()` to fix rolled-over fields via `mktime(3)`.
+
+### Timezone Handling
+
+```c
+static void
+set_timezone_or_die(const char *tz_value, const char *what)
+{
+    if (setenv("TZ", tz_value, 1) != 0)
+        die_errno("setenv %s", what);
+    tzset();
+}
+```
+
+The `-u` flag sets `TZ=UTC0`. The `-z` flag sets `TZ` to the specified
+value only for output formatting (input parsing uses the original timezone).
+
+### Legacy Time Format
+
+The BSD legacy format `[[[[cc]yy]mm]dd]HH]MM[.ss]` is parsed
+right-to-left:
+
+```c
+static void
+parse_legacy_time(const char *text, const struct timespec *base, struct timespec *ts)
+{
+    /* Parse from rightmost position:
+     * 1. [.ss]  - optional seconds
+     * 2. MM     - minutes (required)
+     * 3. HH     - hours
+     * 4. dd     - day
+     * 5. mm     - month
+     * 6. [cc]yy - year
+     */
+}
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `clock_gettime(2)` | Read current time with nanosecond precision |
+| `clock_settime(2)` | Set system clock (requires root) |
+| `stat(2)` | Get file modification time for `-r filename` |
+| `setenv(3)` | Set `TZ` environment variable |
+| `strftime(3)` | Format broken-down time |
+| `strptime(3)` | Parse time from formatted string |
+| `mktime(3)` | Normalize broken-down time |
+| `localtime_r(3)` | Thread-safe time conversion |
+
+## Format Strings
+
+`date` supports all `strftime(3)` format specifiers plus:
+
+| Specifier | Meaning |
+|-----------|---------|
+| `%N` | Nanoseconds (extension, expanded before strftime) |
+| `%+` | Default format (equivalent to `%a %b %e %T %Z %Y`) |
+
+Common `strftime` specifiers:
+
+| Specifier | Output |
+|-----------|--------|
+| `%Y` | 4-digit year (2026) |
+| `%m` | Month (01-12) |
+| `%d` | Day (01-31) |
+| `%H` | Hour (00-23) |
+| `%M` | Minute (00-59) |
+| `%S` | Second (00-60) |
+| `%T` | Time as `%H:%M:%S` |
+| `%Z` | Timezone abbreviation |
+| `%z` | Numeric timezone (`+0000`) |
+| `%s` | Epoch seconds |
+| `%a` | Abbreviated weekday |
+| `%b` | Abbreviated month |
+
+## Examples
+
+```sh
+# Default output
+date
+# → Sat Apr  5 14:30:00 UTC 2026
+
+# Custom format
+date "+%Y-%m-%d %H:%M:%S"
+# → 2026-04-05 14:30:00
+
+# ISO 8601
+date -Iseconds
+# → 2026-04-05T14:30:00+00:00
+
+# RFC 2822
+date -R
+# → Sat, 05 Apr 2026 14:30:00 +0000
+
+# UTC
+date -u
+
+# Epoch seconds
+date +%s
+# → 1775578200
+
+# Date arithmetic: tomorrow
+date -v +1d
+
+# Date arithmetic: last Monday
+date -v -monday
+
+# Date arithmetic: 3 months from now, at midnight
+date -v +3m -v 0H -v 0M -v 0S
+
+# Parse input format
+date -f "%Y%m%d" "20260405" "+%A, %B %d"
+# → Sunday, April 05
+
+# Display file modification time
+date -r /etc/passwd
+
+# Display epoch time
+date -r 1775578200
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success |
+| 1    | Error (invalid format, failed to set time, etc.) |
diff --git a/docs/handbook/corebinutils/dd.md b/docs/handbook/corebinutils/dd.md
new file mode 100644
index 0000000000..df0108c231
--- /dev/null
+++ b/docs/handbook/corebinutils/dd.md
@@ -0,0 +1,407 @@
+# dd — Data Duplicator
+
+## Overview
+
+`dd` copies and optionally converts data between files or devices. It operates
+at the block level with configurable input/output block sizes, supports
+ASCII/EBCDIC conversion, case conversion, byte swapping, sparse output,
+speed throttling, and real-time progress reporting.
+
+**Source**: `dd/dd.c`, `dd/dd.h`, `dd/extern.h`, `dd/args.c`, `dd/conv.c`,
+`dd/conv_tab.c`, `dd/gen.c`, `dd/misc.c`, `dd/position.c`
+**Origin**: BSD 4.4, Keith Muller / Lance Visser
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+dd [operand=value ...]
+```
+
+## Operands
+
+`dd` uses a unique JCL-style syntax (not `getopt`):
+
+| Operand | Description | Default |
+|---------|-------------|---------|
+| `if=file` | Input file | stdin |
+| `of=file` | Output file | stdout |
+| `bs=n` | Block size (sets both ibs and obs) | 512 |
+| `ibs=n` | Input block size | 512 |
+| `obs=n` | Output block size | 512 |
+| `cbs=n` | Conversion block size | — |
+| `count=n` | Number of input blocks to copy | All |
+| `skip=n` / `iseek=n` | Skip n input blocks | 0 |
+| `seek=n` / `oseek=n` | Seek n output blocks | 0 |
+| `files=n` | Copy n input files (tape only) | 1 |
+| `fillchar=c` | Fill character for sync padding | NUL/space |
+| `speed=n` | Maximum bytes per second | Unlimited |
+| `status=value` | Progress reporting mode | — |
+
+### Size Suffixes
+
+Numeric values accept multiplier suffixes:
+
+| Suffix | Multiplier |
+|--------|-----------|
+| `b` | 512 |
+| `k` | 1024 |
+| `m` | 1024² (1,048,576) |
+| `g` | 1024³ (1,073,741,824) |
+| `t` | 1024⁴ |
+| `w` | `sizeof(int)` |
+| `x` | Multiplication (e.g., `2x512` = 1024) |
+
+### conv= Options
+
+| Conversion | Description |
+|------------|-------------|
+| `ascii` | EBCDIC to ASCII |
+| `ebcdic` | ASCII to EBCDIC |
+| `ibm` | ASCII to IBM EBCDIC |
+| `block` | Newline-terminated to fixed-length records |
+| `unblock` | Fixed-length records to newline-terminated |
+| `lcase` | Convert to lowercase |
+| `ucase` | Convert to uppercase |
+| `swab` | Swap every pair of bytes |
+| `noerror` | Continue after read errors |
+| `notrunc` | Don't truncate output file |
+| `sync` | Pad input blocks to ibs with NULs/spaces |
+| `sparse` | Seek over zero-filled output blocks |
+| `fsync` | Physically write output data and metadata |
+| `fdatasync` | Physically write output data |
+| `pareven` | Set even parity on output |
+| `parodd` | Set odd parity on output |
+| `parnone` | Strip parity from input |
+| `parset` | Set parity bit on output |
+
+### iflag= and oflag= Options
+
+| Flag | Description |
+|------|-------------|
+| `direct` | Use `O_DIRECT` for direct I/O |
+| `fullblock` | Accumulate full input blocks |
+
+### status= Values
+
+| Value | Description |
+|-------|-------------|
+| `noxfer` | Suppress transfer statistics |
+| `none` | Suppress everything |
+| `progress` | Print periodic progress via SIGALRM |
+
+## Source Architecture
+
+### File Responsibilities
+
+| File | Purpose |
+|------|---------|
+| `dd.c` | Main control flow: `main()`, `setup()`, `dd_in()`, `dd_close()` |
+| `dd.h` | Shared types: `IO`, `STAT`, conversion flags (40+ bit flags) |
+| `extern.h` | External function declarations and global variable exports |
+| `args.c` | JCL argument parser: `jcl()`, operand table, size parsing |
+| `conv.c` | Conversion functions: `def()`, `block()`, `unblock()` |
+| `conv_tab.c` | ASCII/EBCDIC translation tables (256-byte arrays) |
+| `gen.c` | Signal handling: `prepare_io()`, `before_io()`, `after_io()` |
+| `misc.c` | Summary output, progress reporting, timing |
+| `position.c` | Input/output positioning: `pos_in()`, `pos_out()` |
+
+### Key Data Structures
+
+#### IO Structure (I/O Stream State)
+
+```c
+typedef struct {
+    u_char  *db;        /* Buffer address */
+    u_char  *dbp;       /* Current buffer I/O pointer */
+    ssize_t  dbcnt;     /* Current buffer byte count */
+    ssize_t  dbrcnt;    /* Last read byte count */
+    ssize_t  dbsz;      /* Block size */
+    u_int    flags;     /* ISCHR | ISPIPE | ISTAPE | ISSEEK | NOREAD | ISTRUNC */
+    const char *name;   /* Filename */
+    int      fd;        /* File descriptor */
+    off_t    offset;    /* Blocks to skip */
+    off_t    seek_offset; /* Sparse output offset */
+} IO;
+```
+
+Device type flags:
+
+| Flag | Value | Meaning |
+|------|-------|---------|
+| `ISCHR` | 0x01 | Character device |
+| `ISPIPE` | 0x02 | Pipe or socket |
+| `ISTAPE` | 0x04 | Tape device |
+| `ISSEEK` | 0x08 | Seekable |
+| `NOREAD` | 0x10 | Write-only (output opened without read) |
+| `ISTRUNC` | 0x20 | Truncatable |
+
+#### STAT Structure (Statistics)
+
+```c
+typedef struct {
+    uintmax_t in_full;   /* Full input blocks transferred */
+    uintmax_t in_part;   /* Partial input blocks */
+    uintmax_t out_full;  /* Full output blocks */
+    uintmax_t out_part;  /* Partial output blocks */
+    uintmax_t trunc;     /* Truncated records */
+    uintmax_t swab;      /* Odd-length swab blocks */
+    uintmax_t bytes;     /* Total bytes written */
+    struct timespec start; /* Start timestamp */
+} STAT;
+```
+
+#### Conversion Flags
+
+The `ddflags` global is a 64-bit bitmask with 37 defined flags:
+
+```c
+#define C_ASCII       0x0000000000000001ULL
+#define C_BLOCK       0x0000000000000002ULL
+#define C_BS          0x0000000000000004ULL
+/* ... 34 more flags ... */
+#define C_IDIRECT     0x0000000800000000ULL
+#define C_ODIRECT     0x0000001000000000ULL
+```
+
+### Argument Parsing (args.c)
+
+`dd` uses its own JCL-style parser instead of `getopt`:
+
+```c
+static const struct arg {
+    const char *name;
+    void (*f)(char *);
+    uint64_t set, noset;
+} args[] = {
+    { "bs",       f_bs,       C_BS,    C_BS|C_IBS|C_OBS|C_OSYNC },
+    { "cbs",      f_cbs,      C_CBS,   C_CBS },
+    { "conv",     f_conv,     0,       0 },
+    { "count",    f_count,    C_COUNT, C_COUNT },
+    { "files",    f_files,    C_FILES, C_FILES },
+    { "fillchar", f_fillchar, C_FILL,  C_FILL },
+    { "ibs",      f_ibs,      C_IBS,   C_BS|C_IBS },
+    { "if",       f_if,       C_IF,    C_IF },
+    { "iflag",    f_iflag,    0,       0 },
+    { "obs",      f_obs,      C_OBS,   C_BS|C_OBS },
+    { "of",       f_of,       C_OF,    C_OF },
+    { "oflag",    f_oflag,    0,       0 },
+    { "seek",     f_seek,     C_SEEK,  C_SEEK },
+    { "skip",     f_skip,     C_SKIP,  C_SKIP },
+    { "speed",    f_speed,    0,       0 },
+    { "status",   f_status,   C_STATUS,C_STATUS },
+};
+```
+
+Arguments are looked up via `bsearch()` in the sorted table.
+
+The `noset` field prevents conflicting options: e.g., `bs=` sets
+`C_BS|C_IBS|C_OBS|C_OSYNC` and forbids re-specifying any of those.
+
+### Conversion Functions (conv.c)
+
+Three conversion modes:
+
+#### `def()` — Default (No Conversion)
+
+```c
+void def(void)
+{
+    if ((t = ctab) != NULL)
+        for (inp = in.dbp - (cnt = in.dbrcnt); cnt--; ++inp)
+            *inp = t[*inp];
+
+    out.dbp = in.dbp;
+    out.dbcnt = in.dbcnt;
+
+    if (in.dbcnt >= out.dbsz)
+        dd_out(0);
+}
+```
+
+Simple buffer pass-through with optional character table translation.
+
+#### `block()` — Variable → Fixed Length
+
+Converts newline-terminated records to fixed-length records padded with
+spaces to `cbs` bytes. Used for ASCII-to-EBCDIC record conversion.
+
+#### `unblock()` — Fixed → Variable Length
+
+Converts fixed-length records back to newline-terminated format by
+stripping trailing spaces and appending newlines.
+
+### Signal Handling (gen.c)
+
+`dd` handles several signals:
+
+| Signal | Handler | Purpose |
+|--------|---------|---------|
+| SIGINFO/SIGUSR1 | `siginfo_handler()` | Print transfer summary |
+| SIGALRM | `sigalarm_handler()` | Periodic progress (with `status=progress`) |
+| SIGINT/SIGTERM | Default + atexit | Print summary before exit |
+
+The `prepare_io()`, `before_io()`, `after_io()` functions manage signal
+masking during I/O operations to prevent interruption during critical
+sections.
+
+```c
+volatile sig_atomic_t need_summary;   /* Set by SIGINFO */
+volatile sig_atomic_t need_progress;  /* Set by SIGALRM */
+volatile sig_atomic_t kill_signal;    /* Set by termination signals */
+```
+
+### Progress Reporting (misc.c)
+
+```c
+void summary(void)
+{
+    /* Print: "X+Y records in\nA+B records out\nN bytes transferred in T secs" */
+    double elapsed = secs_elapsed();
+    /* Print human-readable transfer rate */
+}
+```
+
+The `format_scaled()` helper renders byte counts in human-readable form
+(kB, MB, GB) using configurable base (1000 or 1024).
+
+### Buffer Allocation
+
+Direct I/O requires page-aligned buffers:
+
+```c
+static void *
+alloc_io_buffer(size_t size)
+{
+    if ((ddflags & (C_IDIRECT | C_ODIRECT)) == 0)
+        return malloc(size);
+
+    size_t alignment = sysconf(_SC_PAGESIZE);
+    if (alignment == 0 || alignment == (size_t)-1)
+        alignment = 4096;
+    void *buf;
+    posix_memalign(&buf, alignment, size);
+    return buf;
+}
+```
+
+### Sparse Output
+
+With `conv=sparse`, `dd` uses `lseek(2)` to skip over blocks of zeros
+instead of writing them:
+
+```c
+#define BISZERO(p, s) ((s) > 0 && *((const char *)p) == 0 && \
+    !memcmp((const void *)(p), (const void *)((const char *)p + 1), (s) - 1))
+```
+
+### Setup and I/O
+
+The `setup()` function in `dd.c` handles:
+
+1. Opening input/output files with appropriate flags
+2. Detecting device types (`getfdtype()`)
+3. Allocating I/O buffers
+4. Setting up character conversion tables (parity, case)
+5. Positioning input/output streams
+6. Truncating output if needed
+
+```c
+static void setup(void)
+{
+    /* Open input */
+    if (in.name == NULL) {
+        in.name = "stdin";
+        in.fd = STDIN_FILENO;
+    } else {
+        iflags = (ddflags & C_IDIRECT) ? O_DIRECT : 0;
+        in.fd = open(in.name, O_RDONLY | iflags, 0);
+    }
+
+    /* Open output */
+    oflags = O_CREAT;
+    if (!(ddflags & (C_SEEK | C_NOTRUNC)))
+        oflags |= O_TRUNC;
+    if (ddflags & C_OFSYNC)
+        oflags |= O_SYNC;
+    if (ddflags & C_ODIRECT)
+        oflags |= O_DIRECT;
+    out.fd = open(out.name, O_RDWR | oflags, DEFFILEMODE);
+
+    /* Allocate buffers */
+    if (!(ddflags & (C_BLOCK | C_UNBLOCK))) {
+        in.db = alloc_io_buffer(out.dbsz + in.dbsz - 1);
+        out.db = in.db;  /* Single shared buffer */
+    } else {
+        in.db = alloc_io_buffer(MAX(in.dbsz, cbsz) + cbsz);
+        out.db = alloc_io_buffer(out.dbsz + cbsz);
+    }
+}
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `open(2)` | Open input/output files |
+| `read(2)` | Read input blocks |
+| `write(2)` | Write output blocks |
+| `lseek(2)` | Position streams, sparse output |
+| `ftruncate(2)` | Truncate output file |
+| `close(2)` | Close file descriptors |
+| `ioctl(2)` | Tape device queries (`MTIOCGET`) |
+| `sigaction(2)` | Install signal handlers |
+| `setitimer(2)` | Periodic SIGALRM for progress |
+| `clock_gettime(2)` | Elapsed time calculation |
+| `posix_memalign(3)` | Page-aligned buffers for direct I/O |
+| `sysconf(3)` | Get page size |
+
+## Examples
+
+```sh
+# Copy a disk image
+dd if=/dev/sda of=disk.img bs=4M status=progress
+
+# Write an image to a device
+dd if=image.iso of=/dev/sdb bs=4M conv=fsync
+
+# Create a 1GB sparse file
+dd if=/dev/zero of=sparse.img bs=1 count=0 seek=1G
+
+# Convert ASCII to uppercase
+dd if=input.txt of=output.txt conv=ucase
+
+# Copy with direct I/O
+dd if=data.bin of=data2.bin bs=4k iflag=direct oflag=direct
+
+# Network transfer (with throttling)
+dd if=large_file.tar bs=1M speed=10M | ssh remote 'dd of=large_file.tar'
+
+# Skip first 100 blocks of input
+dd if=tape.raw of=data.bin skip=100 bs=512
+
+# Show progress with SIGUSR1
+dd if=/dev/sda of=backup.img bs=1M &
+kill -USR1 $!
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success |
+| 1    | Error (open, read, write, or conversion failure) |
+
+## Summary Output Format
+
+```
+X+Y records in
+A+B records out
+N bytes (H) transferred in T.TTT secs (R/s)
+```
+
+Where:
+- `X` = full input blocks, `Y` = partial input blocks
+- `A` = full output blocks, `B` = partial output blocks
+- `N` = total bytes, `H` = human-readable size
+- `T` = elapsed seconds, `R` = transfer rate
diff --git a/docs/handbook/corebinutils/df.md b/docs/handbook/corebinutils/df.md
new file mode 100644
index 0000000000..c7b364f3e0
--- /dev/null
+++ b/docs/handbook/corebinutils/df.md
@@ -0,0 +1,264 @@
+# df — Display Filesystem Space Usage
+
+## Overview
+
+`df` reports total, used, and available disk space for mounted filesystems.
+It supports multiple output formats (POSIX, human-readable, SI), filesystem
+type filtering, inode display, and Linux-native mount information parsing.
+
+**Source**: `df/df.c` (single file, 100+ functions)
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+df [-abcgHhiklmPTtx] [-t type] [file ...]
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-a` | Show all filesystems including zero-size ones |
+| `-b` | Display sizes in 512-byte blocks |
+| `-c` | Print total line at end |
+| `-g` | Display sizes in gigabytes |
+| `-H` | Human-readable with SI units (1000-based) |
+| `-h` | Human-readable with binary units (1024-based) |
+| `-i` | Show inode information instead of block usage |
+| `-k` | Display sizes in kilobytes |
+| `-l` | Show only local (non-remote) filesystems |
+| `-m` | Display sizes in megabytes |
+| `-P` | POSIX output format (one line per filesystem) |
+| `-T` | Show filesystem type column |
+| `-t type` | Filter to specified filesystem type |
+| `-x` | Exclude specified filesystem type |
+| `,` | Use thousands separator in output |
+
+## Source Analysis
+
+### Key Data Structures
+
+```c
+struct options {
+    bool show_all;
+    bool show_inodes;
+    bool show_type;
+    bool posix_format;
+    bool human_readable;
+    bool si_units;
+    bool local_only;
+    bool show_total;
+    bool thousands_separator;
+    /* block size settings from -b/-k/-m/-g or BLOCKSIZE env */
+};
+
+struct mount_entry {
+    char *source;         /* Device path (/dev/sda1) */
+    char *target;         /* Mount point (/home) */
+    char *fstype;         /* Filesystem type (ext4, tmpfs) */
+    char *options;        /* Mount options (rw,noatime) */
+    dev_t device;         /* Device number */
+};
+
+struct mount_table {
+    struct mount_entry *entries;
+    size_t count;
+    size_t capacity;
+};
+
+struct row {
+    char *filesystem;     /* Formatted filesystem column */
+    char *type;           /* Filesystem type */
+    char *size;           /* Total size */
+    char *used;           /* Used space */
+    char *avail;          /* Available space */
+    char *capacity;       /* Percentage used */
+    char *mount_point;    /* Mount point path */
+    char *iused;          /* Inodes used */
+    char *ifree;          /* Inodes free */
+};
+
+struct column_widths {
+    int filesystem;
+    int type;
+    int size;
+    int used;
+    int avail;
+    int capacity;
+    int mount_point;
+};
+```
+
+### Linux-Native Mount Parsing
+
+Unlike BSD which uses `getmntinfo(3)` / `statfs(2)`, this port reads
+`/proc/self/mountinfo` directly:
+
+```c
+static int
+parse_mountinfo(struct mount_table *table)
+{
+    FILE *fp = fopen("/proc/self/mountinfo", "r");
+    /* Parse each line:
+     * ID PARENT_ID MAJOR:MINOR ROOT MOUNT_POINT OPTIONS ... - FSTYPE SOURCE SUPER_OPTIONS
+     */
+    while (getline(&line, &linesz, fp) != -1) {
+        /* Extract fields, unescape special characters */
+        entry.source = unescape_mountinfo(source_str);
+        entry.target = unescape_mountinfo(target_str);
+        entry.fstype = strdup(fstype_str);
+    }
+}
+```
+
+#### Escape Handling
+
+Mount paths in `/proc/self/mountinfo` use octal escapes for special
+characters (spaces, newlines, backslashes):
+
+```c
+static char *
+unescape_mountinfo(const char *text)
+{
+    /* Convert \040 → space, \011 → tab, \012 → newline, \134 → backslash */
+}
+```
+
+### Filesystem Stats
+
+`df` uses `statvfs(2)` instead of BSD's `statfs(2)`:
+
+```c
+struct statvfs sv;
+if (statvfs(mount_point, &sv) != 0)
+    return -1;
+
+total_blocks = sv.f_blocks;
+free_blocks  = sv.f_bfree;
+avail_blocks = sv.f_bavail;  /* Available to unprivileged users */
+block_size   = sv.f_frsize;
+
+total_inodes = sv.f_files;
+free_inodes  = sv.f_ffree;
+```
+
+### Remote Filesystem Detection
+
+The `-l` (local only) flag requires distinguishing local from remote
+filesystems:
+
+```c
+static bool
+is_remote_filesystem(const struct mount_entry *entry)
+{
+    /* Check filesystem type */
+    if (strcmp(entry->fstype, "nfs") == 0 ||
+        strcmp(entry->fstype, "nfs4") == 0 ||
+        strcmp(entry->fstype, "cifs") == 0 ||
+        strcmp(entry->fstype, "smbfs") == 0 ||
+        strcmp(entry->fstype, "fuse.sshfs") == 0)
+        return true;
+
+    /* Check source for remote indicators (host:path or //host/share) */
+    if (strchr(entry->source, ':') != NULL)
+        return true;
+    if (entry->source[0] == '/' && entry->source[1] == '/')
+        return true;
+
+    return false;
+}
+```
+
+### Human-Readable Formatting
+
+```c
+static char *
+format_human_readable(uint64_t bytes, bool si)
+{
+    unsigned int base = si ? 1000 : 1024;
+    const char *const *units = si ? si_units : binary_units;
+    /* Scale and format: "1.5G", "234M", "45K" */
+}
+```
+
+### BLOCKSIZE Environment
+
+The `BLOCKSIZE` environment variable can override the default block size:
+
+```c
+char *bs = getenv("BLOCKSIZE");
+if (bs != NULL) {
+    /* Parse: "512", "K", "M", "G", or "1k", "4k", etc. */
+}
+```
+
+### Safe Integer Arithmetic
+
+`df` performs arithmetic with overflow protection:
+
+```c
+/* Safe multiplication with clamping */
+static uint64_t
+safe_mul(uint64_t a, uint64_t b)
+{
+    if (a != 0 && b > UINT64_MAX / a)
+        return UINT64_MAX;  /* Clamp instead of overflow */
+    return a * b;
+}
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `statvfs(2)` | Query filesystem statistics |
+| `stat(2)` | Identify filesystem for file arguments |
+| `open(2)` / `read(2)` | Parse `/proc/self/mountinfo` |
+
+## Examples
+
+```sh
+# Default output
+df
+
+# Human-readable sizes
+df -h
+
+# Show filesystem type
+df -hT
+
+# Only local filesystems
+df -hl
+
+# POSIX format
+df -P
+
+# Inode usage
+df -i
+
+# Specific filesystem
+df /home
+
+# Total line
+df -hc
+
+# Specific filesystem type
+df -t ext4
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success |
+| 1    | Error accessing filesystem |
+
+## Differences from GNU df
+
+- Uses `/proc/self/mountinfo` directly (no libmount)
+- No `--output` for custom column selection
+- `-c` for total line (GNU uses `--total`)
+- BLOCKSIZE env var compatibility (BSD convention)
+- No `--sync` / `--no-sync` options
diff --git a/docs/handbook/corebinutils/echo.md b/docs/handbook/corebinutils/echo.md
new file mode 100644
index 0000000000..da7df16cec
--- /dev/null
+++ b/docs/handbook/corebinutils/echo.md
@@ -0,0 +1,158 @@
+# echo — Write Arguments to Standard Output
+
+## Overview
+
+`echo` writes its arguments to standard output, separated by spaces, followed
+by a newline. It is intentionally minimal — the FreeBSD/BSD implementation
+does not support GNU-style `-e` escape processing.
+
+**Source**: `echo/echo.c` (single file)
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+echo [-n] [string ...]
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-n` | Suppress trailing newline |
+
+Only a leading `-n` is recognized as an option. Any other arguments
+(including `--`) are treated as literal strings and printed.
+
+## Source Analysis
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Parse arguments and write output |
+| `write_all()` | Retry-safe `write(2)` loop handling `EINTR` |
+| `warn_errno()` | Error reporting to stderr |
+| `trim_trailing_backslash_c()` | Check if final argument ends with `\c` |
+
+### Option Processing
+
+`echo` does NOT use `getopt(3)`. It manually checks for `-n`:
+
+```c
+int main(int argc, char *argv[])
+{
+    bool suppress_newline = false;
+
+    argv++;  /* Skip program name */
+
+    /* Only leading -n flags are consumed */
+    while (*argv && strcmp(*argv, "-n") == 0) {
+        suppress_newline = true;
+        argv++;
+    }
+
+    /* Everything else is literal output */
+}
+```
+
+### The `\c` Convention
+
+If the **last** argument ends with `\c`, the trailing newline is suppressed
+and the `\c` itself is not printed:
+
+```c
+static bool
+trim_trailing_backslash_c(const char *arg, size_t *len)
+{
+    if (*len >= 2 && arg[*len - 2] == '\\' && arg[*len - 1] == 'c') {
+        *len -= 2;
+        return true;  /* Suppress newline */
+    }
+    return false;
+}
+```
+
+### I/O Strategy
+
+Instead of `printf` or `writev`, echo uses a `write(2)` loop:
+
+```c
+static int
+write_all(int fd, const void *buf, size_t count)
+{
+    const char *p = buf;
+    ssize_t n;
+
+    while (count > 0) {
+        n = write(fd, p, count);
+        if (n < 0) {
+            if (errno == EINTR)
+                continue;
+            return -1;
+        }
+        p += n;
+        count -= n;
+    }
+    return 0;
+}
+```
+
+This avoids `IOV_MAX` limitations that would apply with `writev(2)` when
+there are many arguments.
+
+### Key Behaviors
+
+| Input | Output | Notes |
+|-------|--------|-------|
+| `echo hello` | `hello\n` | Basic usage |
+| `echo -n hello` | `hello` | No trailing newline |
+| `echo -n -n hello` | `hello` | Multiple `-n` consumed |
+| `echo -- hello` | `-- hello\n` | `--` is NOT end-of-options |
+| `echo -e hello` | `-e hello\n` | `-e` is NOT recognized |
+| `echo "hello\c"` | `hello` | `\c` suppresses newline |
+| `echo ""` | `\n` | Empty string → just newline |
+
+## Portability Notes
+
+- **BSD echo** (this implementation): Only `-n` and trailing `\c`
+- **GNU echo**: Supports `-e` for escape sequences (`\n`, `\t`, etc.)
+  and `-E` to disable them
+- **POSIX echo**: Behavior of `-n` and backslash sequences is
+  implementation-defined
+- **Shell built-in**: Most shells have a built-in `echo` that may differ
+  from the external command
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `write(2)` | All output to stdout |
+
+## Examples
+
+```sh
+# Simple output
+echo Hello, World!
+
+# No trailing newline
+echo -n "prompt> "
+
+# Literal dash-n (only leading -n is recognized)
+echo "The flag is -n"
+
+# Multiple arguments
+echo one two three
+# → "one two three"
+
+# Suppress newline with \c
+echo "no newline\c"
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success |
+| 1    | Write error |
diff --git a/docs/handbook/corebinutils/ed.md b/docs/handbook/corebinutils/ed.md
new file mode 100644
index 0000000000..3e51e576b6
--- /dev/null
+++ b/docs/handbook/corebinutils/ed.md
@@ -0,0 +1,306 @@
+# ed — Line Editor
+
+## Overview
+
+`ed` is the standard POSIX line editor. It operates on a text buffer that
+resides in a temporary scratch file, supports regular expression search and
+substitution, global commands, undo, and file I/O. This implementation derives
+from Andrew Moore's BSD `ed` and the algorithm described in Kernighan and
+Plauger's *Software Tools in Pascal*.
+
+**Source**: `ed/main.c`, `ed/ed.h`, `ed/compat.c`, `ed/compat.h`, `ed/buf.c`,
+`ed/glbl.c`, `ed/io.c`, `ed/re.c`, `ed/sub.c`, `ed/undo.c`
+**Origin**: BSD 4.4, Andrew Moore (Talke Studio)
+**License**: BSD-2-Clause
+
+## Synopsis
+
+```
+ed [-] [-sx] [-p string] [file]
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-` | Suppress diagnostics (same as `-s`) |
+| `-s` | Script mode: suppress byte counts and `!` prompts |
+| `-x` | Encryption mode (**not supported on Linux**) |
+| `-p string` | Set the command prompt (default: no prompt) |
+
+## Source Architecture
+
+### File Responsibilities
+
+| File | Purpose | Key Functions |
+|------|---------|---------------|
+| `main.c` | Main loop, command dispatch, signals | `main()`, `exec_command()`, signal handlers |
+| `ed.h` | Types, constants, function prototypes | `line_t`, `undo_t`, error codes |
+| `compat.c/h` | Linux portability shims | `strlcpy`, `strlcat` replacements |
+| `buf.c` | Scratch file buffer management | `get_sbuf_line()`, `put_sbuf_line()` |
+| `glbl.c` | Global command (g/re/cmd) | `exec_global()`, mark management |
+| `io.c` | File I/O (read/write) | `read_file()`, `write_file()`, `read_stream()` |
+| `re.c` | Regular expression handling | `get_compiled_pattern()`, `search_*()` |
+| `sub.c` | Substitution command | `substitute()`, replacement parsing |
+| `undo.c` | Undo stack management | `push_undo_stack()`, `undo_last()` |
+
+### Key Data Structures
+
+#### Line Node (linked list element)
+
+```c
+typedef struct line {
+    struct line *q_forw;   /* Next line in buffer */
+    struct line *q_back;   /* Previous line in buffer */
+    off_t        seek;     /* Byte offset in scratch file */
+    int          len;      /* Line length */
+} line_t;
+```
+
+The edit buffer is a doubly-linked circular list of `line_t` nodes. Line
+content is stored in an external scratch file, not in memory.
+
+#### Undo Record
+
+```c
+typedef struct undo {
+    int type;              /* UADD, UDEL, UMOV, VMOV */
+    line_t *h;             /* Head of affected line range */
+    line_t *t;             /* Tail of affected line range */
+    /* ... */
+} undo_t;
+```
+
+#### Constants
+
+```c
+#define ERR   (-2)    /* General error */
+#define EMOD  (-3)    /* Buffer modified warning */
+#define FATAL (-4)    /* Fatal error (abort) */
+
+#define MINBUFSZ 512
+#define SE_MAX   30   /* Max regex subexpressions */
+#define LINECHARS INT_MAX
+```
+
+#### Global Flags
+
+```c
+#define GLB  001   /* Global command active */
+#define GPR  002   /* Print after command */
+#define GLS  004   /* List after command */
+#define GNP  010   /* Enumerate after command */
+#define GSG  020   /* Global substitute */
+```
+
+### Main Loop
+
+```c
+int main(volatile int argc, char **volatile argv)
+{
+    setlocale(LC_ALL, "");
+
+    /* Detect if invoked as "red" (restricted ed) */
+    red = (n = strlen(argv[0])) > 2 && argv[0][n - 3] == 'r';
+
+    /* Parse options */
+    while ((c = getopt(argc, argv, "p:sx")) != -1) { ... }
+
+    /* Signal setup */
+    signal(SIGHUP, signal_hup);    /* Emergency save */
+    signal(SIGQUIT, SIG_IGN);      /* Ignore quit */
+    signal(SIGINT, signal_int);    /* Interrupt handling */
+    signal(SIGWINCH, handle_winch); /* Terminal resize */
+
+    /* Initialize buffers, load file if specified */
+    init_buffers();
+    if (argc && is_legal_filename(*argv))
+        read_file(*argv, 0);
+
+    /* Command loop */
+    for (;;) {
+        if (prompt) fputs(prompt, stdout);
+        status = get_tty_line();
+        if (status == EOF) break;
+        status = exec_command();
+    }
+}
+```
+
+### Buffer Management (buf.c)
+
+The scratch file strategy avoids unlimited memory consumption:
+
+- Lines are stored in a temporary file created with `mkstemp(3)`
+- `put_sbuf_line()` appends a line to the scratch file and returns its offset
+- `get_sbuf_line()` reads a line back from the scratch file by offset
+- The `line_t` linked list tracks offsets and lengths, not actual text
+
+```c
+/* Append line to scratch file, return its node */
+line_t *put_sbuf_line(const char *text);
+
+/* Read line from scratch file via offset */
+char *get_sbuf_line(const line_t *lp);
+```
+
+### File I/O (io.c)
+
+```c
+long read_file(char *fn, long n)
+{
+    /* Open file or pipe (if fn starts with '!') */
+    fp = (*fn == '!') ? popen(fn + 1, "r") : fopen(strip_escapes(fn), "r");
+
+    /* Read lines into buffer after line n */
+    size = read_stream(fp, n);
+
+    /* Print byte count unless in script mode */
+    if (!scripted)
+        fprintf(stdout, "%lu\n", size);
+}
+```
+
+The `read_stream()` function reads from `fp`, appending each line to the
+edit buffer via `put_sbuf_line()`, and maintaining the undo stack for
+rollback.
+
+### Regular Expressions (re.c)
+
+Uses POSIX `regex.h` (via `regcomp(3)` / `regexec(3)`):
+
+```c
+typedef regex_t pattern_t;
+
+pattern_t *get_compiled_pattern(void);
+/* Compiles the current regex pattern, caching the last used pattern */
+```
+
+### Substitution (sub.c)
+
+The `s/pattern/replacement/flags` command:
+- Supports `\1` through `\9` backreferences
+- `g` flag for global replacement
+- Count for nth occurrence replacement
+- `&` in replacement refers to the matched text
+
+### Undo (undo.c)
+
+Every buffer modification pushes an undo record:
+
+```c
+undo_t *push_undo_stack(int type, long from, long to);
+int undo_last(void);   /* Reverse last modification */
+```
+
+Undo types: `UADD` (lines added), `UDEL` (lines deleted), `UMOV` (lines moved).
+
+### Signal Handling
+
+| Signal | Handler | Action |
+|--------|---------|--------|
+| `SIGHUP` | `signal_hup()` | Save buffer to `ed.hup` and exit |
+| `SIGINT` | `signal_int()` | Set interrupt flag, longjmp to command prompt |
+| `SIGWINCH` | `handle_winch()` | Update terminal width for `l` command |
+| `SIGQUIT` | `SIG_IGN` | Ignored |
+
+### Restricted Mode (red)
+
+When invoked as `red`, the editor restricts:
+- Shell commands (`!command`) are forbidden
+- Filenames with `/` or starting with `!` are rejected
+- Directory changes are prevented
+
+## Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `(.)a` | Append text after line |
+| `(.)i` | Insert text before line |
+| `(.,.)c` | Change (replace) lines |
+| `(.,.)d` | Delete lines |
+| `(.,.)p` | Print lines |
+| `(.,.)l` | List lines (show non-printable characters) |
+| `(.,.)n` | Number and print lines |
+| `(.,.)m(.)` | Move lines |
+| `(.,.)t(.)` | Copy (transfer) lines |
+| `(.,.)s/re/replacement/flags` | Substitute |
+| `(.,.)g/re/command` | Global: apply command to matching lines |
+| `(.,.)v/re/command` | Inverse global: apply to non-matching lines |
+| `(.,.)w file` | Write lines to file |
+| `(.,.)W file` | Append lines to file |
+| `e file` | Edit file (replaces buffer) |
+| `E file` | Edit unconditionally |
+| `f file` | Set default filename |
+| `r file` | Read file into buffer |
+| `(.)r !command` | Read command output into buffer |
+| `u` | Undo last command |
+| `(.)=` | Print line number |
+| `(.,.)j` | Join lines |
+| `(.)k(c)` | Mark line with character c |
+| `q` | Quit (warns if modified) |
+| `Q` | Quit unconditionally |
+| `H` | Toggle verbose error messages |
+| `h` | Print last error message |
+| `!command` | Execute shell command |
+
+### Addressing
+
+| Address | Meaning |
+|---------|---------|
+| `.` | Current line |
+| `$` | Last line |
+| `n` | Line number n |
+| `-n` / `+n` | Relative to current line |
+| `/re/` | Next line matching regex |
+| `?re?` | Previous line matching regex |
+| `'c` | Line marked with character c |
+| `,` | Equivalent to `1,$` |
+| `;` | Equivalent to `.,$` |
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `mkstemp(3)` | Create scratch file |
+| `read(2)` / `write(2)` | Scratch file I/O |
+| `lseek(2)` | Position in scratch file |
+| `fopen(3)` / `fclose(3)` | Read/write user files |
+| `popen(3)` / `pclose(3)` | Shell command execution |
+| `regcomp(3)` / `regexec(3)` | Regular expression matching |
+| `sigsetjmp(3)` / `siglongjmp(3)` | Interrupt recovery |
+
+## Examples
+
+```sh
+# Edit a file
+ed myfile.txt
+
+# Script mode (for automation)
+printf '1,3p\nq\n' | ed -s myfile.txt
+
+# Global substitution
+printf 'g/old/s//new/g\nw\nq\n' | ed -s myfile.txt
+
+# With prompt
+ed -p '> ' myfile.txt
+
+# Read from pipe
+echo '!ls -la' | ed
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success |
+| 1    | Error |
+| 2    | Usage error |
+
+## Linux-Specific Notes
+
+- The `-x` (encryption) option prints an error and exits, as Linux
+  does not provide the BSD `des_setkey(3)` functions.
+- `strlcpy(3)` / `strlcat(3)` are provided by `compat.c` when not
+  available in the system libc.
+- The `SIGWINCH` handler uses `ioctl(TIOCGWINSZ)` for terminal size.
diff --git a/docs/handbook/corebinutils/error-handling.md b/docs/handbook/corebinutils/error-handling.md
new file mode 100644
index 0000000000..f82eec0b1c
--- /dev/null
+++ b/docs/handbook/corebinutils/error-handling.md
@@ -0,0 +1,315 @@
+# Error Handling — Corebinutils Patterns
+
+## Overview
+
+Corebinutils uses a layered error handling strategy: BSD `err(3)` functions
+as the primary interface, custom `error_errno()`/`error_msg()` wrappers in
+utilities that need more control, and consistent exit codes following
+POSIX conventions.
+
+## err(3) Family
+
+The BSD `<err.h>` functions are used throughout:
+
+```c
+#include <err.h>
+
+/* Fatal errors (print message + errno + exit) */
+err(1, "open '%s'", filename);
+/* → "utility: open 'file.txt': No such file or directory\n" */
+
+/* Fatal errors (print message + exit, no errno) */
+errx(2, "invalid option: -%c", ch);
+/* → "utility: invalid option: -z\n" */
+
+/* Non-fatal warnings (print message + errno, continue) */
+warn("stat '%s'", filename);
+/* → "utility: stat 'file.txt': Permission denied\n" */
+
+/* Non-fatal warnings (print message, no errno, continue) */
+warnx("skipping '%s': not a regular file", filename);
+/* → "utility: skipping 'foo': not a regular file\n" */
+```
+
+### When to Use Each
+
+| Function | Fatal? | Shows errno? | Use Case |
+|----------|--------|-------------|----------|
+| `err()` | Yes | Yes | Syscall failure, must exit |
+| `errx()` | Yes | No | Bad input, usage error |
+| `warn()` | No | Yes | Syscall failure, can continue |
+| `warnx()` | No | No | Validation issue, can continue |
+
+## Custom Error Functions
+
+Several utilities define their own error reporting for program name
+control or additional formatting:
+
+### Pattern: error_errno / error_msg
+
+```c
+static const char *progname;
+
+static void
+error_errno(const char *fmt, ...)
+{
+    int saved_errno = errno;
+    va_list ap;
+
+    fprintf(stderr, "%s: ", progname);
+    va_start(ap, fmt);
+    vfprintf(stderr, fmt, ap);
+    va_end(ap);
+    fprintf(stderr, ": %s\n", strerror(saved_errno));
+}
+
+static void
+error_msg(const char *fmt, ...)
+{
+    va_list ap;
+
+    fprintf(stderr, "%s: ", progname);
+    va_start(ap, fmt);
+    vfprintf(stderr, fmt, ap);
+    va_end(ap);
+    fputc('\n', stderr);
+}
+```
+
+Used by: `mkdir`, `chmod`, `hostname`, `domainname`, `nproc`
+
+### Pattern: die / die_errno
+
+```c
+static void __dead2
+die(const char *fmt, ...)
+{
+    va_list ap;
+    fprintf(stderr, "%s: ", progname);
+    va_start(ap, fmt);
+    vfprintf(stderr, fmt, ap);
+    va_end(ap);
+    fputc('\n', stderr);
+    exit(1);
+}
+
+static void __dead2
+die_errno(const char *fmt, ...)
+{
+    int saved = errno;
+    va_list ap;
+    fprintf(stderr, "%s: ", progname);
+    va_start(ap, fmt);
+    vfprintf(stderr, fmt, ap);
+    va_end(ap);
+    fprintf(stderr, ": %s\n", strerror(saved));
+    exit(1);
+}
+```
+
+Used by: `sleep`, `echo`
+
+### Pattern: verror_message (centralized)
+
+```c
+static void
+verror_message(const char *fmt, va_list ap, bool with_errno)
+{
+    int saved = errno;
+    fprintf(stderr, "%s: ", progname);
+    vfprintf(stderr, fmt, ap);
+    if (with_errno)
+        fprintf(stderr, ": %s", strerror(saved));
+    fputc('\n', stderr);
+}
+```
+
+## Exit Code Conventions
+
+### Standard Codes
+
+| Code | Meaning | Used By |
+|------|---------|---------|
+| 0 | Success | All utilities |
+| 1 | General error | Most utilities |
+| 2 | Usage/syntax error | test, expr, timeout, mv |
+
+### Utility-Specific Codes
+
+| Utility | Code | Meaning |
+|---------|------|---------|
+| `test` | 0 | Expression is true |
+| `test` | 1 | Expression is false |
+| `test` | 2 | Invalid expression |
+| `expr` | 0 | Non-null, non-zero result |
+| `expr` | 1 | Null or zero result |
+| `expr` | 2 | Invalid expression |
+| `expr` | 3 | Internal error |
+| `timeout` | 124 | Command timed out |
+| `timeout` | 125 | `timeout` itself failed |
+| `timeout` | 126 | Command not executable |
+| `timeout` | 127 | Command not found |
+
+### Exit on First Error vs. Accumulate
+
+Two patterns are observed:
+
+```c
+/* Pattern 1: Exit immediately on error */
+if (stat(path, &sb) < 0)
+    err(1, "stat");
+
+/* Pattern 2: Accumulate errors, exit with status */
+int errors = 0;
+for (i = 0; i < argc; i++) {
+    if (process(argv[i]) < 0) {
+        warn("failed: %s", argv[i]);
+        errors = 1;
+    }
+}
+return errors;
+```
+
+Pattern 2 is used by multi-argument utilities (rm, chmod, cp, ln)
+to process as many arguments as possible even when some fail.
+
+## errno Preservation
+
+All error functions save `errno` before calling any function that
+might modify it (like `fprintf`):
+
+```c
+static void
+error_errno(const char *fmt, ...)
+{
+    int saved = errno;   /* Save before fprintf */
+    /* ... */
+    fprintf(stderr, ": %s\n", strerror(saved));
+}
+```
+
+## Signal Error Recovery
+
+### sigsetjmp/siglongjmp (ed)
+
+```c
+static sigjmp_buf jmpbuf;
+
+static void
+signal_handler(int sig)
+{
+    (void)sig;
+    siglongjmp(jmpbuf, 1);
+}
+
+/* In main loop */
+if (sigsetjmp(jmpbuf, 1) != 0) {
+    /* Returned from signal — reset state */
+    fputs("?\n", stderr);
+}
+```
+
+### Flag-Based (sleep, dd)
+
+```c
+static volatile sig_atomic_t got_signal;
+
+static void
+handler(int sig)
+{
+    got_signal = sig;
+}
+
+/* In main loop */
+if (got_signal) {
+    cleanup();
+    exit(128 + got_signal);
+}
+```
+
+## Validation Patterns
+
+### At System Boundaries
+
+```c
+/* Validate user input */
+if (argc < 2) {
+    usage();
+    /* NOTREACHED */
+}
+
+/* Validate parsed values */
+if (val < 0 || val > MAX_VALUE)
+    errx(2, "value out of range: %ld", val);
+
+/* Validate system call results */
+if (open(path, O_RDONLY) < 0)
+    err(1, "open");
+```
+
+### String-to-Number Conversion
+
+```c
+static long
+parse_number(const char *str)
+{
+    char *end;
+    errno = 0;
+    long val = strtol(str, &end, 10);
+
+    if (end == str || *end != '\0')
+        errx(2, "not a number: %s", str);
+    if (errno == ERANGE)
+        errx(2, "number out of range: %s", str);
+
+    return val;
+}
+```
+
+## Write Error Detection
+
+### Pattern: Check stdout at exit
+
+```c
+/* Catch write errors (e.g., broken pipe) */
+if (fclose(stdout) == EOF)
+    err(1, "stdout");
+
+/* Or equivalently */
+if (fflush(stdout) == EOF)
+    err(1, "write error");
+```
+
+### Pattern: write_all loop
+
+```c
+static int
+write_all(int fd, const void *buf, size_t count)
+{
+    const char *p = buf;
+    while (count > 0) {
+        ssize_t n = write(fd, p, count);
+        if (n < 0) {
+            if (errno == EINTR)
+                continue;
+            return -1;
+        }
+        p += n;
+        count -= n;
+    }
+    return 0;
+}
+```
+
+Used by: `echo`, `cat`, `dd`
+
+## Summary of Conventions
+
+1. Use `err(3)` family when available and sufficient
+2. Define custom wrappers only when program name control is needed
+3. Save `errno` immediately — before any library calls
+4. Exit 0 for success, 1 for errors, 2 for usage
+5. Multi-argument commands accumulate errors
+6. Validate at system boundaries (input parsing, syscall returns)
+7. Signal handlers set flags only — no complex logic
+8. Always check `write(2)` / `fclose(3)` return values
diff --git a/docs/handbook/corebinutils/expr.md b/docs/handbook/corebinutils/expr.md
new file mode 100644
index 0000000000..cd7e8a214c
--- /dev/null
+++ b/docs/handbook/corebinutils/expr.md
@@ -0,0 +1,194 @@
+# expr — Evaluate Expressions
+
+## Overview
+
+`expr` evaluates arithmetic, string, and logical expressions from the command
+line and writes the result to standard output. It implements a recursive
+descent parser with automatic type coercion between strings, numeric strings,
+and integers.
+
+**Source**: `expr/expr.c` (single file)
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+expr expression
+```
+
+## Source Analysis
+
+### Value Types
+
+```c
+enum value_type {
+    INTEGER,         /* Pure integer (from arithmetic) */
+    NUMERIC_STRING,  /* String that looks like a number */
+    STRING,          /* General string */
+};
+
+struct value {
+    enum value_type type;
+    union {
+        intmax_t ival;
+        char *sval;
+    };
+};
+```
+
+`expr` automatically coerces between types during operations. A value
+like `"42"` starts as `NUMERIC_STRING` and is promoted to `INTEGER` for
+arithmetic.
+
+### Parser Architecture
+
+`expr` uses a recursive descent parser with operator precedence:
+
+```
+parse_expr()
+  └── parse_or()         /* | operator (lowest precedence) */
+        └── parse_and()     /* & operator */
+              └── parse_compare() /* =, !=, <, >, <=, >= */
+                    └── parse_add()   /* +, - */
+                          └── parse_mul()   /* *, /, % */
+                                └── parse_primary() /* atoms, ( expr ), : regex */
+```
+
+### Operators
+
+#### Arithmetic Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `+` | Addition | `expr 2 + 3` → `5` |
+| `-` | Subtraction | `expr 5 - 2` → `3` |
+| `*` | Multiplication | `expr 4 \* 3` → `12` |
+| `/` | Integer division | `expr 10 / 3` → `3` |
+| `%` | Modulo | `expr 10 % 3` → `1` |
+
+#### Comparison Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `=` | Equal | `expr abc = abc` → `1` |
+| `!=` | Not equal | `expr abc != def` → `1` |
+| `<` | Less than | `expr 1 \< 2` → `1` |
+| `>` | Greater than | `expr 2 \> 1` → `1` |
+| `<=` | Less or equal | `expr 1 \<= 1` → `1` |
+| `>=` | Greater or equal | `expr 2 \>= 1` → `1` |
+
+Comparisons between numeric strings use numeric ordering; otherwise
+locale-aware string comparison (`strcoll`) is used.
+
+#### Logical Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `\|` | OR (short-circuit) | `expr 0 \| 5` → `5` |
+| `&` | AND (short-circuit) | `expr 1 \& 2` → `1` |
+
+#### String/Regex Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `:` | Regex match | `expr hello : 'hel\(.*\)'` → `lo` |
+| `match` | Same as `:` | `expr match hello 'h.*'` |
+| `substr` | Substring | `expr substr hello 2 3` → `ell` |
+| `index` | Character position | `expr index hello l` → `3` |
+| `length` | String length | `expr length hello` → `5` |
+
+### Regex Matching
+
+The `:` operator uses POSIX basic regular expressions (`regcomp` with
+`REG_NOSUB` or group capture):
+
+```c
+/* expr STRING : REGEX */
+/* Returns captured \(...\) group or match length */
+```
+
+If the regex contains `\(...\)`, the captured substring is returned.
+Otherwise, the length of the match is returned.
+
+### Overflow Checking
+
+All arithmetic operations check for integer overflow:
+
+```c
+static intmax_t
+safe_add(intmax_t a, intmax_t b)
+{
+    if ((b > 0 && a > INTMAX_MAX - b) ||
+        (b < 0 && a < INTMAX_MIN - b))
+        errx(2, "integer overflow");
+    return a + b;
+}
+```
+
+### Locale Awareness
+
+String comparisons use `strcoll(3)` for locale-correct ordering:
+
+```c
+/* Compare as strings using locale collation */
+result = strcoll(left->sval, right->sval);
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `regcomp(3)` / `regexec(3)` | Regular expression matching |
+| `strcoll(3)` | Locale-aware string comparison |
+
+## Examples
+
+```sh
+# Arithmetic
+expr 2 + 3           # → 5
+expr 10 / 3          # → 3
+expr 7 % 4           # → 3
+
+# String length
+expr length "hello"  # → 5
+
+# Regex match (capture group)
+expr "hello-world" : 'hello-\(.*\)'  # → world
+
+# Regex match (length)
+expr "hello" : '.*'  # → 5
+
+# Substring
+expr substr "hello" 2 3  # → ell
+
+# Index (first occurrence)
+expr index "hello" "lo"  # → 3
+
+# Comparisons
+expr 42 = 42   # → 1
+expr abc \< def  # → 1
+
+# Logical OR (returns first non-zero/non-empty)
+expr 0 \| 5    # → 5
+expr "" \| alt # → alt
+
+# In shell scripts
+count=$(expr $count + 1)
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Expression is neither null nor zero |
+| 1    | Expression is null or zero |
+| 2    | Expression is invalid |
+| 3    | Internal error |
+
+## Differences from GNU expr
+
+- No `--help` or `--version`
+- Identical POSIX semantics for `:` operator
+- Locale-aware string comparison by default
+- Overflow results in error, not wraparound
diff --git a/docs/handbook/corebinutils/hostname.md b/docs/handbook/corebinutils/hostname.md
new file mode 100644
index 0000000000..d6ea83bff2
--- /dev/null
+++ b/docs/handbook/corebinutils/hostname.md
@@ -0,0 +1,154 @@
+# hostname — Get or Set the System Hostname
+
+## Overview
+
+`hostname` reads or sets the system hostname. On Linux it uses `uname(2)` to
+read and `sethostname(2)` to write. The `-f` (FQDN) option is explicitly
+unsupported because resolving a fully qualified domain name requires
+NSS/DNS, which is outside the scope of a core utility.
+
+**Source**: `hostname/hostname.c` (single file)
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+hostname [-s | -d] [name-of-host]
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-s` | Print short hostname (truncate at first `.`) |
+| `-d` | Print domain part only (after first `.`) |
+| `-f` | **Not supported on Linux** — exits with error |
+
+## Source Analysis
+
+### Data Structures
+
+```c
+struct options {
+    bool short_name;    /* -s: truncate at first dot */
+    bool domain_only;   /* -d: print after first dot */
+    bool set_mode;      /* hostname was provided as argument */
+    const char *new_hostname;
+};
+```
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Dispatch between get/set modes |
+| `parse_args()` | `getopt(3)` option parsing |
+| `dup_hostname()` | Fetch hostname from `uname(2)` and duplicate it |
+| `print_hostname()` | Print full, short, or domain part |
+| `set_hostname()` | Set hostname via `sethostname(2)` |
+| `linux_hostname_max()` | Query max hostname length from UTS namespace |
+
+### Reading the Hostname
+
+```c
+static char *
+dup_hostname(void)
+{
+    struct utsname uts;
+
+    if (uname(&uts) < 0)
+        err(1, "uname");
+    return strdup(uts.nodename);
+}
+```
+
+### Setting the Hostname
+
+```c
+static void
+set_hostname(const char *name)
+{
+    size_t max_len = linux_hostname_max();
+    size_t len = strlen(name);
+
+    if (len > max_len)
+        errx(1, "hostname too long: %zu > %zu", len, max_len);
+
+    if (sethostname(name, len) < 0)
+        err(1, "sethostname");
+}
+```
+
+### Short/Domain Modes
+
+```c
+static void
+print_hostname(const char *hostname, const struct options *opts)
+{
+    if (opts->short_name) {
+        /* Truncate at first '.' */
+        const char *dot = strchr(hostname, '.');
+        if (dot)
+            printf("%.*s\n", (int)(dot - hostname), hostname);
+        else
+            puts(hostname);
+    } else if (opts->domain_only) {
+        /* Print after first '.' or empty */
+        const char *dot = strchr(hostname, '.');
+        puts(dot ? dot + 1 : "");
+    } else {
+        puts(hostname);
+    }
+}
+```
+
+### Max Hostname Length
+
+```c
+static size_t
+linux_hostname_max(void)
+{
+    long val = sysconf(_SC_HOST_NAME_MAX);
+    return (val > 0) ? (size_t)val : 64;
+}
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `uname(2)` | Read current hostname |
+| `sethostname(2)` | Set new hostname (requires `CAP_SYS_ADMIN`) |
+| `sysconf(3)` | Query `_SC_HOST_NAME_MAX` |
+
+## Examples
+
+```sh
+# Print hostname
+hostname
+
+# Print short hostname
+hostname -s
+
+# Print domain part
+hostname -d
+
+# Set hostname (requires root)
+hostname myserver.example.com
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success |
+| 1    | Error (sethostname failed, invalid option) |
+
+## Differences from GNU hostname
+
+- No `-f` / `--fqdn` — Linux requires NSS for FQDN resolution
+- No `--ip-address` / `-i`
+- No `--alias` / `-a`
+- No `--all-fqdns` / `--all-ip-addresses`
+- Simpler: read or set only, no DNS lookups
diff --git a/docs/handbook/corebinutils/kill.md b/docs/handbook/corebinutils/kill.md
new file mode 100644
index 0000000000..eb4d8d55bf
--- /dev/null
+++ b/docs/handbook/corebinutils/kill.md
@@ -0,0 +1,237 @@
+# kill — Send Signals to Processes
+
+## Overview
+
+`kill` sends signals to processes or lists available signals. This
+implementation supports both numeric and named signal specifications,
+real-time signals (`SIGRT`), and can be compiled as a shell built-in.
+
+**Source**: `kill/kill.c` (single file)
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+kill [-s signal_name] pid ...
+kill -l [exit_status ...]
+kill -signal_name pid ...
+kill -signal_number pid ...
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-s signal` | Send the named signal |
+| `-l` | List available signal names |
+| `-signal_name` | Send named signal (e.g., `-TERM`) |
+| `-signal_number` | Send signal by number (e.g., `-15`) |
+
+## Source Analysis
+
+### Signal Table
+
+The signal table maps names to numbers using a macro-generated array:
+
+```c
+struct signal_entry {
+    const char *name;
+    int number;
+};
+
+#define SIGNAL_ENTRY(sig) { #sig, SIG##sig }
+
+static const struct signal_entry signal_table[] = {
+    SIGNAL_ENTRY(HUP),
+    SIGNAL_ENTRY(INT),
+    SIGNAL_ENTRY(QUIT),
+    SIGNAL_ENTRY(ILL),
+    SIGNAL_ENTRY(TRAP),
+    SIGNAL_ENTRY(ABRT),
+    SIGNAL_ENTRY(EMT),     /* If available */
+    SIGNAL_ENTRY(FPE),
+    SIGNAL_ENTRY(KILL),
+    SIGNAL_ENTRY(BUS),
+    SIGNAL_ENTRY(SEGV),
+    SIGNAL_ENTRY(SYS),
+    SIGNAL_ENTRY(PIPE),
+    SIGNAL_ENTRY(ALRM),
+    SIGNAL_ENTRY(TERM),
+    SIGNAL_ENTRY(URG),
+    SIGNAL_ENTRY(STOP),
+    SIGNAL_ENTRY(TSTP),
+    SIGNAL_ENTRY(CONT),
+    SIGNAL_ENTRY(CHLD),
+    SIGNAL_ENTRY(TTIN),
+    SIGNAL_ENTRY(TTOU),
+    SIGNAL_ENTRY(IO),
+    SIGNAL_ENTRY(XCPU),
+    SIGNAL_ENTRY(XFSZ),
+    SIGNAL_ENTRY(VTALRM),
+    SIGNAL_ENTRY(PROF),
+    SIGNAL_ENTRY(WINCH),
+    SIGNAL_ENTRY(INFO),    /* If available */
+    SIGNAL_ENTRY(USR1),
+    SIGNAL_ENTRY(USR2),
+    /* ... */
+};
+```
+
+### Key Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Parse options and dispatch signal or list |
+| `normalize_signal_name()` | Canonicalize signal name (strip `SIG` prefix, uppercase) |
+| `parse_signal_option_token()` | Parse `-SIGNAL` shorthand |
+| `parse_signal_for_dash_s()` | Parse signal name/number for `-s` |
+| `signal_name_for_number()` | Reverse lookup: number → name |
+| `printsignals()` | List all signals (for `-l`) |
+| `max_signal_number()` | Find highest valid signal |
+| `parse_pid_argument()` | Parse and validate PID string |
+
+### Signal Name Normalization
+
+```c
+static const char *
+normalize_signal_name(const char *name)
+{
+    /* Strip optional "SIG" prefix */
+    if (strncasecmp(name, "SIG", 3) == 0)
+        name += 3;
+
+    /* Case-insensitive lookup in signal_table */
+    for (size_t i = 0; i < SIGNAL_TABLE_SIZE; i++) {
+        if (strcasecmp(name, signal_table[i].name) == 0)
+            return signal_table[i].name;
+    }
+    return NULL;
+}
+```
+
+### Parsing Signal Options
+
+The option parsing handles three forms:
+
+```c
+/* Form 1: kill -s SIGNAL pid */
+/* Form 2: kill -SIGNAL pid (dash prefix) */
+/* Form 3: kill -NUMBER pid */
+
+static int
+parse_signal_option_token(const char *token)
+{
+    /* Try as number first */
+    char *end;
+    long val = strtol(token, &end, 10);
+    if (*end == '\0' && val >= 0 && val <= max_signal_number())
+        return (int)val;
+
+    /* Try as name */
+    const char *name = normalize_signal_name(token);
+    if (name) {
+        /* Look up number from normalized name */
+        return number_for_name(name);
+    }
+
+    errx(2, "unknown signal: %s", token);
+}
+```
+
+### Real-Time Signal Support
+
+```c
+/* SIGRTMIN+n and SIGRTMAX-n notation */
+#ifdef SIGRTMIN
+    if (strncasecmp(name, "RTMIN", 5) == 0) {
+        int offset = (name[5] == '+') ? atoi(name + 6) : 0;
+        return SIGRTMIN + offset;
+    }
+    if (strncasecmp(name, "RTMAX", 5) == 0) {
+        int offset = (name[5] == '-') ? atoi(name + 6) : 0;
+        return SIGRTMAX - offset;
+    }
+#endif
+```
+
+### Listing Signals
+
+```c
+static void
+printsignals(FILE *fp)
+{
+    int columns = 0;
+    for (int sig = 1; sig <= max_signal_number(); sig++) {
+        const char *name = signal_name_for_number(sig);
+        if (name) {
+            fprintf(fp, "%s", name);
+            if (++columns >= 8) {
+                fputc('\n', fp);
+                columns = 0;
+            } else {
+                fputc('\t', fp);
+            }
+        }
+    }
+}
+```
+
+### Signal from Exit Status
+
+When given an exit status with `-l`, the signal number is extracted:
+
+```c
+/* exit_status > 128 means killed by signal (exit_status - 128) */
+if (exit_status > 128)
+    sig = exit_status - 128;
+```
+
+### Shell Built-in Integration
+
+```c
+#ifdef SHELL
+/* When compiled into the shell (sh/), kill is a built-in */
+/* Uses different error reporting and argument parsing */
+int killcmd(int argc, char *argv[]);
+#endif
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `kill(2)` | Send signal to process or process group |
+
+## Examples
+
+```sh
+# Send SIGTERM (default)
+kill 1234
+
+# Send SIGKILL
+kill -9 1234
+kill -KILL 1234
+kill -s KILL 1234
+
+# Send to process group
+kill -TERM -1234
+
+# List all signals
+kill -l
+
+# Signal name from exit status
+kill -l 137
+# → KILL (137 - 128 = 9 = SIGKILL)
+
+# Real-time signal
+kill -s RTMIN+3 1234
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | All signals sent successfully |
+| 1    | Error sending signal to at least one process |
+| 2    | Usage error |
diff --git a/docs/handbook/corebinutils/ln.md b/docs/handbook/corebinutils/ln.md
new file mode 100644
index 0000000000..848ebb72c0
--- /dev/null
+++ b/docs/handbook/corebinutils/ln.md
@@ -0,0 +1,190 @@
+# ln — Make Links
+
+## Overview
+
+`ln` creates hard links or symbolic links between files. It supports
+interactive prompting, forced overwriting, verbose output, and optional
+warnings for missing symbolic link targets.
+
+**Source**: `ln/ln.c` (single file)
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+ln [-sfhivFLPnw] source_file [target_file]
+ln [-sfhivFLPnw] source_file ... target_dir
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-s` | Create symbolic links instead of hard links |
+| `-f` | Force: remove existing target files |
+| `-i` | Interactive: prompt before overwriting |
+| `-n` | Don't follow symlinks on the target |
+| `-v` | Verbose: print each link created |
+| `-w` | Warn if symbolic link target does not exist |
+| `-h` | Don't follow symlink if target is a symlink to a directory |
+| `-F` | Remove existing target directory before linking |
+| `-L` | Follow symlinks on the source |
+| `-P` | Don't follow symlinks on the source (default for hard links) |
+
+## Source Analysis
+
+### Data Structures
+
+```c
+struct ln_options {
+    bool force;                /* -f: remove existing targets */
+    bool remove_dir;           /* -F: remove existing directories */
+    bool no_target_follow;     /* -n/-h: don't follow target symlinks */
+    bool interactive;          /* -i: prompt before replace */
+    bool follow_source_symlink; /* -L: follow source symlinks */
+    bool symbolic;             /* -s: create symlinks */
+    bool verbose;              /* -v: print actions */
+    bool warn_missing;         /* -w: warn on missing symlink target */
+    int linkch;                /* Function: link or symlink */
+};
+```
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Parse options, determine single vs. multi-target mode |
+| `linkit()` | Create one link (core logic) |
+| `remove_existing_target()` | Unlink or rmdir existing target |
+| `samedirent()` | Check if source and target are the same file |
+| `should_append_basename()` | Determine if target is a directory |
+| `stat_parent_dir()` | Stat the parent directory of a path |
+| `warn_missing_symlink_source()` | Check if symlink target exists |
+| `prompt_replace()` | Interactive yes/no prompt |
+
+### Core Linking Logic
+
+```c
+static int
+linkit(const char *source, const char *target,
+       const struct ln_options *opts)
+{
+    /* Check if target already exists */
+    if (lstat(target, &sb) == 0) {
+        /* Same file check */
+        if (samedirent(source, target)) {
+            warnx("%s and %s are the same", source, target);
+            return 1;
+        }
+
+        /* Interactive prompt */
+        if (opts->interactive && !prompt_replace(target))
+            return 0;
+
+        /* Remove existing target */
+        if (opts->force || opts->interactive)
+            remove_existing_target(target, opts);
+    }
+
+    /* Create the link */
+    if (opts->symbolic) {
+        if (symlink(source, target) < 0) {
+            warn("symlink %s -> %s", target, source);
+            return 1;
+        }
+    } else {
+        if (link(source, target) < 0) {
+            warn("link %s -> %s", target, source);
+            return 1;
+        }
+    }
+
+    /* Warn about dangling symlinks */
+    if (opts->symbolic && opts->warn_missing)
+        warn_missing_symlink_source(source, target);
+
+    /* Verbose output */
+    if (opts->verbose)
+        printf("%s -> %s\n", target, source);
+
+    return 0;
+}
+```
+
+### Sameness Detection
+
+```c
+static int
+samedirent(const char *source, const char *target)
+{
+    struct stat sb_src, sb_tgt;
+
+    if (stat(source, &sb_src) < 0)
+        return 0;
+    if (stat(target, &sb_tgt) < 0)
+        return 0;
+
+    return (sb_src.st_dev == sb_tgt.st_dev &&
+            sb_src.st_ino == sb_tgt.st_ino);
+}
+```
+
+### Target Resolution
+
+When the target is a directory, the source basename is appended:
+
+```c
+static int
+should_append_basename(const char *target,
+                       const struct ln_options *opts)
+{
+    struct stat sb;
+    int (*statfn)(const char *, struct stat *);
+
+    /* -n/-h: use lstat to not follow target symlinks */
+    statfn = opts->no_target_follow ? lstat : stat;
+
+    if (statfn(target, &sb) == 0 && S_ISDIR(sb.st_mode))
+        return 1;
+    return 0;
+}
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `link(2)` | Create hard link |
+| `symlink(2)` | Create symbolic link |
+| `lstat(2)` | Stat without following symlinks |
+| `stat(2)` | Stat following symlinks |
+| `unlink(2)` | Remove existing target |
+| `rmdir(2)` | Remove existing target directory (`-F`) |
+| `readlink(2)` | Resolve symlink for display |
+
+## Examples
+
+```sh
+# Hard link
+ln file1.txt file2.txt
+
+# Symbolic link
+ln -s /usr/local/bin/python3 /usr/bin/python
+
+# Force overwrite
+ln -sf new_target link_name
+
+# Verbose with warning
+ln -svw /opt/myapp/bin/app /usr/local/bin/app
+
+# Multiple files into directory
+ln -s file1 file2 file3 /tmp/links/
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | All links created successfully |
+| 1    | Error creating one or more links |
diff --git a/docs/handbook/corebinutils/ls.md b/docs/handbook/corebinutils/ls.md
new file mode 100644
index 0000000000..e6c6314170
--- /dev/null
+++ b/docs/handbook/corebinutils/ls.md
@@ -0,0 +1,314 @@
+# ls — List Directory Contents
+
+## Overview
+
+`ls` lists files and directory contents with extensive formatting,
+sorting, filtering, and colorization options. This implementation uses
+the Linux `statx(2)` syscall for file metadata (including birth time),
+and provides column, long, stream, and single-column layout modes.
+
+**Source**: `ls/ls.c`, `ls/ls.h`, `ls/print.c`, `ls/cmp.c`, `ls/util.c`,
+`ls/extern.h`
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+ls [-ABCFGHILPRSTUWabcdfghiklmnopqrstuvwxy1,] [--color[=when]]
+   [--group-directories-first] [file ...]
+```
+
+## Source Architecture
+
+### File Responsibilities
+
+| File | Purpose | Key Functions |
+|------|---------|---------------|
+| `ls.c` | Main, option parsing, directory traversal | `main()`, `parse_options()`, `collect_directory_entries()` |
+| `ls.h` | Type definitions, enums, structs | `layout_mode`, `sort_mode`, `time_field` |
+| `print.c` | Output formatting for all layout modes | `printlong()`, `printcol()`, `printstream()` |
+| `cmp.c` | Sorting comparators | `namecmp()`, `mtimecmp()`, `sizecmp()` |
+| `util.c` | Helper functions | `emalloc()`, `printescaped()` |
+| `extern.h` | Function prototypes across files | All cross-file declarations |
+
+### Enums (ls.h)
+
+```c
+enum layout_mode {
+    SINGLE,    /* One file per line (-1) */
+    COLUMNS,   /* Multi-column (-C) */
+    LONG,      /* Long listing (-l) */
+    STREAM,    /* Comma-separated (-m) */
+};
+
+enum sort_mode {
+    BY_NAME,       /* Default alphabetical */
+    BY_TIME,       /* -t: modification/access/birth/change time */
+    BY_SIZE,       /* -S: file size */
+    BY_VERSION,    /* --sort=version: version number sort */
+    UNSORTED,      /* -f: no sorting */
+};
+
+enum time_field {
+    MTIME,    /* Modification time (default) */
+    ATIME,    /* Access time (-u) */
+    BTIME,    /* Birth/creation time (-U) */
+    CTIME,    /* Inode change time (-c) */
+};
+
+enum follow_mode {
+    FOLLOW_NEVER,    /* -P: never follow symlinks */
+    FOLLOW_ALWAYS,   /* -L: always follow */
+    FOLLOW_CMDLINE,  /* -H: follow on command line only */
+};
+
+enum color_mode {
+    COLOR_NEVER,
+    COLOR_ALWAYS,
+    COLOR_AUTO,      /* Only when stdout is a TTY */
+};
+```
+
+### File Time Struct
+
+```c
+struct file_time {
+    struct timespec ts;
+    bool available;     /* False if filesystem doesn't support it */
+};
+```
+
+### statx(2) Integration
+
+Since musl libc may not provide `statx` wrappers, `ls` defines the
+syscall interface inline:
+
+```c
+static int
+linux_statx(int dirfd, const char *path, int flags,
+            unsigned int mask, struct statx *stx)
+{
+    return syscall(__NR_statx, dirfd, path, flags, mask, stx);
+}
+```
+
+This enables birth time (`btime`) on filesystems that support it
+(ext4, btrfs, XFS) where traditional `stat(2)` does not expose it.
+
+### Option Parsing
+
+```c
+static const char *optstring =
+    "ABCFGHILPRSTUWabcdfghiklmnopqrstuvwxy1,";
+
+static void
+parse_options(int argc, char *argv[])
+{
+    /* Short options via getopt(3) */
+    while ((ch = getopt_long(argc, argv, optstring,
+                             long_options, NULL)) != -1) {
+        switch (ch) {
+        case 'l': layout = LONG; break;
+        case 'C': layout = COLUMNS; break;
+        case '1': layout = SINGLE; break;
+        case 'm': layout = STREAM; break;
+        case 't': sort = BY_TIME; break;
+        case 'S': sort = BY_SIZE; break;
+        case 'r': reverse = true; break;
+        case 'a': show_hidden = ALL; break;
+        case 'A': show_hidden = ALMOST_ALL; break;
+        case 'R': recurse = true; break;
+        /* ... more options ... */
+        }
+    }
+}
+```
+
+### Long Options
+
+| Long Option | Description |
+|-------------|-------------|
+| `--color[=when]` | Colorize output (always/auto/never) |
+| `--group-directories-first` | Sort directories before files |
+| `--sort=version` | Version-number sort |
+
+### Directory Traversal
+
+```c
+static void
+collect_directory_entries(const char *dir, struct entry_list *list)
+{
+    DIR *dp = opendir(dir);
+    struct dirent *ent;
+
+    while ((ent = readdir(dp)) != NULL) {
+        /* Skip . and .. (unless -a) */
+        if (!show_hidden && ent->d_name[0] == '.')
+            continue;
+
+        struct entry *e = alloc_entry(ent->d_name);
+        stat_with_policy(dir, e);
+        list_append(list, e);
+    }
+    closedir(dp);
+}
+```
+
+### Recursive Listing
+
+```c
+static void
+list_directory(const char *path, int depth)
+{
+    collect_directory_entries(path, &entries);
+    sort_entries(&entries);
+    display_entries(&entries);
+
+    if (recurse) {
+        for (each entry that is a directory) {
+            if (should_recurse(entry)) {
+                /* Cycle detection: check device/inode */
+                if (visit_stack_contains(entry->ino, entry->dev))
+                    warnx("cycle detected: %s", path);
+                else
+                    list_directory(full_path, depth + 1);
+            }
+        }
+    }
+}
+```
+
+### Birth Time via statx
+
+```c
+static void
+fill_birthtime(struct entry *e, const struct statx *stx)
+{
+    if (stx->stx_mask & STATX_BTIME) {
+        e->btime.ts.tv_sec = stx->stx_btime.tv_sec;
+        e->btime.ts.tv_nsec = stx->stx_btime.tv_nsec;
+        e->btime.available = true;
+    } else {
+        e->btime.available = false;
+    }
+}
+```
+
+### Sorting (cmp.c)
+
+Comparators are selected based on the sort mode and direction:
+
+```c
+int namecmp(const struct entry *a, const struct entry *b);
+int mtimecmp(const struct entry *a, const struct entry *b);
+int atimecmp(const struct entry *a, const struct entry *b);
+int btimecmp(const struct entry *a, const struct entry *b);
+int ctimecmp(const struct entry *a, const struct entry *b);
+int sizecmp(const struct entry *a, const struct entry *b);
+```
+
+All comparators fall back to `namecmp()` for stable ordering when
+primary keys are equal.
+
+### Output Formatting (print.c)
+
+| Function | Layout Mode |
+|----------|-------------|
+| `printlong()` | `-l` long listing with permissions, owner, size, date |
+| `printcol()` | `-C` multi-column (default for TTY) |
+| `printstream()` | `-m` comma-separated stream |
+| `printsingle()` | `-1` one per line (default for pipe) |
+
+Human-readable sizes (`-h`) format with K, M, G, T suffixes.
+
+## Full Options Reference
+
+| Flag | Description |
+|------|-------------|
+| `-a` | Show all entries (including `.` and `..`) |
+| `-A` | Show almost all (exclude `.` and `..`) |
+| `-b` | Print C-style escapes for non-printable chars |
+| `-C` | Multi-column output (default if TTY) |
+| `-c` | Use ctime (inode change time) for sorting/display |
+| `-d` | List directories themselves, not contents |
+| `-F` | Append type indicator (`/`, `*`, `@`, `=`, `%`, `\|`) |
+| `-f` | Unsorted, show all |
+| `-G` | Colorize output (same as `--color=auto`) |
+| `-g` | Long format without owner |
+| `-H` | Follow symlinks on command line |
+| `-h` | Human-readable sizes |
+| `-I` | Suppress auto-column mode |
+| `-i` | Print inode number |
+| `-k` | Use 1024-byte blocks |
+| `-L` | Follow all symlinks |
+| `-l` | Long listing format |
+| `-m` | Stream (comma-separated) output |
+| `-n` | Numeric UID/GID |
+| `-o` | Long format without group |
+| `-P` | Never follow symlinks |
+| `-p` | Append `/` to directories |
+| `-q` | Replace non-printable with `?` |
+| `-R` | Recursive listing |
+| `-r` | Reverse sort order |
+| `-S` | Sort by size (largest first) |
+| `-s` | Print block count |
+| `-T` | Show complete time information |
+| `-t` | Sort by time |
+| `-U` | Use birth time |
+| `-u` | Use access time |
+| `-v` | Sort version numbers naturally |
+| `-w` | Force raw (non-printable) output |
+| `-x` | Multi-column sorted across |
+| `-y` | Sort by extension |
+| `-1` | One entry per line |
+| `,` | Thousands separator in sizes |
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `statx(2)` | File metadata including birth time |
+| `stat(2)` / `lstat(2)` | Fallback file metadata |
+| `opendir(3)` / `readdir(3)` | Directory enumeration |
+| `readlink(2)` | Resolve symlink targets |
+| `ioctl(TIOCGWINSZ)` | Terminal width detection |
+| `isatty(3)` | Detect if stdout is a terminal |
+| `getpwuid(3)` / `getgrgid(3)` | User/group name lookup |
+
+## Linux-Specific Notes
+
+- Uses `statx(2)` directly via `syscall()` for birth time support
+- Defines `struct statx` inline for musl compatibility
+- No BSD file flags (`-o`, `-W` not supported)
+- No MAC label support (`-Z` not supported)
+
+## Examples
+
+```sh
+# Long listing
+ls -la
+
+# Human-readable, sorted by size
+ls -lhS
+
+# Recursive with color
+ls -R --color=auto
+
+# Sort by modification time
+ls -lt
+
+# Show birth time (on supporting filesystems)
+ls -lU
+
+# Directories first
+ls --group-directories-first
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success |
+| 1    | Minor problem (cannot access one file) |
+| 2    | Serious trouble (cannot access command line argument) |
diff --git a/docs/handbook/corebinutils/mkdir.md b/docs/handbook/corebinutils/mkdir.md
new file mode 100644
index 0000000000..dfdbf75d27
--- /dev/null
+++ b/docs/handbook/corebinutils/mkdir.md
@@ -0,0 +1,194 @@
+# mkdir — Make Directories
+
+## Overview
+
+`mkdir` creates directories with specified permissions. It shares the
+`mode_compile()` / `mode_apply()` engine with `chmod` for parsing
+symbolic and numeric mode specifications. With `-p`, it creates all
+missing intermediate directories.
+
+**Source**: `mkdir/mkdir.c`, `mkdir/mode.c`, `mkdir/mode.h` (shared with chmod)
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+mkdir [-pv] [-m mode] directory ...
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-m mode` | Set permissions (numeric or symbolic) |
+| `-p` | Create parent directories as needed |
+| `-v` | Print each directory as it is created |
+
+## Source Analysis
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Parse options and iterate over arguments |
+| `create_single_path()` | Create one directory (no `-p`) |
+| `create_parents_path()` | Create directory with parents (`-p`) |
+| `create_component()` | Create a single path component |
+| `mkdir_with_umask()` | Atomically apply umask during `mkdir(2)` |
+| `existing_directory()` | Check if a path already exists as a directory |
+| `current_umask()` | Atomically read the current umask |
+| `mode_compile()` | Parse mode string to command array (shared) |
+| `mode_apply()` | Apply compiled mode to existing permissions |
+
+### Simple Creation
+
+```c
+static int
+create_single_path(const char *path, mode_t mode)
+{
+    if (mkdir(path, mode) < 0) {
+        error_errno("cannot create directory '%s'", path);
+        return 1;
+    }
+
+    /* If explicit mode was specified, chmod to override umask */
+    if (explicit_mode) {
+        if (chmod(path, mode) < 0) {
+            error_errno("cannot set permissions on '%s'", path);
+            return 1;
+        }
+    }
+
+    if (verbose)
+        printf("mkdir: created directory '%s'\n", path);
+
+    return 0;
+}
+```
+
+### Parent Directory Creation
+
+```c
+static int
+create_parents_path(const char *path, mode_t mode,
+                    mode_t intermediate_mode)
+{
+    char *buf = strdup(path);
+    char *p = buf;
+
+    /* Skip leading slashes */
+    while (*p == '/') p++;
+
+    /* Create each component */
+    while (*p) {
+        char *slash = strchr(p, '/');
+        if (slash) *slash = '\0';
+
+        if (!existing_directory(buf)) {
+            if (mkdir_with_umask(buf, intermediate_mode) < 0) {
+                if (errno != EEXIST) {
+                    error_errno("cannot create '%s'", buf);
+                    return 1;
+                }
+            }
+            if (verbose)
+                printf("mkdir: created directory '%s'\n", buf);
+        }
+
+        if (slash) {
+            *slash = '/';
+            p = slash + 1;
+        } else {
+            break;
+        }
+    }
+
+    /* Apply final mode to the leaf directory */
+    if (chmod(buf, mode) < 0) { ... }
+    return 0;
+}
+```
+
+### Atomic Umask Handling
+
+To prevent race conditions when setting permissions:
+
+```c
+static mode_t
+current_umask(void)
+{
+    /* Atomically read umask by setting and restoring */
+    mode_t mask = umask(0);
+    umask(mask);
+    return mask;
+}
+
+static int
+mkdir_with_umask(const char *path, mode_t mode)
+{
+    /* Use more restrictive intermediate perms:
+     * u+wx so the creator can write subdirs */
+    mode_t old = umask(0);
+    int ret = mkdir(path, mode);
+    umask(old);
+    return ret;
+}
+```
+
+Intermediate directories are created with `0300 | mode` to ensure the
+creating user always has write and execute access to create children,
+even if the specified mode is more restrictive.
+
+### Mode Compilation (Shared with chmod)
+
+```c
+/* Numeric modes */
+mkdir -m 755 mydir
+/* → mode_compile("755") returns compiled bitcmd array */
+
+/* Symbolic modes */
+mkdir -m u=rwx,g=rx,o=rx mydir
+/* → mode_compile("u=rwx,g=rx,o=rx") */
+
+/* Default mode */
+/* 0777 & ~umask (typically 0755) */
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `mkdir(2)` | Create directory |
+| `chmod(2)` | Set final permissions |
+| `umask(2)` | Read/set file creation mask |
+| `stat(2)` | Check if path exists |
+
+## Examples
+
+```sh
+# Simple directory
+mkdir mydir
+
+# With specific permissions
+mkdir -m 700 private_dir
+
+# Create parent directories
+mkdir -p /opt/myapp/lib/plugins
+
+# Verbose
+mkdir -pv a/b/c
+# mkdir: created directory 'a'
+# mkdir: created directory 'a/b'
+# mkdir: created directory 'a/b/c'
+
+# Symbolic mode
+mkdir -m u=rwx,g=rx,o= restricted_dir
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | All directories created successfully |
+| 1    | Error creating one or more directories |
diff --git a/docs/handbook/corebinutils/mv.md b/docs/handbook/corebinutils/mv.md
new file mode 100644
index 0000000000..c6b7369301
--- /dev/null
+++ b/docs/handbook/corebinutils/mv.md
@@ -0,0 +1,285 @@
+# mv — Move (Rename) Files
+
+## Overview
+
+`mv` moves or renames files and directories. When the source and target
+are on the same filesystem, it uses `rename(2)`. When they are on
+different filesystems, it performs a copy-and-remove fallback with
+extended attribute preservation.
+
+**Source**: `mv/mv.c` (single file)
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+mv [-finv] source target
+mv [-finv] source ... directory
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-f` | Force: do not prompt before overwriting |
+| `-i` | Interactive: prompt before overwriting |
+| `-n` | No clobber: do not overwrite existing files |
+| `-v` | Verbose: print each file as it is moved |
+
+## Source Analysis
+
+### Data Structures
+
+```c
+struct mv_options {
+    bool force;               /* -f: overwrite without asking */
+    bool interactive;         /* -i: prompt before overwrite */
+    bool no_clobber;          /* -n: never overwrite */
+    bool no_target_dir_follow; /* Don't follow target symlinks */
+    bool verbose;             /* -v: display moves */
+};
+
+struct move_target {
+    char *path;
+    struct stat sb;
+    bool is_directory;
+};
+```
+
+### Constants
+
+```c
+#define MV_EXIT_ERROR  1
+#define MV_EXIT_USAGE  2
+
+#define COPY_BUFFER_MIN  (128 * 1024)   /* 128 KB */
+#define COPY_BUFFER_MAX  (2 * 1024 * 1024)  /* 2 MB */
+```
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Parse options, determine single vs. multi-target |
+| `handle_single_move()` | Move one source to one target |
+| `apply_existing_target_policy()` | Handle `-f`, `-i`, `-n` logic |
+| `copy_move_fallback()` | Cross-device copy+remove |
+| `copy_file_data()` | Buffer-based data copy |
+| `copy_file_xattrs()` | Preserve extended attributes |
+| `copy_directory_tree()` | Recursive directory copy |
+| `apply_path_metadata()` | Set ownership, permissions, timestamps |
+| `remove_source_tree()` | Remove original after copy |
+
+### Core Move Logic
+
+```c
+static int
+handle_single_move(const char *source, const char *target,
+                   const struct mv_options *opts)
+{
+    /* Check for self-move */
+    struct stat src_sb, tgt_sb;
+    if (stat(source, &src_sb) < 0)
+        return MV_EXIT_ERROR;
+
+    /* Handle existing target */
+    if (lstat(target, &tgt_sb) == 0) {
+        /* Same file? (device + inode) */
+        if (src_sb.st_dev == tgt_sb.st_dev &&
+            src_sb.st_ino == tgt_sb.st_ino) {
+            warnx("'%s' and '%s' are the same file", source, target);
+            return MV_EXIT_ERROR;
+        }
+
+        /* Apply -f/-i/-n policy */
+        int policy = apply_existing_target_policy(target, &tgt_sb, opts);
+        if (policy != 0)
+            return policy;
+    }
+
+    /* Try rename(2) first — fast path */
+    if (rename(source, target) == 0) {
+        if (opts->verbose)
+            printf("'%s' -> '%s'\n", source, target);
+        return 0;
+    }
+
+    /* Cross-device: copy then remove */
+    if (errno == EXDEV)
+        return copy_move_fallback(source, target, &src_sb, opts);
+
+    warn("rename '%s' to '%s'", source, target);
+    return MV_EXIT_ERROR;
+}
+```
+
+### Cross-Device Copy Fallback
+
+When `rename(2)` fails with `EXDEV` (different filesystems):
+
+```c
+static int
+copy_move_fallback(const char *source, const char *target,
+                   const struct stat *src_sb,
+                   const struct mv_options *opts)
+{
+    if (S_ISDIR(src_sb->st_mode)) {
+        /* Recursive directory copy */
+        if (copy_directory_tree(source, target) != 0)
+            return MV_EXIT_ERROR;
+    } else {
+        /* Regular file copy */
+        if (copy_file_data(source, target) != 0)
+            return MV_EXIT_ERROR;
+    }
+
+    /* Preserve metadata */
+    apply_path_metadata(target, src_sb);
+
+    /* Preserve extended attributes */
+    copy_file_xattrs(source, target);
+
+    /* Remove original */
+    remove_source_tree(source, src_sb);
+
+    if (opts->verbose)
+        printf("'%s' -> '%s'\n", source, target);
+
+    return 0;
+}
+```
+
+### Adaptive Buffer Sizing
+
+```c
+static int
+copy_file_data(const char *source, const char *target)
+{
+    /* Allocate buffer based on available memory */
+    size_t bufsize = COPY_BUFFER_MAX;
+    char *buf = NULL;
+
+    while (bufsize >= COPY_BUFFER_MIN) {
+        buf = malloc(bufsize);
+        if (buf) break;
+        bufsize /= 2;
+    }
+
+    int src_fd = open(source, O_RDONLY);
+    int tgt_fd = open(target, O_WRONLY | O_CREAT | O_TRUNC, 0666);
+
+    ssize_t n;
+    while ((n = read(src_fd, buf, bufsize)) > 0) {
+        if (write_all(tgt_fd, buf, n) < 0) {
+            warn("write '%s'", target);
+            return -1;
+        }
+    }
+
+    free(buf);
+    close(src_fd);
+    close(tgt_fd);
+    return 0;
+}
+```
+
+### Extended Attribute Preservation
+
+```c
+#include <sys/xattr.h>
+
+static void
+copy_file_xattrs(const char *source, const char *target)
+{
+    ssize_t list_len = listxattr(source, NULL, 0);
+    if (list_len <= 0)
+        return;
+
+    char *list = malloc(list_len);
+    listxattr(source, list, list_len);
+
+    for (char *name = list; name < list + list_len;
+         name += strlen(name) + 1) {
+        ssize_t val_len = getxattr(source, name, NULL, 0);
+        if (val_len < 0) continue;
+
+        char *val = malloc(val_len);
+        getxattr(source, name, val, val_len);
+        setxattr(target, name, val, val_len, 0);
+        free(val);
+    }
+
+    free(list);
+}
+```
+
+### Metadata Preservation
+
+```c
+static void
+apply_path_metadata(const char *target, const struct stat *sb)
+{
+    /* Ownership */
+    chown(target, sb->st_uid, sb->st_gid);
+
+    /* Permissions */
+    chmod(target, sb->st_mode);
+
+    /* Timestamps */
+    struct timespec times[2] = {
+        sb->st_atim,   /* Access time */
+        sb->st_mtim,   /* Modification time */
+    };
+    utimensat(AT_FDCWD, target, times, 0);
+}
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `rename(2)` | Same-device move (fast path) |
+| `read(2)` / `write(2)` | Cross-device data copy |
+| `stat(2)` / `lstat(2)` | File metadata |
+| `chown(2)` | Preserve ownership |
+| `chmod(2)` | Preserve permissions |
+| `utimensat(2)` | Preserve timestamps |
+| `listxattr(2)` | List extended attributes |
+| `getxattr(2)` / `setxattr(2)` | Copy extended attributes |
+| `unlink(2)` / `rmdir(2)` | Remove source after copy |
+
+## Examples
+
+```sh
+# Rename a file
+mv old.txt new.txt
+
+# Move into directory
+mv file.txt /tmp/
+
+# Interactive mode
+mv -i important.txt /backup/
+
+# No clobber
+mv -n *.txt /archive/
+
+# Verbose
+mv -v file1 file2 file3 /dest/
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | All moves successful |
+| 1    | Error during move |
+| 2    | Usage error |
+
+## Differences from GNU mv
+
+- No `--backup` / `-b` option
+- No `--suffix` / `-S`
+- No `--target-directory` / `-t`
+- No `--update` / `-u`
+- Simpler cross-device fallback without sparse file optimization
diff --git a/docs/handbook/corebinutils/overview.md b/docs/handbook/corebinutils/overview.md
new file mode 100644
index 0000000000..0ac41deee5
--- /dev/null
+++ b/docs/handbook/corebinutils/overview.md
@@ -0,0 +1,362 @@
+# Corebinutils — Overview
+
+## What Is Corebinutils?
+
+Corebinutils is Project Tick's collection of core command-line utilities, ported
+from FreeBSD and adapted for Linux with musl libc. It provides the foundational
+user-space programs that every Unix system needs — file manipulation, process
+control, text processing, and system information tools — built from
+battle-tested FreeBSD sources rather than GNU coreutils.
+
+The project targets a clean, auditable, BSD-licensed alternative to the GNU
+toolchain. Every utility compiles against musl libc by default, producing
+statically-linkable binaries with minimal dependencies.
+
+## Heritage and Licensing
+
+All utilities derive from FreeBSD's `/usr/src/bin/` tree, carrying BSD
+3-Clause or BSD 2-Clause licenses from the original Berkeley and FreeBSD
+contributors. Project Tick's modifications (Copyright 2026) maintain the same
+licensing terms. No GPL-licensed code is present in the tree.
+
+The copyright headers trace a direct lineage:
+
+```
+Copyright (c) 1989, 1993, 1994
+    The Regents of the University of California.  All rights reserved.
+Copyright (c) 2026
+    Project Tick. All rights reserved.
+```
+
+Key contributors acknowledged across the codebase include Keith Muller (dd),
+Andrew Moore (ed), Michael Fischbein (ls), Ken Smith (mv), and Lance Visser
+(dd).
+
+## Design Philosophy
+
+### Linux-Native, Not Compatibility Layers
+
+Unlike many BSD-to-Linux ports that ship a compatibility shim library,
+corebinutils rewrites platform-specific code using native Linux APIs:
+
+- **`/proc/self/mountinfo`** replaces BSD `getmntinfo(3)` in `df`
+- **`statx(2)`** replaces BSD `stat(2)` for birth time in `ls`
+- **`sched_getaffinity(2)`** replaces BSD `cpuset_getaffinity(2)` in `nproc`
+- **`sethostname(2)` from `<unistd.h>`** replaces BSD kernel calls in `hostname`
+- **`prctl(PR_SET_CHILD_SUBREAPER)`** replaces BSD `procctl` in `timeout`
+- **`fdopendir(3)` + `readdir(3)`** replaces BSD FTS functions in `rm`
+
+### musl-First Toolchain
+
+The build system preferentially selects musl-based compilers. The configure
+script tries, in order:
+
+1. `musl-clang`
+2. `clang --target=<arch>-linux-musl`
+3. `clang --target=<arch>-unknown-linux-musl`
+4. `musl-gcc`
+5. `clang` (generic)
+6. `cc`
+7. `gcc`
+
+If a glibc toolchain is detected, configure refuses to proceed unless
+`--allow-glibc` is explicitly passed.
+
+### No External Dependencies
+
+Core utilities have zero runtime dependencies beyond libc. Optional features
+(readline in `csh`, crypto in `ed`) probe for system libraries at configure
+time but degrade gracefully when absent.
+
+## Complete Utility List
+
+### File Operations
+
+| Utility   | Description                          | Complexity | Source Files |
+|-----------|--------------------------------------|------------|-------------|
+| `cat`     | Concatenate and display files        | Simple     | 1 `.c`      |
+| `cp`      | Copy files and directory trees       | Medium     | 3+ `.c`     |
+| `dd`      | Block-level data copying/conversion  | Complex    | 8+ `.c`     |
+| `ln`      | Create hard and symbolic links       | Medium     | 1 `.c`      |
+| `mv`      | Move/rename files and directories    | Medium     | 1 `.c`      |
+| `rm`      | Remove files and directories         | Medium     | 1 `.c`      |
+| `rmdir`   | Remove empty directories             | Simple     | 1 `.c`      |
+
+### Directory Operations
+
+| Utility     | Description                        | Complexity | Source Files |
+|-------------|------------------------------------|------------|-------------|
+| `ls`        | List directory contents            | Complex    | 5+ `.c`     |
+| `mkdir`     | Create directories                 | Medium     | 2 `.c`      |
+| `pwd`       | Print working directory            | Simple     | 1 `.c`      |
+| `realpath`  | Canonicalize file paths            | Simple     | 1 `.c`      |
+
+### Permission and Attribute Management
+
+| Utility     | Description                        | Complexity | Source Files |
+|-------------|------------------------------------|------------|-------------|
+| `chmod`     | Change file permissions            | Medium     | 2 `.c`      |
+| `chflags`   | Change file flags (BSD compat)     | Medium     | 4 `.c`      |
+| `getfacl`   | Display file ACLs                  | Medium     | 1 `.c`      |
+| `setfacl`   | Set file ACLs                      | Medium     | 1 `.c`      |
+
+### Process Management
+
+| Utility     | Description                        | Complexity | Source Files |
+|-------------|------------------------------------|------------|-------------|
+| `kill`      | Send signals to processes          | Medium     | 1 `.c`      |
+| `ps`        | List running processes             | Complex    | 6+ `.c`     |
+| `pkill`     | Signal processes by name/attribute | Medium     | 1+ `.c`     |
+| `pwait`     | Wait for process termination       | Simple     | 1 `.c`      |
+| `timeout`   | Run command with time limit        | Medium     | 1 `.c`      |
+
+### Text Processing
+
+| Utility   | Description                          | Complexity | Source Files |
+|-----------|--------------------------------------|------------|-------------|
+| `echo`    | Write arguments to stdout            | Simple     | 1 `.c`      |
+| `ed`      | Line-oriented text editor            | Complex    | 10+ `.c`    |
+| `expr`    | Evaluate expressions                 | Medium     | 1 `.c`      |
+| `test`    | Conditional expression evaluation    | Medium     | 1 `.c`      |
+
+### Date and Time
+
+| Utility   | Description                          | Complexity | Source Files |
+|-----------|--------------------------------------|------------|-------------|
+| `date`    | Display/set system date and time     | Medium     | 2 `.c`      |
+| `sleep`   | Pause for specified duration         | Simple     | 1 `.c`      |
+
+### System Information
+
+| Utility          | Description                     | Complexity | Source Files |
+|------------------|---------------------------------|------------|-------------|
+| `df`             | Report filesystem space usage   | Complex    | 1 `.c`      |
+| `hostname`       | Get/set system hostname         | Simple     | 1 `.c`      |
+| `domainname`     | Get/set NIS domain name         | Simple     | 1 `.c`      |
+| `nproc`          | Count available processors      | Simple     | 1 `.c`      |
+| `freebsd-version`| Show FreeBSD version (compat)   | Simple     | Shell script|
+| `uuidgen`        | Generate UUIDs                  | Simple     | 1 `.c`      |
+
+### Shells
+
+| Utility | Description                          | Complexity | Source Files |
+|---------|--------------------------------------|------------|-------------|
+| `sh`    | POSIX-compatible shell               | Very High  | 60+ `.c`    |
+| `csh`   | C-shell (tcsh port)                  | Very High  | 30+ `.c`    |
+
+### Archive and Mail
+
+| Utility | Description                          | Complexity | Source Files |
+|---------|--------------------------------------|------------|-------------|
+| `pax`   | POSIX archive utility (tar/cpio)     | Complex    | 30+ `.c`    |
+| `rmail` | Remote mail handler                  | Simple     | 1 `.c`      |
+
+### Miscellaneous
+
+| Utility     | Description                        | Complexity | Source Files |
+|-------------|------------------------------------|------------|-------------|
+| `sync`      | Flush filesystem buffers           | Simple     | 1 `.c`      |
+| `stty`      | Set terminal characteristics       | Medium     | 2+ `.c`     |
+| `cpuset`    | CPU affinity management            | Medium     | 1 `.c`      |
+
+## Shared Components
+
+The `contrib/` directory provides libraries shared across utilities:
+
+### `contrib/libc-vis/`
+BSD `vis(3)` and `unvis(3)` functions for encoding and decoding special
+characters. Used by `ls` for safe filename display and by `pax` for
+header encoding.
+
+### `contrib/libedit/`
+BSD `editline(3)` library providing command-line editing with history and
+completion support. Used by `csh` and `sh` for interactive input.
+
+### `contrib/printf/`
+Shared `printf` format string processing used by multiple utilities that
+need custom format string expansion beyond standard `printf(3)`.
+
+## Project Structure
+
+```
+corebinutils/
+├── configure           # Top-level configure script (POSIX sh)
+├── README.md           # Build instructions
+├── .gitattributes      # Git configuration
+├── .gitignore          # Build artifact exclusions
+├── contrib/            # Shared libraries
+│   ├── libc-vis/       # vis(3)/unvis(3)
+│   ├── libedit/        # editline(3)
+│   └── printf/         # Shared printf helpers
+├── cat/                # Each utility in its own directory
+│   ├── cat.c           # Main source
+│   ├── GNUmakefile     # Per-utility build rules
+│   ├── cat.1           # Manual page
+│   └── README.md       # Port-specific notes
+├── chmod/
+│   ├── chmod.c
+│   ├── mode.c          # Shared mode parsing library
+│   ├── mode.h
+│   └── GNUmakefile
+├── ...                 # (33 utility directories total)
+└── sh/                 # Full POSIX shell (60+ source files)
+```
+
+## Utility Complexity Classification
+
+### Tier 1 — Simple (1 source file, <500 lines)
+
+`cat`, `echo`, `hostname`, `domainname`, `nproc`, `pwd`, `realpath`, `rmdir`,
+`sleep`, `sync`, `uuidgen`, `pwait`
+
+These utilities typically have a `main()` function that parses options with
+`getopt(3)`, performs a single system call, and exits. Error handling follows
+the `err(3)`/`warn(3)` pattern.
+
+### Tier 2 — Medium (1-3 source files, 500-2000 lines)
+
+`chmod` (with `mode.c`), `cp` (with `utils.c`, `fts.c`), `date` (with
+`vary.c`), `kill`, `ln`, `mkdir` (with `mode.c`), `mv`, `rm`, `test`,
+`timeout`, `expr`, `df`
+
+These utilities involve more complex option parsing, recursive directory
+traversal, or multi-step algorithms. They share code through header files
+and sometimes reuse `mode.c`/`mode.h`.
+
+### Tier 3 — Complex (5+ source files, 2000+ lines)
+
+`dd` (8 source files), `ed` (10 source files), `ls` (5 source files),
+`ps` (6 source files), `pax` (30+ source files)
+
+These are substantial programs with their own internal architecture:
+- `dd`: argument parser, conversion engine, signal handling, I/O position logic
+- `ed`: command parser, buffer manager, regex engine, undo system
+- `ls`: stat engine, sort/compare, print/format, ANSI color
+- `ps`: /proc parser, format string engine, process filter, output formatter
+
+### Tier 4 — Shells (30-60+ source files)
+
+`sh` and `csh` are full POSIX-compatible shells with lexers, parsers, job
+control, signal handling, built-in commands, and editline integration.
+
+## Key Differences from GNU Coreutils
+
+| Feature                | Corebinutils (BSD)          | GNU Coreutils              |
+|------------------------|-----------------------------|----------------------------|
+| License                | BSD-3-Clause / BSD-2-Clause | GPL-3.0                    |
+| Default libc           | musl                        | glibc                      |
+| `echo` behavior        | No `-e` flag (BSD compat)   | `-e` for escape sequences  |
+| `test` parser          | Recursive descent           | Varies by implementation   |
+| `ls` birth time        | `statx(2)` syscall          | `statx(2)` or fallback     |
+| `dd` progress          | SIGINFO + `status=progress` | `status=progress`          |
+| `sleep` units          | `s`, `m`, `h`, `d` suffixes | `s`, `m`, `h`, `d` (GNU ext)|
+| Build system           | `./configure` + `GNUmakefile`| Autotools (autoconf/automake)|
+| Error functions        | `err(3)`/`warn(3)` from libc| `error()` from gnulib      |
+| FTS implementation     | In-tree custom `fts.c`      | gnulib FTS or `nftw(3)`    |
+
+## Signal Handling Conventions
+
+Most utilities follow a consistent signal handling pattern:
+
+- **SIGINFO / SIGUSR1**: Progress reporting. `dd`, `chmod`, `sleep`, and
+  others install a handler that sets a `volatile sig_atomic_t` flag, which
+  the main loop checks to print status information.
+
+- **SIGINT**: Graceful termination. Utilities performing recursive operations
+  check for pending signals between iterations.
+
+- **SIGHUP**: In `ed`, triggers an emergency save of the edit buffer to a
+  temporary file.
+
+Signal handlers are installed via `sigaction(2)` rather than the legacy
+`signal(2)` function, ensuring reliable semantics across platforms.
+
+## Error Handling Patterns
+
+All utilities exit with standardized codes:
+
+| Exit Code | Meaning                                  |
+|-----------|------------------------------------------|
+| 0         | Success                                  |
+| 1         | General failure                          |
+| 2         | Usage error (invalid arguments)          |
+| 124       | Command timed out (`timeout` only)       |
+| 125       | `timeout` internal error                 |
+| 126       | Command found but not executable         |
+| 127       | Command not found                        |
+
+Error messages follow the BSD pattern:
+```c
+error_errno("open %s", path);   // "mv: open /foo: Permission denied"
+error_msg("invalid mode: %s", arg);  // "chmod: invalid mode: xyz"
+```
+
+Many utilities provide custom `error_errno()` / `error_msg()` wrappers that
+prepend the program name, format the message, and optionally append
+`strerror(errno)`.
+
+## Memory Management
+
+Corebinutils utilities follow BSD memory conventions:
+
+- **Dynamic allocation**: `malloc(3)` with explicit `NULL` checks, typically
+  wrapped in `xmalloc()` that calls `err(1, "malloc")` on failure.
+- **No fixed-size buffers** for user-controlled data (paths, format strings).
+- **Adaptive buffer sizing**: `cat` and `cp` scale I/O buffers based on
+  available physical memory via `sysconf(_SC_PHYS_PAGES)`.
+- **Explicit cleanup**: `free()` is called in long-running loops to avoid
+  accumulation, though single-pass utilities may rely on process exit.
+
+### Buffer Strategy Example (from `cat.c` and `cp/utils.c`):
+
+```c
+#define PHYSPAGES_THRESHOLD (32*1024)
+#define BUFSIZE_MAX         (2*1024*1024)
+#define BUFSIZE_SMALL       (128*1024)
+
+if (sysconf(_SC_PHYS_PAGES) > PHYSPAGES_THRESHOLD)
+    bufsize = MIN(BUFSIZE_MAX, MAXPHYS * 8);
+else
+    bufsize = BUFSIZE_SMALL;
+```
+
+## Testing
+
+Each utility directory may contain its own test suite, invoked through:
+
+```sh
+make -f GNUmakefile test
+```
+
+Or for a specific utility:
+
+```sh
+make -f GNUmakefile check-cat
+make -f GNUmakefile check-ls
+```
+
+Tests that require root privileges or specific kernel features print `SKIP`
+and continue without failing the overall test run.
+
+## Building Quick Reference
+
+```sh
+cd corebinutils/
+./configure                          # Detect toolchain, generate build files
+make -f GNUmakefile -j$(nproc) all   # Build all utilities
+make -f GNUmakefile test             # Run test suites
+make -f GNUmakefile stage            # Copy binaries to out/bin/
+make -f GNUmakefile install          # Install to $PREFIX/bin
+```
+
+See [building.md](building.md) for detailed configure options and build
+customization.
+
+## Further Reading
+
+- [architecture.md](architecture.md) — Build system internals, code organization
+- [building.md](building.md) — Configure options, dependencies, cross-compilation
+- Individual utility documentation: [cat.md](cat.md), [ls.md](ls.md),
+  [dd.md](dd.md), [ps.md](ps.md), etc.
+- [code-style.md](code-style.md) — C coding conventions
+- [error-handling.md](error-handling.md) — Error patterns and exit codes
diff --git a/docs/handbook/corebinutils/ps.md b/docs/handbook/corebinutils/ps.md
new file mode 100644
index 0000000000..cbbd749a44
--- /dev/null
+++ b/docs/handbook/corebinutils/ps.md
@@ -0,0 +1,298 @@
+# ps — Process Status
+
+## Overview
+
+`ps` displays information about active processes. This implementation
+reads process data from the Linux `/proc` filesystem and presents it
+through BSD-style format strings. It provides a custom `struct kinfo_proc`
+that mirrors FreeBSD's interface while reading from Linux procfs.
+
+**Source**: `ps/ps.c`, `ps/ps.h`, `ps/fmt.c`, `ps/keyword.c`,
+`ps/print.c`, `ps/nlist.c`, `ps/extern.h`
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+ps [-AaCcdefHhjLlMmrSTuvwXxZ] [-D fmt] [-G gid[,gid...]]
+   [-J jail] [-N system] [-O fmt] [-o fmt] [-p pid[,pid...]]
+   [-t tty[,tty...]] [-U user[,user...]] [-g group[,group...]]
+```
+
+## Source Architecture
+
+### File Responsibilities
+
+| File | Purpose |
+|------|---------|
+| `ps.c` | Main program, option parsing, process collection |
+| `ps.h` | Data structures, constants, STAILQ macros |
+| `fmt.c` | Format string parsing and column management |
+| `keyword.c` | Format keyword definitions and lookup table |
+| `print.c` | Column value formatters (PID, user, CPU, etc.) |
+| `nlist.c` | Name list support (noop on Linux) |
+| `extern.h` | Cross-file function declarations |
+
+### Key Data Structures
+
+#### Process Information (Linux replacement for BSD kinfo_proc)
+
+```c
+struct kinfo_proc {
+    pid_t   ki_pid;        /* Process ID */
+    pid_t   ki_ppid;       /* Parent PID */
+    pid_t   ki_pgid;       /* Process group ID */
+    pid_t   ki_sid;        /* Session ID */
+    uid_t   ki_uid;        /* Real UID */
+    uid_t   ki_ruid;       /* Real UID (copy) */
+    uid_t   ki_svuid;      /* Saved UID */
+    gid_t   ki_rgid;       /* Real GID */
+    gid_t   ki_svgid;      /* Saved GID */
+    gid_t   ki_groups[KI_NGROUPS]; /* Supplementary groups */
+    int     ki_ngroups;    /* Number of groups */
+    dev_t   ki_tdev;       /* TTY device */
+    int     ki_flag;       /* Process flags */
+    int     ki_stat;       /* Process state */
+    char    ki_comm[COMMLEN + 1]; /* Command name */
+    char    ki_wmesg[WMESGLEN + 1]; /* Wait channel */
+    int     ki_nice;       /* Nice value */
+    int     ki_pri;        /* Priority */
+    long    ki_size;       /* Virtual size */
+    long    ki_rssize;     /* Resident size */
+    struct timeval ki_start; /* Start time */
+    struct timeval ki_rusage; /* Resource usage */
+    /* ... additional fields ... */
+};
+```
+
+#### KINFO Wrapper
+
+```c
+typedef struct {
+    struct kinfo_proc *ki_p;
+    char *ki_args;      /* Full command line */
+    char *ki_env;       /* Environment (if -E) */
+    double ki_pcpu;     /* Computed %CPU */
+    long ki_memsize;    /* Computed memory size */
+} KINFO;
+```
+
+#### Format Variable
+
+```c
+typedef struct {
+    const char *name;    /* Keyword name (e.g., "pid", "user") */
+    const char *header;  /* Column header (e.g., "PID", "USER") */
+    int width;           /* Column width */
+    int (*sprnt)(KINFO *); /* Print function */
+    int flag;            /* Format flags */
+} VAR;
+```
+
+### Constants
+
+```c
+#define COMMLEN   256   /* Max command name length */
+#define WMESGLEN  64    /* Max wait message length */
+#define KI_NGROUPS 16   /* Max supplementary groups tracked */
+```
+
+### musl Compatibility
+
+FreeBSD uses `STAILQ_*` macros extensively, but musl's `<sys/queue.h>`
+may not provide them. `ps.h` defines custom implementations:
+
+```c
+#ifndef STAILQ_HEAD
+#define STAILQ_HEAD(name, type)                         \
+struct name {                                           \
+    struct type *stqh_first;                            \
+    struct type **stqh_last;                            \
+}
+#define STAILQ_ENTRY(type)                              \
+struct {                                                \
+    struct type *stqe_next;                             \
+}
+#define STAILQ_INIT(head) do { ... } while (0)
+#define STAILQ_INSERT_TAIL(head, elm, field) do { ... } while (0)
+#define STAILQ_FOREACH(var, head, field) ...
+#endif
+```
+
+### Predefined Format Strings
+
+```c
+/* Default format (-f not specified) */
+const char *dfmt = "pid,tt,stat,time,command";
+
+/* Jobs format (-j) */
+const char *jfmt = "user,pid,ppid,pgid,sid,jobc,stat,tt,time,command";
+
+/* Long format (-l) */
+const char *lfmt = "uid,pid,ppid,cpu,pri,nice,vsz,rss,wchan,stat,tt,time,command";
+
+/* User format (-u) */
+const char *ufmt = "user,pid,%cpu,%mem,vsz,rss,tt,stat,start,time,command";
+
+/* Virtual memory format (-v) */
+const char *vfmt = "pid,stat,time,sl,re,pagein,vsz,rss,lim,tsiz,%cpu,%mem,command";
+```
+
+### /proc Parsing
+
+Process data is read from multiple `/proc/[pid]/` files:
+
+| File | Data Extracted |
+|------|----------------|
+| `/proc/[pid]/stat` | PID, PPID, PGID, state, priority, nice, threads, start time |
+| `/proc/[pid]/status` | UID, GID, groups, memory (VmSize, VmRSS) |
+| `/proc/[pid]/cmdline` | Full command line arguments |
+| `/proc/[pid]/environ` | Environment variables (if requested) |
+| `/proc/[pid]/wchan` | Wait channel name |
+| `/proc/[pid]/fd/0` | Controlling TTY detection |
+
+### Process Filtering
+
+```c
+/* Option string */
+#define PS_ARGS "AaCcD:defG:gHhjJ:LlM:mN:O:o:p:rSTt:U:uvwXxZ"
+
+struct listinfo {
+    int count;
+    int maxcount;
+    int *list;        /* Array of values to match */
+    int (*addelem)(struct listinfo *, const char *);
+};
+```
+
+Filtering by PID, UID, GID, TTY, session, and process group uses
+`struct listinfo` with dynamic arrays and element-specific parsers.
+
+### Column Formatting (keyword.c)
+
+The keyword table maps format names to print functions:
+
+```c
+static VAR var[] = {
+    {"pid",     "PID",     5, s_pid,     0},
+    {"ppid",    "PPID",    5, s_ppid,    0},
+    {"user",    "USER",    8, s_user,    0},
+    {"uid",     "UID",     5, s_uid,     0},
+    {"gid",     "GID",     5, s_gid,     0},
+    {"%cpu",    "%CPU",    4, s_pcpu,    0},
+    {"%mem",    "%MEM",    4, s_pmem,    0},
+    {"vsz",     "VSZ",     6, s_vsz,     0},
+    {"rss",     "RSS",     5, s_rss,     0},
+    {"tt",      "TT",      3, s_tty,     0},
+    {"stat",    "STAT",    4, s_stat,    0},
+    {"time",    "TIME",    8, s_time,    0},
+    {"command", "COMMAND", 16, s_command, COMM},
+    {"args",    "COMMAND", 16, s_args,    COMM},
+    {"comm",    "COMMAND", 16, s_comm,    COMM},
+    {"nice",    "NI",      3, s_nice,    0},
+    {"pri",     "PRI",     3, s_pri,     0},
+    {"wchan",   "WCHAN",   8, s_wchan,   0},
+    {"start",   "STARTED", 8, s_start,   0},
+    /* ... more keywords ... */
+    {NULL, NULL, 0, NULL, 0},  /* Sentinel */
+};
+```
+
+### Global State
+
+```c
+int cflag;          /* Raw CPU usage */
+int eval;           /* Exit value */
+time_t now;         /* Current time */
+int rawcpu;         /* Don't compute decay */
+int sumrusage;      /* Sum child usage */
+int termwidth;      /* Terminal width */
+int showthreads;    /* Show threads (-H) */
+int hlines;         /* Header repeat interval */
+```
+
+## Options Reference
+
+| Flag | Description |
+|------|-------------|
+| `-A` / `-e` | All processes |
+| `-a` | Processes with terminals (except session leaders) |
+| `-C` | Raw CPU percentage |
+| `-c` | Show command name only (not full path) |
+| `-d` | All except session leaders |
+| `-f` | Full format |
+| `-G gid` | Filter by real group ID |
+| `-g group` | Filter by group name |
+| `-H` | Show threads |
+| `-h` | Repeat header every screenful |
+| `-j` | Jobs format |
+| `-L` | Show all threads (LWP) |
+| `-l` | Long format |
+| `-M` | Display MAC label |
+| `-m` | Sort by memory usage |
+| `-O fmt` | Add columns to default format |
+| `-o fmt` | Custom output format |
+| `-p pid` | Filter by PID |
+| `-r` | Running processes only |
+| `-S` | Include child time |
+| `-T` | Show threads for current terminal |
+| `-t tty` | Filter by TTY |
+| `-U user` | Filter by effective user |
+| `-u` | User format |
+| `-v` | Virtual memory format |
+| `-w` | Wide output |
+| `-X` | Skip processes without controlling TTY |
+| `-x` | Include processes without controlling TTY |
+| `-Z` | Show security context |
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `opendir(3)` / `readdir(3)` | Enumerate `/proc/` PIDs |
+| `open(2)` / `read(2)` | Read `/proc/[pid]/*` files |
+| `stat(2)` | Get file owner for UID detection |
+| `getpwuid(3)` / `getgrgid(3)` | UID/GID to name resolution |
+| `ioctl(TIOCGWINSZ)` | Terminal width |
+| `sysconf(3)` | Clock ticks, page size |
+
+## Examples
+
+```sh
+# Default process list
+ps
+
+# All processes, user format
+ps aux
+
+# Full format
+ps -ef
+
+# Custom columns
+ps -o pid,user,%cpu,%mem,command
+
+# Filter by user
+ps -U root
+
+# Jobs format
+ps -j
+
+# Long format with threads
+ps -lH
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success |
+| 1    | Error |
+
+## Linux-Specific Notes
+
+- Reads from `/proc` filesystem instead of BSD `kvm_getprocs(3)`
+- Custom `struct kinfo_proc` replaces BSD's `<sys/user.h>` variant
+- STAILQ macros defined inline for musl compatibility
+- No jail (`-J`) support on Linux
+- No Capsicum sandboxing
diff --git a/docs/handbook/corebinutils/pwd.md b/docs/handbook/corebinutils/pwd.md
new file mode 100644
index 0000000000..8f584e3357
--- /dev/null
+++ b/docs/handbook/corebinutils/pwd.md
@@ -0,0 +1,152 @@
+# pwd — Print Working Directory
+
+## Overview
+
+`pwd` prints the absolute pathname of the current working directory.
+It supports logical mode (using `$PWD`) and physical mode (resolving
+symlinks). Logical mode is the default, with fallback to physical
+if validation fails.
+
+**Source**: `pwd/pwd.c` (single file)
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+pwd [-L | -P]
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-L` | Logical: use `$PWD` (default) |
+| `-P` | Physical: resolve all symlinks |
+
+When both are specified, the last one wins.
+
+## Source Analysis
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Parse options and dispatch |
+| `getcwd_logical()` | Validate and use `$PWD` |
+| `getcwd_physical()` | Resolve via `getcwd(3)` |
+| `usage()` | Print usage message |
+
+### Logical Mode (Default)
+
+```c
+static char *
+getcwd_logical(void)
+{
+    const char *pwd = getenv("PWD");
+
+    /* Must be set and absolute */
+    if (!pwd || pwd[0] != '/')
+        return NULL;
+
+    /* Must not contain "." or ".." components */
+    if (contains_dot_components(pwd))
+        return NULL;
+
+    /* Must refer to the same directory as "." */
+    struct stat pwd_sb, dot_sb;
+    if (stat(pwd, &pwd_sb) < 0 || stat(".", &dot_sb) < 0)
+        return NULL;
+    if (pwd_sb.st_dev != dot_sb.st_dev ||
+        pwd_sb.st_ino != dot_sb.st_ino)
+        return NULL;
+
+    return strdup(pwd);
+}
+```
+
+The `$PWD` validation ensures:
+1. The value is an absolute path
+2. It contains no `.` or `..` components
+3. The path resolves to the same inode as `.`
+
+### Physical Mode
+
+```c
+static char *
+getcwd_physical(void)
+{
+    /* POSIX: getcwd(NULL, 0) dynamically allocates */
+    return getcwd(NULL, 0);
+}
+```
+
+Uses the POSIX extension `getcwd(NULL, 0)` which allocates the
+returned buffer dynamically, avoiding fixed-size buffer limitations.
+
+### Main Logic
+
+```c
+int main(int argc, char *argv[])
+{
+    int mode = MODE_LOGICAL;  /* Default: logical */
+
+    while ((ch = getopt(argc, argv, "LP")) != -1) {
+        switch (ch) {
+        case 'L': mode = MODE_LOGICAL; break;
+        case 'P': mode = MODE_PHYSICAL; break;
+        default:  usage();
+        }
+    }
+
+    char *cwd;
+    if (mode == MODE_LOGICAL) {
+        cwd = getcwd_logical();
+        if (!cwd)
+            cwd = getcwd_physical();  /* Fallback */
+    } else {
+        cwd = getcwd_physical();
+    }
+
+    if (!cwd)
+        err(1, "getcwd");
+
+    puts(cwd);
+    free(cwd);
+    return 0;
+}
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `getcwd(3)` | Physical working directory |
+| `stat(2)` | Validate `$PWD` against `.` |
+| `getenv(3)` | Read `$PWD` environment variable |
+
+## Examples
+
+```sh
+# Default (logical)
+pwd
+# /home/user/projects/mylink  (preserves symlink name)
+
+# Physical
+pwd -P
+# /home/user/actual/path  (resolved symlinks)
+
+# Demonstrate difference
+cd /tmp
+ln -s /usr/local/share mylink
+cd mylink
+pwd -L   # → /tmp/mylink
+pwd -P   # → /usr/local/share
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success |
+| 1    | Error (cannot determine directory) |
diff --git a/docs/handbook/corebinutils/realpath.md b/docs/handbook/corebinutils/realpath.md
new file mode 100644
index 0000000000..bf7c1d421f
--- /dev/null
+++ b/docs/handbook/corebinutils/realpath.md
@@ -0,0 +1,119 @@
+# realpath — Resolve to Canonical Path
+
+## Overview
+
+`realpath` resolves each given pathname to its canonical absolute form
+by expanding all symbolic links, resolving `.` and `..` references,
+and removing extra `/` characters.
+
+**Source**: `realpath/realpath.c` (single file)
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+realpath [-q] [path ...]
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-q` | Quiet: suppress error messages for non-existent paths |
+
+## Source Analysis
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Parse options and resolve loop |
+| `resolve_path()` | Wrapper around `realpath(3)` |
+| `set_progname()` | Extract program name from `argv[0]` |
+| `print_line()` | Safe stdout writing |
+| `usage()` | Print usage message |
+| `warnx_msg()` | Warning without errno |
+| `warn_path_errno()` | Warning with errno for path |
+
+### Core Logic
+
+```c
+static int
+resolve_path(const char *path, bool quiet)
+{
+    char *resolved = realpath(path, NULL);
+    if (!resolved) {
+        if (!quiet)
+            warn("%s", path);
+        return 1;
+    }
+
+    puts(resolved);
+    free(resolved);
+    return 0;
+}
+```
+
+### Main Loop
+
+```c
+int main(int argc, char *argv[])
+{
+    bool quiet = false;
+    int ch, errors = 0;
+
+    while ((ch = getopt(argc, argv, "q")) != -1) {
+        switch (ch) {
+        case 'q': quiet = true; break;
+        default:  usage();
+        }
+    }
+    argc -= optind;
+    argv += optind;
+
+    if (argc == 0)
+        usage();
+
+    for (int i = 0; i < argc; i++)
+        errors |= resolve_path(argv[i], quiet);
+
+    return errors ? 1 : 0;
+}
+```
+
+Uses `realpath(path, NULL)` (POSIX.1-2008) for dynamic buffer
+allocation, avoiding `PATH_MAX` limitations.
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `realpath(3)` | Canonicalize pathname |
+
+## Examples
+
+```sh
+# Simple resolution
+realpath ../foo/bar
+# → /home/user/foo/bar
+
+# Resolve symlink
+ln -s /usr/local/bin target
+realpath target
+# → /usr/local/bin
+
+# Quiet mode (no error for missing)
+realpath -q /nonexistent/path
+# (no output, exit 1)
+
+# Multiple paths
+realpath /tmp/../etc ./relative/path
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | All paths resolved successfully |
+| 1    | One or more paths could not be resolved |
diff --git a/docs/handbook/corebinutils/rm.md b/docs/handbook/corebinutils/rm.md
new file mode 100644
index 0000000000..36c92e34ec
--- /dev/null
+++ b/docs/handbook/corebinutils/rm.md
@@ -0,0 +1,293 @@
+# rm — Remove Files and Directories
+
+## Overview
+
+`rm` removes files and directories. It supports recursive removal,
+interactive prompting, forced deletion, and protects against removal
+of `/`, `.`, and `..`. Directory traversal uses `openat(2)` and
+`fdopendir(3)` for safe recursive descent.
+
+**Source**: `rm/rm.c` (single file)
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+rm [-dfiIPRrvWx] file ...
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-d` | Remove empty directories (like `rmdir`) |
+| `-f` | Force: no prompts, ignore nonexistent files |
+| `-i` | Interactive: prompt for each file |
+| `-I` | Prompt once before recursive removal or >3 files |
+| `-P` | Overwrite before delete (BSD; not on Linux) |
+| `-R` / `-r` | Recursive: remove directories and contents |
+| `-v` | Verbose: print each file as removed |
+| `-W` | Whiteout (BSD union fs; not on Linux) |
+| `-x` | Stay on one filesystem |
+
+## Source Analysis
+
+### Data Structures
+
+```c
+struct options_t {
+    bool force;         /* -f */
+    bool interactive;   /* -i */
+    bool prompt_once;   /* -I */
+    bool recursive;     /* -R/-r */
+    bool remove_empty;  /* -d */
+    bool verbose;       /* -v */
+    bool one_fs;        /* -x */
+    bool stdin_tty;     /* Whether stdin is a TTY */
+};
+```
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Parse options and dispatch |
+| `remove_path()` | Remove a single top-level argument |
+| `remove_simple_path()` | Remove non-directory file |
+| `remove_path_at()` | Recursive removal at directory fd |
+| `prompt_for_removal()` | Interactive prompt for single file |
+| `prompt_for_directory_descent()` | Prompt before entering directory |
+| `prompt_once()` | One-time batch prompt (`-I`) |
+| `prompt_yesno()` | Read yes/no from terminal |
+| `join_path()` | Path concatenation |
+| `path_is_writable()` | Check write access |
+
+### Safety Checks
+
+```c
+static int
+remove_path(const char *path, const struct options_t *opts)
+{
+    /* Reject "/" */
+    if (strcmp(path, "/") == 0) {
+        warnx("\"/\" may not be removed");
+        return 1;
+    }
+
+    /* Reject "." and ".." */
+    const char *base = basename(path);
+    if (strcmp(base, ".") == 0 || strcmp(base, "..") == 0) {
+        warnx("\".\" and \"..\" may not be removed");
+        return 1;
+    }
+
+    struct stat sb;
+    if (lstat(path, &sb) < 0) {
+        if (opts->force)
+            return 0;  /* Silently ignore */
+        warn("%s", path);
+        return 1;
+    }
+
+    if (S_ISDIR(sb.st_mode) && opts->recursive)
+        return remove_path_at(AT_FDCWD, path, &sb, opts);
+    else
+        return remove_simple_path(path, &sb, opts);
+}
+```
+
+### Recursive Removal
+
+```c
+static int
+remove_path_at(int dirfd, const char *path,
+               const struct stat *sb,
+               const struct options_t *opts)
+{
+    /* Prompt before descending */
+    if (opts->interactive &&
+        !prompt_for_directory_descent(path))
+        return 0;
+
+    /* Open directory safely */
+    int fd = openat(dirfd, path,
+                    O_RDONLY | O_DIRECTORY | O_NOFOLLOW);
+    if (fd < 0) {
+        warn("cannot open '%s'", path);
+        return 1;
+    }
+
+    /* One-filesystem check */
+    if (opts->one_fs) {
+        struct stat dir_sb;
+        fstat(fd, &dir_sb);
+        if (dir_sb.st_dev != sb->st_dev) {
+            warnx("skipping '%s' (different filesystem)", path);
+            close(fd);
+            return 1;
+        }
+    }
+
+    DIR *dp = fdopendir(fd);
+    struct dirent *ent;
+    int errors = 0;
+
+    while ((ent = readdir(dp)) != NULL) {
+        /* Skip . and .. */
+        if (ent->d_name[0] == '.' &&
+            (ent->d_name[1] == '\0' ||
+             (ent->d_name[1] == '.' && ent->d_name[2] == '\0')))
+            continue;
+
+        struct stat child_sb;
+        if (fstatat(fd, ent->d_name, &child_sb,
+                    AT_SYMLINK_NOFOLLOW) < 0) {
+            warn("%s/%s", path, ent->d_name);
+            errors = 1;
+            continue;
+        }
+
+        if (S_ISDIR(child_sb.st_mode)) {
+            /* Cycle detection: compare device/inode */
+            errors |= remove_path_at(fd,
+                          ent->d_name, &child_sb, opts);
+        } else {
+            /* Prompt and remove */
+            if (!opts->force &&
+                !prompt_for_removal(path, ent->d_name,
+                                    &child_sb, opts))
+                continue;
+            if (unlinkat(fd, ent->d_name, 0) < 0) {
+                warn("cannot remove '%s/%s'", path, ent->d_name);
+                errors = 1;
+            } else if (opts->verbose) {
+                printf("removed '%s/%s'\n", path, ent->d_name);
+            }
+        }
+    }
+    closedir(dp);
+
+    /* Remove the directory itself */
+    if (unlinkat(dirfd, path, AT_REMOVEDIR) < 0) {
+        warn("cannot remove '%s'", path);
+        errors = 1;
+    } else if (opts->verbose) {
+        printf("removed directory '%s'\n", path);
+    }
+
+    return errors;
+}
+```
+
+### Interactive Prompting
+
+```c
+static bool
+prompt_for_removal(const char *dir, const char *name,
+                   const struct stat *sb,
+                   const struct options_t *opts)
+{
+    if (opts->force)
+        return true;
+
+    /* Always prompt in -i mode */
+    if (opts->interactive) {
+        fprintf(stderr, "remove %s '%s/%s'? ",
+                filetype_name(sb->st_mode), dir, name);
+        return prompt_yesno();
+    }
+
+    /* Prompt for non-writable files (unless -f) */
+    if (!path_is_writable(sb) && opts->stdin_tty) {
+        fprintf(stderr, "remove write-protected %s '%s/%s'? ",
+                filetype_name(sb->st_mode), dir, name);
+        return prompt_yesno();
+    }
+
+    return true;
+}
+
+static bool
+prompt_yesno(void)
+{
+    char buf[128];
+    if (fgets(buf, sizeof(buf), stdin) == NULL)
+        return false;
+    return (buf[0] == 'y' || buf[0] == 'Y');
+}
+```
+
+### Batch Prompt (-I)
+
+```c
+static bool
+prompt_once(int count, const char *first_path,
+            const struct options_t *opts)
+{
+    if (!opts->prompt_once)
+        return true;
+
+    if (count > 3 || opts->recursive) {
+        fprintf(stderr,
+                "remove %d arguments%s? ",
+                count,
+                opts->recursive ? " recursively" : "");
+        return prompt_yesno();
+    }
+    return true;
+}
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `unlink(2)` | Remove file |
+| `unlinkat(2)` | Remove file/directory relative to dirfd |
+| `openat(2)` | Open directory for traversal |
+| `fdopendir(3)` | DIR stream from file descriptor |
+| `fstatat(2)` | Stat relative to dirfd |
+| `lstat(2)` | Stat without following symlinks |
+| `readdir(3)` | Read directory entries |
+| `rmdir(2)` | Remove empty directory |
+
+## Examples
+
+```sh
+# Remove a file
+rm file.txt
+
+# Force remove (no prompts)
+rm -f *.o
+
+# Recursive remove
+rm -rf build/
+
+# Interactive
+rm -ri important_dir/
+
+# Verbose
+rm -rv old_directory/
+
+# Prompt once
+rm -I *.log
+
+# Stay on one filesystem
+rm -rx /mounted/dir/
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | All files removed successfully |
+| 1    | Error removing one or more files |
+
+## Differences from GNU rm
+
+- No `--preserve-root` / `--no-preserve-root` (always refuses `/`)
+- No `--one-file-system` long option (uses `-x` instead)
+- No `--interactive=WHEN` (only `-i` and `-I`)
+- `-P` (overwrite) is BSD-only and not functional on Linux
+- `-W` (whiteout) is BSD-only
diff --git a/docs/handbook/corebinutils/sleep.md b/docs/handbook/corebinutils/sleep.md
new file mode 100644
index 0000000000..b562daff3a
--- /dev/null
+++ b/docs/handbook/corebinutils/sleep.md
@@ -0,0 +1,218 @@
+# sleep — Suspend Execution for an Interval
+
+## Overview
+
+`sleep` pauses for the specified duration. It supports fractional seconds,
+multiple arguments (accumulated), unit suffixes (`s`, `m`, `h`, `d`),
+and `SIGINFO`/`SIGUSR1` for progress reporting.
+
+**Source**: `sleep/sleep.c` (single file)
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+sleep number[suffix] ...
+```
+
+## Options
+
+No flags. Arguments are durations with optional unit suffixes.
+
+## Unit Suffixes
+
+| Suffix | Meaning | Multiplier |
+|--------|---------|------------|
+| `s` (default) | Seconds | 1 |
+| `m` | Minutes | 60 |
+| `h` | Hours | 3600 |
+| `d` | Days | 86400 |
+
+## Source Analysis
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Parse arguments and sleep loop |
+| `parse_interval()` | Parse numeric value with unit suffix |
+| `scale_interval()` | Apply unit multiplier with overflow check |
+| `seconds_to_timespec()` | Convert float seconds to `struct timespec` |
+| `seconds_from_timespec()` | Extract seconds from `struct timespec` |
+| `install_info_handler()` | Set up `SIGINFO`/`SIGUSR1` handler |
+| `report_remaining()` | Print remaining time on signal |
+| `die()` / `die_errno()` | Error handling |
+| `usage()` | Print usage and exit |
+
+### Argument Accumulation
+
+Multiple arguments are summed:
+
+```c
+int main(int argc, char *argv[])
+{
+    double total = 0.0;
+
+    for (int i = 1; i < argc; i++) {
+        double interval = parse_interval(argv[i]);
+        total += interval;
+    }
+
+    if (total > (double)TIME_T_MAX)
+        die("total sleep duration too large");
+
+    struct timespec ts = seconds_to_timespec(total);
+    install_info_handler();
+
+    /* Sleep loop with EINTR restart */
+    while (nanosleep(&ts, &ts) < 0) {
+        if (errno != EINTR)
+            die_errno("nanosleep");
+
+        /* SIGINFO handler may have reported progress */
+    }
+
+    return 0;
+}
+```
+
+### Interval Parsing
+
+```c
+static double
+parse_interval(const char *arg)
+{
+    char *end;
+    double val = strtod(arg, &end);
+
+    if (end == arg || val < 0)
+        die("invalid time interval: %s", arg);
+
+    /* Apply unit suffix */
+    if (*end != '\0') {
+        val = scale_interval(val, *end);
+        end++;
+    }
+
+    if (*end != '\0')
+        die("invalid time interval: %s", arg);
+
+    return val;
+}
+
+static double
+scale_interval(double val, char unit)
+{
+    switch (unit) {
+    case 's': return val;
+    case 'm': return val * 60.0;
+    case 'h': return val * 3600.0;
+    case 'd': return val * 86400.0;
+    default:
+        die("invalid unit: %c", unit);
+    }
+}
+```
+
+### Progress Reporting
+
+```c
+static volatile sig_atomic_t info_requested;
+
+static void
+signal_handler(int sig)
+{
+    (void)sig;
+    info_requested = 1;
+}
+
+static void
+install_info_handler(void)
+{
+    struct sigaction sa = {
+        .sa_handler = signal_handler,
+        .sa_flags = 0,
+    };
+    sigemptyset(&sa.sa_mask);
+
+#ifdef SIGINFO
+    sigaction(SIGINFO, &sa, NULL);
+#endif
+    sigaction(SIGUSR1, &sa, NULL);
+}
+
+static void
+report_remaining(const struct timespec *remaining)
+{
+    double secs = seconds_from_timespec(remaining);
+    fprintf(stderr, "sleep: about %.1f second(s) remaining\n", secs);
+    info_requested = 0;
+}
+```
+
+When `nanosleep` returns with `EINTR` and the remaining time is in `ts`,
+the handler flag is checked and progress is reported before restarting.
+
+### Overflow Protection
+
+```c
+static struct timespec
+seconds_to_timespec(double sec)
+{
+    struct timespec ts;
+
+    if (sec >= (double)TIME_T_MAX) {
+        ts.tv_sec = TIME_T_MAX;
+        ts.tv_nsec = 0;
+    } else {
+        ts.tv_sec = (time_t)sec;
+        ts.tv_nsec = (long)((sec - ts.tv_sec) * 1e9);
+    }
+
+    return ts;
+}
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `nanosleep(2)` | Sleep with nanosecond precision |
+| `sigaction(2)` | Install signal handlers |
+
+## Examples
+
+```sh
+# Sleep 5 seconds
+sleep 5
+
+# Fractional seconds
+sleep 0.5
+
+# With units
+sleep 2m      # 2 minutes
+sleep 1.5h    # 90 minutes
+sleep 1d      # 24 hours
+
+# Multiple arguments (accumulated)
+sleep 1m 30s  # 90 seconds total
+
+# Check remaining time (send SIGUSR1 from another terminal)
+kill -USR1 $(pgrep sleep)
+# → "sleep: about 42.3 second(s) remaining"
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success (slept for full duration) |
+| 1    | Error (invalid argument) |
+
+## Differences from GNU sleep
+
+- POSIX-compliant with BSD extensions
+- Supports `SIGINFO` (on systems that have it, otherwise `SIGUSR1`)
+- Same unit suffix support (`s`, `m`, `h`, `d`)
+- Multiple arguments are accumulated (same as GNU)
diff --git a/docs/handbook/corebinutils/test.md b/docs/handbook/corebinutils/test.md
new file mode 100644
index 0000000000..11b429ab2a
--- /dev/null
+++ b/docs/handbook/corebinutils/test.md
@@ -0,0 +1,248 @@
+# test — Evaluate Conditional Expressions
+
+## Overview
+
+`test` (also invoked as `[`) evaluates file attributes, string comparisons,
+and integer arithmetic, returning an exit status of 0 (true) or 1 (false).
+It uses a recursive descent parser with short-circuit evaluation and
+supports both POSIX and BSD extensions.
+
+**Source**: `test/test.c` (single file)
+**Origin**: BSD 4.4, University of California, Berkeley
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+test expression
+[ expression ]
+```
+
+When invoked as `[`, the last argument must be `]`.
+
+## Source Analysis
+
+### Parser Architecture
+
+```c
+struct parser {
+    int argc;
+    char **argv;
+    int pos;     /* Current argument index */
+};
+
+enum token {
+    TOK_OPERAND,   /* String/number operand */
+    TOK_UNARY,     /* Unary operator (-f, -d, etc.) */
+    TOK_BINARY,    /* Binary operator (-eq, =, etc.) */
+    TOK_NOT,       /* ! */
+    TOK_AND,       /* -a */
+    TOK_OR,        /* -o */
+    TOK_LPAREN,    /* ( */
+    TOK_RPAREN,    /* ) */
+    TOK_END,       /* End of arguments */
+};
+```
+
+### Operator Table
+
+```c
+struct operator {
+    const char *name;
+    enum token type;
+    int (*eval)(/* ... */);
+};
+```
+
+### Recursive Descent Grammar
+
+```
+parse_expr()
+  └── parse_oexpr()      /* -o (OR, lowest precedence) */
+        └── parse_aexpr()    /* -a (AND) */
+              └── parse_nexpr()  /* ! (NOT) */
+                    └── parse_primary() /* atoms, ( expr ) */
+```
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Entry: handle `[`/`test` invocation, drive parser |
+| `current_arg()` | Return current argument |
+| `peek_arg()` | Look at next argument |
+| `advance_arg()` | Consume current argument |
+| `lex_token()` | Classify current argument as token type |
+| `find_operator()` | Look up operator in table |
+| `parse_primary()` | Parse `( expr )`, unary ops, binary ops |
+| `parse_nexpr()` | Parse `! expression` |
+| `parse_aexpr()` | Parse `expr -a expr` |
+| `parse_oexpr()` | Parse `expr -o expr` |
+| `parse_binop()` | Evaluate binary operators |
+| `evaluate_file_test()` | Evaluate file test primaries |
+| `compare_integers()` | Integer comparison |
+| `compare_mtime()` | File modification time comparison |
+| `newer_file()` | `-nt` test |
+| `older_file()` | `-ot` test |
+| `same_file()` | `-ef` test |
+| `parse_int()` | Parse integer with error checking |
+| `effective_access()` | `eaccess(2)` or `faccessat(AT_EACCESS)` |
+
+### File Test Primaries
+
+| Operator | Test | System Call |
+|----------|------|------------|
+| `-b file` | Block special | `stat(2)` + `S_ISBLK` |
+| `-c file` | Character special | `stat(2)` + `S_ISCHR` |
+| `-d file` | Directory | `stat(2)` + `S_ISDIR` |
+| `-e file` | Exists | `stat(2)` |
+| `-f file` | Regular file | `stat(2)` + `S_ISREG` |
+| `-g file` | Set-GID bit | `stat(2)` + `S_ISGID` |
+| `-h file` | Symbolic link | `lstat(2)` + `S_ISLNK` |
+| `-k file` | Sticky bit | `stat(2)` + `S_ISVTX` |
+| `-L file` | Symbolic link | `lstat(2)` + `S_ISLNK` |
+| `-p file` | Named pipe (FIFO) | `stat(2)` + `S_ISFIFO` |
+| `-r file` | Readable | `eaccess(2)` or `faccessat(2)` |
+| `-s file` | Non-zero size | `stat(2)` + `st_size > 0` |
+| `-S file` | Socket | `stat(2)` + `S_ISSOCK` |
+| `-t fd` | Is a terminal | `isatty(3)` |
+| `-u file` | Set-UID bit | `stat(2)` + `S_ISUID` |
+| `-w file` | Writable | `eaccess(2)` or `faccessat(2)` |
+| `-x file` | Executable | `eaccess(2)` or `faccessat(2)` |
+| `-O file` | Owned by EUID | `stat(2)` + `st_uid == geteuid()` |
+| `-G file` | Group matches EGID | `stat(2)` + `st_gid == getegid()` |
+
+### String Operators
+
+| Operator | Description |
+|----------|-------------|
+| `-z string` | String is zero length |
+| `-n string` | String is non-zero length |
+| `s1 = s2` | Strings are identical |
+| `s1 == s2` | Strings are identical (alias) |
+| `s1 != s2` | Strings differ |
+| `s1 < s2` | String less than (lexicographic) |
+| `s1 > s2` | String greater than (lexicographic) |
+
+### Integer Operators
+
+| Operator | Description |
+|----------|-------------|
+| `n1 -eq n2` | Equal |
+| `n1 -ne n2` | Not equal |
+| `n1 -lt n2` | Less than |
+| `n1 -le n2` | Less or equal |
+| `n1 -gt n2` | Greater than |
+| `n1 -ge n2` | Greater or equal |
+
+### File Comparison Operators
+
+| Operator | Description |
+|----------|-------------|
+| `f1 -nt f2` | f1 is newer than f2 |
+| `f1 -ot f2` | f1 is older than f2 |
+| `f1 -ef f2` | f1 and f2 are the same file (device + inode) |
+
+### Short-Circuit Evaluation
+
+```c
+static int
+parse_oexpr(struct parser *p)
+{
+    int result = parse_aexpr(p);
+
+    while (current_is(p, "-o")) {
+        advance_arg(p);
+        int right = parse_aexpr(p);
+        result = result || right;  /* Short-circuit */
+    }
+
+    return result;
+}
+
+static int
+parse_aexpr(struct parser *p)
+{
+    int result = parse_nexpr(p);
+
+    while (current_is(p, "-a")) {
+        advance_arg(p);
+        int right = parse_nexpr(p);
+        result = result && right;  /* Short-circuit */
+    }
+
+    return result;
+}
+```
+
+### Bracket Mode
+
+```c
+int main(int argc, char *argv[])
+{
+    /* If invoked as "[", last arg must be "]" */
+    const char *progname = basename(argv[0]);
+    if (strcmp(progname, "[") == 0) {
+        if (argc < 2 || strcmp(argv[argc - 1], "]") != 0)
+            errx(2, "missing ]");
+        argc--;  /* Remove trailing ] */
+    }
+
+    if (argc <= 1)
+        return 1;  /* No expression → false */
+
+    struct parser p = { argc - 1, argv + 1, 0 };
+    int result = parse_oexpr(&p);
+
+    if (p.pos < p.argc)
+        errx(2, "unexpected argument: %s", current_arg(&p));
+
+    return !result;  /* 0 = true, 1 = false */
+}
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `stat(2)` | File attribute tests |
+| `lstat(2)` | Symlink tests (`-h`, `-L`) |
+| `eaccess(2)` / `faccessat(2)` | Permission tests (`-r`, `-w`, `-x`) |
+| `isatty(3)` | Terminal test (`-t`) |
+| `geteuid(3)` / `getegid(3)` | Ownership tests (`-O`, `-G`) |
+
+## Examples
+
+```sh
+# File exists
+test -f /etc/passwd && echo "exists"
+
+# Using [ syntax
+[ -d /tmp ] && echo "is a directory"
+
+# String comparison
+[ "$var" = "hello" ] && echo "match"
+
+# Integer comparison
+[ "$count" -gt 10 ] && echo "more than 10"
+
+# Combined with AND
+[ -f file.txt -a -r file.txt ] && echo "readable file"
+
+# File newer than another
+[ config.new -nt config.old ] && echo "config updated"
+
+# Negation
+[ ! -e /tmp/lockfile ] && echo "no lock"
+
+# Parenthesized expression
+[ \( -f a -o -f b \) -a -r c ]
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Expression is true |
+| 1    | Expression is false |
+| 2    | Invalid expression (syntax error) |
diff --git a/docs/handbook/corebinutils/timeout.md b/docs/handbook/corebinutils/timeout.md
new file mode 100644
index 0000000000..3186b42886
--- /dev/null
+++ b/docs/handbook/corebinutils/timeout.md
@@ -0,0 +1,297 @@
+# timeout — Run a Command with a Time Limit
+
+## Overview
+
+`timeout` runs a command and kills it if it exceeds a time limit. It
+supports a two-stage kill strategy: first send a configurable signal
+(default `SIGTERM`), then optionally send a second kill signal after
+a grace period. Uses `prctl(PR_SET_CHILD_SUBREAPER)` to reliably
+reap grandchild processes.
+
+**Source**: `timeout/timeout.c` (single file)
+**Origin**: BSD/Project Tick
+**License**: BSD-3-Clause
+
+## Synopsis
+
+```
+timeout [--preserve-status] [--foreground] [-k duration]
+        [-s signal] [--verbose] duration command [arg ...]
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-s signal` | Signal to send on timeout (default: `SIGTERM`) |
+| `-k duration` | Kill signal to send after grace period |
+| `--preserve-status` | Exit with the command's status, not 124 |
+| `--foreground` | Don't create a new process group |
+| `--verbose` | Print diagnostics when sending signals |
+
+## Source Analysis
+
+### Constants
+
+```c
+#define EXIT_TIMEOUT   124   /* Command timed out */
+#define EXIT_INVALID   125   /* timeout itself failed */
+#define EXIT_CMD_ERROR 126   /* Command found but not executable */
+#define EXIT_CMD_NOENT 127   /* Command not found */
+```
+
+### Data Structures
+
+```c
+struct options {
+    bool foreground;         /* --foreground */
+    bool preserve;           /* --preserve-status */
+    bool verbose;            /* --verbose */
+    bool kill_after_set;     /* -k was specified */
+    int timeout_signal;      /* -s signal (default SIGTERM) */
+    double duration;         /* Primary timeout */
+    double kill_after;       /* Grace period before SIGKILL */
+    const char *command_name;
+    char **command_argv;
+};
+
+struct child_state {
+    pid_t pid;
+    int status;
+    bool exited;
+    bool signaled;
+};
+
+struct runtime_state {
+    struct child_state child;
+    bool first_timeout_sent;
+    bool kill_sent;
+};
+
+enum deadline_kind {
+    DEADLINE_TIMEOUT,     /* Primary timeout */
+    DEADLINE_KILL,        /* Kill-after grace period */
+};
+```
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Parse options, fork, wait with timers |
+| `parse_duration_or_die()` | Parse duration string (fractional seconds + units) |
+| `monotonic_seconds()` | Read `CLOCK_MONOTONIC` |
+| `enable_subreaper_or_die()` | Call `prctl(PR_SET_CHILD_SUBREAPER)` |
+| `send_signal_to_command()` | Send signal to child/process group |
+| `arm_second_timer()` | Set up kill-after timer |
+| `reap_children()` | Wait for all descendants |
+| `child_exec()` | Child process: exec the command |
+
+### Signal Table
+
+`timeout` shares the same signal table as `kill`:
+
+```c
+/* Same SIGNAL_ENTRY() macro and signal_entry table */
+/* Supports named signals: TERM, KILL, HUP, INT, etc. */
+/* Supports SIGRTMIN+n notation */
+```
+
+### Duration Parsing
+
+```c
+static double
+parse_duration_or_die(const char *str)
+{
+    char *end;
+    double val = strtod(str, &end);
+
+    if (end == str || val < 0)
+        errx(EXIT_INVALID, "invalid duration: %s", str);
+
+    /* Apply unit suffix */
+    switch (*end) {
+    case '\0':
+    case 's': break;          /* seconds (default) */
+    case 'm': val *= 60; break;
+    case 'h': val *= 3600; break;
+    case 'd': val *= 86400; break;
+    default:
+        errx(EXIT_INVALID, "invalid unit: %c", *end);
+    }
+
+    return val;
+}
+```
+
+### Subreaper
+
+The Linux-specific `prctl(PR_SET_CHILD_SUBREAPER)` ensures that orphaned
+grandchild processes are reparented to `timeout` instead of PID 1:
+
+```c
+static void
+enable_subreaper_or_die(void)
+{
+    if (prctl(PR_SET_CHILD_SUBREAPER, 1) < 0)
+        err(EXIT_INVALID, "prctl(PR_SET_CHILD_SUBREAPER)");
+}
+```
+
+### Two-Stage Kill Strategy
+
+```
+┌──────────────────────────────────────────────────┐
+│  timeout 30 -k 5 -s TERM ./long_running_task     │
+│                                                   │
+│  1. Fork and exec ./long_running_task             │
+│  2. Wait up to 30 seconds                         │
+│  3. If still running: send SIGTERM                 │
+│  4. Wait up to 5 more seconds (-k 5)              │
+│  5. If still running: send SIGKILL                 │
+│  6. Reap all children                              │
+└──────────────────────────────────────────────────┘
+```
+
+```c
+/* Primary timeout handler */
+static void
+handle_timeout(struct runtime_state *state,
+               const struct options *opts)
+{
+    if (opts->verbose)
+        warnx("sending signal %s to command '%s'",
+              signal_name_for_number(opts->timeout_signal),
+              opts->command_name);
+
+    send_signal_to_command(state, opts->timeout_signal, opts);
+    state->first_timeout_sent = true;
+
+    /* Arm kill-after timer if specified */
+    if (opts->kill_after_set)
+        arm_second_timer(opts->kill_after);
+}
+
+/* Kill-after timer handler */
+static void
+handle_kill_after(struct runtime_state *state,
+                  const struct options *opts)
+{
+    if (opts->verbose)
+        warnx("sending SIGKILL to command '%s'",
+              opts->command_name);
+
+    send_signal_to_command(state, SIGKILL, opts);
+    state->kill_sent = true;
+}
+```
+
+### Process Group Management
+
+```c
+static void
+send_signal_to_command(struct runtime_state *state,
+                       int sig, const struct options *opts)
+{
+    if (opts->foreground) {
+        /* Send to child only */
+        kill(state->child.pid, sig);
+    } else {
+        /* Send to entire process group */
+        kill(-state->child.pid, sig);
+    }
+}
+
+static void
+child_exec(const struct options *opts)
+{
+    if (!opts->foreground) {
+        /* Create new process group */
+        setpgid(0, 0);
+    }
+
+    execvp(opts->command_name, opts->command_argv);
+
+    /* exec failed */
+    int code = (errno == ENOENT) ? EXIT_CMD_NOENT : EXIT_CMD_ERROR;
+    err(code, "exec '%s'", opts->command_name);
+}
+```
+
+### Timer Implementation
+
+Uses `timer_create(2)` with `CLOCK_MONOTONIC`:
+
+```c
+static void
+arm_timer(double seconds)
+{
+    struct itimerspec its = {
+        .it_value = {
+            .tv_sec = (time_t)seconds,
+            .tv_nsec = (long)((seconds - (time_t)seconds) * 1e9),
+        },
+    };
+
+    timer_t timerid;
+    struct sigevent sev = {
+        .sigev_notify = SIGEV_SIGNAL,
+        .sigev_signo = SIGALRM,
+    };
+
+    timer_create(CLOCK_MONOTONIC, &sev, &timerid);
+    timer_settime(timerid, 0, &its, NULL);
+}
+```
+
+## System Calls Used
+
+| Syscall | Purpose |
+|---------|---------|
+| `fork(2)` | Create child process |
+| `execvp(3)` | Execute the command |
+| `kill(2)` | Send signal to child/group |
+| `waitpid(2)` | Wait for child/grandchild exit |
+| `setpgid(2)` | Create new process group |
+| `prctl(2)` | `PR_SET_CHILD_SUBREAPER` |
+| `timer_create(2)` | POSIX timer for deadline |
+| `timer_settime(2)` | Arm the timer |
+| `clock_gettime(2)` | `CLOCK_MONOTONIC` for elapsed time |
+| `sigaction(2)` | Signal handler setup |
+
+## Examples
+
+```sh
+# Basic timeout (30 seconds)
+timeout 30 make -j4
+
+# With kill-after grace period
+timeout -k 10 60 ./server
+
+# Custom signal
+timeout -s HUP 300 ./daemon
+
+# Verbose
+timeout --verbose 5 sleep 100
+# timeout: sending signal TERM to command 'sleep'
+
+# Preserve exit status
+timeout --preserve-status 10 ./test_runner
+echo $?  # Exit code from test_runner, not 124
+
+# Fractional seconds
+timeout 2.5 curl https://example.com
+
+# Foreground (no process group)
+timeout --foreground 30 ./interactive_app
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 124  | Command timed out |
+| 125  | `timeout` itself failed |
+| 126  | Command found but not executable |
+| 127  | Command not found |
+| other | Command's exit status (or 128+signal if killed) |