snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
ccad4205162d4b1141935edc742a6e0b20449cc9
bare-operating-system/packages/bare-os-seeder/kernel/share/man/man.json
T

2 lines
425 KiB
JSON
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{"schemaVersion":1,"generatedAt":"2026-04-05T08:36:49.114Z","pages":[{"name":"arch","section":1,"title":"arch","synopsis":["arch [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of arch. Full behavior is defined in packages/bare-os-coreutils/src/arch.js.","options":[],"keywords":["arch","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"awk","section":1,"title":"pattern scanning and processing language","synopsis":["awk [OPTION]... [OPERAND]..."],"description":"Pattern-directed scanning and processing. Engine in lib/awk-engine.js; Issue 7–inspired awk subset with documented bounds (includes next/nextfile control flow).","options":[],"keywords":["awk","pattern","field","script"],"seeAlso":[{"name":"sed","section":1},{"name":"grep","section":1}],"bareOsNotes":"See handbook ch.9 for divergence from Issue 7.","examples":[{"caption":"print column 1","code":"awk '{print $1}' file.txt"},{"caption":"field separator","code":"awk -F: '{print $1}' /etc/passwd"},{"caption":"sum numbers in first column","code":"awk '{s+=$1} END{print s}' nums.txt"},{"caption":"lines matching /re/","code":"awk '/error/{print NR\": \"$0}' log.txt"}],"listCategory":"coreutils"},{"name":"baretop","section":1,"title":"baretop","synopsis":["baretop [OPTION]... [OPERAND]..."],"description":"Full-screen session and operator dashboard (htop-inspired): metrics, logical process table from /proc/bare_os/process_table.json, /proc/bare_os mirrors, mem/load meters, eleven tabs, themes and filters. Requires a TTY. See packages/bare-os-coreutils/src/baretop.js for keys and BARE_TOP_* environment variables.","options":[],"keywords":["baretop","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"btop","section":1,"title":"btop","synopsis":["btop [OPTION]... [OPERAND]..."],"description":"Same program as baretop(1); the /bin/btop bundle is identical to baretop. Full-screen session dashboard with logical process table, metrics, and operator /proc panels. See baretop(1) and packages/bare-os-coreutils/src/baretop.js.","options":[],"keywords":["btop","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"base32","section":1,"title":"base32","synopsis":["base32 [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of base32. Full behavior is defined in packages/bare-os-coreutils/src/base32.js.","options":[],"keywords":["base32","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"base64","section":1,"title":"base64","synopsis":["base64 [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of base64. Full behavior is defined in packages/bare-os-coreutils/src/base64.js.","options":[],"keywords":["base64","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"basename","section":1,"title":"strip directory and suffix from pathnames","synopsis":["basename [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of strip directory and suffix from pathnames. Full behavior is defined in packages/bare-os-coreutils/src/basename.js.","options":[],"keywords":["basename","bare-os","coreutils"],"examples":[{"caption":"strip directory","code":"basename /home/user/docs/readme.md"},{"caption":"strip suffix","code":"basename -s .md /path/readme.md"}],"listCategory":"coreutils"},{"name":"basenc","section":1,"title":"basenc","synopsis":["basenc [OPTION]... [OPERAND]..."],"description":"Encode or decode bytes using Base16 (--base16), Base32 (--base32, RFC-style), or Base64 (--base64). Full behavior is defined in packages/bare-os-coreutils/src/basenc.js.","options":[],"keywords":["basenc","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"cat","section":1,"title":"concatenate and print files","synopsis":["cat [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of concatenate and print files. Full behavior is defined in packages/bare-os-coreutils/src/cat.js.","options":[],"keywords":["cat","bare-os","coreutils"],"examples":[{"caption":"stdout several files","code":"cat a.txt b.txt"},{"caption":"number lines (use nl)","code":"cat -n file.txt # if supported; else nl file"},{"caption":"here-string via echo pipe","code":"echo hello | cat"}],"listCategory":"coreutils"},{"name":"chgrp","section":1,"title":"change file group ownership","synopsis":["chgrp [OPTION]... [OPERAND]..."],"description":"Updates group metadata on the personal Hyperdrive for writable paths (session home, $HOME, /tmp, /var/log).","options":[],"keywords":["chgrp","bare-os","coreutils"],"bareOsNotes":"Uses vfs.chown with preserved uid; system image paths are read-only. See packages/bare-os-booter/lib/vfs.js.","examples":[{"caption":"set group by name","code":"chgrp guest shared.conf"}],"listCategory":"coreutils"},{"name":"chmod","section":1,"title":"change file mode bits","synopsis":["chmod MODE FILE...","MODE is octal (e.g. 644) or symbolic (e.g. u+rw)"],"description":"Sets file mode bits on the VFS. Supports POSIX-style symbolic modes (u/g/o/a, +/-/=, rwxX) and octal modes.","options":[],"keywords":["chmod","mode","permission","octal","symbolic"],"diagnostics":["chmod: No such file","chmod: invalid mode"],"bareOsNotes":"Applies to Hyperdrive metadata; not a host inode.","examples":[{"caption":"octal","code":"chmod 644 ~/.profile"},{"caption":"recursive-ish (run find + chmod per file)","code":"find . -type f -name \"*.sh\" -print"},{"caption":"symbolic user bits","code":"chmod u+x script.sh"},{"caption":"all read, owner write","code":"chmod a+r,u+w shared.txt"}],"listCategory":"coreutils"},{"name":"chown","section":1,"title":"change file owner and group","synopsis":["chown [OPTION]... [OPERAND]..."],"description":"Updates uid/gid metadata on the personal Hyperdrive where the booter allows writes; euid 0 may set any owner.","options":[],"keywords":["chown","bare-os","coreutils"],"bareOsNotes":"OWNER/GROUP may be numeric or root/guest/nobody/current user. See vfs chown and identity env UID/GID.","examples":[{"caption":"group only","code":"chown :guest file.txt"},{"caption":"numeric ids","code":"chown 1000:1000 notes.txt"}],"listCategory":"coreutils"},{"name":"cksum","section":1,"title":"write file checksums and sizes","synopsis":["cksum [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of write file checksums and sizes. Full behavior is defined in packages/bare-os-coreutils/src/cksum.js.","options":[],"keywords":["cksum","bare-os","coreutils"],"examples":[{"caption":"checksum file","code":"cksum iso.img"},{"caption":"verify pipeline","code":"cat f | cksum"}],"listCategory":"coreutils"},{"name":"clear","section":1,"title":"clear the terminal screen","synopsis":["clear [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of clear the terminal screen. Full behavior is defined in packages/bare-os-coreutils/src/clear.js.","options":[],"keywords":["clear","bare-os","coreutils"],"examples":[{"caption":"wipe screen","code":"clear"}],"listCategory":"coreutils"},{"name":"comm","section":1,"title":"comm","synopsis":["comm [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of comm. Full behavior is defined in packages/bare-os-coreutils/src/comm.js.","options":[],"keywords":["comm","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"cmp","section":1,"title":"cmp","synopsis":["cmp [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of cmp. Full behavior is defined in packages/bare-os-coreutils/src/cmp.js.","options":[],"keywords":["cmp","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"cp","section":1,"title":"copy files","synopsis":["cp [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of copy files. Full behavior is defined in packages/bare-os-coreutils/src/cp.js.","options":[],"keywords":["cp","bare-os","coreutils"],"examples":[{"caption":"copy file","code":"cp src.txt dest.txt"},{"caption":"into directory","code":"cp a b c ~/backup/"},{"caption":"preserve implied (if implemented)","code":"cp -R proj proj.bak"}],"listCategory":"coreutils"},{"name":"crontab","section":1,"title":"user crontab manipulation","synopsis":["crontab [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of user crontab manipulation. Full behavior is defined in packages/bare-os-coreutils/src/crontab.js.","options":[],"keywords":["crontab","bare-os","coreutils"],"examples":[{"caption":"list jobs","code":"crontab -l"},{"caption":"install from file","code":"crontab ~/.crontab"},{"caption":"remove all","code":"crontab -r"}],"listCategory":"coreutils"},{"name":"curl","section":1,"title":"curl","synopsis":["curl [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of curl. Full behavior is defined in packages/bare-os-coreutils/src/curl.js.","options":[],"keywords":["curl","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"cut","section":1,"title":"cut out selected fields of each line","synopsis":["cut [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of cut out selected fields of each line. Full behavior is defined in packages/bare-os-coreutils/src/cut.js.","options":[],"keywords":["cut","bare-os","coreutils"],"examples":[{"caption":"fields by delimiter","code":"cut -d: -f1,3 /etc/passwd"},{"caption":"characters","code":"cut -c1-16 file.txt"}],"listCategory":"coreutils"},{"name":"date","section":1,"title":"display or set date and time","synopsis":["date [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of display or set date and time. Full behavior is defined in packages/bare-os-coreutils/src/date.js.","options":[],"keywords":["date","bare-os","coreutils"],"examples":[{"caption":"RFC-ish output","code":"date"},{"caption":"epoch seconds","code":"date +%s"}],"listCategory":"coreutils"},{"name":"dd","section":1,"title":"dd","synopsis":["dd [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of dd. Full behavior is defined in packages/bare-os-coreutils/src/dd.js.","options":[],"keywords":["dd","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"df","section":1,"title":"df","synopsis":["df [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of df. Full behavior is defined in packages/bare-os-coreutils/src/df.js.","options":[],"keywords":["df","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"diff","section":1,"title":"diff","synopsis":["diff [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of diff. Full behavior is defined in packages/bare-os-coreutils/src/diff.js.","options":[],"keywords":["diff","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"dir","section":1,"title":"dir","synopsis":["dir [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of dir. Full behavior is defined in packages/bare-os-coreutils/src/dir.js.","options":[],"keywords":["dir","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"dirname","section":1,"title":"return directory portion of a pathname","synopsis":["dirname [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return directory portion of a pathname. Full behavior is defined in packages/bare-os-coreutils/src/dirname.js.","options":[],"keywords":["dirname","bare-os","coreutils"],"examples":[{"caption":"parent path","code":"dirname /a/b/c.txt"},{"caption":"compose with basename","code":"p=/x/y/z; echo $(dirname $p)/$(basename $p)"}],"listCategory":"coreutils"},{"name":"dircolors","section":1,"title":"dircolors","synopsis":["dircolors [-b] [FILE]","dircolors -p"],"description":"Print LS_COLORS from a dircolors database (GNU subset: TERM blocks, key/value pairs). -p prints the default Bare OS database.","options":[{"flag":"-b, --sh","meaning":"Bourne-shell export LS_COLORS"},{"flag":"-p, --print-database","meaning":"Print default database"}],"keywords":["dircolors","LS_COLORS","color"],"bareOsNotes":"FILE read via VFS.","listCategory":"coreutils"},{"name":"du","section":1,"title":"estimate file space usage","synopsis":["du [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of estimate file space usage. Full behavior is defined in packages/bare-os-coreutils/src/du.js.","options":[],"keywords":["du","bare-os","coreutils"],"examples":[{"caption":"sizes under cwd","code":"du ."},{"caption":"human (if supported)","code":"du -h ~"}],"listCategory":"coreutils"},{"name":"edit","section":1,"title":"edit","synopsis":["edit [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of edit. Full behavior is defined in packages/bare-os-coreutils/src/edit.js.","options":[],"keywords":["edit","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"echo","section":1,"title":"write arguments to standard output","synopsis":["echo [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of write arguments to standard output. Full behavior is defined in packages/bare-os-coreutils/src/echo.js.","options":[],"keywords":["echo","bare-os","coreutils"],"examples":[{"caption":"literal","code":"echo hello world"},{"caption":"no newline (if -n supported)","code":"echo -n OK"}],"listCategory":"coreutils"},{"name":"env","section":1,"title":"set the environment for command invocation","synopsis":["env [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of set the environment for command invocation. Full behavior is defined in packages/bare-os-coreutils/src/env.js.","options":[],"keywords":["env","bare-os","coreutils"],"examples":[{"caption":"print environment","code":"env"},{"caption":"run with override","code":"env PATH=/bin:/usr/bin man ls"}],"listCategory":"coreutils"},{"name":"exit","section":1,"title":"exit the shell or booter session","synopsis":["exit [status]"],"description":"When run as /bin/exit, requests the booter to end the session via ctx.requestBooterExit. Status defaults to 0.","options":[],"keywords":["exit","bare-os","coreutils"],"bareOsNotes":"Also available as a shell builtin with different wiring.","examples":[{"caption":"leave session with status","code":"exit 0"},{"caption":"from script","code":"/bin/exit 42"}],"listCategory":"coreutils"},{"name":"expand","section":1,"title":"expand","synopsis":["expand [-t LIST] [FILE]..."],"description":"Convert tabs to spaces. One -t width uses uniform stops; a comma-separated increasing list uses POSIX-style tab stops (repeating interval from the last two stops).","options":[{"flag":"-t LIST","meaning":"Tab width or comma-separated tab stops (e.g. 8 or 1,4,8)."}],"keywords":["expand","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"expr","section":1,"title":"expr","synopsis":["expr [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of expr. Full behavior is defined in packages/bare-os-coreutils/src/expr.js.","options":[],"keywords":["expr","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"factor","section":1,"title":"factor","synopsis":["factor [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of factor. Full behavior is defined in packages/bare-os-coreutils/src/factor.js.","options":[],"keywords":["factor","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"false","section":1,"title":"return false value","synopsis":["false [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return false value. Full behavior is defined in packages/bare-os-coreutils/src/false.js.","options":[],"keywords":["false","bare-os","coreutils"],"examples":[{"caption":"force failure in pipeline tests","code":"false; echo $?"}],"listCategory":"coreutils"},{"name":"find","section":1,"title":"find files","synopsis":["find [PATH...] [EXPRESSION]"],"description":"Walks directories and applies expressions (-name, -type, -print, -maxdepth, logical -and/-or/-not).","options":[],"keywords":["find","directory","walk","search"],"bareOsNotes":"Expression syntax is a simplified subset.","examples":[{"caption":"files by name glob","code":"find . -name \"*.js\""},{"caption":"directories only","code":"find . -type d"},{"caption":"max depth","code":"find . -maxdepth 2 -type f"},{"caption":"OR names","code":"find . \\( -name \"*.c\" -o -name \"*.h\" \\)"}],"listCategory":"coreutils"},{"name":"fmt","section":1,"title":"fmt","synopsis":["fmt [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of fmt. Full behavior is defined in packages/bare-os-coreutils/src/fmt.js.","options":[],"keywords":["fmt","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"fold","section":1,"title":"fold","synopsis":["fold [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of fold. Full behavior is defined in packages/bare-os-coreutils/src/fold.js.","options":[],"keywords":["fold","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"getconf","section":1,"title":"get configuration values","synopsis":["getconf [OPTION]... [OPERAND]..."],"description":"Prints a fixed subset of configuration limits for Bare OS (JavaScript runtime and VFS). There is no host sysconf(3); values are documented constants, not live kernel queries.","options":[{"flag":"-a","meaning":"Write all known variables (name then value per pair)"}],"keywords":["getconf","bare-os","coreutils"],"bareOsNotes":"Unknown variable names exit with status 1. Not a full Issue 7 getconf implementation.","examples":[{"caption":"path length limit","code":"getconf PATH_MAX"},{"caption":"list known names and values","code":"getconf -a"}],"listCategory":"coreutils"},{"name":"getfacl","section":1,"title":"getfacl","synopsis":["getfacl [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of getfacl. Full behavior is defined in packages/bare-os-coreutils/src/getfacl.js.","options":[],"keywords":["getfacl","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"git-pear","section":1,"title":"git-pear","synopsis":["git-pear [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of git-pear. Full behavior is defined in packages/bare-os-coreutils/src/git-pear.js.","options":[],"keywords":["git-pear","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"grep","section":1,"title":"pattern matching utility","synopsis":["grep [-E|-F] [-i] [-v] [-n] [-c] [-l] [-q] [-s] [-H|-h] [-e pat] ... [-f file] ... [pattern] [file...]"],"description":"Searches input or files for lines matching a pattern. Uses JavaScript RegExp unless -F (fixed string). Not bit-identical to GNU grep.","options":[{"flag":"-E","meaning":"Extended regex (accepted; patterns use JS RegExp)"},{"flag":"-F","meaning":"Fixed string match"},{"flag":"-i","meaning":"Ignore case"},{"flag":"-v","meaning":"Invert match"},{"flag":"-n","meaning":"Prefix lines with line number"},{"flag":"-c","meaning":"Count matching lines only"},{"flag":"-l","meaning":"List files with matches"},{"flag":"-q","meaning":"Quiet (exit status only)"},{"flag":"-s","meaning":"Suppress error messages"},{"flag":"-H / -h","meaning":"Force / suppress filename prefix"},{"flag":"-e pat","meaning":"Specify pattern"},{"flag":"-f file","meaning":"Read patterns from file"}],"keywords":["grep","search","regex","pattern","filter"],"seeAlso":[{"name":"sed","section":1},{"name":"awk","section":1}],"bareOsNotes":"UTF-16 strings and JS regex differ from strict POSIX/GNU.","examples":[{"caption":"recursive feel (grep each file)","code":"grep -n error *.log"},{"caption":"case insensitive","code":"grep -i todo NOTES.md"},{"caption":"invert (lines without)","code":"grep -v '^#' config"},{"caption":"fixed string (no regex)","code":"grep -F \"v1.0\" CHANGES"},{"caption":"count matches","code":"grep -c FAIL build.log"},{"caption":"only filenames","code":"grep -l main *.js"},{"caption":"multiple patterns","code":"grep -e foo -e bar file.txt"}],"listCategory":"coreutils"},{"name":"groups","section":1,"title":"groups","synopsis":["groups [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of groups. Full behavior is defined in packages/bare-os-coreutils/src/groups.js.","options":[],"keywords":["groups","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"head","section":1,"title":"copy the first part of files","synopsis":["head [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of copy the first part of files. Full behavior is defined in packages/bare-os-coreutils/src/head.js.","options":[],"keywords":["head","bare-os","coreutils"],"examples":[{"caption":"first 10 lines","code":"head /etc/os-release"},{"caption":"first N","code":"head -n 50 big.log"},{"caption":"stdin","code":"cat long.txt | head"}],"listCategory":"coreutils"},{"name":"hdms","section":1,"title":"Hyperswarm distributed map store","synopsis":["hdms [OPTION]... [OPERAND]..."],"description":"Invokes ctx.runHdms when the booter provides HDMS integration; otherwise prints unavailable.","options":[],"keywords":["hdms","hyperswarm","map"],"bareOsNotes":"Optional booter capability.","examples":[{"caption":"when booter wires HDMS","code":"hdms ls /mnt"},{"caption":"otherwise","code":"# prints unavailable without ctx.runHdms"}],"listCategory":"coreutils"},{"name":"help","section":1,"title":"Bare OS help summary","synopsis":["help"],"description":"Prints a one-screen summary of shell builtins and /bin command names. Use man for long-form documentation.","options":[],"keywords":["help","summary","builtins","commands"],"seeAlso":[{"name":"man","section":1},{"name":"bare-os-shell","section":1}],"examples":[{"caption":"quick index","code":"help"},{"caption":"then deep dive","code":"man grep"}],"listCategory":"coreutils"},{"name":"hostid","section":1,"title":"hostid","synopsis":["hostid [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of hostid. Full behavior is defined in packages/bare-os-coreutils/src/hostid.js.","options":[],"keywords":["hostid","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"hostname","section":1,"title":"set or print hostname","synopsis":["hostname [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of set or print hostname. Full behavior is defined in packages/bare-os-coreutils/src/hostname.js.","options":[],"keywords":["hostname","bare-os","coreutils"],"examples":[{"caption":"show host","code":"hostname"}],"listCategory":"coreutils"},{"name":"iconv","section":1,"title":"iconv","synopsis":["iconv [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of iconv. Full behavior is defined in packages/bare-os-coreutils/src/iconv.js.","options":[],"keywords":["iconv","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"id","section":1,"title":"return user identity","synopsis":["id [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return user identity. Full behavior is defined in packages/bare-os-coreutils/src/id.js.","options":[],"keywords":["id","bare-os","coreutils"],"examples":[{"caption":"who am I numerically","code":"id"}],"listCategory":"coreutils"},{"name":"install","section":1,"title":"install","synopsis":["install [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of install. Full behavior is defined in packages/bare-os-coreutils/src/install.js.","options":[],"keywords":["install","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"join","section":1,"title":"join","synopsis":["join [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of join. Full behavior is defined in packages/bare-os-coreutils/src/join.js.","options":[],"keywords":["join","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"kill","section":1,"title":"kill","synopsis":["kill [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of kill. Full behavior is defined in packages/bare-os-coreutils/src/kill.js.","options":[],"keywords":["kill","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"kernel-boot-diff","section":1,"title":"kernel-boot-diff","synopsis":["kernel-boot-diff [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of kernel-boot-diff. Full behavior is defined in packages/bare-os-coreutils/src/kernel-boot-diff.js.","options":[],"keywords":["kernel-boot-diff","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"kernel-doctor","section":1,"title":"kernel-doctor","synopsis":["kernel-doctor [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of kernel-doctor. Full behavior is defined in packages/bare-os-coreutils/src/kernel-doctor.js.","options":[],"keywords":["kernel-doctor","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"kernel-explain","section":1,"title":"kernel-explain","synopsis":["kernel-explain [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of kernel-explain. Full behavior is defined in packages/bare-os-coreutils/src/kernel-explain.js.","options":[],"keywords":["kernel-explain","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"kernel-fsck","section":1,"title":"kernel-fsck","synopsis":["kernel-fsck [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of kernel-fsck. Full behavior is defined in packages/bare-os-coreutils/src/kernel-fsck.js.","options":[],"keywords":["kernel-fsck","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"kernel-home-snapshot","section":1,"title":"kernel-home-snapshot","synopsis":["kernel-home-snapshot [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of kernel-home-snapshot. Full behavior is defined in packages/bare-os-coreutils/src/kernel-home-snapshot.js.","options":[],"keywords":["kernel-home-snapshot","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"kernel-manifest-validate","section":1,"title":"kernel-manifest-validate","synopsis":["kernel-manifest-validate [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of kernel-manifest-validate. Full behavior is defined in packages/bare-os-coreutils/src/kernel-manifest-validate.js.","options":[],"keywords":["kernel-manifest-validate","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"kernel-preflight","section":1,"title":"kernel-preflight","synopsis":["kernel-preflight [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of kernel-preflight. Full behavior is defined in packages/bare-os-coreutils/src/kernel-preflight.js.","options":[],"keywords":["kernel-preflight","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"kernel-triage","section":1,"title":"kernel-triage","synopsis":["kernel-triage [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of kernel-triage. Full behavior is defined in packages/bare-os-coreutils/src/kernel-triage.js.","options":[],"keywords":["kernel-triage","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"jq","section":1,"title":"command-line JSON processor (jq language subset)","synopsis":["jq [-n] [-R] [-s] [-c] [-r] [-e] [-f file] filter [file...]","jq reads JSON (concatenated values or NDJSON-style streams) from files or stdin."],"description":"Runs a jq filter program against JSON values. The engine is vendored jqjs (pure JavaScript), not the C implementation at https://github.com/jqlang/jq — language coverage and edge cases differ.","options":[{"flag":"-n, --null-input","meaning":"Use null as the sole input (ignore file/stdin for input)"},{"flag":"-R, --raw-input","meaning":"Treat each line as a string instead of JSON"},{"flag":"-s, --slurp","meaning":"Read all inputs into one array; run the filter once"},{"flag":"-c, --compact-output","meaning":"Compact JSON on output"},{"flag":"-r, --raw-output","meaning":"Print strings without JSON quotes"},{"flag":"-e, --exit-status","meaning":"Set exit status from outputs (no output → 4; last false/null → 1)"},{"flag":"-f, --from-file","meaning":"Read filter program from file"}],"keywords":["jq","json","query","filter","jqjs"],"seeAlso":[{"name":"grep","section":1},{"name":"awk","section":1}],"bareOsNotes":"Engine: lib/jq-engine.js from @sscots/jqjs (mwh/jqjs). Missing vs C jq: try/catch, user-defined functions, recurse, many builtins, modules, full Unicode. See upstream jqjs README for the feature matrix.","examples":[{"caption":"pretty-print","code":"jq . data.json"},{"caption":"field","code":"jq .version package.json"},{"caption":"slurp array","code":"jq -s 'map(.x) | add' parts.jsonl"},{"caption":"compact","code":"jq -c '.[] | select(.ok)' items.json"}],"listCategory":"coreutils"},{"name":"ln","section":1,"title":"link files","synopsis":["ln [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of link files. Full behavior is defined in packages/bare-os-coreutils/src/ln.js.","options":[],"keywords":["ln","bare-os","coreutils"],"examples":[{"caption":"symlink","code":"ln -s target name"},{"caption":"hard link (if supported)","code":"ln file linkname"}],"listCategory":"coreutils"},{"name":"link","section":1,"title":"link","synopsis":["link FILE1 FILE2"],"description":"Calls ctx.bareOsSyscall('link') with absolute paths resolved by the VFS. On stock Hyperdrive the booter implements link via file copy unless BARE_OS_VFS_STRICT_HARDLINK requests EOPNOTSUPP. Defined in packages/bare-os-coreutils/src/link.js.","options":[],"keywords":["link","hardlink","bare-os","coreutils"],"seeAlso":[{"name":"ln","section":1},{"name":"symlink","section":7}],"listCategory":"coreutils"},{"name":"logger","section":1,"title":"logger","synopsis":["logger [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of logger. Full behavior is defined in packages/bare-os-coreutils/src/logger.js.","options":[],"keywords":["logger","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"login","section":1,"title":"begin a session on the system","synopsis":["login [OPTION]... [OPERAND]..."],"description":"When invoked from /bin, behavior aligns with session identity hooks (see booter). Prefer the shell builtin for passphrase entry.","options":[],"keywords":["login","identity","passphrase"],"seeAlso":[{"name":"logout","section":1}],"examples":[{"caption":"unlock existing identity","code":"login my passphrase words here"},{"caption":"register new","code":"login --new first time passphrase"}],"listCategory":"coreutils"},{"name":"logout","section":1,"title":"end session (save vault)","synopsis":["logout [OPTION]... [OPERAND]..."],"description":"Ends session; may persist vault depending on booter and flags.","options":[],"keywords":["logout","session"],"seeAlso":[{"name":"login","section":1}],"examples":[{"caption":"end session","code":"logout"},{"caption":"save vault hint","code":"logout --save"}],"listCategory":"coreutils"},{"name":"logname","section":1,"title":"return the user's login name","synopsis":["logname [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return the user's login name. Full behavior is defined in packages/bare-os-coreutils/src/logname.js.","options":[],"keywords":["logname","bare-os","coreutils"],"examples":[{"caption":"login name","code":"logname"}],"listCategory":"coreutils"},{"name":"ls","section":1,"title":"list directory contents","synopsis":["ls [-1al] [--color[=never|auto|always]] [FILE...]"],"description":"Lists directory contents. Long format shows mode, links, owner, group, size, mtime, and symlink targets. With color (default auto on a TTY), directories, symlinks, executables, and permission bits are highlighted.","options":[{"flag":"-a","meaning":"Include names starting with ."},{"flag":"-l","meaning":"Long listing"},{"flag":"-1","meaning":"One name per line (short format)"},{"flag":"--color[=never|auto|always]","meaning":"ANSI colors: never, auto (TTY only), or always; plain --color is auto"}],"keywords":["ls","list","directory","dir"],"environment":["NO_COLOR — disable color even when a TTY or --color=always"],"bareOsNotes":"Hides .bareos_empty marker like other tools.","examples":[{"caption":"long + hidden","code":"ls -la ~"},{"caption":"one per line","code":"ls -1 /bin | head"},{"caption":"multiple paths","code":"ls /bin /etc"}],"listCategory":"coreutils"},{"name":"man","section":1,"title":"display on-line manual pages","synopsis":["man [-k keyword] [-f name] [-l] [[section] name]","man reads /share/man/man.json on the system drive."],"description":"Displays manual pages from the merged JSON database. Section 1: /bin and git/shell pages. Section 7: handbook (man handbook) and developer guide (man devguide), merged at build from handbook/*.md and developer-guide/*.md.","options":[{"flag":"-k, --apropos","meaning":"Search keywords and titles (substring)"},{"flag":"-f, --whatis","meaning":"One-line description for exact name"},{"flag":"-l, --list","meaning":"List pages grouped by category (/bin, git/shell, handbook, developer guide), then alphabetically"}],"keywords":["man","manual","help","documentation","apropos","whatis","cheat","examples"],"environment":["MANWIDTH — wrap width (default 72, min 40)","NO_COLOR — disable bold headings on TTY"],"seeAlso":[{"name":"help","section":1},{"name":"bare-os-handbook","section":7},{"name":"bare-os-developer-guide","section":7}],"bareOsNotes":"No troff; no embedded DB fallback in v1.","examples":[{"caption":"open page","code":"man sed"},{"caption":"handbook TOC (section 7)","code":"man handbook"},{"caption":"handbook chapter by section","code":"man 7 handbook-01-introduction"},{"caption":"apropos","code":"man -k copy"},{"caption":"whatis","code":"man -f grep"},{"caption":"all pages","code":"man -l"},{"caption":"narrow terminal","code":"MANWIDTH=64 man awk"}],"listCategory":"coreutils"},{"name":"md5sum","section":1,"title":"md5sum","synopsis":["md5sum [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of md5sum. Full behavior is defined in packages/bare-os-coreutils/src/md5sum.js.","options":[],"keywords":["md5sum","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"mkdir","section":1,"title":"make directories","synopsis":["mkdir [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of make directories. Full behavior is defined in packages/bare-os-coreutils/src/mkdir.js.","options":[],"keywords":["mkdir","bare-os","coreutils"],"examples":[{"caption":"one dir","code":"mkdir proj"},{"caption":"parents","code":"mkdir -p a/b/c"}],"listCategory":"coreutils"},{"name":"mkfifo","section":1,"title":"make FIFO special files","synopsis":["mkfifo [OPTION]... [OPERAND]..."],"description":"Creates an in-memory named channel for IPC under /run/bare-os/ipc/<name> when the booter exposes ctx.bareOsIpc. Paths must be under that prefix (e.g. /run/bare-os/ipc/demo). Not a kernel FIFO on Hyperdrive; use shell pipelines for stream composition between utilities.","options":[],"keywords":["mkfifo","bare-os","coreutils"],"bareOsNotes":"Optional BARE_OS_IPC_NAMESPACE prefixes the logical channel key. See handbook ch.9 (FIFOs, simulated IPC).","examples":[{"caption":"create a named IPC channel","code":"mkfifo /run/bare-os/ipc/demo"}],"listCategory":"coreutils"},{"name":"mktemp","section":1,"title":"mktemp","synopsis":["mktemp [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of mktemp. Full behavior is defined in packages/bare-os-coreutils/src/mktemp.js.","options":[],"keywords":["mktemp","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"mount","section":1,"title":"mount","synopsis":["mount [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of mount. Full behavior is defined in packages/bare-os-coreutils/src/mount.js.","options":[],"keywords":["mount","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"mv","section":1,"title":"move or rename files","synopsis":["mv [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of move or rename files. Full behavior is defined in packages/bare-os-coreutils/src/mv.js.","options":[],"keywords":["mv","bare-os","coreutils"],"examples":[{"caption":"rename","code":"mv old.txt new.txt"},{"caption":"into dir","code":"mv *.txt ~/inbox/"}],"listCategory":"coreutils"},{"name":"nano","section":1,"title":"nano","synopsis":["nano [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of nano. Full behavior is defined in packages/bare-os-coreutils/src/nano.js.","options":[],"keywords":["nano","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"nl","section":1,"title":"line numbering utility","synopsis":["nl [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of line numbering utility. Full behavior is defined in packages/bare-os-coreutils/src/nl.js.","options":[],"keywords":["nl","bare-os","coreutils"],"examples":[{"caption":"number all lines","code":"nl README.md"}],"listCategory":"coreutils"},{"name":"nohup","section":1,"title":"run command (hangup is a no-op in Bare OS)","synopsis":["nohup [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of run command (hangup is a no-op in Bare OS). Full behavior is defined in packages/bare-os-coreutils/src/nohup.js.","options":[],"keywords":["nohup","bare-os","coreutils"],"examples":[{"caption":"run utility (no real SIGHUP in guest)","code":"nohup long-job.sh"}],"listCategory":"coreutils"},{"name":"nproc","section":1,"title":"nproc","synopsis":["nproc [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of nproc. Full behavior is defined in packages/bare-os-coreutils/src/nproc.js.","options":[],"keywords":["nproc","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"numfmt","section":1,"title":"numfmt","synopsis":["numfmt [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of numfmt. Full behavior is defined in packages/bare-os-coreutils/src/numfmt.js.","options":[],"keywords":["numfmt","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"od","section":1,"title":"octal dump","synopsis":["od [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of octal dump. Full behavior is defined in packages/bare-os-coreutils/src/od.js.","options":[],"keywords":["od","bare-os","coreutils"],"examples":[{"caption":"hex dump vibe","code":"od -c file.bin | head"}],"listCategory":"coreutils"},{"name":"openssl","section":1,"title":"openssl","synopsis":["openssl [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of openssl. Full behavior is defined in packages/bare-os-coreutils/src/openssl.js.","options":[],"keywords":["openssl","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"oidc-publish","section":1,"title":"oidc-publish","synopsis":["oidc-publish [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of oidc-publish. Full behavior is defined in packages/bare-os-coreutils/src/oidc-publish.js.","options":[],"keywords":["oidc-publish","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"paste","section":1,"title":"paste","synopsis":["paste [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of paste. Full behavior is defined in packages/bare-os-coreutils/src/paste.js.","options":[],"keywords":["paste","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"patch","section":1,"title":"patch","synopsis":["patch [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of patch. Full behavior is defined in packages/bare-os-coreutils/src/patch.js.","options":[],"keywords":["patch","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"pathchk","section":1,"title":"check pathname portability","synopsis":["pathchk [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of check pathname portability. Full behavior is defined in packages/bare-os-coreutils/src/pathchk.js.","options":[],"keywords":["pathchk","bare-os","coreutils"],"examples":[{"caption":"portable path check","code":"pathchk -p \"$HOME/file name\""}],"listCategory":"coreutils"},{"name":"pr","section":1,"title":"pr","synopsis":["pr [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of pr. Full behavior is defined in packages/bare-os-coreutils/src/pr.js.","options":[],"keywords":["pr","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"printenv","section":1,"title":"print environment variables","synopsis":["printenv [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of print environment variables. Full behavior is defined in packages/bare-os-coreutils/src/printenv.js.","options":[],"keywords":["printenv","bare-os","coreutils"],"examples":[{"caption":"one variable","code":"printenv HOME"},{"caption":"all","code":"printenv"}],"listCategory":"coreutils"},{"name":"printf","section":1,"title":"format and print","synopsis":["printf [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of format and print. Full behavior is defined in packages/bare-os-coreutils/src/printf.js.","options":[],"keywords":["printf","bare-os","coreutils"],"examples":[{"caption":"format","code":"printf \"hex=%x dec=%d\\n\" 255 255"},{"caption":"no newline","code":"printf \"%s\" OK"}],"listCategory":"coreutils"},{"name":"procstat","section":1,"title":"procstat","synopsis":["procstat [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of procstat. Full behavior is defined in packages/bare-os-coreutils/src/procstat.js.","options":[],"keywords":["procstat","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"ps","section":1,"title":"ps","synopsis":["ps [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of ps. Full behavior is defined in packages/bare-os-coreutils/src/ps.js.","options":[],"keywords":["ps","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"pwd","section":1,"title":"return working directory name","synopsis":["pwd [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return working directory name. Full behavior is defined in packages/bare-os-coreutils/src/pwd.js.","options":[],"keywords":["pwd","bare-os","coreutils"],"examples":[{"caption":"where am I","code":"pwd"}],"listCategory":"coreutils"},{"name":"readlink","section":1,"title":"print symbolic link targets","synopsis":["readlink [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of print symbolic link targets. Full behavior is defined in packages/bare-os-coreutils/src/readlink.js.","options":[],"keywords":["readlink","bare-os","coreutils"],"examples":[{"caption":"symlink target","code":"readlink ~/.config"}],"listCategory":"coreutils"},{"name":"realpath","section":1,"title":"realpath","synopsis":["realpath [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of realpath. Full behavior is defined in packages/bare-os-coreutils/src/realpath.js.","options":[],"keywords":["realpath","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"rev","section":1,"title":"rev","synopsis":["rev [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of rev. Full behavior is defined in packages/bare-os-coreutils/src/rev.js.","options":[],"keywords":["rev","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"rm","section":1,"title":"remove files","synopsis":["rm [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of remove files. Full behavior is defined in packages/bare-os-coreutils/src/rm.js.","options":[],"keywords":["rm","bare-os","coreutils"],"examples":[{"caption":"file","code":"rm tmp.txt"},{"caption":"tree","code":"rm -rf build/"}],"listCategory":"coreutils"},{"name":"rmdir","section":1,"title":"remove empty directories","synopsis":["rmdir [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of remove empty directories. Full behavior is defined in packages/bare-os-coreutils/src/rmdir.js.","options":[],"keywords":["rmdir","bare-os","coreutils"],"examples":[{"caption":"empty dir","code":"rmdir olddir"}],"listCategory":"coreutils"},{"name":"savevault","section":1,"title":"encrypt snapshot of personal drive","synopsis":["savevault [OPTION]... [OPERAND]..."],"description":"Encrypts a copy of the personal drive under /.bare/vault/ when identity services are available.","options":[],"keywords":["savevault","vault","encrypt","backup"],"seeAlso":[{"name":"login","section":1}],"examples":[{"caption":"snapshot encrypted vault","code":"savevault"}],"listCategory":"coreutils"},{"name":"sed","section":1,"title":"stream editor","synopsis":["sed [OPTION]... [OPERAND]..."],"description":"Stream editor with a subset of POSIX sed. Large engine is vendored in lib/sed-engine.js.","options":[],"keywords":["sed","stream","edit","substitute"],"seeAlso":[{"name":"awk","section":1},{"name":"grep","section":1}],"bareOsNotes":"JavaScript implementation; edge cases differ from GNU sed.","examples":[{"caption":"substitute first per line","code":"sed 's/foo/bar/' file.txt"},{"caption":"global per line","code":"sed 's/ //g' spaced.txt"},{"caption":"in-place (if supported)","code":"sed -i.bak 's/^/# /' f.cfg"},{"caption":"print line 5 only","code":"sed -n '5p' file"},{"caption":"delete blank lines","code":"sed '/^$/d' file"}],"listCategory":"coreutils"},{"name":"seq","section":1,"title":"print sequences of numbers","synopsis":["seq [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of print sequences of numbers. Full behavior is defined in packages/bare-os-coreutils/src/seq.js.","options":[],"keywords":["seq","bare-os","coreutils"],"examples":[{"caption":"1..10","code":"seq 1 10"},{"caption":"step","code":"seq 0 2 20"}],"listCategory":"coreutils"},{"name":"setfacl","section":1,"title":"setfacl","synopsis":["setfacl [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of setfacl. Full behavior is defined in packages/bare-os-coreutils/src/setfacl.js.","options":[],"keywords":["setfacl","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"sha1sum","section":1,"title":"sha1sum","synopsis":["sha1sum [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of sha1sum. Full behavior is defined in packages/bare-os-coreutils/src/sha1sum.js.","options":[],"keywords":["sha1sum","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"sha256sum","section":1,"title":"sha256sum","synopsis":["sha256sum [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of sha256sum. Full behavior is defined in packages/bare-os-coreutils/src/sha256sum.js.","options":[],"keywords":["sha256sum","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"sha512sum","section":1,"title":"sha512sum","synopsis":["sha512sum [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of sha512sum. Full behavior is defined in packages/bare-os-coreutils/src/sha512sum.js.","options":[],"keywords":["sha512sum","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"sh","section":1,"title":"sh","synopsis":["sh [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of sh. Full behavior is defined in packages/bare-os-coreutils/src/sh.js.","options":[],"keywords":["sh","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"shuf","section":1,"title":"shuf","synopsis":["shuf [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of shuf. Full behavior is defined in packages/bare-os-coreutils/src/shuf.js.","options":[],"keywords":["shuf","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"sleep","section":1,"title":"suspend execution for an interval","synopsis":["sleep [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of suspend execution for an interval. Full behavior is defined in packages/bare-os-coreutils/src/sleep.js.","options":[],"keywords":["sleep","bare-os","coreutils"],"examples":[{"caption":"pause seconds","code":"sleep 2"}],"listCategory":"coreutils"},{"name":"sort","section":1,"title":"sort lines","synopsis":["sort [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of sort lines. Full behavior is defined in packages/bare-os-coreutils/src/sort.js.","options":[],"keywords":["sort","bare-os","coreutils"],"examples":[{"caption":"lexicographic","code":"sort names.txt"},{"caption":"numeric","code":"sort -n scores.txt"},{"caption":"unique","code":"sort -u tags.txt"}],"listCategory":"coreutils"},{"name":"split","section":1,"title":"split","synopsis":["split [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of split. Full behavior is defined in packages/bare-os-coreutils/src/split.js.","options":[],"keywords":["split","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"ssh-keygen","section":1,"title":"ssh-keygen","synopsis":["ssh-keygen [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of ssh-keygen. Full behavior is defined in packages/bare-os-coreutils/src/ssh-keygen.js.","options":[],"keywords":["ssh-keygen","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"stat","section":1,"title":"display file status","synopsis":["stat [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of display file status. Full behavior is defined in packages/bare-os-coreutils/src/stat.js.","options":[],"keywords":["stat","bare-os","coreutils"],"examples":[{"caption":"metadata","code":"stat ~/README.md"}],"listCategory":"coreutils"},{"name":"sum","section":1,"title":"sum","synopsis":["sum [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of sum. Full behavior is defined in packages/bare-os-coreutils/src/sum.js.","options":[],"keywords":["sum","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"sync","section":1,"title":"sync","synopsis":["sync [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of sync. Full behavior is defined in packages/bare-os-coreutils/src/sync.js.","options":[],"keywords":["sync","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"tar","section":1,"title":"tar","synopsis":["tar [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of tar. Full behavior is defined in packages/bare-os-coreutils/src/tar.js.","options":[],"keywords":["tar","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"tac","section":1,"title":"tac","synopsis":["tac [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of tac. Full behavior is defined in packages/bare-os-coreutils/src/tac.js.","options":[],"keywords":["tac","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"tail","section":1,"title":"copy the last part of a file","synopsis":["tail [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of copy the last part of a file. Full behavior is defined in packages/bare-os-coreutils/src/tail.js.","options":[],"keywords":["tail","bare-os","coreutils"],"examples":[{"caption":"last lines","code":"tail -n 20 app.log"},{"caption":"follow vibe (Bare: poll manually)","code":"tail error.log"}],"listCategory":"coreutils"},{"name":"tee","section":1,"title":"duplicate standard input","synopsis":["tee [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of duplicate standard input. Full behavior is defined in packages/bare-os-coreutils/src/tee.js.","options":[],"keywords":["tee","bare-os","coreutils"],"examples":[{"caption":"copy stdout to file","code":"cat x | tee copy.txt | wc -l"}],"listCategory":"coreutils"},{"name":"test","section":1,"title":"evaluate a condition","synopsis":["test [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of evaluate a condition. Full behavior is defined in packages/bare-os-coreutils/src/test.js.","options":[],"keywords":["test","bare-os","coreutils"],"examples":[{"caption":"file exists","code":"test -f ~/.barerc && echo yes"},{"caption":"directory","code":"test -d /home/user"},{"caption":"string equal","code":"test \"$USER\" = guest"}],"listCategory":"coreutils"},{"name":"theme","section":1,"title":"theme","synopsis":["theme [list|current|set <name>|apply]"],"description":"Switch Bare OS UI preset: updates ~/.barerc theme line, sets BARE_OS_THEME, calls bareOsApplyTheme when available.","options":[],"keywords":["theme","colors","prompt"],"bareOsNotes":"list/current work without booter hooks; set/apply need ctx.bareOsApplyTheme.","listCategory":"coreutils"},{"name":"time","section":1,"title":"time a simple command","synopsis":["time [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of time a simple command. Full behavior is defined in packages/bare-os-coreutils/src/time.js.","options":[],"keywords":["time","bare-os","coreutils"],"examples":[{"caption":"wall time a command","code":"time sort big.txt"}],"listCategory":"coreutils"},{"name":"timeout","section":1,"title":"run command with bounded wall time","synopsis":["timeout [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of run command with bounded wall time. Full behavior is defined in packages/bare-os-coreutils/src/timeout.js.","options":[],"keywords":["timeout","bare-os","coreutils"],"examples":[{"caption":"kill long job after 5s","code":"timeout 5 slow-cmd"}],"listCategory":"coreutils"},{"name":"touch","section":1,"title":"change file timestamps or create files","synopsis":["touch [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of change file timestamps or create files. Full behavior is defined in packages/bare-os-coreutils/src/touch.js.","options":[],"keywords":["touch","bare-os","coreutils"],"examples":[{"caption":"create empty","code":"touch newfile"},{"caption":"refresh mtime","code":"touch -c existing"}],"listCategory":"coreutils"},{"name":"tr","section":1,"title":"translate or delete characters","synopsis":["tr [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of translate or delete characters. Full behavior is defined in packages/bare-os-coreutils/src/tr.js.","options":[],"keywords":["tr","bare-os","coreutils"],"examples":[{"caption":"uppercase","code":"echo hi | tr 'a-z' 'A-Z'"},{"caption":"delete chars","code":"tr -d '\\r' < win.txt"}],"listCategory":"coreutils"},{"name":"truncate","section":1,"title":"truncate","synopsis":["truncate [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of truncate. Full behavior is defined in packages/bare-os-coreutils/src/truncate.js.","options":[],"keywords":["truncate","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"true","section":1,"title":"return true value","synopsis":["true [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return true value. Full behavior is defined in packages/bare-os-coreutils/src/true.js.","options":[],"keywords":["true","bare-os","coreutils"],"examples":[{"caption":"always success","code":"true && echo ok"}],"listCategory":"coreutils"},{"name":"tsort","section":1,"title":"tsort","synopsis":["tsort [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of tsort. Full behavior is defined in packages/bare-os-coreutils/src/tsort.js.","options":[],"keywords":["tsort","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"tty","section":1,"title":"return user's terminal name","synopsis":["tty [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return user's terminal name. Full behavior is defined in packages/bare-os-coreutils/src/tty.js.","options":[],"keywords":["tty","bare-os","coreutils"],"examples":[{"caption":"am I a tty","code":"tty"}],"listCategory":"coreutils"},{"name":"ulimit","section":1,"title":"ulimit","synopsis":["ulimit [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of ulimit. Full behavior is defined in packages/bare-os-coreutils/src/ulimit.js.","options":[],"keywords":["ulimit","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"uname","section":1,"title":"return operating system name","synopsis":["uname [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of return operating system name. Full behavior is defined in packages/bare-os-coreutils/src/uname.js.","options":[],"keywords":["uname","bare-os","coreutils"],"examples":[{"caption":"kernel-ish info","code":"uname -a"}],"listCategory":"coreutils"},{"name":"uniq","section":1,"title":"uniq","synopsis":["uniq [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of uniq. Full behavior is defined in packages/bare-os-coreutils/src/uniq.js.","options":[],"keywords":["uniq","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"unlink","section":1,"title":"unlink","synopsis":["unlink [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of unlink. Full behavior is defined in packages/bare-os-coreutils/src/unlink.js.","options":[],"keywords":["unlink","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"umount","section":1,"title":"umount","synopsis":["umount [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of umount. Full behavior is defined in packages/bare-os-coreutils/src/umount.js.","options":[],"keywords":["umount","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"unexpand","section":1,"title":"unexpand","synopsis":["unexpand [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of unexpand. Full behavior is defined in packages/bare-os-coreutils/src/unexpand.js.","options":[],"keywords":["unexpand","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"uptime","section":1,"title":"uptime","synopsis":["uptime [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of uptime. Full behavior is defined in packages/bare-os-coreutils/src/uptime.js.","options":[],"keywords":["uptime","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"users","section":1,"title":"users","synopsis":["users [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of users. Full behavior is defined in packages/bare-os-coreutils/src/users.js.","options":[],"keywords":["users","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"vdir","section":1,"title":"vdir","synopsis":["vdir [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of vdir. Full behavior is defined in packages/bare-os-coreutils/src/vdir.js.","options":[],"keywords":["vdir","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"wc","section":1,"title":"word, line, and byte or character count","synopsis":["wc [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of word, line, and byte or character count. Full behavior is defined in packages/bare-os-coreutils/src/wc.js.","options":[],"keywords":["wc","bare-os","coreutils"],"examples":[{"caption":"lines words bytes","code":"wc README.md"},{"caption":"stdin only","code":"cat f | wc -l"}],"listCategory":"coreutils"},{"name":"wget","section":1,"title":"wget","synopsis":["wget [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of wget. Full behavior is defined in packages/bare-os-coreutils/src/wget.js.","options":[],"keywords":["wget","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"which","section":1,"title":"locate a command","synopsis":["which [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of locate a command. Full behavior is defined in packages/bare-os-coreutils/src/which.js.","options":[],"keywords":["which","bare-os","coreutils"],"examples":[{"caption":"resolve on PATH","code":"which ls"}],"listCategory":"coreutils"},{"name":"who","section":1,"title":"who","synopsis":["who [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of who. Full behavior is defined in packages/bare-os-coreutils/src/who.js.","options":[],"keywords":["who","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"whoami","section":1,"title":"display effective user ID","synopsis":["whoami [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of display effective user ID. Full behavior is defined in packages/bare-os-coreutils/src/whoami.js.","options":[],"keywords":["whoami","bare-os","coreutils"],"examples":[{"caption":"effective user","code":"whoami"}],"listCategory":"coreutils"},{"name":"xattr","section":1,"title":"xattr","synopsis":["xattr [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of xattr. Full behavior is defined in packages/bare-os-coreutils/src/xattr.js.","options":[],"keywords":["xattr","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"xargs","section":1,"title":"construct argument lists and invoke utility","synopsis":["xargs [OPTION]... [OPERAND]..."],"description":"Reads stdin into argument batches and runs **`ctx.runBinCommand`** (same as the shell). Enforces stdin size, token count, batch size, and invocation limits for safety.","options":[{"flag":"-0, --null","meaning":"Input items are null-terminated, not whitespace-separated"},{"flag":"-n, --max-args","meaning":"Up to N arguments per utility invocation (capped at 128)"}],"keywords":["xargs","bare-os","coreutils"],"bareOsNotes":"No host process spawn; not full POSIX xargs (no -I, -P, etc.). See src/xargs.js for limits.","examples":[{"caption":"pass lines as arguments","code":"printf 'a\\nb\\n' | xargs echo"},{"caption":"one argument per run","code":"printf 'a\\nb\\n' | xargs -n1 echo"},{"caption":"workaround for complex scripts","code":"# for f in *.txt; do grep -l foo $f; done"}],"listCategory":"coreutils"},{"name":"yes","section":1,"title":"yes","synopsis":["yes [OPTION]... [OPERAND]..."],"description":"Bare OS implementation of yes. Full behavior is defined in packages/bare-os-coreutils/src/yes.js.","options":[],"keywords":["yes","bare-os","coreutils"],"listCategory":"coreutils"},{"name":"bare-cron","section":1,"title":"Bare OS minute scheduler (bare-initd unit)","synopsis":["Managed via systemctl(1): systemctl status bare-cron","Crontab files: /etc/bare-os/crontab, ~/.crontab, ~/.config/bare-os/timers/*.timer"],"description":"The **bare-cron** bare-initd unit runs a bounded in-process scheduler: classic five-field lines, **@reboot**, optional **JitterSec=**, and systemd-inspired timer drop-ins (**OnCalendar=**, **EveryMs=**, **OnInactiveSec=**, **Persistent=**). Jobs execute through **ctx.execLine**; errors may be logged under **/var/log/bare-os/cron.log** when configured. This is not full **cron**(8) or **systemd.timer**(5) parity.","options":[],"keywords":["cron","scheduler","bare-initd","timer","crontab"],"seeAlso":[{"name":"systemctl","section":1},{"name":"crontab","section":1}],"bareOsNotes":"Implementation: packages/bare-os-booter/lib/bare-cron.js. Dependency: **kernel-logger** before **bare-cron** in the default initd graph.","examples":[{"caption":"list scheduler unit","code":"systemctl status bare-cron"},{"caption":"user crontab line (five-field)","code":"0 * * * * echo hourly"}],"listCategory":"extra"},{"name":"bare-os-ctx-bare","section":7,"title":"ctx.bare library and drive bundles","synopsis":["# reference — not a shell command"],"description":"Documents BARE_OS_BARE_MODULES and BARE_OS_BARE_DRIVE_BUNDLES for the booter ctx.bare registry. In-image scripts (AsyncFunction) use ctx.bare.<key> instead of import(). Keys come from host dynamic import of packages listed in packages/bare-os-booter/lib/bare-module-manifest.json, then optional merge from trusted IIFE bundles under /lib/bare/bundles/ on the system image (see manifest.json there). Set BARE_OS_BARE_MODULES=0 to omit ctx.bare entirely. Set BARE_OS_BARE_DRIVE_BUNDLES=0 to skip executing drive bundles (host imports only). Rebuild bundles with npm run build -w bare-os-bare-libs.","options":[],"keywords":["BARE_OS_BARE_MODULES","BARE_OS_BARE_DRIVE_BUNDLES","ctx.bare","bare-module-manifest","bare-os-bare-libs"],"environment":["BARE_OS_BARE_MODULES — set to 0 or false to disable ctx.bare (hardened sessions).","BARE_OS_BARE_DRIVE_BUNDLES — set to 0 or false to skip loading /lib/bare/bundles/*.js into ctx.bare."],"seeAlso":[{"name":"bare-os-developer-guide","section":7}],"bareOsNotes":"See developer-guide/05-modules-and-imports.md and 12-bare-modules-and-pear-ecosystem.md.","examples":[],"listCategory":"extra"},{"name":"bare-os-shell","section":1,"title":"Bare OS interactive shell builtins","synopsis":["# builtins only — no full POSIX sh grammar"],"description":"The line-at-a-time shell supports aliases, simple pipelines (simulated), redirection, and the builtins below. Compound commands (if, for, while) are not available.","options":[],"aliases":["sh-builtins"],"keywords":["shell","builtin","cd","export","alias","bare-os-shell","sh-builtins"],"builtins":[{"name":"alias","synopsis":["alias","alias name=value ...","unalias name ..."],"description":"Define or list command aliases. unalias removes definitions."},{"name":"cd","synopsis":["cd [DIR]"],"description":"Change working directory via vfs.chdir; default is HOME."},{"name":"export","synopsis":["export NAME=value ..."],"description":"Set environment variables visible to child /bin invocations."},{"name":"unset","synopsis":["unset NAME ..."],"description":"Remove variables; readonly names cannot be unset."},{"name":"readonly","synopsis":["readonly NAME[=value] ..."],"description":"Mark variables read-only."},{"name":"umask","synopsis":["umask [octal]"],"description":"Show or set shell file creation mask (stored in env UMASK)."},{"name":"command","synopsis":["command -v|-V NAME","command ARGV..."],"description":"Resolve or run a command without using shell functions (none) or aliases for -v/-V."},{"name":"type","synopsis":["type NAME"],"description":"Report whether NAME is a builtin or a path under PATH."},{"name":"login / logout","synopsis":["login [--new] passphrase...","logout [--save]"],"description":"Identity unlock/register and session teardown; require booter hooks."},{"name":":","synopsis":[":"],"description":"No-op builtin."},{"name":"exit","synopsis":["exit [n]"],"description":"Request booter exit with status n (builtin path)."}],"seeAlso":[{"name":"help","section":1},{"name":"man","section":1}],"bareOsNotes":"Pipelines do not use OS pipes; see handbook ch.4 and ch.9.","examples":[{"caption":"pipeline (simulated)","code":"ls -1 /bin | grep man"},{"caption":"redirect out","code":"echo hi > ~/hello.txt"},{"caption":"append","code":"date >> ~/log.txt"},{"caption":"alias + use","code":"alias ll='ls -la'\nll ~"},{"caption":"export for children","code":"export EDITOR=ed\nman ls"},{"caption":"temp var for one command","code":"PATH=/bin man which"}],"listCategory":"extra"},{"name":"systemctl","section":1,"title":"bare-initd service control (systemd-like subset)","synopsis":["systemctl list|list-units","systemctl status [UNIT] [--lines N]","systemctl show|cat UNIT","systemctl is-failed UNIT","systemctl reset-failed [UNIT]","systemctl logs UNIT [--lines N]","systemctl start|stop|restart UNIT","systemctl enable|disable UNIT","systemctl is-enabled UNIT","systemctl is-active UNIT","systemctl help","journalctl -u UNIT [--lines N|-n N]"],"description":"Lists and manages session-scoped bare-initd units (kernel-logger, bare-cron, …). Implemented by packages/bare-os-booter/lib/systemctl-cli.js (kernel-runner); /bin stubs exist for PATH and man(1). Verbs match --help: show/cat dump unit fields; is-failed; reset-failed (logical no-op on stock initd); enable/disable toggle ~/.config/bare-os/initd/disabled.txt; is-enabled / is-active; logs and status accept --lines. journalctl supports -u, --lines, -n. The legacy name bare-initctl is still accepted as an alias.","options":[{"flag":"--lines N","meaning":"Tail N lines from the unit log (status, logs, journalctl)"}],"aliases":["bare-initctl"],"keywords":["bare-initd","initctl","service","supervisor","cron","systemd"],"bareOsNotes":"journalctl only supports -u UNIT and optional --lines / -n. Unknown systemd verbs are not implemented.","seeAlso":[{"name":"crontab","section":1},{"name":"bare-os-shell","section":1}],"examples":[{"caption":"list units","code":"systemctl list-units"},{"caption":"restart scheduler","code":"systemctl restart bare-cron"},{"caption":"tail cron errors","code":"journalctl -u bare-cron --lines 20"}],"listCategory":"extra"},{"name":"git","section":1,"title":"Bare OS git front-end (isomorphic-git)","synopsis":["git [-C dir] <subcommand> [ARGUMENTS...]"],"description":"Runs isomorphic-git against the VFS-backed adapter. Remote HTTP(S) uses BARE_OS_GIT_HTTP when set; otherwise Pear bare module fetch.","options":[{"flag":"-C dir","meaning":"Run as if git was started in dir"}],"environment":["BARE_OS_GIT_HTTP — optional fetch implementation for remotes","GIT_* — standard hints where supported"],"keywords":["git","version control","repository","clone","commit","isomorphic-git"],"bareOsNotes":"Not a separate /bin script; booter delegates argv[0]=git to git-cli.js.","seeAlso":[{"name":"bare-os-shell","section":1}],"examples":[{"caption":"new repo","code":"git init -C ~/myrepo"},{"caption":"status","code":"git -C ~/myrepo status"},{"caption":"clone over HTTP (needs remote + fetch)","code":"git clone https://example.com/repo.git ~/work/repo"},{"caption":"config local","code":"git -C ~/myrepo config user.email \"[email protected]\""},{"caption":"log one line","code":"git -C ~/myrepo log --oneline -5"}],"listCategory":"extra"},{"name":"bare-os-handbook","section":7,"title":"Bare OS handbook — table of contents and reading order","synopsis":["man 7 bare-os-handbook","Handbook chapter (plain text from handbook/README.md)"],"description":"BARE OPERATING SYSTEM — HANDBOOK\n\nBare OS is an experimental, P2P-first system image: a Merkle-addressed Hyperdrive you replicate from peers over Hyperswarm, plus a second drive for everything that should stay yours (home, identity, logs). This handbook is the narrative spine—written like a long-form technical article so you can read it cover to cover or jump to a chapter. It explains why the pieces exist, how they connect, and where to look when something breaks.\n\nThis project is experimental research software, not a production OS. It is licensed under Apache-2.0 (LICENSE <../LICENSE>).\n\nON THIS PAGE\n\n- How this handbook fits the repo <#how-this-handbook-fits-the-repo>\n- Who should read what <#who-should-read-what-three-paths>\n- Chapters <#chapters>\n- Packages in one sentence each <#packages-in-one-sentence-each>\n- Root README <#root-readme>\n\nHOW THIS HANDBOOK FITS THE REPO\n\nDocumentation home <../docs/README.md> — Single map of every tree: user manual, this handbook, developer guide, reference, glossary <../docs/glossary.md>, FAQ <../docs/faq.md>, troubleshooting router <../docs/troubleshooting.md>, contributing to docs <../docs/CONTRIBUTING-DOCS.md>.\n\nPreface — why Bare OS <00-preface.md> — Thesis, comparison to classic images, security limits, outlook, contributor paths.\n\n*This handbook (handbook/.md)** — Story, architecture, protocol, runtime, identity, POSIX surface, operations, and research directions.\n\nUser manual <../users-manual/README.md> — Short operator-oriented path: clone, run seeder and booter, use the shell and identity features, find man and troubleshooting without reading cover to cover.\n\ndocs/reference/README.md <../docs/reference/README.md> — File-by-file inventory, environment variables, data-flow diagram.\n\ndocs/architecture/KERNEL_CONTRACT.md <../docs/architecture/KERNEL_CONTRACT.md> — Single-page contract: subsystems, boot steps, ctx semver, typed errors.\n\ndeveloper-guide/README.md <../developer-guide/README.md> — How to write run(ctx, argv) / start(ctx), extend /bin, and test under Pear.\n\nKernel extensions <../docs/reference/kernel-extensions.md> — Kernel feature bitmask, seed-channel RPC, and capability bits.\n\nThe ctx object is versioned for kernels and scripts that depend on booter behavior. Treat packages/bare-os-booter/CHANGELOG.md <../packages/bare-os-booter/CHANGELOG.md> as the contract history (bareOsCtxApiVersion / BARE_OS_CTX_API_VERSION). TypeScript authors can use packages/bare-os-booter/lib/bare-os-ctx.d.ts <../packages/bare-os-booter/lib/bare-os-ctx.d.ts>.\n\nWHO SHOULD READ WHAT (THREE PATHS)\n\nI want to run it. Start at the user manual <../users-manual/README.md> or the root README.md <../README.md>, then Chapter 7 — Operations <07-operations-and-development.md> (install, npm test, seeder/booter, Pear). Skim Chapter 1 <01-introduction.md> for vocabulary.\n\nI want to change the image or /bin. Read Preface <00-preface.md> → Chapter 6 <06-kernel-and-binaries.md> → the developer guide <../developer-guide/README.md>, especially extending coreutils <../developer-guide/06-extending-bin-coreutils.md> and the ctx object <../developer-guide/02-the-context-object.md>.\n\nI want the architecture and trust model. Read Preface <00-preface.md> → Chapter 2 — Blueprints <02-blueprints.md> → Chapter 3 — Protocol <03-protocol-and-disk.md> → Chapter 4 — Booter runtime <04-the-booter-runtime.md> → Chapter 5 — Identity <05-identity-vault-and-hdms.md>.\n\nCHAPTERS\n\n- Preface <00-preface.md> — Whitepaper-style thesis, documentation map, security limits, research directions, contributing.\n- 01 — Introduction <01-introduction.md> — Goals, vocabulary, Holepunch stack, clone-to-prompt story.\n- 02 — Blueprints <02-blueprints.md> — Layered architecture, trust, boot-flow diagram.\n- 03 — Protocol and disk <03-protocol-and-disk.md> — MBR, swarm, Protomux, SwarmDisk, failure matrix.\n- 04 — The booter runtime <04-the-booter-runtime.md> — ctx, VFS, shell, kernel, initd, cron, REPL, host bridges.\n- 05 — Identity, vault, HDMS <05-identity-vault-and-hdms.md> — Guest vs user, account blob, vault, extra drives.\n- 06 — Kernel and binaries <06-kernel-and-binaries.md> — /boot/init.js, coreutils pipeline, /bin summary.\n- 07 — Operations and development <07-operations-and-development.md> — CI, pretest, Pear channels, env vars, troubleshooting.\n- 08 — Git on Bare OS <08-git-on-bare-os.md> — isomorphic-git, VFS adapter, HTTP modes.\n- 09 — POSIX utilities, shell, VFS <09-posix-utilities-shell-and-vfs.md> — XCU-style /bin, shell, divergence from Issue 7.\n- 10 — Manual pages and online help <10-manpages-and-online-help.md> — man(1), JSON DB, handbook ingest, help vs man.\n- 11 — Kernel program and research <11-kernel-program-and-research.md> — Pear/Bare/holepunch context, capability words, non-goals.\n- 12 — P2P stack vs POSIX boundaries <12-p2p-stack-and-posix-boundaries.md> — Hypercore replication, swarm, Protomux, and how they relate to the declared POSIX profile and non-goals.\n\nPear workflows, ctx.bare, drive bundles: developer-guide ch.11 <../developer-guide/11-kernel-pear-cookbook.md> and ch.12 <../developer-guide/12-bare-modules-and-pear-ecosystem.md>.\n\nPACKAGES IN ONE SENTENCE EACH\n\n- bare-os-protocol <../packages/bare-os-protocol/README.md> — Shared topic string, MBR layout, Protomux message IDs, and kernel feature bits used by seeder and booter.\n- bare-os-seeder <../packages/bare-os-seeder/README.md> — Stages kernel/ into a system Hyperdrive, publishes the MBR block and joins the swarm so booters can replicate the image.\n- bare-os-booter <../packages/bare-os-booter/README.md> — Joins the swarm, opens system + personal drives, builds ctx, runs /boot/init.js, shell, initd, cron, and delegated tools (git, curl, wget).\n- bare-os-coreutils <../packages/bare-os-coreutils/README.md> — Sources and build for /bin utilities plus the merged man.json database.\n- bare-os-bare-libs <../packages/bare-os-bare-libs/README.md> — Builds optional /lib/bare bundles merged into ctx.bare when enabled.\n\nThe staged tree also includes kernel/README.md <../kernel/README.md> (what lands on the system drive) and scripts/README.md <../scripts/README.md> (repo automation). Pear release links and host env notes: PEAR-RUN.md <../PEAR-RUN.md>.\n\nROOT README\n\nThe top-level README.md <../README.md> is the short runbook (clone, npm ci, seeder/booter commands). Use it when you only need copy-paste steps.\n\n_License: Apache-2.0 — see LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","bare","os","table","contents","and","reading","order"],"seeAlso":[{"name":"handbook-00-preface","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/README.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","aliases":["handbook","bare-os-handbook-index"],"listCategory":"handbook"},{"name":"handbook-00-preface","section":7,"title":"Preface — why Bare OS exists","synopsis":["man 7 handbook-00-preface","Handbook chapter (plain text from handbook/00-preface.md)"],"description":"PREFACE — WHY BARE OS EXISTS\n\nTime to read: about 12 minutes. Prerequisites: curiosity about peer-to-peer software; no Holepunch background required.\n\nMost operating system images are fetched from a single place: an HTTP mirror, a registry, or a block device someone prepared for you. Bare operating system asks a different question: what if the “golden image” were a content-addressed tree that many peers could help you replicate, so discovery and distribution look more like joining a swarm than downloading a monolithic blob?\n\nThis preface states the thesis in plain language, places the project next to familiar ideas, names what the design does not promise, and points you to the chapters that unpack each layer. The code in this repository is experimental research software—useful for learning and prototyping, not audited for production threat models.\n\nTHE THESIS IN ONE PARAGRAPH\n\nBare OS is a Unix-flavored environment whose system root lives on a Hyperdrive keyed from a tiny 512-byte MBR you read from peers. A seeder application publishes that drive; a booter application finds peers on a fixed Hyperswarm topic, replicates the drive, mounts a separate personal Hyperdrive for mutable state, and runs a JavaScript kernel (/boot/init.js) and a Tier-1 /bin built from small AsyncFunction scripts. Execution is one host process (Pear or Node) simulating POSIX paths, a line shell, and synthetic /proc-style views—not a hardware kernel.\n\nON THIS PAGE\n\n- The thesis in one paragraph <#the-thesis-in-one-paragraph>\n- How this handbook relates to other docs <#how-this-handbook-relates-to-other-docs>\n- Comparison frame <#comparison-frame-not-marketing>\n- Security and limits <#security-and-limits>\n- Research directions <#research-directions>\n- Contributing <#contributing--first-steps>\n- Where to read next <#where-to-read-next>\n\nHOW THIS HANDBOOK RELATES TO OTHER DOCS\n\n- Documentation home <../docs/README.md> — Navigation hub for all trees plus shared glossary <../docs/glossary.md>, FAQ <../docs/faq.md>, and troubleshooting <../docs/troubleshooting.md>.\n- Handbook (handbook/.md) — Story and mental model*: why two drives, how the wire protocol boots the image, what the shell and identity layers do.\n- User manual <../users-manual/README.md> — Run and use: install, seeder and booter, shell basics, identity, troubleshooting, without reading the full architecture first.\n- docs/reference/ <../docs/reference/README.md> — Where everything lives: package paths, complete environment variable tables, byte-level MBR layout.\n- developer-guide/ <../developer-guide/README.md> — How to implement: ctx fields, coreutils build, testing with Brittle, Pear staging.\n- Contributing to documentation <../docs/CONTRIBUTING-DOCS.md> — Style and CI: admonitions, Mermaid, link checks, terminology governance.\n\nIf you edit handbook Markdown, those files are also ingested into man(7) inside the image (see Chapter 10 <10-manpages-and-online-help.md>); diagrams in mermaid fences are omitted in the terminal viewer—read the repo for figures.\n\nCOMPARISON FRAME (NOT MARKETING)\n\nVersus a static ISO or container layer: the system image is still “files in a tree,” but replication is sparse and keyed: peers contribute blocks; you verify structure against Hyperdrive semantics rather than trusting a single CDN tarball.\n\nVersus a traditional multi-user kernel: there is no fork, no hardware isolation between “processes,” and no guarantee that malicious /bin scripts cannot read host memory. Commands are JavaScript in the booter’s realm. See Security and limits <#security-and-limits> below.\n\nVersus “put / on IPFS”: the stack here is Holepunch-shaped (Corestore, Hyperdrive, Hyperswarm, Protomux) with a deliberate boot protocol (MBR block 0, seed channel, optional capability RPC). The goal is a coherent dev story (seeder + booter Pear apps), not maximal compatibility with every content network.\n\nSECURITY AND LIMITS\n\nBare OS separates system (replicated image) from personal (your writable drive), but does not sandbox the shell: anything execLine can do inherits the Pear/Node process capabilities. Identity uses PBKDF2 and AEAD for the on-disk account blob and vault snapshots—passphrase quality still matters, and ciphertext only stays private if replication and backups are under your control.\n\nFor a developer-oriented trust discussion (eval boundaries, import vs in-image scripts), read developer-guide — Security and trust <../developer-guide/09-security-and-trust.md>. Chapter 5 adds a trust boundary <05-identity-vault-and-hdms.md#trust-boundaries-what-the-design-does-not-promise> summary for identity and HDMS.\n\nRESEARCH DIRECTIONS\n\nThe codebase is a testbed for P2P distribution, POSIX ergonomics on Hyperdrive, optional ctx.bare module bundles, seed-channel capability negotiation, and Pear host bridges (reload, mirrors, snapshots). Open threads include stronger isolation (workers, Pear isolates), richer networking parity, and operational hardening. Treat roadmap bullets in Chapter 4 <04-the-booter-runtime.md#roadmap-and-out-of-scope> as current intent, not commitments.\n\nCONTRIBUTING — FIRST STEPS\n\n- Documentation: Follow the voice of this handbook (short hooks, clear “related” links). Run npm run build -w bare-os-coreutils after changing man pages; handbook ingest runs in that build.\n- Code: Read developer-guide README <../developer-guide/README.md>, then the package README for the area you touch (bare-os-booter, bare-os-coreutils, etc.). Run npm test from the repo root before opening a PR.\n\nWHERE TO READ NEXT\n\n- Vocabulary and a clone-to-prompt story — Chapter 1 — Introduction <01-introduction.md>.\n- Boxes, arrows, trust — Chapter 2 — Blueprints <02-blueprints.md>.\n- Wire format and failure modes — Chapter 3 — Protocol and disk <03-protocol-and-disk.md>.\n\nRelated: Handbook home <README.md> · Root README <../README.md> · docs/reference <../docs/reference/README.md> · CHANGELOG — ctx API <../packages/bare-os-booter/CHANGELOG.md>\n\n_This project is experimental research software, not a production OS. License: Apache-2.0 — LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","00","preface","why","bare","exists"],"seeAlso":[{"name":"handbook-01-introduction","section":7},{"name":"bare-os-handbook","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/00-preface.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-01-introduction","section":7,"title":"Chapter 1 — Introduction: what “Bare OS” is","synopsis":["man 7 handbook-01-introduction","Handbook chapter (plain text from handbook/01-introduction.md)"],"description":"CHAPTER 1 — INTRODUCTION: WHAT “BARE OS” IS\n\nTime to read: about 8 minutes. Prerequisites: none; Preface <00-preface.md> first if you want the thesis in essay form.\n\nIf you have only a minute: Bare operating system is a tiny Unix-flavored environment whose root filesystem is a Hyperdrive replicated from peers. A seeder publishes that drive and a 512-byte MBR over Hyperswarm; a booter joins the swarm, downloads the image, mounts a second Hyperdrive for per-user mutable state, and runs JavaScript “kernel” and /bin scripts inside a Bare or Node runtime.\n\nThe rest of this chapter sets vocabulary straight—without it, the architecture diagrams in Chapter 2 <02-blueprints.md> will not stick.\n\nON THIS PAGE\n\n- From git clone to a first prompt <#from-git-clone-to-a-first-prompt-story-not-a-runbook>\n- The problem this project explores <#the-problem-this-project-explores>\n- Key vocabulary <#key-vocabulary>\n- Why Hyperdrive and Hyperswarm <#why-hyperdrive-and-hyperswarm>\n- Relationship to Pear and Bare <#relationship-to-pear-and-bare>\n- Where to go next <#where-to-go-next>\n\nFROM GIT CLONE TO A FIRST PROMPT (STORY, NOT A RUNBOOK)\n\nImagine two terminals on the same machine. In one you run the seeder: it loads the kernel/ tree into a system Hyperdrive, writes a 512-byte MBR (magic BIOS, embedded public keys), and joins Hyperswarm on the project topic plus the drive’s discovery key. In the other you run the booter: it joins the topic, finds a peer, opens a Protomux channel, reads block 0, parses the MBR, opens the system drive by key, creates your personal drive, and hands off to /boot/init.js. You see a line prompt; everything “POSIX” after that is the booter’s VFS and shell simulating a machine.\n\nExact commands, env vars, and Pear workflows live in Chapter 7 — Operations <07-operations-and-development.md> and the root README.md <../README.md>. This paragraph is only the narrative spine.\n\nTHE PROBLEM THIS PROJECT EXPLORES\n\nTraditional OS images live on block devices or tarball layers. Here, the image is a Merkle tree you can address by key and replicate live. Peers do not hand you a .iso; they help you fill in the same Hyperdrive from the same discovery key.\n\nThat raises three design questions this repo answers in code:\n\n1. Discovery — How does a fresh node find _someone_ who has block 0 (the MBR) and the drive root?\n2. Separation of concerns — What is immutable-ish OS vs mutable per-device home?\n3. Execution model — What runs in the host process vs what is “inside” the simulated POSIX surface?\n\nBare OS picks: one swarm topic for the project, Protomux channels for control + replication, two Hyperdrives (system + personal), and AsyncFunction-loaded JS for kernel and utilities.\n\nKEY VOCABULARY\n\n- System drive — Hyperdrive containing /boot/init.js, /bin, /etc; replicated from the seeder image.\n- Personal drive — Separate Hyperdrive (Corestore namespace) for $HOME, /.bare, cron, and logs.\n- MBR — 512 bytes: magic BIOS plus embedded Hyperdrive public keys (primary and optional failover slots).\n- Kernel — /boot/init.js with async function start(ctx); a session loop, not a hardware microkernel.\n- /bin — Small JavaScript programs (async function run(ctx, argv)) built from bare-os-coreutils, including a TTY editor (edit, nano) and usual POSIX-style tools.\n- VFS — Booter-provided path layer: routes paths under $HOME to the personal drive, otherwise the system drive.\n- ctx — Context object passed to kernel and commands: vfs, console, execLine, identity hooks, and many optional bridges.\n- Guest — Default session before login: predictable HOME=/home/guest, no Ed25519 identity material exposed.\n- HDMS — Hyperdrive management: optional extra drives mounted under /mnt after unlock.\n\nHOLEPUNCH STACK (FIRST-USE DEFINITIONS)\n\nUse these names consistently across docs:\n\n- Hyperdrive — Append-only, sparse-friendly filesystem identified by a public key; good for a shared OS tree.\n- Hyperswarm — DHT-style peer discovery; Bare OS uses a topic (bare-os-v1) and drive discovery keys.\n- Protomux — Multiplexes logical channels on one encrypted stream; the bare-os-v1 channel carries MBR reads and replication.\n- Corestore — Storage backend that holds Hyperdrive cores; seeder and booter use separate store paths.\n- Bare — Minimal JavaScript runtime; Pear wraps Bare for distributable apps (the seeder and booter are Pear apps).\n\nWHY HYPERDRIVE AND HYPERSWARM\n\nHyperdrive gives you a single-writer (per key) log-backed filesystem with deterministic reads and sparse replication—good for an OS tree that many nodes can share.\n\nHyperswarm gives you topic-based and discovery-key-based peer finding. The seeder joins both the bare-os-v1 topic (so booters find _some_ peer) and the drive discovery key (so Hyperdrive replication completes).\n\nYou do not need to agree with every product choice to read the code: the handbook describes what the repo does, not whether it is the only way to build a P2P OS.\n\nRELATIONSHIP TO PEAR AND BARE\n\n- Bare is a minimal JavaScript runtime used by Pear apps.\n- Both seeder and booter are Pear applications (pear field in package.json) and can run under node index.js for development.\n- brittle-bare vs brittle-node split in tests reflects native addons (e.g. identity crypto) that only load on Bare.\n\nWHERE TO GO NEXT\n\n- Essay-length thesis: Preface <00-preface.md>\n- Big picture: Chapter 2 — Blueprints <02-blueprints.md>\n- Wire protocol: Chapter 3 <03-protocol-and-disk.md>\n- Day-to-day hacking: Chapter 7 <07-operations-and-development.md>\n\nNext: Chapter 2 — Blueprints <02-blueprints.md>\n\nRelated: Documentation home <../docs/README.md> · Glossary <../docs/glossary.md> · Handbook home <README.md> · Kernel extensions <../docs/reference/kernel-extensions.md> · CHANGELOG — ctx API <../packages/bare-os-booter/CHANGELOG.md>\n\n_Experimental research software, not a production OS. Apache-2.0 — LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","01","introduction","what","bare"],"seeAlso":[{"name":"handbook-02-blueprints","section":7},{"name":"handbook-00-preface","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/01-introduction.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-02-blueprints","section":7,"title":"Chapter 2 — Blueprints: architecture and trust","synopsis":["man 7 handbook-02-blueprints","Handbook chapter (plain text from handbook/02-blueprints.md)"],"description":"CHAPTER 2 — BLUEPRINTS: ARCHITECTURE AND TRUST\n\nTime to read: about 10 minutes. Prerequisites: Chapter 1 <01-introduction.md> vocabulary.\n\nThis chapter is the aerial view: boxes, arrows, and what is allowed to trust what. Implementation details live in later chapters.\n\nFor a comparison to classic images and security limits, see Preface — Comparison frame and Security <00-preface.md#comparison-frame-not-marketing>.\n\nON THIS PAGE\n\n- Boot path from seeder to shell <#0-boot-path-from-seeder-to-shell>\n- Two applications, one protocol <#1-two-applications-one-protocol>\n- Two drives on the booter <#2-two-drives-on-the-booter>\n- Protocol, MBR, and discovery <#3-protocol-mbr-and-discovery>\n- Execution stack inside the booter <#4-execution-stack-inside-the-booter>\n- Services after the console exists <#5-services-after-the-console-exists>\n- Identity states <#6-identity-states>\n- What is not here (boundary) <#7-what-is-not-here-boundary>\n\n0. BOOT PATH FROM SEEDER TO SHELL\n\nThe following is the conceptual ordering (not every substep on the wire). It complements the reference sequence diagram in Architecture: end-to-end data flow <../docs/reference/architecture-data-flow.md>.\n\n1. TWO APPLICATIONS, ONE PROTOCOL\n\n- The seeder is the publisher of the OS image (plus MBR in a small RAM map).\n- The booter is a consumer that refuses to invent a local copy: it must see peers.\n\n2. TWO DRIVES ON THE BOOTER\n\nTrust model (pragmatic):\n\n- System drive content is whatever replicated from the swarm matching the MBR keys. In dev you treat the seeder as trusted; in the wild this is “who you peer with.”\n- Personal drive is your namespace (Corestore bare-os-personal-v1). It holds secrets, cron, dotfiles, HDMS registry, vault snapshots.\n\n3. PROTOCOL, MBR, AND DISCOVERY\n\nThe shared package bare-os-protocol pins:\n\n- TOPIC_STRING === 'bare-os-v1'\n- topicKey() = crypto.hash(b4a.from(TOPIC_STRING))\n- MBR layout: 512 bytes, magic BIOS, primary key at offset 8, optional failover keys at 40 and 72\n\nMBR layout (512 bytes, see bare-os-protocol/constants.js):\n\n- Bytes 0–3: BIOS magic\n- Bytes 8–39: primary system Hyperdrive public key\n- Bytes 40–71, 72–103: optional additional keys\n\nProtomux channel bare-os-v1 carries:\n\n- Block read requests (MBR and any indexed RAM the seeder exposes)\n- Hyperdrive replication on the same socket\n- Gossip bitfield (message 2), manifest search (3/4), and *bare_os. RPC (5/6) on the seed channel — including bare_os.capabilities, bare_os.replication_status, bare_os.manifest_hints, bare_os.peer_health, bare_os.staging_slot** (see packages/bare-os-protocol/lib/channel.js; Kernel extensions <../docs/reference/kernel-extensions.md>)\n\n4. EXECUTION STACK INSIDE THE BOOTER\n\nKernel and /bin scripts are not separate processes. They are AsyncFunction closures in the same JS realm as the booter, with a synthetic ctx instead of syscalls.\n\n5. SERVICES AFTER THE CONSOLE EXISTS\n\nstopBareInitd() runs from REPL session cleanup so timers do not leak across session restarts.\n\nBare mobile lifecycle: when the host registers bareOsRegisterSuspendHook / bareOsRegisterResumeHook, the booter wires bare-initd so units with ExecStop= / ExecStart= (or equivalent stop/start paths) run in dependency order on suspend and resume—mirroring ordered service pause on mobile shells without real process freeze.\n\n6. IDENTITY STATES\n\nGuest and unlocked sessions share the same booter process; the state machine below is about environment and policy, not separate OS processes.\n\n- Guest: fixed HOME=/home/guest, read-oriented personal tree policy for some operations.\n- Unlocked: HOME under /home/<pubkey-prefix>, HDMS can attach writable drives, crontab install/remove allowed.\n\nFull story: Chapter 5 — Identity, vault, HDMS <05-identity-vault-and-hdms.md>.\n\n7. WHAT IS _NOT_ HERE (BOUNDARY)\n\n- No hardware kernel, no MMU, no ELF loader for native /bin.\n- No container cgroup isolation—commands are JS with full host capability of the Pear/Bare process.\n- Future: stronger isolation would compose Bare workers, Pear runtime isolates, or bare-kit-style embeds; the stock ctx.bareOsSandboxRunScript hook is a documented placeholder until then (see developer guide security chapter).\n- No global consensus: two booters can diverge if they replicate different forks of the same discovery key (Hyperdrive versioning is a separate concern).\n\nNext: Chapter 3 — Protocol and disk <03-protocol-and-disk.md>\n\nRelated: Preface <00-preface.md> · Handbook home <README.md> · Kernel extensions <../docs/reference/kernel-extensions.md>\n\n_Experimental research software, not a production OS. Apache-2.0 — LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","02","blueprints","architecture","and","trust"],"seeAlso":[{"name":"handbook-03-protocol-and-disk","section":7},{"name":"handbook-01-introduction","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/02-blueprints.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-03-protocol-and-disk","section":7,"title":"Chapter 3 — Protocol, MBR, and SwarmDisk","synopsis":["man 7 handbook-03-protocol-and-disk","Handbook chapter (plain text from handbook/03-protocol-and-disk.md)"],"description":"CHAPTER 3 — PROTOCOL, MBR, AND SWARMDISK\n\nTime to read: about 12 minutes. Prerequisites: Chapter 2 — Blueprints <02-blueprints.md>.\n\nHere we connect bare-os-protocol to what seeder and booter actually do on the wire and in RAM. For byte offsets and constants, keep package-bare-os-protocol <../docs/reference/package-bare-os-protocol.md> open. For kernel feature bits and seed-channel RPC behavior, see Kernel extensions <../docs/reference/kernel-extensions.md>.\n\nON THIS PAGE\n\n- The MBR in plain language <#the-mbr-in-plain-language>\n- Seeder lifecycle <#seeder-lifecycle>\n- Booter: from peers to Hyperdrive <#booter-from-peers-to-hyperdrive>\n- Message IDs <#message-ids--what-each-is-for>\n- Kernel feature bitmask (documentation) <#kernel-feature-bitmask-documentation>\n- Personal drive replication <#personal-drive-replication>\n\nTHE MBR IN PLAIN LANGUAGE\n\nThink of the MBR as a business card for the system image: 512 bytes that say “this Hyperdrive key (and optional alternates) is the OS you want.” The first bytes are the ASCII magic BIOS so booters do not mistake random data for a catalog. Starting at offset 8, the card embeds 32-byte public keys—the primary system drive first, then optional failover keys at 40 and 72 if you publish multiple compatible images.\n\nThe booter always tries to obtain block 0 through the swarm-backed SwarmDisk; it does not silently fall back to your git checkout’s kernel/. That design choice forces you to confront availability: if nobody is seeding, you do not boot.\n\nDetails: bare-os-protocol/constants.js <../packages/bare-os-protocol/constants.js> and the reference doc above.\n\nSEEDER LIFECYCLE\n\n1. Resolve kernel root (BARE_OS_KERNEL_ROOT or vendored kernel/).\n2. Optionally rebuild coreutils when running under Node (file: URL) — skipped under Pear.\n3. Open Corestore + Hyperdrive, stageKernelTree:\n- init.js → /boot/init.js\n- bin/ → /bin/\n- etc/ → /etc/\n- Other paths under the kernel tree map to the same path on the drive; README.md at the kernel root is skipped (repository layout doc only — not installed as /README.md).\n4. Build MBR with buildMbr(drive.key) and store block 0 in a Map (localRAM).\n5. Hyperswarm join(topicKey()) and join(drive.discoveryKey).\n6. On each connection: Protomux + setupSeedChannel, which:\n- Answers read index requests from localRAM (index 0 → MBR)\n- Attaches drive.replicate(stream)\n- Optionally pairs a second channel bare-os-app-v1 when BARE_OS_PROTOMUX_APP_CHANNEL is set on the host/seeder (namespaced application RPC alongside the OS control plane on bare-os-v1; see bare-os-protocol PROTOCOL_APP_CHANNEL_NAME).\n\n!Hyperswarm and Protomux handshake <../docs/images/hyperswarm-protomux.png>\n\n> Note\n> Offsets, magic bytes, and message IDs are specified in package-bare-os-protocol <../docs/reference/package-bare-os-protocol.md>; this sequence is the behavioral summary.\n\nOPTIONAL READ-ONLY SYSTEM ALIAS MOUNT\n\nWhen the host sets BARE_OS_VFS_SYSTEM_RO_ALIAS to an absolute path (for example /snapshot/system), the VFS routes that prefix to the same read-only system Hyperdrive as / (writes denied via mntReadOnly). The path appears in /proc/mounts as bare-os-system-ro-alias. Use it for scripts and docs that expect a distinct “versioned root” without opening a second drive.\n\nBOOTER: FROM PEERS TO HYPERDRIVE\n\nSwarmDisk (booter) mirrors the seeder’s channel handlers:\n\n- read(index) — if not local RAM, broadcast msg 0 to peers, await msg 1 (timeout).\n- addPeer — open channel, replicate system (and later personal) drives on the mux stream.\n\nBoot path:\n\n1. Wait until disk.peers.size > 0 or boot timeout.\n2. parseMbr(await disk.read(0)) → list of 32-byte keys.\n3. For each key, try Hyperdrive(store, key) + replicate until /boot/init.js exists.\n4. Initialize personal drive namespace and join its discovery key.\n5. Hand off to executeKernel.\n\nThere is intentionally no “use my checkout’s kernel/ if the network fails” path—the project forces you to think about availability of the swarm.\n\nMESSAGE IDS — WHAT EACH IS FOR\n\nAligned with packages/bare-os-protocol/lib/channel.js and swarm-disk.js. The boot-critical path is 0/1 plus Hyperdrive replication on the same socket; the rest supports discovery, ops, and capability negotiation (see Kernel extensions <../docs/reference/kernel-extensions.md>).\n\n- 0 (client → peers) — Fetch a RAM block by index (block 0 is the MBR) when the booter has no local copy.\n- 1 (peer → client) — Return the bytes for that index (or otherwise satisfy the read contract).\n- 2 (gossip stub) — Bitfield buffer for optional capability and gossip experiments (see kernel feature bits).\n- 3 / 4 (search request / response) — Manifest search so operators can ask whether the image contains a path without walking the whole tree client-side.\n- 5 / 6 (RPC request / response) — *bare_os. RPC: version, health, kernel info, capabilities, replication_status**, gossip; strict boot can require answers before trusting the image.\n\nThe important path for boot is 0/1 plus Hyperdrive replication on the same socket.\n\nBOOTER DISK.OS BRIDGE (AFTER INITD)\n\nOnce initd has started, the stock booter assigns disk.os on SwarmDisk. Peers use the same Protomux channel (messages 3–6) to query the running booter—not the static seeder RAM map:\n\n- searchLocal(query) — case-insensitive substring match over system Hyperdrive paths (recursive list, capped), returned on message 4.\n- execRpc(module, method, args) — whitelisted *bare_os. calls only, UTF-8 result string on message 6**:\n- bare_os.ping → pong\n- bare_os.ctx_api_version → BARE_OS_CTX_API_VERSION\n- bare_os.uptime_ms → ms since booter VFS construction started\n- bare_os.system_revision → JSON of ctx.bareOsSystemRevision\n- bare_os.ipc_list → JSON array of FIFO channel names\n- bare_os.service_names → JSON array of initd unit names\n- bare_os.echo → JSON {\"args\":[…]} (debug)\n- bare_os.disk_os_hints → JSON schema 2: protocolPackageVersion, protomuxChannelSchemaVersion, booterPackageVersion, plus mirrorDriveHintV2, httpDhtProxyHint, auxiliaryDriveCount — advisory for operators only (parity with seed kernel_info / capabilities semver fields).\n- bare_os.replication_operator_sketch → JSON schema 3: schema 2 fields plus optional blindTopologySketchV3 (BARE_OS_BLIND_PEER_TOPOLOGY_V3_JSON) and hyperblobsDedupSketch (BARE_OS_HYPERBLOBS_STATS_JSON) — non-secret operator JSON only.\n- bare_os.replication_operator_intent — cap-gated (BARE_OS_DISK_OS_OPERATOR_INTENT_RPC=1): accepts a JSON object string, appends one disk_os.replication_operator_intent row via ctx.bareOsAuditLogAppendBatch when the booter wires auditBatch; EPERM when disabled.\n- Unknown pairs throw BareOsKernelError with code BARE_OS_EXEC_RPC_UNKNOWN (surfaced as RPC error text).\n\nsearchLocal: scans the system Hyperdrive, then each SwarmDisk.auxiliaryDrives entry (read-only mirrors), dedupes paths, caps at 256 hits. Optional BARE_OS_DISK_OS_SEARCH_THROTTLE_MS (0–500) inserts a short setTimeout between drive scans to reduce load on slow replicas (offline-first friendly).\n\nImplementation: packages/bare-os-booter/lib/bare-os-disk-os-bridge.js <../packages/bare-os-booter/lib/bare-os-disk-os-bridge.js>. Architecture overview: docs/architecture/KERNEL_CONTRACT.md <../docs/architecture/KERNEL_CONTRACT.md>.\n\nKERNEL FEATURE BITMASK (DOCUMENTATION)\n\nThe package bare-os-protocol exports lib/kernel-feature-bits.js (re-exported from index.js) with versioned capability words describing optional booter / image capabilities (word 1: bits, word 2: bits2, word 3: bits3, word 4: bits4, word 5: bits5; always >>> 0 when masking). Peers see a 250-byte bitfield on message 2 (gossip stub; bit 0 set today). The seeder answers bare_os.capabilities over RPC with doc / featureBitsDoc, bits, bits2, bits3, bits4, bits5, protocolPackageVersion, role, protocol so the booter can compare before MBR read (BARE_OS_SEED_CAP_STRICT covers all non-zero words the stock booter advertises). bare_os.replication_status adds seeder-local replication hints; bare_os.replication_queue (with bounded queue / snapshot notes), bare_os.capability_attestation, bare_os.mbr_layout, bare_os.snapshot_hints, and bare_os.peer_firewall_stats are optional RPCs (hints only; guests do not verify crypto). mbr_layout / replication JSON may surface parsed failover key slots (MBR offsets 40 / 72) as hex hints for operators, plus optional staging slot, manifest, peer health, and firewall sketches when the seeder implements them. Guests read dumps under /proc/bare_os_features, /proc/bare_os/, and related /proc nodes. Unknown bits should be ignored.\n\nAuthoritative tables: Kernel extensions <../docs/reference/kernel-extensions.md>.\n\nPERSONAL DRIVE REPLICATION\n\nSwarmDisk.initPersonalDrive creates a separate Hyperdrive under a stable Corestore namespace and swarm.join(personalDrive.discoveryKey). Your $HOME tree can therefore sync across your devices if peers share that discovery key—orthogonal to the system image key from the MBR.\n\nHost logging: mount and writability warnings use emitSwarmDiskHostLog in swarm-disk.js <../packages/bare-os-booter/lib/swarm-disk.js>. When BARE_OS_BOOT_TRACE is json or ndjson, one structured type\":\"booterHost\" line ( component\":\"swarm_disk\" ) is written to stderr per event; otherwise messages go to stderr (info) or console.warn (warnings), not guest ctx.console.\n\nWhat you should expect: personal data persists under the same store path between runs; if you delete the booter Corestore or switch BARE_OS_BOOT_STORE, you effectively get a new personal namespace unless you restore keys. Multi-device sync only happens if another device joins the same personal discovery key—there is no automatic “cloud account”; it is still P2P replication semantics.\n\nFAILURE MODES YOU WILL SEE IN THE WILD\n\nBooter exits after boot timeout — Likely no peer on the bare-os-v1 topic, or Hyperswarm is blocked. Start a seeder on the same network, review BARE_OS_BOOT_TIMEOUT_MS, and confirm HYPERSWARM_BOOTSTRAP if you use custom bootstrap nodes.\n\nInvalid MBR or parse error — Block 0 may not be from this project, the RAM map may be corrupt, or the seeder may be mismatched. Align bare-os-protocol versions between seeder and booter and rebuild the MBR from a known-good drive.\n\nDrive never finishes replicating — Often a discovery key mismatch, flaky peers, or a stalled mux. Watch peer counts, restart the seeder, inspect logs, and verify the booter joined the system discovery key from the MBR.\n\nCapabilities or strict seed errors — The booter may expect features the seeder image does not advertise. Align package versions; relax BARE_OS_SEED_CAP_STRICT only if you understand the tradeoff (Kernel extensions <../docs/reference/kernel-extensions.md>).\n\nPersonal files missing on a new machine — You may be using a new Corestore path or a new personal drive. Restore the same BARE_OS_BOOT_STORE (or key backup); the personal drive is not the system MBR key.\n\nNext: Chapter 4 — The booter runtime <04-the-booter-runtime.md>\n\nRelated: Chapter 2 — Blueprints <02-blueprints.md> · Handbook home <README.md> · Kernel extensions <../docs/reference/kernel-extensions.md> · Environment appendix <../docs/reference/environment-and-posix-appendix.md>\n\n_Experimental research software, not a production OS. Apache-2.0 — LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","03","protocol","and","disk","mbr","swarmdisk"],"seeAlso":[{"name":"handbook-04-the-booter-runtime","section":7},{"name":"handbook-02-blueprints","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/03-protocol-and-disk.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-04-the-booter-runtime","section":7,"title":"Chapter 4 — The booter runtime: ctx, VFS, shell, kernel, services","synopsis":["man 7 handbook-04-the-booter-runtime","Handbook chapter (plain text from handbook/04-the-booter-runtime.md)"],"description":"CHAPTER 4 — THE BOOTER RUNTIME: CTX, VFS, SHELL, KERNEL, SERVICES\n\nTime to read: about 20 minutes (skim headings first). Prerequisites: Chapters 2–3 <02-blueprints.md>.\n\nThe booter is the largest package because it is the machine: everything the user experiences as “the OS” (except the raw Hyperdrive bytes) is assembled in packages/bare-os-booter/index.js and *lib/.js**.\n\nCTX AT A GLANCE (SURFACE AREA)\n\nctx is the single handle passed into /boot/init.js and every /bin utility. You can think of it as the simulated machine:\n\n- ctx.vfs — path operations across system + personal drives (readFile, writeFile, stat, chdir, …).\n- ctx.console — log / error wired to the session console (and often mirrored to kernel logs).\n- ctx.execLine / ctx.readLine — the line shell and prompt input.\n- ctx.runBinCommand — run a /bin command as if typed (used by time, xargs, etc.).\n- Identity — hooks and state for guest vs unlocked sessions (login / logout).\n- Optional ctx.bare — merged Bare module map when the host allows imports + optional drive bundles (see below).\n- Policy and caps — ctx.bareOsRuntimeCaps, optional httpFetch (policy fetch for delegated curl/wget when a fetch backend exists at ctx build), IPC FIFOs, HDMS, Pear reload requests, audit flags, …\n\nThe authoritative field list and versioning story are in developer-guide — The context object <../developer-guide/02-the-context-object.md> and CHANGELOG <../packages/bare-os-booter/CHANGELOG.md>.\n\nBOOT SPLASH AND STDIO\n\nresolveStdio() picks session stdin/stdout appropriate for Pear/Bare vs Node. When stdout is a TTY and BARE_OS_NO_SPLASH is unset, createBootSplash draws a full-screen boot UI tied to BARE_OS_BOOT_TIMEOUT_MS: a centered block with title, tagline, framed log area and progress bar sized to the terminal, phase lines with spinner, and optional footer lines (booter and protocol versions from main()). Vertical padding is capped so very tall terminals do not push content too far down. prepareForKernel() clears the screen and restores the cursor before the line editor attaches.\n\nNon-TTY mode skips splash noise; automation uses BARE_OS_SKIP_REPL=1.\n\nEXECUTEKERNEL IN ONE PARAGRAPH\n\nAfter the system and personal drives exist:\n\n1. Build shellEnv (guest defaults: HOME, PATH, USER, …, BARE_OS_CTX_API_VERSION), copying host keys when set — including *BARE_OS_PIPELINE_, BARE_OS_SHELL_STREAMING, BARE_OS_SHELL_STREAMING_MULT, BARE_OS_SHELL_CMDSUBST, BARE_OS_SHELL_CMDSUBST_MAX_BYTES, boot and audit toggles (BARE_OS_BOOT_PROFILE, BARE_OS_ONBOOT, BARE_OS_BOOT_STRICT, BARE_OS_RC_D_SKIP, BARE_OS_BOOT_MINIMAL, BARE_OS_BOOT_SKIP, BARE_OS_BOOT_TRACE, BARE_OS_KERNEL_SELFTEST, BARE_OS_SELFTEST_FORMAT, BARE_OS_AUDIT, BARE_OS_AUDIT_JSON, BARE_OS_AUDIT_REDACT, BARE_OS_BOOT_ALLOWLIST, BARE_OS_EXEC_MAX_DEPTH, BARE_OS_IPC_, BARE_OS_IPC_CHANNEL_MAX_BYTES, BARE_OS_HTTP_ALLOWLIST, BARE_OS_HTTP_DENYLIST, BARE_OS_TLS_PIN_SHA256, BARE_OS_VFS_WATCH, BARE_OS_VFS_UNION_PREFIXES, BARE_OS_VFS_UNION_WRITE_DENY, BARE_OS_VFS_BIN_CACHE, BARE_OS_IMAGE_DIGEST, BARE_OS_PEAR_CHANNEL, BARE_OS_PEAR_RELEASE, BARE_OS_BARE_MODULES, BARE_OS_BARE_DRIVE_BUNDLES, BARE_OS_BOOT_MANIFEST, BARE_OS_BOOT_MANIFEST_SIGN, BARE_OS_BOOT_MANIFEST_PUBKEY_HEX, BARE_OS_BOOT_POLICY, BARE_OS_SANDBOX_SCRIPT, BARE_OS_SANDBOX_WORKER, BARE_OS_INITD_MAX_PARALLEL, BARE_OS_INITD_JOURNAL_MAX_LINES, BARE_OS_URANDOM_CRYPTO, BARE_OS_TELEMETRY_NDJSON, BARE_OS_SEED_RPC_HANDSHAKE, BARE_OS_SEED_CAP_STRICT, BARE_OS_SEED_CAP_FAIL, BARE_OS_BLIND_BOOTSTRAP_URL, BARE_OS_BLIND_BOOTSTRAP_JSON, BARE_OS_MIRROR_READ_KEY, PEAR_CHANNEL, Capability word 9 keys (BARE_OS_SOCKS_PROXY_MAP_JSON, BARE_OS_BARE_CRYPTO_VERSION, BARE_OS_PEAR_IPC_PACKAGE_VERSION, BARE_OS_PEAR_UPDATER_CHANNEL, BARE_OS_HAPPY_EYEBALLS_V3_MODE, BARE_OS_BIN_WORKER_WASM_MS_MAX, BARE_OS_PROBE_ID_BARE_MODULE_CRYPTO_STAGING, optional BARE_OS__JSON for /proc/bare_os/ Capability word 9 files), and Capability word 10 keys (BARE_OS_PROBE_ID_PEAR_INSPECT_LOGGER_TLS, BARE_OS_BARE_RPC_PROBE_CLASS, BARE_OS_MTLS_PROXY_MAP_JSON, BARE_OS_THREAD_POOL_TELEMETRY_JSON, BARE_OS_HAPPY_EYEBALLS_V4_MODE, BARE_OS_BARE_BOOT_VERSION, BARE_OS_BARE_LOGGER_VERSION, BARE_OS_BARE_TLS_VERSION, BARE_OS_LIFECYCLE_SCHEMA_VERSION, optional BARE_OS__JSON for Capability word 10 /proc/bare_os/ files — see Chapter 7 <07-operations-and-development.md>, the environment appendix <../docs/reference/environment-and-posix-appendix.md#14-environment-variables-complete-list>, Kernel extensions <../docs/reference/kernel-extensions.md>, and the context object developer guide <../developer-guide/02-the-context-object.md>. Set BARE_OS_BOOT_PROFILE_RESOLVED from the host override or the first line of /etc/bare-os/profile on the system drive; assign BARE_OS_SESSION_ID for /run/bare-os/session. Seed /run/bare-os/boot.json fields imageDigest, pearChannel, pearRelease, and accumulate booterPhases (vfs, ctx, repl, initd, kernel_invoke) for observability alongside kernel phases*.\n2. createBareOsIpc({ maxFifoBytes, perChannelMaxBytes?, ipcRpcToken?, enableFanout?, maxJsonRpcLineBytes? }) — in-memory FIFOs under /run/bare-os/ipc/<name>; optional per-name byte caps via BARE_OS_IPC_CHANNEL_MAX_BYTES (JSON map); pushJson/takeJson with optional shared-secret field bareOsIpcToken when BARE_OS_IPC_RPC_TOKEN is set; fan-out topics fanoutPublish/fanoutSubscribe (disable with BARE_OS_IPC_FANOUT=0); createDuplexBridge(baseName) pairs two push/take sides for bidirectional byte streams; duplexJsonRoundTrip(side, request) sends one JSON object and awaits one JSON reply (bounded); stats includes fan-out subscriber counts.\n3. createVfs(drive, personalDrive, shellEnv, mntRef, vfsOptions?) — the two-drive router; optional vfsOptions supply procSnapshot (/proc/version, cmdline), dynamic text for /proc/net/dev, /proc/diskstats, /proc/bare_os_quotas, /proc/bare_os_resources, /proc/bare_os_features, /sys/class/net/lo, bootProfileText, sessionText, initdRunText, bootReadyJsonText, getVirtualReaders for /run/bare-os/virtual/<name>, etc.\n4. After VFS: buildBareCtxObjectFromHost + maybeMergeBareFromDrive fill a bareLibrary map (host imports first; drive bundles only add missing keys). /lib/bare/manifest.json and */lib/bare/bundles/.js are trusted like /bin**. See developer guide ch.12 <../developer-guide/12-bare-modules-and-pear-ecosystem.md>.\n5. Construct ctx: disks, vfs, bareOsIpc, env, b4a, optional bare: Object.freeze(bareLibrary) when BARE_OS_BARE_MODULES is enabled, topic, bareOsRuntimeCaps (pipeline limits, quotas, pseudo path list, feature flags such as vfsWatch, ipcRpcJson, ipcFanout, initdSocketActivation, bareCtxModules, bareDriveBundles), optional httpFetch (policy-wrapped fetch when globalThis.fetch or ctx.bare.fetch is available at ctx build — see HTTP: curl and wget <../docs/reference/http-curl-and-wget.md>), optional bareOsHostStats from the bare-os module, bareOsGetResourceStatus, bareOsRegisterVirtualFile, Pear/sandbox stubs, identity hooks, bareOsSubscribeBootEvent / bareOsEmitBootEvent, bareOsSubscribeHdmsLifecycle, bareOsAwaitInitdUnits, runHdms, requestBooterExit, bareOsPublishBootReady, …\n6. applyGuestEnv + ensureGuestHome — identity stub and /.bare skeleton on the personal drive (after the ctx object exists).\n7. createKernelReplSession — fish-style readLine + console bound to the same stdout as the prompt.\n8. Set ctx.execLine, ctx.readLine, ctx.runBinCommand — optional AbortSignal/timeoutMs on execLine, readLine, runBinCommand, and VFS readFile/writeFile; exit, optional audit logging (BARE_OS_AUDIT, BARE_OS_AUDIT_JSON, redaction), execLine nesting cap (BARE_OS_EXEC_MAX_DEPTH), then execShellLine.\n9. await startBareInitd(ctx) — see below.\n10. runKernelFromSource(initSource, ctx) — runs /boot/init.js.\n\nCleanup path closes swarm/drives and calls session.cleanup(), which runs stopBareInitd().\n\nVFS: TWO DRIVES, ONE PATH SPACE\n\nlib/vfs.js implements resolveLogical with unix-path-resolve(cwd, userPath) (two arguments only—important when reading the code).\n\n- Paths under $HOME resolve to the personal Hyperdrive under /.bare-os/home/<HOME-basename>/… (mutable writeFile / unlink where policy allows); writable /var/log uses /.bare-os/var/log/<same-basename>/…; writable /tmp uses /.bare-os/tmp/<same-basename>/… (session-isolated scratch). With BARE_OS_PERSONAL_ACCT_PREFIX=1, these three subtrees nest under /.bare-os/acct/<id>/… first (see multi-account design <../docs/design/multi-account-personal-subvolumes.md>).\n- Guest vs sealed /.bare: In guest mode, /.bare/account, /.bare/vault/, and vault-rotation-audit paths are not readable or writable (and readdir / .bare hides account / vault names) unless BARE_OS_GUEST_BARE_READ_ALL=1. login / logout** also clear warm read caches, reset simulated shell jobs, and reload fish history so another principal’s session does not bleed through.\n- Legacy flat-root migration — One-time lift from personal / into the active home prefix is governed by BARE_OS_PERSONAL_ROOT_MIGRATE and state /.bare-os/migration/legacy-root-v1.json; guest skips the lift when an account blob exists (so another user’s legacy files never land in /home/guest). Optional BARE_OS_GUEST_SCRUB wipes guest /tmp and selected caches when entering guest.\n- Other absolute paths hit the system drive (OS image).\n- Hyperdrive rejects / as a filename; the VFS special-cases logical root for stat, chdir, exists.\n\nVirtual listings include /home (session-specific), /mnt when HDMS mounts exist, and injected root entries proc, sys, tmp when absent from the system image.\n\nCatalog detail: Chapter 9 <09-posix-utilities-shell-and-vfs.md>.\n\nPSEUDO /PROC, /SYS, /RUN, /DEV (MOSTLY READ-ONLY)\n\nThese paths are synthetic (not stored on either Hyperdrive). They exist for inspection and scripting ergonomics, not Linux ABI compatibility. In blog terms: /proc is “what is this session doing?”; /sys is “tiny sysfs-shaped stubs”; /run is “volatile session state the booter owns”; /dev is “just enough device names that scripts stop crashing”; session /tmp is “scratch space that never lands on the read-only system drive.”\n\n- /proc: version, bare_os_version, uptime, meminfo, cpuinfo, loadavg, mounts, diskstats (peer-scaled synthetic lines), bare_os_quotas (JSON: pipeline limits, exec-depth cap, IPC cap, session stats, FIFO stats), bare_os_resources, bare_os_features (includes advertised stock words bits2 … bits10 when non-zero, optional seedHandshake summary after bare_os.capabilities RPC when enabled), bare_os_swarm (bounded P2P / session snapshot when the host provides it), bare_os_replication (JSON hints: version, peers, last error; may embed manifestHints, peerHealth, stagingSlot, seedSnapshotHints, seedPeerFirewallStats, seedReplication, mbrKeysHex from seed RPCs), bare_os_manifest_hints, bare_os_peer_health, bare_os_staging_slot, bare_os_snapshot_hints, bare_os_provenance (digest / signing / Pear channel summary), bare_os_pear_ipc_registry (well-known Pear IPC channel names), bare_os_pear_trust (operator JSON from BARE_OS_PEAR_TRUST_JSON), bare_os_initd_dag / bare_os_initd_graph (initd dependency graph JSON; graph may include a dot string), boot_graph.json (declarative kernel boot stage graph + boot-ready snapshot), bare_os_rlimits (getrlimit-shaped mirror of runtime caps), bare_os_hdms_health (non-secret mount/registry summary), bare_os_metrics_live (coalesced quotas/resources snapshot; interval BARE_OS_PROC_POLL_MS; schema 2 adds delegate inflight / rate-bucket samples), bare_os_net_summary (operator rollup of swarm topic, peer count, seed RPC hints; optional transport from BARE_OS_NET_TRANSPORT_STATS_JSON; optional udxTuning / hyperswarmTuning from BARE_OS_UDX_TUNING_JSON / BARE_OS_HYPERSWARM_TUNING_JSON), bare_os_host_os.json (Holepunch bare-os or injected JSON), bare_os_sync_window.json (BARE_OS_REPLICATION_SYNC_WINDOWS UTC windows), bare_os_debug.json when BARE_OS_KERNEL_DEBUG=1 (non-secret masks), bare_os_extensions.json / bare_os_hdms_hints.json (kernel extension registry + HDMS/autopass hints), bare_os_capabilities (human-readable dump of ctx.bareOsRuntimeCaps; bare_os_capabilities.json or Accept: application/json for machine output), bare_os_bootstrap, bare_os_union (JSON: union read prefixes + BARE_OS_VFS_UNION_WRITE_DENY), bare_os_seed_handshake (raw handshake / error object), bare_os_virtual_registry (registered virtual file metadata), /proc/bare_os/ (stable names + index.json mirroring the flat *bare_os_ aliases), net/dev (P2P-oriented stub), net/tcp, net/udp (header-only stubs), self/ with environ, cmdline, cgroups, exe, fd/0–2 (stub targets), plus bare_os_session_stats. environ omits keys whose names look secret-bearing (e.g. PASSWORD, TOKEN, VAULT) and only includes a small public set plus BARE_OS_ (including BARE_OS_SESSION_ID*).\n- /sys: fs/bare_os/version, fs/bare_os/build_id (same payload sources as /proc/version / build id), class/net/lo — one pseudo file whose text is operstate and carrier lines from the booter’s sysClassNetLoText hook (stock: operstate reflects swarm peer count carrier 0/1; see createVfs in vfs.js <../packages/bare-os-booter/lib/vfs.js>), devices/virtual/ — navigable empty directory for script portability (no per-device files).\n- /sys/fs/bare_os/version: same text as /proc/version.\n- /run/bare-os/units: tab-separated snapshot of bare-initd registered units (phase, start time, description).\n- /run/bare-os/unit-journal/: append-only NDJSON per unit (<name>.ndjson) for start/stop/health/restart events (size-capped); journalctl -u also tails this file when present.\n- /run/bare-os/boot_profile: one line (plus newline): resolved boot profile name (BARE_OS_BOOT_PROFILE from the host, else first line of /etc/bare-os/profile, else empty). Listed in ctx.bareOsRuntimeCaps.pseudoFsPaths.\n- /run/bare-os/session: session UUID (from BARE_OS_SESSION_ID) plus newline.\n- /run/bare-os/virtual/: optional kernel-registered synthetic files via ctx.bareOsRegisterVirtualFile.\n- /dev/null, /dev/zero: minimal device semantics — null discards writes and reads empty; zero reads a fixed 64 KiB zero buffer. Not infinite /dev/zero like Linux.\n- /dev/shm: directory of in-memory named segments (/dev/shm/<name>); readdir lists segment names; unlink removes a segment. This is not host shm_open—it is a guest-local buffer registry for scripts and tests.\n\nNon-goals: no real PIDs, accurate meminfo, or guarantees of path parity with Linux.\n\nvfs.watch(logicalPath) (Hyperdrive-backed paths only — not pseudo roots): returns { watcher, destroy, logicalAbs, driveFolder }; use Hyperdrive’s async iterator on watcher. Disabled when host sets BARE_OS_VFS_WATCH=0. With BARE_OS_VFS_WATCH_PSEUDO=1 or BARE_OS_VFS_WATCH_SWARM=1, a bounded poll watcher is also available on allowlisted /proc paths (metrics, swarm, replication). See ctx.bareOsRuntimeCaps.features.vfsWatch.\n\nUnion read: when BARE_OS_VFS_UNION_PREFIXES lists comma-separated logical prefixes, readFile / readlink on those paths may merge the system image with overlays (see vfs.js and ctx.bareOsRuntimeCaps.features.vfsUnionRead). BARE_OS_VFS_BIN_CACHE=1 enables a small LRU read cache for /bin entries, invalidated when vfs.watch notifications fire on watched prefixes.\n\nImplementation note: pseudo-file content is UTF-8 encoded with b4a, not TextEncoder, because some Bare/Pear runtimes omit the Web Encoding globals (TextEncoder / TextDecoder). The same applies elsewhere in the booter and in-image utilities that must run on Bare.\n\n/DEV AND /RUN (MINIMAL SUBSET)\n\nSee Pseudo /proc, /sys, /run, /dev above. A full device tree and /run parity with Linux are still out of scope.\n\nCTX.BARE AND DRIVE BUNDLES\n\nAfter the VFS exists, buildBareCtxObjectFromHost plus maybeMergeBareFromDrive fill a bareLibrary map: host-configured imports first, then /lib/bare/manifest.json and */lib/bare/bundles/.js on the system drive may supply only missing keys. Those paths are trusted like /bin**—they ship in the replicated image.\n\nUse this when you want real ESM modules (Holepunch *bare- packages) inside an otherwise AsyncFunction-only tree. Trust stance: enabling BARE_OS_BARE_MODULES** and drive bundles expands attack surface; treat manifests as part of your image signing story.\n\nDeep dive: developer-guide ch.12 — Bare modules and Pear ecosystem <../developer-guide/12-bare-modules-and-pear-ecosystem.md> · kernel/lib/bare/ <../kernel/lib/bare/> · PEAR-RUN.md — BARE_OS_BARE_MODULES <../PEAR-RUN.md>.\n\nPEAR HOST BRIDGES AND HTTP POLICY\n\nThe booter exposes policy-gated hooks so a Pear host can react without forking the guest kernel:\n\n- ctx.bareOsRequestPearReload(opts?) — ask the host to reload the Pear runtime (OTA-style); optional persistRequest writes ~/.bare-os/pear-reload.request. Env mirrors BARE_OS_PEAR_CHANNEL, BARE_OS_PEAR_RELEASE, PEAR_CHANNEL into /run/bare-os/boot.json.\n- ctx.bareOsRequestMirror({ key?, label? }), ctx.bareOsExportPersonalSnapshot({ label? }), ctx.bareOsPearIpcEmit(channel, payload) — return hints or booleans; on Node the booter emits process events for embedding apps to implement real mirrors or snapshots.\n\nHTTP CLIENTS (CURL / WGET)\n\nDelegated curl and wget run from the booter’s host delegate registry before any /bin script on the system drive. They use a Fetch-shaped stack: policy-wrapped ctx.httpFetch when set, else ctx.bare.fetch from host imports or /lib/bare/bundles, else globalThis.fetch. On minimal Pear/Bare hosts, ensureBareFetchGlobals may install globals from bare-fetch or bare-https when no native fetch exists. Outbound URLs are constrained by BARE_OS_HTTP_ALLOWLIST / BARE_OS_HTTP_DENYLIST, optional BARE_OS_TLS_PIN_SHA256 (and init.bareOsCurlTls for curl TLS details), and optional BARE_OS_DNS_ALLOWLIST. The drive still ships /bin/curl and /bin/wget as manifest stubs; normal sessions never execute them.\n\nCanonical reference: HTTP: curl and wget <../docs/reference/http-curl-and-wget.md> · Flag matrix: CLI_PARITY.md <../packages/bare-os-booter/CLI_PARITY.md> · Full env tables: environment appendix <../docs/reference/environment-and-posix-appendix.md> · Pear notes: PEAR-RUN.md <../PEAR-RUN.md>.\n\nROADMAP AND OUT-OF-SCOPE\n\nRemaining gaps are tracked in packages/bare-os-booter/CLI_PARITY.md, POSIX appendix — gaps <../docs/reference/environment-and-posix-appendix.md#14a-posix-userland-appendix-implemented-vs-gaps>, and Kernel extensions <../docs/reference/kernel-extensions.md>: transports and flags curl/wget may never match GNU; pipelines remain bounded captures rather than kernel pipes; bareOsSandboxRunScript is not a hard hardware-style isolate yet (optional stronger paths are documented in bare-os-sandbox.js); socket-activation idle stop remains directional work, not a promise.\n\nMilestone shape (current intent): (1) VFS + shell + synthetic proc/run + boot trace + allowlists — largely in place; (2) man and incremental /bin flags; (3) delegated HTTP parity where feasible; (4) init/protocol hardening as needs arise.\n\nDirectories: vfs.mkdir(path, { recursive }) and vfs.rmdir(path) implement POSIX-like tree creation and removal using a .bareos_empty marker file for empty directories (aligned with git-fs-adapter). See Chapter 9 <09-posix-utilities-shell-and-vfs.md>.\n\nctx.runBinCommand(argv) — same resolution as external commands in the shell; exposed for utilities such as /bin/time.\n\nSHELL AND KERNEL RUNNER\n\nexecShellLine (lib/shell.js):\n\n- Tokenizes words, quotes, escapes, $VAR, pipelines |, redirections > / >> / <.\n- Builtins: alias, unalias, cd, export, unset, readonly, umask, :, command, type, login, logout, exit, jobs, fg, wait, bounded if/while/for/case — plus external commands via runBinCommand. Optional BARE_OS_SHELL_CMDSUBST enables bounded $(…) in words; optional BARE_OS_SHELL_STREAMING scales pipeline capture caps. readonly blocks export and assignment writes to the same name; command -v / -V and type use resolveBinInPath for PATH lookup.\n- First-word aliases (defaults like ll → ls -la, nano → edit) expand after $VAR substitution; alias / unalias match the restricted ~/.barerc syntax (not full POSIX sh).\n- Pipes capture console.log into the next stage or a string sink.\n\nrunBinCommand (lib/kernel-runner.js):\n\n1. If argv[0] contains / — resolve via VFS, drive.get, runScriptFromSource.\n2. Else if the name ends with .js — resolve $PWD/name.js first (same as explicit ./ for many cases).\n3. Else walk PATH on the system drive only.\n\nrunScriptFromSource strips an optional #! line, runs the script body as top-level code in an async function, then awaits a top-level run(ctx, argv) if one is defined (optional for user scripts; /bin utilities always define run). It catches errors—logs to ctx.console.error without unwinding the kernel loop.\n\nrunKernelFromSource requires async function start(ctx) at the top level of /boot/init.js.\n\n~/.BARERC (RESTRICTED STARTUP FILE)\n\nOn guest and logged-in identity transitions, the booter loads ~/.barerc from the personal drive if it exists. On login (unlocked identity), if the file is missing, the booter creates a comment-only skeleton you can edit. Only these forms are applied (other lines are ignored; set BARE_OS_STRICT_BARC=1 to log warnings):\n\n- export NAME=value — same name rules as the shell builtin; value is expanded like export in execShellLine.\n- alias name=value and unalias — same behavior as the interactive builtins (unalias -a resets to the default alias table).\n\nThere is no arbitrary command execution, source, or control flow — it is intentionally not a full sh profile.\n\nBARE-INITD, CRON, AND THEMES\n\nbare-initd.js (below) starts DAG-ordered units after the console exists. bare-cron (also below) reads /etc/bare-os/crontab and ~/.crontab.\n\nThemes live in docs/themes/README.md <../docs/themes/README.md> — preset packs (for example Nord) that align LS_COLORS, prompt colors, and sample Alacritty / Warp YAML so your host terminal and the in-guest theme / dircolors utilities agree. At login, ~/.barerc may contain theme nord (plus export / alias lines) to set *BARE_OS_COLOR_** without hand-editing escape codes.\n\nBARE-INITD AND KERNEL LOGGER\n\nbare-initd.js:\n\n- registerBareService({ name, start, stop?, description?, logPath? }) — optional stop enables systemctl stop / restart for that unit; logPath is a logical VFS path for systemctl status / logs\n- startBareInitd(ctx) — ensures /var/log/bare-os (see below), then DAG-ordered start with optional parallelism (BARE_OS_INITD_MAX_PARALLEL, default 1). Skips units listed in ~/.config/bare-os/initd/disabled.txt. Drop-ins ~/.config/bare-os/units/<name>.unit support [Unit] keys After=, Before=, Requires=, Wants=, TimeoutStartSec=, TimeoutStopSec=, Restart=, RestartSec=, OnFailure=, FailureAction=, ExecStartPost=, SocketActivationIpc= (defers start() until the first read on that FIFO), IdleSec= (with socket activation and a stop handler: stop after idle seconds between FIFO messages), ReadinessPath= (VFS path until exists, or exec:<execLine> gated by ReadinessTimeoutSec=), ReadinessTimeoutSec=, ConditionPathExists= (skip start when missing), AssertPathExists= (fail unit when missing). Optional fragments *~/.config/bare-os/units.d/<name>/.conf (sorted .conf) merge after the main .unit and before ~/.config/bare-init/units/ overrides. Cycles in After/Before are detected and logged; affected units fail start. Default bare-cron runs after kernel-logger. Per-service try/catch, [bare-initd] name: err on failure; failures append to /var/log/bare-os/initd.log and the structured unit journal; runtime state active / failed / inactive. waitForBareInitdUnits(names, timeoutMs) polls until listed units are active (exposed as ctx.bareOsAwaitInitdUnits). Mobile Bare.suspend / Bare.wakeup walks stop handlers in reverse boot order and start hooks forward, matching the DAG snapshot in /proc/bare_os/initd_graph.json. Coalesced /proc/bare_os/metrics_live.json (and ctx.bareOsReadProcMetricsLive()) include initdReadiness (schema 2**) for unit readiness summaries.\n- listBareServices(), getBareServiceRuntime(name), findBareServiceDefinition(name), startBareService / stopBareService / restartBareService — introspection and lifecycle (used by the CLI below)\n- bareInitdShutdownActiveUnitsReverse(ctx) — REPL session.cleanup awaits this first: calls stop on every active unit with a stop handler, in reverse boot-DAG order (same direction as mobile suspend).\n- registerKernelShutdownHook(fn) + runKernelShutdownHooks() — async-friendly teardown after initd reverse stop, before disposers; then stopBareInitd() clears intervals and runs registerBareInitdDisposer callbacks.\n- registerBareInitdDisposer(fn) + stopBareInitd() — for intervals and synchronous teardown\n- Kernel logger — mirrors console.log/error to /var/log/bare-os/kernel-console.log. The VFS exposes /var as a virtual directory and maps /var/log/… onto the personal Hyperdrive at /.bare-os/var/log/… (the system image drive stays read-only). Each log file is trimmed when it grows past 512 KiB (last 256 KiB kept plus a notice line).\n\nBuilt-in kernel-logger wraps ctx.console.log / error to append UTF-8 lines to that path (with stop / restart support). startBareInitd also creates /var/log/bare-os and a short README there. Other services use the same tree (e.g. cron.log). Failures to write logs are swallowed so logging never kills the session.\n\nService control: /bin/systemctl is implemented by the booter (kernel-runner delegates to systemctl-cli.js), not by eval’d image JS. Subcommands: list / list-units (shows PRESET enabled/disabled from disabled.txt), status, logs, start, stop, restart, enable, disable, is-enabled. journalctl -u UNIT (log tail only) shares the same backend. The legacy name bare-initctl is still accepted as an alias. enable / disable only affect the next startBareInitd (personal-drive config); runtime start / stop remain session commands. See man systemctl.\n\nBARE-CRON\n\nbare-cron.js registers service bare-cron:\n\n- Reads /etc/bare-os/crontab on the system image (if present), then ~/.crontab on the personal drive (silent if missing). Invalid lines are skipped and logged to /var/log/bare-os/cron.log.\n- Loads timer drop-ins from *~/.config/bare-os/timers/.timer (max 8 files): [Timer] with OnCalendar= (five cron fields) + ExecLine= — merged into the same minute tick as crontab jobs; optional JitterSec= (spread execLine within 0…N seconds); or EveryMs= (1000–86400000) + ExecLine= — fixed-interval setInterval jobs (optional JitterSec= delays the first tick); or OnInactiveSec= + ExecLine= — fire after the last timer run finishes plus an idle window (Persistent= keeps scheduling state where supported). Image examples: /etc/bare-os/timers/.timer.example on the system drive (copy into ~/.config/bare-os/timers/ and rename to .timer**).\n- Parses five-field cron lines + command remainder, @reboot + command (once per bare-cron start), and optional leading JitterSec=N on the command side for calendar lines.\n- Aligns to minute boundaries, setInterval(60s), runs await ctx.execLine(command) with per-line in-flight guard; job errors are appended to /var/log/bare-os/cron.log as well as console.error. Calendar lines use wall-clock minute ticks; EveryMs= timers use monotonic-ish setInterval spacing (not drift-corrected to NTP — see distributed time sync in /proc/bare_os when enabled). With BARE_OS_TIMER_EVERY_MS_MONOTONIC=1, EveryMs= units may prefer monotonic scheduling where the runtime supports it.\n- One disposer at module load clears timers on session shutdown; stopBareCron is also the unit stop for systemctl.\n\nInstall/list/remove user crontab with /bin/crontab (see Chapter 6 <06-kernel-and-binaries.md>). See Developer guide ch.11 <../developer-guide/11-kernel-pear-cookbook.md> for timer file layout.\n\nSHELL SESSION, CONTROLLING TTY SKETCH, AND JOB-CONTROL GAPS\n\nThe interactive shell keeps ctx.shellSessionState: sid (session id), nextPgid (for & background jobs), foregroundPgid (reset to sid before each foreground line — session-leader model), and controllingTty (/dev/console or ipc:<session-fifo> when BARE_OS_SESSION_FIFO / BARE_OS_IPC_SESSION_FIFO is set). Background jobs record sid / pgid in ctx.shellBackgroundJobs for jobs output. This is not full POSIX job control: there is no tcsetpgrp, no SIGTSTP/SIGCONT pipeline to the host TTY, and fg/bg are not implemented. Host SIGINT may arrive as bare-os:host-sigint (via optional bare-signals or process.on('SIGINT')) for cooperative cancellation; ctx.bareOsSendSignal also records PIPE / CHLD / USR1 / USR2 on synthetic PIDs without ending the session.\n\nREPL: FISH-STYLE LINE EDITOR\n\nWhen stdin/stdout are a capable TTY and BARE_OS_FISH≠0, fish-readline.js provides history, hints, and synchronized Console output so prompts and console.log do not fight. History files live on the personal drive keyed by user identity, so guests and logged-in users do not stomp each other’s command recall. Set BARE_OS_FISH=0 for minimal readline or pipes-first automation; BARE_OS_SKIP_REPL=1 skips the interactive kernel loop entirely.\n\nImplementation touchpoint: packages/bare-os-booter/lib/fish-readline.js <../packages/bare-os-booter/lib/fish-readline.js>.\n\nDEBUG\n\ndebug-repl.js and env-driven logging can trace readline and write paths—useful when stdin is a pipe vs TTY.\n\nNext: Chapter 5 — Identity, vault, HDMS <05-identity-vault-and-hdms.md>\n\nRelated: Preface — Security <00-preface.md> · Kernel extensions <../docs/reference/kernel-extensions.md> · CHANGELOG <../packages/bare-os-booter/CHANGELOG.md>\n\n_Experimental research software, not a production OS. Apache-2.0 — LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","04","the","booter","runtime","ctx","vfs","shell","kernel","services"],"seeAlso":[{"name":"handbook-05-identity-vault-and-hdms","section":7},{"name":"handbook-03-protocol-and-disk","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/04-the-booter-runtime.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-05-identity-vault-and-hdms","section":7,"title":"Chapter 5 — Identity, vault, and HDMS","synopsis":["man 7 handbook-05-identity-vault-and-hdms","Handbook chapter (plain text from handbook/05-identity-vault-and-hdms.md)"],"description":"CHAPTER 5 — IDENTITY, VAULT, AND HDMS\n\nTime to read: about 12 minutes. Prerequisites: Chapter 4 — Booter runtime <04-the-booter-runtime.md> (VFS and shell).\n\nThis chapter covers who the session is (guest vs unlocked), where keys live, encrypted vault snapshots, and extra Hyperdrives under /mnt. Cryptographic details are implemented in identity-account.js <../packages/bare-os-booter/lib/identity-account.js> and identity-session.js <../packages/bare-os-booter/lib/identity-session.js>; here we stay at prose level.\n\nEND-TO-END: FROM COLD BOOT TO AN HDMS MOUNT\n\n1. Boot — The booter applies guest defaults: USER=guest, HOME=/home/guest, no Ed25519 material in the environment. You can already read the system image and write guest-scoped paths on the personal drive.\n2. login — You provide a passphrase. If the account exists, the booter decrypts /.bare/account and derives session keys; if login --new, it mints a new Ed25519 keypair and writes a v2 blob (see below).\n3. Unlocked — HOME moves under /home/<pubkey-prefix>, BARE_OS_PUBLIC_KEY is set, and HDMS may attach extra Hyperdrives registered on the personal drive.\n4. hdms mount … — Writable or read-only drives appear under /mnt/<label>; the registry JSON on the personal drive is the source of truth.\n5. logout — Sensitive material is zeroed; you return to guest. logout --save or savevault can snapshot selected paths into /.bare/vault/ as encrypted records.\n\nPairing hints (operators): when the host sets BARE_OS_AUTOPASS_INVITE_URL, the guest exposes a JSON hint at /proc/bare_os/hdms_hints.json. The guest does not open network URLs automatically; hosts or operators consume the hint out-of-band. /proc/bare_os/hdms_health.json (and flat alias) summarizes non-secret mount/registry metadata (counts, labels) for dashboards—no key material.\n\nUnlock errors (automation): when unlockIdentity in identity-session.js <../packages/bare-os-booter/lib/identity-session.js> throws, stable Error.code values include BARE_OS_IDENTITY_NO_ACCOUNT (no /.bare/account blob) and BARE_OS_IDENTITY_PASSPHRASE_REJECTED (decrypt/parse failure; error.cause carries the underlying error when present). Human-readable messages remain for interactive login.\n\nCron note: crontab install/remove requires unlocked identity so arbitrary guests cannot overwrite ~/.crontab.\n\nGUEST SESSION\n\nOn boot, applyGuestEnv sets:\n\n- USER / LOGNAME — guest\n- HOME / PWD — /home/guest\n- BARE_OS_IDENTITY — guest\n- Empty or absent BARE_OS_PUBLIC_KEY\n\nThe personal drive still persists: guest data is not anonymous to the drive—it is simply the unauthenticated profile.\n\nHome and session logs on disk: logical $HOME and /var/log map to the personal Hyperdrive under /.bare-os/home/<basename> and /.bare-os/var/log/<basename>, where <basename> is the first segment of HOME (e.g. guest or the 12-hex display name). That keeps guest and unlocked trees separate on the same drive. Shared machine metadata (/.bare/account, /.bare/hdms/, vault blobs, etc.) stays outside those prefixes. On first boot after an upgrade from older booters, a best-effort migration may move non-reserved files from the personal drive root into the current session’s home prefix when that prefix is still empty.\n\nACCOUNT BLOB: /.BARE/ACCOUNT AND CRYPTOGRAPHY IN PROSE\n\nidentity-account.js defines v2 on-disk format:\n\n- Magic BAREOS01, version 2\n- 32-byte Ed25519 public key (your identity handle in the UI)\n- PBKDF2-SHA256 salt + iteration count (default 210000) — slows passphrase guessing\n- ChaCha20-Poly1305 seal over the 64-byte secret key material (bare-crypto)\n\nWhat this means in practice: the passphrase never sits on disk; the blob stores salt + iterations + ciphertext. Unlocking derives a key from the passphrase, decrypts the signing secret, and keeps derived session state in memory. login --new creates a new account; login decrypts an existing one. Legacy v1 blobs are rejected with a message to recreate.\n\nVault (savevault, logout --save): selected files are snapshotted into /.bare/vault/ as AEAD-protected / sealed blobs at rest (path hashing + keys derived from the unlocked session material in the implementation). Vault ciphertext is only as good as your passphrase, backups, and who can replicate your personal drive. NDJSON checkpoints still append under /.bare/vault-rotation-audit.ndjson; when ctx.bareOsAuditLogAppendBatch exists, the booter mirrors identity_unlock / vault_save rows into the host audit chain as identity.vault_audit_mirror for hash-chained accountability.\n\nUNLOCKED SESSION\n\nidentity-session.js:\n\n- Updates ctx.vfs.env with real USER, HOME under /home/<pubkey-prefix>, BARE_OS_PUBLIC_KEY, derived UID/GID-like fields from a hash of the public key.\n- vfs.chdir to the new home.\n- onIdentityUnlocked (from index.js) activates HDMS with Corestore, swarm bootstrap, personal drive, mount map.\n- loadBarerc runs inside applyUnlockedEnv after a successful login or login --new (with createSkeletonIfMissing: true on first unlock), so ~/.barerc exports and aliases apply immediately—custom kernels normally do not need to reload barerc themselves. Use ctx.onIdentityUnlocked if you want an extra banner or post-login message.\n\nlogout zeroes sensitive material and returns to guest; logout --save (and savevault) snapshot selected paths into /.bare/vault/ as encrypted records (see identity-account.js helpers for AEAD and path hashing).\n\nHDMS (HYPERDRIVE MANAGEMENT)\n\nhdms-manager.js implements /bin/hdms via ctx.runHdms(argv):\n\n- Registry JSON on the personal drive: /.bare/hdms/registry.json\n- Writable drives: new Corestore namespace + Hyperdrive, label, replicate to swarm\n- Read-only drives: open by key string\n- invite / pair — uses Autopass (static ESM import for Pear tracing)\n\nassertLoggedIn requires ctx.identity.state === 'unlocked' and active controller—guests can list mounts that are already open but cannot mutate registry until login.\n\nVFS exposes /mnt/<label>/... for mounted drives; writable mounts allow put on those routes.\n\nKernel hooks: ctx.bareOsSubscribeHdmsLifecycle(fn) runs your callback after HDMS activate and before deactivate with { kind: 'afterActivate' | 'beforeDeactivate', labels?: string[] } so custom /boot/init.js can refresh mounts-dependent state without forking HDMS. The stock booter also invokes onAfterActivate on the hdms module export when present (see Developer guide ch.11 <../developer-guide/11-kernel-pear-cookbook.md>).\n\nEXAMPLE SESSION (ILLUSTRATIVE TRANSCRIPT)\n\n [guest@bare:/home/guest] > login\n …\n [alice@bare:/home/a1b2c3d4e5f6] > hdms list\n (no mounts)\n [alice@bare:/home/a1b2c3d4e5f6] > hdms create-workspace notes\n …\n [alice@bare:/home/a1b2c3d4e5f6] > ls /mnt\n notes\n [alice@bare:/home/a1b2c3d4e5f6] > touch /mnt/notes/hello.txt\n\nExact subcommands and flags: man hdms after a coreutils build.\n\nHOST PAIRING HINTS (AUTOPASS-STYLE)\n\nOperators may set BARE_OS_AUTOPASS_INVITE_URL on the host so the guest exposes /proc/bare_os/hdms_hints.json with an invite URL field. The guest never opens that URL; Pear or operator tooling consumes it outside the session.\n\nMirror-drive style hints for replication workflows use ctx.bareOsEmitMirrorDriveHint (see developer-guide ch.11 <../developer-guide/11-kernel-pear-cookbook.md>).\n\nTRUST BOUNDARIES: WHAT THE DESIGN DOES _NOT_ PROMISE\n\n- Passphrase strength matters: PBKDF2 iterations slow brute force but do not fix weak secrets.\n- Vault ciphertext is only as safe as the derived key and where copies replicate.\n- Operator /proc and telemetry — Synthetic */proc/bare_os/ files are documentation-first operator mirrors. They must not carry vault passphrases, raw private keys, or sealed vault blobs; ctx.bareOsVaultAuditSummary returns only coarse identity state (hasPublicKey, identityState), not key material. Prefer NDJSON audit mirrors (identity.vault_audit_mirror**) for accountability rather than expanding proc payloads.\n- JS in-process commands can exfiltrate keys from memory—this is a toy OS shell, not a sandbox. See Preface — Security <00-preface.md#security-and-limits> and developer-guide — Security and trust <../developer-guide/09-security-and-trust.md>.\n\nNext: Chapter 6 — Kernel and binaries <06-kernel-and-binaries.md>\n\nRelated: Handbook home <README.md> · Chapter 4 <04-the-booter-runtime.md>\n\n_Experimental research software, not a production OS. Apache-2.0 — LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","05","identity","vault","and","hdms"],"seeAlso":[{"name":"handbook-06-kernel-and-binaries","section":7},{"name":"handbook-04-the-booter-runtime","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/05-identity-vault-and-hdms.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-06-kernel-and-binaries","section":7,"title":"Chapter 6 — Kernel and /bin utilities","synopsis":["man 7 handbook-06-kernel-and-binaries","Handbook chapter (plain text from handbook/06-kernel-and-binaries.md)"],"description":"CHAPTER 6 — KERNEL AND /BIN UTILITIES\n\nTime to read: about 15 minutes. Prerequisites: Chapter 4 <04-the-booter-runtime.md>, Chapter 5 <05-identity-vault-and-hdms.md> for identity-aware paths.\n\nThe kernel is a single script. The utilities are many small scripts. Both follow strict AsyncFunction contracts so the same code runs under Bare without a bundler per command.\n\nON THIS PAGE\n\n- The kernel loop in plain language <#the-kernel-loop-in-plain-language>\n- /boot/init.js <#bootinitjs>\n- Coreutils build pipeline <#coreutils-build-pipeline>\n- Command reference (summary) <#command-reference-summary>\n\nTHE KERNEL LOOP IN PLAIN LANGUAGE\n\nAfter boot snippets and the banner, stock /boot/init.js enters an infinite read/eval loop: readLine returns one user line; execLine runs it through the same shell as interactive typing (pipelines, redirects, builtins). Exceptions are caught so a bad script does not exit the session—the booter logs and continues. There is no second process: the “kernel” is a JavaScript loop in the booter, not a ring-0 scheduler.\n\nShell entry is still ctx.execLine; /bin utilities are ctx.runBinCommand or runScriptFromSource from the runner. For why import does not work inside /bin sources, read developer-guide — Modules and imports <../developer-guide/05-modules-and-imports.md>.\n\nP2P CONSISTENCY MODEL (SHORT)\n\nBare OS is offline-first but swarm-backed: the host booter joins Hyperswarm, replicates system and personal Hyperdrives, and exposes a merged VFS to the guest. The guest kernel only sees ctx.drive, ctx.vfs, and cooperative hooks — it does not open raw sockets for replication. BARE_OS_OFFLINE_LKG_BOOT and BARE_OS_LKG_SYSTEM_KEY_HEX describe boot without live peers; disk.os and seed RPCs (handbook ch.3 <03-protocol-and-disk.md>) carry operator-facing replication sketches. Mirror mounts (/mirror, union prefixes) are read models over replicated content; treat stale reads as normal until cores catch up, and use /proc/bare_os/metrics_live.json (replicationLive) plus BARE_OS_VFS_WARM_CACHE_PREFIX_INVALIDATE when you need length-driven warm-cache eviction during replication.\n\n/BOOT/INIT.JS\n\nStaged from kernel/init.js, which is a bundled artifact: edit kernel/lib/init/init-main.js <../../kernel/lib/init/init-main.js> (and optional kernel/lib/boot/ <../../kernel/lib/boot/> helpers), then run npm run bundle:kernel ( node scripts/bundle-kernel-init.mjs ) so kernel/init.js and the seeder copy stay in sync—do not hand-edit only the bundle output. Responsibilities (typical):\n\n1. Print /etc/os-release via ctx.drive.get + b4a.toString\n2. Print optional /etc/motd if present\n3. Optional boot profile: first line of /etc/bare-os/profile, overridden by host BARE_OS_BOOT_PROFILE; if the name is safe, run /etc/bare-os/rc.profile.<name> when present (before main rc)\n4. Run non-comment lines from /etc/bare-os/rc through execLine (boot-time shell snippets)\n5. Run digit-prefixed snippets under /etc/bare-os/rc.d/ (same rules as before)\n6. Run optional /etc/bare-os/rc.local (non-comment lines via execLine, after rc.d)\n7. Run digit-prefixed snippets under /etc/bare-os/kernel.d/ (same skip rules as rc.d) after rc.local\n8. Run optional */etc/bare-os/kernel.ext.d/.json drop-ins listing trusted scripts under /lib/bare-os/extensions/ (via ctx.bareOsRunImageScript); JSON may include dependsOn, requires, after, and before for extension-id ordering (topological sort; cycles fall back unless strict policy fails). Each load is recorded for /proc/bare_os/extensions.json when ctx.bareOsRegisterKernelExtensionRecord is available. With BARE_OS_KERNEL_EXT_D_HOT_RELOAD=1, after boot ctx.bareOsReloadKernelExtDropinsSafe() may append newly listed scripts only (no unload); optional audit /run/bare-os/kernel-ext-reload.ndjson**\n9. Print a one-line hint (commands, login, paths), or /etc/bare-os/banner / /etc/issue when present\n10. When BARE_OS_SKIP_REPL: optional onboot — every non-comment line from host BARE_OS_ONBOOT (newline-separated), or if unset, every such line from /etc/bare-os/onboot in order, via execLine\n11. Loop forever:\n\n- line = await readLine('')\n- Break on null (EOF / session end)\n- Skip empty lines\n- try/catch around execLine(t) so stray throws do not kill the loop\n\nThe prompt ([user@host:path] > ) is applied by the booter’s readline layer, not by init.js.\n\nBOOT PROFILES, RECOVERY, AND READINESS\n\nWhen to use which (practically):\n\n- Normal dev — leave profiles unset; use /etc/bare-os/rc and friends on the system image.\n- *BARE_OS_BOOT_PROFILE / rc.profile. — opt into extra PATH, aliases, or distro-specific setup without** forking init.js.\n- BARE_OS_BOOT_MINIMAL — “something is broken in rc” recovery: you still get os-release / motd and a prompt, but skip heavy boot phases.\n- BARE_OS_BOOT_SKIP — surgical skips (comma list) when bisecting which boot phase fails.\n- BARE_OS_BOOT_ALLOWLIST + BARE_OS_BOOT_STRICT — distributor mode: only vetted first tokens from /etc/bare-os/boot.allow run during boot snippets.\n- BARE_OS_KERNEL_SELFTEST + BARE_OS_SELFTEST_FORMAT=tap — CI smoke inside the image after boot.\n- ctx.bareOsPublishBootReady — automation hooks that watch /run/bare-os/ready or boot.json (see Kernel extensions <../docs/reference/kernel-extensions.md> for related caps).\n\nBOOT KNOBS (ENV AND HOOKS)\n\n- BARE_OS_BOOT_PROFILE / /etc/bare-os/profile — First line names /etc/bare-os/rc.profile.<name> (before rc). Suggested names: dev (extra PATH, aliases), ci (BARE_OS_SKIP_REPL + BARE_OS_ONBOOT smoke lines), kiosk (minimal rc.d, fixed onboot).\n- BARE_OS_BOOT_MINIMAL — Skip rc, rc.d, rc.local, kernel.d, onboot, and profile *rc.profile. — recovery shell with os-release / motd** only.\n- BARE_OS_BOOT_SKIP — Comma list of phases to skip: profile, rc, rc.d, rc.local, kernel.d, kernel.ext.d, onboot.\n- BARE_OS_BOOT_SAFE_MODE — Skips rc.d, kernel.ext.d, and onboot after boot policy merge (recovery).\n- BARE_OS_BOOT_TRANSACTION_JOURNAL / BARE_OS_BOOT_CHECKPOINT — Append boot NDJSON / last-phase checkpoint under /run/bare-os/ when ctx.vfs allows; journal lines and checkpoints carry a bootStage (preflight, policy, rc, extensions, services, shell) — see Kernel program <../developer-guide/kernel-program.md>.\n- BARE_OS_BOOT_DRY_RUN — Parse boot snippets but skip trusted execLine and kernel.ext.d scripts (CI).\n- BARE_OS_BOOT_POLICY_PATH, policyFallbackPaths (in boot.policy.json) — Tiered policy path and merged skip phases from secondary files under /etc/bare-os/.\n- BARE_OS_BOOT_ROLLBACK_APPLY + /run/bare-os/boot-rollback.marker — Operator rollback selector for merged skip phases.\n\n| | Dry-run (BARE_OS_BOOT_DRY_RUN) | Rollback marker (BARE_OS_BOOT_ROLLBACK_APPLY) |\n| Executes trusted boot snippets | No (parsed only) | Yes (normal boot with merged skips) |\n| Primary goal | CI / doctor preflight without side effects | Recover from a bad rollout by skipping selected stages |\n| Key artifact | stderr / trace only | /run/bare-os/boot-rollback.marker JSON merged into boot policy skips |\n- BARE_OS_REQUIRE_CTX_API_MIN / BARE_OS_BOOT_ABI_STRICT — Compare ctx.bareOsCtxApiVersion to a minimum semver when strict.\n- BARE_OS_BOOT_TRACE=ndjson (or json) — One JSON object per completed boot stage on stderr (bootTraceSchemaVersion: 2, type\":\"boot\", step / stage / phase, ms, plus sessionId / ts for ndjson). Guest os-release, motd, and banner lines additionally emit type\":\"bootOutput\" records with a preview of the text (textPreview); interactive output remains ctx.console.log.\n- BARE_OS_KERNEL_SELFTEST — After boot snippets, run a short trusted execLine checklist.\n- BARE_OS_SELFTEST_FORMAT=tap — Same self-test emits TAP lines on stderr (CI-friendly).\n- BARE_OS_BOOT_ALLOWLIST=1 — Only run boot snippet lines whose first shell token is listed in /etc/bare-os/boot.allow (plus safe builtins); distributors can start from etc/bare-os/boot.allow.example on the system image. Pair with BARE_OS_BOOT_STRICT to exit on the first disallowed or failing line.\n- BARE_OS_EXEC_MAX_DEPTH — Max nested execLine depth (host → session; default 64).\n- ctx.bareOsPublishBootReady(...) — Kernel calls this when boot is complete; populates /run/bare-os/ready (1 / 0) and /run/bare-os/boot.json (imageDigest, pearChannel, pearRelease are pre-seeded from host env when set — see environment variables reference <../docs/reference/environment-and-posix-appendix.md#14-environment-variables-complete-list>).\n- BARE_OS_BOOT_MANIFEST — When 1 / true, the stock kernel verifies /etc/bare-os/boot.manifest.json against an expected SHA-256 (see kernel init.js and ctx.bareOsBootFileSha256Hex). Example layout: kernel/etc/bare-os/boot.manifest.example.json <../kernel/etc/bare-os/boot.manifest.example.json>.\n- BARE_OS_BOOT_MANIFEST_SIGN, BARE_OS_BOOT_MANIFEST_PUBKEY_HEX — Optional Ed25519 over the raw manifest bytes: expects /etc/bare-os/boot.manifest.sig and ctx.bareOsVerifyBootManifestSignature (host/booter). Mismatch fails boot with a clear stderr line.\n- ctx.bareOsRegisterBootStepHook / bareOsInvokeBootStepHooks — Kernel extensions can observe before: / after: stock boot stages (e.g. rc, repl) without replacing init.js. Legacy bareOsRegisterBootPhaseHook / bareOsInvokeBootPhaseHooks remain. See developer guide §2 <../developer-guide/02-the-context-object.md>.\n- BARE_OS_BOOT_POLICY, /etc/bare-os/boot.policy.json — When enabled, merges skipPhases, denyBootPhases, optional minKernelCapabilitiesPrimary / requireSeedCaps, v2 maxExecLineDepth / denyEnvKeys / requireProcNodes, v3 requireKernelCapabilitiesExtendedSeedingPlatform / requireKernelCapabilitiesRlimitsDelegatesShell, allowedPearIpcChannels, denyVfsPrefixes, maxInitdRestartsPerUnit, v4 requireKernelCapabilitiesOfflineNetExtensions, denyExecLineBuiltins, allowedCtxMethods, later requireKernelCapabilitiesHostTransportDelegates … requireKernelCapabilitiesPearInspectLoggerTls, and v9 requirePearRuntimeRange, denyBareModuleSpecifierPatterns, requireBareCryptoMin, denyKernelSyscalls, requirePearIpcMin, extensionSignerPinsV2, offlineLkgManifestMaxAgeSec, bootPhasesRequireProcIndexMinSchema, plus v10 requireBareBootMin, denyBareRpcMethodPatterns, maxPearInspectDepth, requireBareLoggerMin, denyAutobaseDiscoveryChannels, requireBareTlsMin, extensionSignerPinsV3, offlineLkgRequirePearStamp, bootPhasesRequireLifecycleMinSchema (see kernel/etc/bare-os/boot.policy.example.json <../kernel/etc/bare-os/boot.policy.example.json> and docs/schemas/boot.policy.schema.json <../docs/schemas/boot.policy.schema.json>). BARE_OS_BOOT_POLICY_STRICT aborts when a check fails.\n- /etc/bare-os/selftest.d/ — Optional digit-prefixed *.sh snippets run after the main boot path when BARE_OS_KERNEL_SELFTEST is enabled (same execLine rules as other boot snippets). Pair with BARE_OS_SELFTEST_FORMAT=tap** for CI-friendly stderr.\n\nCUSTOM INIT.JS CONTRACT\n\nReplacing /boot/init.js on the system image is supported: the booter loads it with AsyncFunction and expects a top-level async function start(ctx). Stable ctx fields for kernels are documented in Chapter 4 <04-the-booter-runtime.md> and the context object developer guide <../developer-guide/02-the-context-object.md>, including ctx.bareOsRuntimeCaps for pipeline limits, quotas, pseudo path lists, and features (e.g. httpDelegate, gitDelegate, systemctlDelegate, vfsWatch, ipcRpcJson, initdSocketActivation). Use ctx.registerKernelShutdownHook for teardown that must run before stopBareInitd. Boot snippets under /etc/bare-os/rc, /etc/bare-os/rc.d/ (only rc.d files whose names start with a digit), rc.local, kernel.d/ (same digit-prefix rules), *rc.profile., and onboot are trusted (full execLine power); keep them minimal. Optional /etc/bare-os/boot.allow (see boot.allow.example in the kernel tree) lists allowed first tokens when BARE_OS_BOOT_ALLOWLIST=1**.\n\nCOREUTILS BUILD PIPELINE\n\nIn one sentence: developers edit packages/bare-os-coreutils/src/<cmd>.js and optional *lib/-engine.js helpers; build.mjs concatenates a preamble (runtime + engines) per command, emits kernel/bin/<cmd>, and the seeder stages the same bytes into its vendored kernel/bin/ for Pear. lib/commands.mjs is the sorted manifest of every /bin name; the build fails if a command is missing from the manifest or from man/pages/**.\n\n packages/bare-os-coreutils/lib/runtime.js\n +\n (optional) packages/bare-os-coreutils/lib/<engine>.js ← sed-engine, awk-engine, edit-*.js, …\n +\n packages/bare-os-coreutils/src/<cmd>.js\n ↓ (build.mjs, see preamble map)\n kernel/bin/<cmd>\n packages/bare-os-seeder/kernel/bin/<cmd> ← Pear vendored copy\n\nRule: no import in *src/.js — only async function run(ctx, argv) (shared helpers live in lib/runtime.js). Large sed and awk bodies live in lib/-engine.js; md5sum prepends lib/md5.js; jq prepends lib/jq-engine.js; all are concatenated at build time (same global scope as run). edit and nano share src/edit.js and lib/edit-.js; /bin/nano is a separate staged name (default shell alias nano → edit). See lib/commands.mjs for the full sorted /bin** name list.\n\nSIDEBAR: WHY SED AND AWK ARE “ENGINES”\n\nPOSIX sed and awk are large enough that shipping them as one file per command would duplicate parsers and bloat the image. The build prepends shared lib/sed-engine.js / lib/awk-engine.js into the emitted /bin scripts so one JS runtime runs the grammar, while run(ctx, argv) stays the stable entrypoint. Behavior is Issue 7–inspired, not byte-identical to GNU—see Chapter 9 <09-posix-utilities-shell-and-vfs.md>.\n\nFull POSIX-style catalog, stubs, and divergence notes: Chapter 9 — POSIX utilities, shell, and VFS <09-posix-utilities-shell-and-vfs.md>.\n\nDELEGATED COMMANDS (BEFORE /BIN)\n\ngit, curl, wget, and the systemctl family are not executed from the coreutils /bin sources first. runBinCommand <../packages/bare-os-booter/lib/kernel-runner.js> matches the command basename against the host delegate registry (host-delegate-registry.js <../packages/bare-os-booter/lib/host-delegate-registry.js>) before it walks PATH on the system drive. BARE_OS_DELEGATE_ALLOW can disable individual kinds (git, curl, wget, systemctl). The system image still contains /bin/curl and /bin/wget for which / ls /bin parity; when a delegate is excluded, the stock booter wires ctx.bareOsRunCurlCli / ctx.bareOsRunWgetCli so those drive-resident scripts invoke the same fetch-based backends as the delegates.\n\nHTTP details: Reference — HTTP: curl and wget <../docs/reference/http-curl-and-wget.md> · Policy: Developer guide — Security and trust <../developer-guide/09-security-and-trust.md>.\n\nFILE METADATA AND PERMISSIONS (NOT FULL POSIX)\n\nHyperdrive entries carry optional metadata.bareOs (mode, uid, gid, names, mtime) set on vfs.writeFile. New files use UMASK from the environment (default 022): typically 0644 for data files, 0755 when executable is set. ls -l and stat/lstat read that metadata; seeded system files without bareOs are synthesized (e.g. root, 0555 under /bin). The VFS enforces basic read/write/traverse checks from UID/GID and mode bits. chown / chgrp update that metadata on the personal drive (same writable scope as chmod); this is still not ACLs or a multi-user host kernel.\n\nCOMMAND REFERENCE (SUMMARY)\n\n- systemctl, journalctl — Booter-delegated: list/status/logs/start/stop/restart/enable/disable/is-enabled/is-active for bare-initd units; preset file on personal drive; journalctl -u only; bare-initctl alias; see ch. 4\n- curl, wget — Booter-delegated fetch-based HTTP clients when allowed; /bin copies call ctx.bareOsRunCurlCli / ctx.bareOsRunWgetCli when delegates are narrowed — see HTTP: curl and wget <../docs/reference/http-curl-and-wget.md> and CLI_PARITY.md <../packages/bare-os-booter/CLI_PARITY.md>\n- git — Booter-delegated (isomorphic-git); see Chapter 8 <08-git-on-bare-os.md>\n- basename, dirname — Path manipulation\n- cat, head, tail, nl — Text\n- clear — ANSI clear screen\n- crontab — -l list, -r remove, <file> install (~/.crontab; writes need login)\n- date — Date/time\n- echo, printf-like simplicity — Args to stdout\n- edit, nano — TTY full-screen buffer editor (same source for both /bin names; stock alias nano → edit); requires real TTY — see ch. 9 §5.2a <09-posix-utilities-shell-and-vfs.md>\n- env, printenv — Environment\n- exit — Sets exit code / session end via booter\n- false, true — Status\n- grep — Line filter: -E/-F, -i, -v, -w, -x, -n, -c, -l, -o, -m, -q, -s, -e, -f, -H/-h; JS RegExp, not full GNU/PCRE\n- hdms — Hyperdrive management CLI\n- help — Lists builtins + /bin\n- hostname — Host string\n- id, whoami, tty — Identity / TTY\n- login, logout — Account session\n- ls — Lists directories; *hides . unless -a; -l** uses real mode, owner, group, mtime from VFS stat\n- chmod — Octal (e.g. 644) or symbolic (e.g. u+rw) on writable drives; updates stored metadata + executable bit\n- mkdir, rmdir — mkdir -p; empty dirs use .bareos_empty (see ch. 9)\n- cp, mv, ln — cp -R, mv (copy+delete trees), ln -s only (no hard links)\n- stat, readlink — File metadata and symlink targets\n- printf, cut, tr, od — Formatting and text transforms (ASCII-oriented tr)\n- sed, awk — Large JavaScript engines in *lib/-engine.js** — not byte-identical to GNU/POSIX everywhere; see ch. 9\n- tee, find, du, cksum — Pipe tee, limited find (-maxdepth, -mindepth, -depth, -name, -type), du -k, POSIX CRC cksum\n- mktemp — Creates a temp file under session /tmp (template XXX suffix)\n- git-pear — Thin helper for Git + Pear workflows (channel/release env); see Chapter 8 <08-git-on-bare-os.md>\n- time, logname — Wall-clock time via ctx.runBinCommand; identity string\n- chown, chgrp — Update ownership in metadata.bareOs on the personal drive (same writable scope as chmod); supports :group and numeric ids; root vs owner rules as in VFS\n- mkfifo — Creates a simulated named pipe at /run/bare-os/ipc/<name> (in-memory FIFO in the booter; readFile blocks until writeFile delivers bytes)\n- getconf, xargs — Documented Bare subsets (fixed getconf table; bounded xargs via ctx.runBinCommand)\n- pathchk — Path sanity\n- pwd — Logical cwd\n- rm — Remove files; -r/-R/--recursive for directories, -f/--force (bundled -rf) — uses VFS tree walk + del per entry\n- savevault — Encrypted vault snapshot\n- seq, sleep, sort — Misc\n- test, [ — Conditionals (as implemented)\n- touch — Create/empty files\n- uname — OS string\n- wc, which — Text / PATH lookup\n- uniq, realpath, base64, sha256sum, … — Checksums and path canonicalization (see ch. 9 for md5sum, sha1sum, sha512sum, sum, base32, basenc)\n- paste, split, tac, rev, expand, unexpand, fold, fmt, comm, join, pr, yes, shuf, tsort, factor, expr, numfmt — GNU-style text/data utilities (several are memory- or output-bounded; see ch. 9 and getconf)\n- truncate, unlink, install, df, sync — File sizing, single unlink, copy+chmod, synthetic df, no-op sync\n- arch, groups, hostid, nproc, uptime, users, who — Session / stub introspection\n- dir, vdir — ls -C / ls -l via runBinCommand\n\nExact flags vary—read each src/<cmd>.js for truth.\n\nRUNNING USER SCRIPTS\n\n- ./foo.js — explicit relative path via VFS.\n- foo.js — if the basename ends with .js, the runner tries $PWD/foo.js before scanning PATH on the system drive.\n\nShebang lines #!... are stripped before compilation.\n\nNo ESM in the image: user scripts are AsyncFunction bodies, not Node modules—see developer-guide — User scripts and PATH <../developer-guide/04-user-scripts-and-path.md> and Modules and imports <../developer-guide/05-modules-and-imports.md>.\n\nEDITING THE BANNER\n\nUpdate kernel/init.js and packages/bare-os-seeder/kernel/init.js if you want the staged Pear copy’s first-run text to match (some workflows copy automatically via build; the seeder’s kernel/ tree may be vendored separately—check your release process).\n\nNext: Chapter 7 — Operations <07-operations-and-development.md> · POSIX utilities (detail) <09-posix-utilities-shell-and-vfs.md>\n\nRelated: Identity and HDMS <05-identity-vault-and-hdms.md> · Handbook home <README.md> · Kernel extensions <../docs/reference/kernel-extensions.md>\n\n_Experimental research software, not a production OS. Apache-2.0 — LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","06","kernel","and","binaries","bin","utilities"],"seeAlso":[{"name":"handbook-07-operations-and-development","section":7},{"name":"handbook-05-identity-vault-and-hdms","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/06-kernel-and-binaries.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-07-operations-and-development","section":7,"title":"Chapter 7 — Operations, development, and release","synopsis":["man 7 handbook-07-operations-and-development","Handbook chapter (plain text from handbook/07-operations-and-development.md)"],"description":"CHAPTER 7 — OPERATIONS, DEVELOPMENT, AND RELEASE\n\nTime to read: about 14 minutes. Prerequisites: root README.md <../README.md> or user manual <../users-manual/README.md> for the shortest path; Chapter 3 <03-protocol-and-disk.md> if debugging boot.\n\nThis chapter is the operator’s desk: how to install, test, run Pear apps, interpret CI, and chase common failures.\n\nON THIS PAGE\n\n- Repository layout (monorepo) <#repository-layout-monorepo>\n- Continuous integration <#continuous-integration-github-actions>\n- pretest <#pretest-what-runs-before-npm-test>\n- Holepunch catalog and Bare manifest <#holepunch-catalog-and-bare-manifest-maintainers>\n- Warm read cache (operators) <#warm-read-cache-operators>\n- Release checklist <#release-checklist>\n- Install and test <#install-and-test>\n- Running seeder and booter (Node) <#running-seeder-and-booter-node>\n- Running with Pear <#running-with-pear-recommended-for-real-behavior>\n- Pear channels and staging <#pear-channels-staging-and-pear-links>\n- Environment variables (cheat sheet) <#environment-variables-cheat-sheet>\n- Themes, LS_COLORS, and real terminals <#themes-ls_colors-and-real-terminals>\n- Formatting <#formatting>\n- Troubleshooting <#troubleshooting>\n- Further reading <#further-reading>\n\nREPOSITORY LAYOUT (MONOREPO)\n\n- package.json — Workspaces root; pretest builds coreutils and bare-libs and runs kernel or seeder parity and other verifiers (see root package.json for the exact chain).\n- kernel/ — System image sources staged onto the Hyperdrive.\n- packages/bare-os-protocol — Topic string, MBR layout, Protomux helpers, kernel feature bits.\n- packages/bare-os-coreutils — Build /bin scripts and man.json.\n- packages/bare-os-bare-libs — Build /lib/bare bundles for optional ctx.bare merge.\n- packages/bare-os-seeder — Publish the OS drive and MBR.\n- packages/bare-os-booter — Network boot plus guest runtime.\n- scripts/ — Pear node_modules fixer, parity verifiers, catalog generation, release checklist.\n- data/ — Gitignored legacy Corestore directory (optional; defaults usually under ~/.bare-os).\n\nEach workspace has its own README.md with package-specific commands.\n\nCONTINUOUS INTEGRATION (GITHUB ACTIONS)\n\nThe .github/workflows/ci.yml <../.github/workflows/ci.yml> job:\n\n1. Checks out the repo on ubuntu-latest.\n2. Installs Node 20 with npm cache.\n3. Runs npm ci.\n4. Installs Bare globally: npm install -g bare (matches local identity and crypto tests).\n5. Runs npm run gen:bare-catalog:check — ensures docs/bare-holepunch-catalog.json <../docs/bare-holepunch-catalog.json> is up to date with the generator (no drift in PRs).\n6. Runs npm test, which triggers pretest first (see below).\n\nIf CI fails on gen:bare-catalog:check, run npm run gen:bare-catalog locally and commit the JSON. If pretest fails, read the next section.\n\nPRETEST: WHAT RUNS BEFORE NPM TEST\n\nThe authoritative script lives in root package.json <../package.json> under pretest. It always includes, among other steps:\n\n- npm run build -w bare-os-coreutils — Produces /bin outputs and man.json. Failure usually means stale or broken utilities, TypeScript or syntax errors, or a bad build script.\n- npm run build -w bare-os-bare-libs — Builds ctx.bare bundles. Failure means esbuild errors or bad imports under kernel/lib/bare/. Maintainer hygiene: scripts/sanitize-bare-bundles.mjs strips or rewrites noisy guest-facing *console. in selected vendored bundles before they ship under kernel/lib/bare/bundles/; run it when upstream bundles regress logging (then rebuild bare-libs so ctx.console** / var-log paths stay authoritative).\n- node scripts/verify-kernel-seeder-parity.mjs — Ensures kernel/ matches packages/bare-os-seeder/kernel/. Failure means the Pear seeder would ship the wrong tree; sync before release.\n- node scripts/sync-holepunch-clones.mjs — Optional maintainer report under docs/audit/holepunch-clone-sync-report.json (local holepunchto_repos vs bare-module-manifest.json names).\n- node scripts/verify-holepunch-clone-drift.mjs — When docs/audit/holepunch-drift-repos.json <../docs/audit/holepunch-drift-repos.json> lists repos[], compares each existing clone under BARE_OS_HOLEPUNCH_CLONES_ROOT (default $HOME/dev/pearcli/holepunch-repos/holepunchto_repos) to origin/main; missing clones are skipped. Set BARE_OS_HOLEPUNCH_DRIFT_CHECK=0 to skip (offline CI / no mirror). Pair with periodic git fetch origin main in those clones so the gate stays meaningful.\n- Additional verifiers (ctx API, capability contracts, roadmap wave rows, doc links, man coverage, compatibility matrix strings, Pear import rules, bare manifest smoke) run in the same pretest chain—read package.json for the full ordered list.\n\nIf any step fails, scroll the npm test output for the first non-zero exit; each script prints a specific error string.\n\nHOLEPUNCH CATALOG AND BARE MANIFEST (MAINTAINERS)\n\n- npm run gen:bare-catalog — Refreshes docs/bare-holepunch-catalog.json from upstream metadata (network).\n- npm run gen:bare-catalog:check — Same as above in check mode for CI.\n- npm run sync:bare-manifest — Applies catalog data to packages/bare-os-booter/lib/bare-module-manifest.json <../packages/bare-os-booter/lib/bare-module-manifest.json>, regenerates packages/bare-os-booter/lib/bare-module-manifest.data.mjs <../packages/bare-os-booter/lib/bare-module-manifest.data.mjs> (Pear module-graph copy of the manifest), and updates related booter optionalDependencies.\n- npm run verify:manifest-data — Fails CI if the JSON and .data.mjs payloads diverge (run automatically in pretest / maintainer:kernel-image).\n- npm run smoke:bare-manifest — Import smoke test for manifest entries.\n\nSee docs/README.md <../docs/README.md> and developer-guide ch.12 <../developer-guide/12-bare-modules-and-pear-ecosystem.md>.\n\nBUNDLE PROVENANCE ON THE DRIVE (KERNEL/LIB/BARE/MANIFEST.JSON)\n\nEach npm run build -w bare-os-bare-libs run writes kernel/lib/bare/manifest.json (and mirrors it into packages/bare-os-seeder/kernel/lib/bare/manifest.json) with:\n\n- bundles — /lib/bare/bundles/*.js paths and ctx.bare keys.\n- bundleStats / bundleDiagnostics — row count and per-bundle byte sizes.\n- bundleProvenance — schemaVersion, ISO generatedAt, repo gitCommit (from git rev-parse HEAD when available), host nodeVersion, bundleTier (all unless BARE_OS_BUNDLE_TIER narrowed the build), normativeManifest, and buildScript path.\n\nUse provenance to audit which commit produced an image’s Holepunch IIFEs and to compare bundle tiers across environments.\n\nWARM READ CACHE (OPERATORS)\n\nWhen BARE_OS_VFS_BIN_CACHE and/or BARE_OS_VFS_LIB_BARE_CACHE are on, the booter serves hot /bin and /lib/bare reads from an LRU. After live replication, OTA-style /bin or /lib/bare writes, or kernel.ext.d hot reload that changes bundles, stale bytes are a real risk.\n\n1. Prefer ctx.bareOsVfsBatchWrite for batch put operations — it clears warm entries when paths touch bin/, lib/bare/, boot/init.js, or lib/init/, and uses selective vfs.bareOsEvictLibBareBundlesFromManifest when only lib/bare/bare-module-manifest.json changes.\n2. Call ctx.bareOsInvalidateWarmReadCaches('reason') (or vfs.bareOsClearWarmReadCaches()) after host-driven replication or policy changes that bypass the batch writer.\n3. For manifest-only updates, use ctx.bareOsInvalidateWarmReadCachesFromBareManifestJson(buf) to evict bundles/<ctxKey>.js rows without flushing unrelated cache entries.\n4. Optional BARE_OS_VFS_WARM_CACHE_INVALIDATE_ON_APPEND registers Hypercore append listeners so replication can clear caches automatically (higher churn on busy drives).\n\nTests in packages/bare-os-booter/test.js cover hit/miss, full clear, manifest-selective eviction, and hrpc allowlist helpers adjacent to the VFS suite.\n\nPEAR BUNDLE AND PACK PIPELINE (OS IMAGES)\n\nFor Pear-shaped releases, align pear-bundle / pear-pack with the same kernel/ tree the seeder stages: run npm run build -w bare-os-coreutils and npm run build -w bare-os-bare-libs, verify scripts/verify-kernel-seeder-parity.mjs, then point Pear tooling at packages/bare-os-seeder or the published Hyperdrive key. packages/bare-os-seeder/package.json pear.stage.include must list kernel so Pear ships the vendored tree (the seeder never static-imports those files; without include, pear run pear://… can fail with kernel directory missing when staging with --compact). Keep pear-runtime and bare-os-protocol versions coupled per compatibility-matrix.md <../docs/reference/compatibility-matrix.md>.\n\nRELEASE CHECKLIST\n\nscripts/release-checklist.mjs <../scripts/release-checklist.mjs> is a maintainer aid to sanity-check versioning, artifacts, or release steps before tagging (run node scripts/release-checklist.mjs from the repo root when preparing a release). It complements—not replaces—human review and Pear staging.\n\nINSTALL AND TEST\n\n git clone https://git.ssh.surf/snxraven/bare-operating-system.git\n cd bare-operating-system\n npm ci\n npm test\n\n- booter tests use Node for Hyperdrive + Bare for identity crypto (test.identity.js).\n\nRUNNING SEEDER AND BOOTER (NODE)\n\nFrom packages/bare-os-seeder:\n\n node index.js\n\nStructured seeder logs: set BARE_OS_SEED_LOG_LEVEL (debug, info, warn, error) and, for machine-readable output, BARE_OS_SEED_LOG_FORMAT=ndjson (or json) so each line is a single JSON object with ts, level, msg, and context fields. Default human-readable lines go to stdout.\n\nFrom packages/bare-os-booter:\n\n node index.js\n\nDefault Corestore paths are ~/.bare-os/corestore/seeder and ~/.bare-os/corestore/booter (override base with BARE_OS_HOST_DATA, or set BARE_OS_SEED_STORE / BARE_OS_BOOT_STORE). See each package’s lib/paths.js.\n\nRUNNING WITH PEAR (RECOMMENDED FOR “REAL” BEHAVIOR)\n\nFrom repo root:\n\n npm run os:seeder\n npm run os:booter # second terminal\n\nThese run scripts/ensure-pear-node-modules.mjs first so Pear’s module resolution sees workspace dependencies the same way npm ci does at the repo root—without that shim, pear run from a package directory can miss hoisted node_modules. Do not run pear run os:seeder — os:seeder is an npm script name, not a Pear link.\n\nPEAR CHANNELS, STAGING, AND PEAR:// LINKS\n\nAfter pear stage / pear release, Pear prints a pear://… link per app. Consumers normally run those keys—not arbitrary git checkouts—unless they use dev mode pear run --dev ..\n\nConcrete keys and re-staging steps (seeder/booter channels, versioned links, host env for OTA): PEAR-RUN.md <../PEAR-RUN.md>. That file also documents *BARE_OS_PEAR_, HTTP allow/deny lists, TLS pin env vars, and ctx.bare** toggles mirrored from the host.\n\nOTA-shaped flow (doc contract): Pear’s channel / release metadata on the host pairs with BARE_OS_PEAR_CHANNEL, BARE_OS_PEAR_RELEASE, and optional ctx.bareOsPearUpdaterDelegate() (async) when BARE_OS_PEAR_UPDATER_MODULE or BARE_OS_PEAR_UPDATER_SNAPSHOT_JSON is set—see developer-guide ch.11 — Pear workflows <../developer-guide/11-kernel-pear-cookbook.md>. ctx.bareOsSystemRevision exposes id, pending, and slot for guest policy; /etc/bare-os/boot.policy.json rollback fields and boot markers (BARE_OS_BOOT_ROLLBACK_APPLY, BARE_OS_SYSTEM_REVISION_PENDING) gate whether a newer system key is adopted after the next boot.\n\nENVIRONMENT VARIABLES (CHEAT SHEET)\n\nThese are the variables operators touch most often; the full list is in docs/reference/environment-and-posix-appendix.md <../docs/reference/environment-and-posix-appendix.md#14-environment-variables-complete-list>.\n\nSeeder and paths\n\n- BARE_OS_KERNEL_ROOT — Override the kernel tree path the seeder stages.\n- BARE_OS_HOST_DATA — Base directory for host state (default ~/.bare-os).\n- BARE_OS_SEED_STORE — Seeder Corestore directory.\n- BARE_OS_BOOT_STORE — Booter Corestore directory.\n- BARE_OS_SEED_LOG_LEVEL, BARE_OS_SEED_LOG_FORMAT — Seeder host logger (ndjson / json for one object per line).\n\nBooter behavior\n\n- BARE_OS_BOOT_TIMEOUT_MS — Boot deadline (default 60000).\n- BARE_OS_NO_SPLASH — Disable TTY splash.\n- BARE_OS_SKIP_REPL — Non-interactive kernel.\n- BARE_OS_FISH — Set 0 to disable fish readline.\n- BARE_OS_HOST_BOOTER_LOG — Host diagnostics before guest session: stderr (default), ndjson file under BARE_OS_HOST_BOOTER_LOG_PATH or ~/.bare-os/var/log/booter-host.ndjson, or 0/off to silence. See environment appendix §14.\n- BARE_OS_BOOT_PERF_DETAIL — With 1, guest boot-perf.json gains finer samples and the booter logs bare_stdlib_merge_ns after drive ctx.bare merge.\n- BARE_OS_BARE_SUBPROCESS_BRIDGE, BARE_OS_BARE_SUBPROCESS_TIMEOUT_MS — When the bridge is on, runBin inherits the subprocess timeout cap unless runBin already has an explicit budget; ctx.bareOsReadSubprocessBridgeSnapshot() (schema 4) includes timeoutPolicy echoing these env keys.\n\nNetwork and replication\n\n- HYPERSWARM_BOOTSTRAP — Comma-separated bootstrap nodes for Hyperswarm (booter and HDMS).\n- BARE_OS_REPLICATION_SYNC_WINDOWS — UTC windows (HH:MM-HH:MM, comma-separated); exposes /proc/bare_os/sync_window.json and BARE_OS_REPLICATION_SYNC_WINDOW_ACTIVE.\n\nSeeder RPC hints (optional)\n\n- BARE_OS_SEED_STAGING_PREVIOUS_SLOT — Prior A/B slot hex for rollback hints in staging_slot RPC.\n- BARE_OS_SEED_REPLICATION_QUEUE_DEPTH_HINT — Integer echoed as queueDepthEstimate in replication_queue RPC.\n- BARE_OS_SEED_REPLICATION_SNAPSHOT_NOTE_JSON — JSON string influencing snapshot workflow text on the seeder.\n\nThe booter also copies many *BARE_OS_ toggles from the host into the guest session (pipeline caps, boot strictness, audit, Pear metadata, BARE_OS_VFS_WATCH, BARE_OS_BOOT_ALLOWLIST**, etc.). See the environment appendix for the full list.\n\nLayers in plain language: host env (Pear shell, CI, your laptop) seeds values into shellEnv; the guest sees them as normal environment variables and in /proc/self/environ (filtered). When debugging, ask: was this variable set on the host before launching the booter?\n\nTHEMES, LS_COLORS, AND REAL TERMINALS\n\nThemes are not just aesthetics—they keep ls --color, the fish-style prompt, and host emulator configs aligned so you do not debug “broken colors” when the real issue is a truecolor vs 256-color mismatch.\n\n- ~/.barerc supports theme <preset> (e.g. theme nord) plus export / alias. The active preset fills *BARE_OS_COLOR_ and LS_COLORS unless you set LS_COLORS yourself or BARE_OS_LS_COLORS_LOCKED=1. Use BARE_OS_COLOR_DEPTH (256, 16, or ansi**) on constrained terminals.\n- barerc reload, theme, dircolors — see Chapter 4 <04-the-booter-runtime.md> and man theme.\n- docs/themes/README.md <../docs/themes/README.md> — preset packs and sample Alacritty / Warp YAML (in-house).\n\nFORMATTING\n\n npm run format\n npm run lint\n\nPrettier config: no semicolons, single quotes (.prettierrc).\n\nTROUBLESHOOTING\n\nBooter exits at timeout — No seeder peer on the bare-os-v1 topic. Start the seeder and confirm network reachability.\n\n/bin/foo missing under Pear — Run npm run build -w bare-os-coreutils before staging or seeding so the image includes a fresh /bin build.\n\nautopass or module not found in Pear — Check hoisting, ensure-pear-node-modules, and avoid forbidden static imports in HDMS paths.\n\ntest is not defined in user script — Bug in user JavaScript; the kernel runner should log and continue instead of crashing the session.\n\nDouble cron or log spam — Session restarted without stopBareInitd; REPL cleanup should stop initd timers.\n\nCron day-of-month vs day-of-week — bare-cron matches a job when the usual five fields align; if both day-of-month and day-of-week are non-*`, a match on either field is sufficient (POSIX crontab “OR” rule). See packages/bare-os-booter/lib/bare-cron.js`**.\n\nCI fails gen:bare-catalog:check — Regenerate the catalog with npm run gen:bare-catalog and commit.\n\nverify-kernel-seeder-parity fails — Copy or sync kernel/ → packages/bare-os-seeder/kernel/ per release documentation.\n\nSECURITY, ACL, AND OBSERVABILITY HOOKS\n\nThe booter exposes ctx.bareOsAclEvaluate, audit toggles (BARE_OS_AUDIT, BARE_OS_AUDIT_JSON), and append-only style logging under /var/log/ (see environment appendix). Subsystem-oriented error classes with stable code fields live in packages/bare-os-booter/lib/bare-os-errors.js <../packages/bare-os-booter/lib/bare-os-errors.js>. After initd, disk.os.execRpc accepts only whitelisted *bare_os.** methods—see Chapter 3 — disk.os bridge <03-protocol-and-disk.md>.\n\nFURTHER READING\n\n- docs/README.md <../docs/README.md> — documentation home (all trees, glossary, FAQ)\n- docs/troubleshooting.md <../docs/troubleshooting.md> — symptom router\n- docs/CONTRIBUTING-DOCS.md <../docs/CONTRIBUTING-DOCS.md> — doc style and pretest verifiers\n- docs/reference/README.md <../docs/reference/README.md> — file-by-file reference (authoritative for paths)\n- README.md <../README.md> — short overview\n- User manual <../users-manual/README.md> — operator-oriented runbook\n- Preface <00-preface.md> — thesis and contributor paths\n- Handbook Chapter 3 <03-protocol-and-disk.md> — boot failures on the wire\n\nNext: Chapter 8 — Git on Bare OS <08-git-on-bare-os.md>\n\nRelated: Handbook home <README.md> · CHANGELOG — ctx API <../packages/bare-os-booter/CHANGELOG.md>\n\n_Experimental research software, not a production OS. Apache-2.0 — LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","07","operations","and","development","release"],"seeAlso":[{"name":"handbook-08-git-on-bare-os","section":7},{"name":"handbook-06-kernel-and-binaries","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/07-operations-and-development.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-08-git-on-bare-os","section":7,"title":"Chapter 8 — Git on Bare OS","synopsis":["man 7 handbook-08-git-on-bare-os","Handbook chapter (plain text from handbook/08-git-on-bare-os.md)"],"description":"CHAPTER 8 — GIT ON BARE OS\n\nTime to read: about 8 minutes. Prerequisites: Chapter 4 — VFS <04-the-booter-runtime.md> (path routing), Chapter 7 <07-operations-and-development.md> for env vars.\n\nThe git command in this project is not the GNU Git binary. It is a small CLI in the booter package that calls isomorphic-git <https://isomorphic-git.org/> — a JavaScript implementation with a fixed set of APIs, not parity with every git subcommand you might know from a desktop Linux install.\n\nWHY DELEGATION EXISTS\n\nHyperdrive-resident /bin utilities are built as concatenated scripts and loaded with AsyncFunction. They cannot use Node import to pull in isomorphic-git. When you type git, the booter short-circuits to git-cli.js via a normal ESM import at host level—same pattern as delegated curl, wget, and systemctl. Storage still targets VFS paths (personal drive under $HOME, writable HDMS mounts), not arbitrary host paths.\n\nHOW IT RUNS\n\n- Delegation: When you type git (or an absolute path like /bin/git whose basename is git), the booter loads git-cli.js with a normal ESM import. That avoids the Hyperdrive /bin model, where utilities are concatenated and eval’d without import, which cannot load npm packages.\n- Storage: Repositories live on the VFS (personal drive under $HOME, or writable HDMS mounts). isomorphic-git expects a Node-style fs.promises surface; the booter provides createGitFsFromVfs, which maps those calls onto Hyperdrive-backed paths. Empty directories use a hidden marker file (.bareos_empty) because Hyperdrive does not always mirror POSIX directory semantics.\n\nNETWORK MODES (CLONE, FETCH, PUSH)\n\n- On Node, HTTP defaults to isomorphic-git/http/node (simple-get), loaded via import.meta.resolve when available so package subpaths resolve reliably (including under Pear).\n- If that fails to load, or when you set BARE_OS_GIT_HTTP=web, the CLI uses isomorphic-git/http/web, which expects a global fetch. The booter statically imports the web client so Pear’s bundler can wire isomorphic-git/http/web (dynamic imports from git-cli.js used to fail with “Cannot find referrer”). Node 18+ and browsers already provide fetch; Pear/Bare often does not, so the booter loads bare-fetch (Holepunch) and assigns globalThis.fetch (plus Request / Response / Headers) before using the web client.\n- TLS, proxies, and corporate inspection still depend on the host; certificate errors may surface even when the VFS layer is fine.\n\nMental model: git network I/O is host-shaped; repository bytes are drive-shaped.\n\nEXPECTATIONS AND CONSTRAINTS\n\n- Use git --help inside Bare OS for the supported subcommand list.\n- Unsupported subcommands print a short message; for full API behavior, see the isomorphic-git documentation <https://isomorphic-git.org/docs/en/next/alphabetic>.\n- Very large repos may stress memory and replication more than desktop Git with packfiles on a local disk—this is still a research stack.\n\nGIT-PEAR AND PEAR METADATA\n\n/bin/git-pear is a small coreutils utility that prints or exports Pear-oriented hints (PEAR_CHANNEL, BARE_OS_PEAR_CHANNEL, BARE_OS_PEAR_RELEASE) for scripts that clone or tag against a Pear release channel. It complements git (which remains the isomorphic-git CLI) and is documented in man git-pear after a coreutils build.\n\ngip (when installed on the host) is described in the Developer guide — Kernel + Pear cookbook <../developer-guide/11-kernel-pear-cookbook.md> as a host-side companion for publishing drives; inside the guest image, prefer git + git-pear for VFS-local workflows.\n\nNext: Chapter 9 — POSIX utilities, shell, VFS <09-posix-utilities-shell-and-vfs.md>\n\nRelated: Documentation home <../docs/README.md> · Handbook home <README.md> · PEAR-RUN.md <../PEAR-RUN.md>\n\n_Experimental research software, not a production OS. Apache-2.0 — LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","08","git","on","bare","os"],"seeAlso":[{"name":"handbook-09-posix-utilities-shell-and-vfs","section":7},{"name":"handbook-07-operations-and-development","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/08-git-on-bare-os.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-09-posix-utilities-shell-and-vfs","section":7,"title":"Chapter 9 — POSIX-style utilities, shell builtins, and VFS alignment","synopsis":["man 7 handbook-09-posix-utilities-shell-and-vfs","Handbook chapter (plain text from handbook/09-posix-utilities-shell-and-vfs.md)"],"description":"CHAPTER 9 — POSIX-STYLE UTILITIES, SHELL BUILTINS, AND VFS ALIGNMENT\n\nTime to read: reference chapter (skim §1–2, use §5 as catalog). Prerequisites: Chapter 4 <04-the-booter-runtime.md>, Chapter 6 <06-kernel-and-binaries.md>.\n\nWHY THIS CHAPTER EXISTS\n\nIf you come from Linux or macOS, Bare OS feels like a small Unix: ls, grep, sed, pipelines, and man. Under the hood it is JavaScript utilities on a two-drive VFS with simulated pipes. This chapter is the honest catalog: what matches POSIX.1-2017 XCU <https://pubs.opengroup.org/onlinepubs/9699919799/toc.htm> closely, what is Issue 7–inspired, and what is stubbed or bounded so the runtime stays predictable.\n\nNormative reference: Open Group Issue 7 — use the online utilities index for intended semantics; Bare behavior may intentionally diverge where Hyperdrive or the single-process runtime makes full compliance impossible.\n\nDeclared profile (single spec): POSIX_DECLARED_PROFILE.md <../docs/architecture/POSIX_DECLARED_PROFILE.md> — contract for XCU/XSH-like behavior, proc stand-ins for “syscalls,” and explicit non-goals.\n\nDeclared profile (constants): the protocol package publishes BARE_OS_POSIX_PROFILE_VERSION / BARE_OS_POSIX_PROFILE_ID (bare-os-posix-like), surfaced on /proc/bare_os_features and in /proc/bare_os/syscalls.json (schema 8 for that file — fdModel / signalModel plus opsDetail / posixXsh (schema 2) / socketMsgSurface (schema 3: non-empty ancillary on sendmsg → ENOTSUP + ancillaryReject; recvmsg controllen: 0) / errnoHints, including cooperative fcntl advisory locks with optional F_SETLKW blocking wait (BARE_OS_POSIX_FCNTL_BLOCKING_WAIT) and optional socket-bridge datagram bind/connect/send/sendmsg/recv/recvfrom/recvmsg (passive UDP bind, optional connect on the same fd, send with explicit port/host when bound without default peer) with bounded queues; /proc/bare_os/index.json uses schema 8). getconf BARE_OS_POSIX_XSH_OPS lists the XSH names; getconf BARE_OS_SYSCALL_OPS lists ctx op names only. Cold-boot wall time vs BARE_OS_BOOT_BUDGET_MS_COLD is also written to /run/bare-os/boot-perf.json when the VFS supports it. metrics_live includes initdReadiness (schema 2) and paths such as utilitiesIndexPath → /etc/bare-os/posix_utilities.json when present.\n\nON THIS PAGE\n\n- Why this chapter exists <#why-this-chapter-exists>\n- Executive summary: what is not POSIX here <#1-executive-summary-what-is-not-posix-here>\n- VFS: directories, metadata, and empty folders <#2-vfs-directories-metadata-and-empty-folders>\n- Shell lists, pipelines, and builtins <#3-shell-lists-pipelines-and-builtins-packagesbare-os-booterlibshelljs>\n- Booter ctx helpers <#4-booter-ctx-helpers>\n- /bin utilities (catalog) <#5-bin-utilities-catalog>\n- §6 — sed implementation <#6-sed-implementation>\n- §7 — awk implementation <#7-awk-implementation>\n- §8 — Coreutils build preamble map <#8-coreutils-build-preamble-map>\n- §8.5 — Shell cookbook <#85-shell-cookbook-without-full-posix-sh>\n- §8.7 — Capability word 8 errno / whiteout / FIFO <#87-capability-word-8--bare-fs-errno-rows-union-whiteout-fifo-metrics>\n- §9 — Where to read next <#9-where-to-read-next>\n\nPHILOSOPHY: “ISSUE 7-ISH” IN ONE PARAGRAPH\n\nWe borrow names and muscle memory from POSIX because that makes scripts portable _in spirit_. We do not promise bitwise compatibility with GNU coreutils, binary sh compatibility, or kernel semantics (no real fork, no real FIFOs on disk). When in doubt, read src/<cmd>.js and the environment / POSIX appendix <../docs/reference/environment-and-posix-appendix.md#14a-posix-userland-appendix-implemented-vs-gaps>—the appendix is the checklist view; this chapter is the narrative view.\n\n1. EXECUTIVE SUMMARY: WHAT IS _NOT_ POSIX HERE\n\n- Full POSIX sh grammar — Bare uses a line-at-a-time shell: builtins plus /bin; lists with ; (outside compound statements), &&, and | pipelines; bounded if … fi; bounded while / for (iteration cap BARE_OS_SHELL_LOOP_MAX, default 10000); optional break / continue when BARE_OS_SHELL_LOOP_CONTROL=1; bounded case … esac (BARE_OS_SHELL_CASE_MAX_BRANCHES, default 32). Optional bounded $(…) when BARE_OS_SHELL_CMDSUBST=1 (see §3). With BARE_OS_SHELL_POSIX_MODE=1, subshell-free grouped lists ( compound-list ) run as a single statement (same session context). There are no forked subshells and no full sh grammar.\n- Processes, fork, pipes as OS primitives — Pipelines are simulated by capturing console.log (and merged console.error when 2>&1 is used) into the next command. With BARE_OS_POSIX_FD_SIM=1, extensions may also use ctx.bareOsPosixFdSimPipe / bareOsPosixFdSimRead / bareOsPosixFdSimWrite for bounded in-memory pipe pairs surfaced as logical FDs in /proc/self/fd (not full kernel pipes). Logical FDs support ctx.bareOsSyscall('fcntl', { fd, cmd: 'F_GETFL' | 'F_SETFL', arg }) (Linux-shaped O_APPEND 0x400, O_NONBLOCK 0x800), cooperative F_GETLK / F_SETLK / F_SETLKW on absolute paths (or fd→path), and readiness via ctx.bareOsPosixPoll / ctx.bareOsSyscall('posixPoll', { fds, timeoutMs }) (see /proc/bare_os/syscalls.json). Cooperative locks are not kernel wait queues: F_SETLKW may surface an EINTR-shaped note when the blocking wait budget elapses or a stale-owner grace window passes — there is no host deadlock detector. With BARE_OS_POSIX_SOCKET_FD_BRIDGE=1, socket + connect may use ctx.bare.bareTcp for SOCK_STREAM and ctx.bare.bareDgram for SOCK_DGRAM when merged; passive SOCK_STREAM uses bind, listen, accept (bareTcp.Server) with BARE_OS_POSIX_ACCEPT_QUEUE_MAX; accepted stream fds support send/recv with a bounded segment queue (same cap family as BARE_OS_POSIX_DGRAM_RECVQ_MAX). Bridged UDP supports send, recv, and recvfrom with BARE_OS_POSIX_DGRAM_RECVQ_MAX / BARE_OS_POSIX_DGRAM_RECV_BLOCK_MS_MAX, and poll/select treat the fd readable when the datagram queue is non-empty (listening and TCP-accepted fds use their respective queues).\n- chown / chgrp / real UIDs across users — Single-session identity; metadata carries uid/gid for display and checks, not a multi-user kernel.\n- FIFOs, mknod, real devices — No kernel FIFOs or mknod; mkfifo creates in-memory channels under /run/bare-os/ipc/<name> (see bare-os-ipc.js). Optional BARE_OS_IPC_MAX_CHANNELS caps distinct channel keys; metrics_live.ipcTelemetry mirrors FIFO depth, fan-out counts, and quota counters.\n- Full POSIX/GNU xargs — Bounded implementation: ctx.runBinCommand only; -0, -n (and -nN), optional -P parallelism with effective cap min(requested, BARE_OS_XARGS_MAX_PROCS, 32) (default 8 when env unset; sequential when 0); stdin, token, and invocation caps (see src/xargs.js).\n- getconf / live sysconf — Fixed name table plus -a; values are Bare constants, not host kernel queries (see src/getconf.js). getconf NAME /path delegates to ctx.bareOsPathconf for *_PC_ variables ( _PC_CHOWN_RESTRICTED is 0 under /mirror/** read-only aux mounts).\n- Byte-identical sed / awk / grep — Implementations are JavaScript; regex and edge cases differ from GNU or strict POSIX.\n\nFor the /bin build contract (no import, AsyncFunction load), see Chapter 6 <06-kernel-and-binaries.md>.\n\n> Key idea — two drives, one namespace: utilities almost never care _which_ Hyperdrive backs a path; the VFS routes $HOME, /tmp, and /var/log to personal prefixes and everything else to the system image. See Chapter 4 <04-the-booter-runtime.md>.\n\n2. VFS: DIRECTORIES, METADATA, AND EMPTY FOLDERS\n\npackages/bare-os-booter/lib/vfs.js <../packages/bare-os-booter/lib/vfs.js> exposes a unified path space over the system and personal Hyperdrives (see Chapter 4 <04-the-booter-runtime.md>).\n\n> Key idea — .bareos_empty: empty directories are marked with a hidden sentinel so git and mkdir -p agree on tree shape. Hyperdrive is not POSIX-shaped by default.\n\n2.1 EMPTY DIRECTORIES (.BAREOS_EMPTY)\n\nHyperdrive does not always behave like a POSIX directory tree. Empty directories are represented by a hidden marker file .bareos_empty, consistent with git-fs-adapter.js <../packages/bare-os-booter/lib/git-fs-adapter.js> and Chapter 8 — Git <08-git-on-bare-os.md>. readdir on the raw VFS may list that name; git paths filter it.\n\n2.2 MKDIR AND RMDIR\n\n- vfs.mkdir(path, { recursive, mode }) — creates directories by writing dirname/.bareos_empty. Optional mode sets permission bits on the marker; lstat on the directory derives S_IFDIR from that metadata (with execute bits implied where read bits are set, so paths stay traversable). -p / --parents and -m are implemented by /bin/mkdir. On failure, mkdir prints mkdir: path: CODE: message when the VFS error carries a string code (Holepunch bare-fs / error.code family), else mkdir: path: message only.\n- vfs.rmdir(path) — removes a directory only if it has no entries other than .bareos_empty (and removes the marker).\n\n2.3 PSEUDO /PROC, /SYS, /RUN, /DEV, AND SESSION /TMP\n\n- /proc, /sys, /run, /dev — read-only synthetic trees except /dev/null and /dev/zero accept writes that are discarded, and /dev/shm/<name> accepts writeFile / readFile / unlink for in-memory named segments (see POSIX declared profile <../docs/architecture/POSIX_DECLARED_PROFILE.md>). Other pseudo writeFile / unlink / chmod paths fail as documented there. Linux-shaped synthetic files include /proc/cpuinfo, /proc/meminfo, /proc/loadavg, /proc/net/dev, /proc/diskstats, and data-backed /proc/self/cgroups, /proc/net/tcp, /proc/net/udp (session / swarm / quota hints; stable columns where practical). /proc/bare_os/ (stable aliases + index.json schema 8, listing Pear/Bare operator JSON from Capability words 6–11 such as pear_stage_pointer.json, bare_module_resolution.json, pear_doctor_state.json, bare_boot_phase_map.json, …, plus syscalls.json (schema 8; stock booter caches JSON until warm read-cache invalidation), process_table.json (schema 7: PGID/SID-style fields, parentName, signalRouting, initd binding), metrics.prom, protomux.json (schema 2 RPC pool / backpressure hints), /proc/bare_os_quotas, /proc/bare_os_resources, /proc/bare_os_features, /proc/bare_os_session_stats, /proc/bare_os_swarm, /proc/bare_os_replication, /proc/bare_os_manifest_hints, /proc/bare_os_peer_health, /proc/bare_os_staging_slot, /proc/bare_os_snapshot_hints, /proc/bare_os_provenance, /proc/bare_os_pear_ipc_registry, /proc/bare_os_initd_dag, /proc/bare_os_initd_graph, /proc/bare_os_pear_trust, /proc/bare_os_rlimits, /proc/bare_os_hdms_health, /proc/bare_os_metrics_live (and /proc/bare_os/metrics_live.json), /proc/bare_os/metrics.prom (OpenMetrics text for kernel counters), /proc/bare_os_extensions.json, /proc/bare_os_hdms_hints.json, /proc/bare_os_capabilities (and /proc/bare_os_capabilities.json), /proc/bare_os_bootstrap, /proc/bare_os_union, /proc/bare_os_seed_handshake, /proc/bare_os_virtual_registry, /proc/self/cgroups, /proc/self/exe, /proc/self/fd/0–2, /sys/class/net/lo, /sys/devices/virtual, /sys/fs/bare_os/build_id, */run/bare-os/virtual/, /run/bare-os/unit-journal/.ndjson, /run/bare-os/kernel-ext-reload.ndjson (append-only kernelExtReloadSchemaVersion lines when BARE_OS_KERNEL_EXT_D_HOT_RELOAD and ctx.bareOsReloadKernelExtDropinsSafe() run), and /dev/urandom (each readFile of urandom returns a bounded buffer; not suitable for cryptography unless BARE_OS_URANDOM_CRYPTO is left at default). Optional union write denials use BARE_OS_VFS_UNION_WRITE_DENY (see kernel extensions <../docs/reference/kernel-extensions.md>). With BARE_OS_VFS_WATCH_PSEUDO=1, vfs.watch may poll coalesced metrics_live and metrics.prom. With BARE_OS_VFS_WATCH_SWARM=1, vfs.watch may poll coalesced swarm / replication pseudo files. Use ctx.bareOsReadProcMetricsLive() for the same JSON as metrics_live without a VFS read. /bin/env supports -S / --env-file when BARE_OS_ENV_DASH_S=1. Shell ${…} v2 (##, %%, :=, basename /) requires BARE_OS_SHELL_PARAM_EXPANSION_V2=1 with param expansion enabled. V3 adds :? / :+ when BARE_OS_SHELL_PARAM_EXPANSION_V3=1. Gated local / read-only declare -r use BARE_OS_SHELL_LOCAL_DECLARE=1**.\n- /tmp — writable on the personal drive under /.bare-os/tmp/<HOME-basename>/…, isolated like $HOME and /var/log.\n\n2.4 CHMOD (OCTAL AND SYMBOLIC)\n\n/bin/chmod accepts:\n\n- Octal modes (e.g. 644, 0755) — passed through to vfs.chmod (permission bits; type bits come from the existing entry).\n- Symbolic modes (e.g. u+rw, go-w) — a supported subset of POSIX symbolic chmod; see packages/bare-os-coreutils/src/chmod.js.\n\n/bin/chown and /bin/chgrp update metadata.bareOs on the personal drive via vfs.chown (same writable scope as chmod); root vs owner rules apply, but this is still a single-session runtime (not a multi-user host kernel).\n\n2.5 AUXILIARY READ-ONLY DRIVES (/MIRROR)\n\nWhen HDMS or the booter attaches extra Hyperdrives on disk.auxiliaryDrives, the VFS exposes them read-only under /mirror/aux0, /mirror/aux1, … (also listed in /proc/mounts as bare-os-auxN /mirror/auxN hyperdrive ro rows). ctx.bareOsListMirrorMounts() returns the same ordering and paths for scripts that avoid parsing mounts. This is optional; most images omit auxiliary drives.\n\n2.5.1 READ-THROUGH CACHE (/BIN, OPTIONAL /LIB/BARE)\n\nWith BARE_OS_VFS_BIN_CACHE=1, the booter keeps a bounded LRU of system-drive readFile results for */bin/. Add BARE_OS_VFS_LIB_BARE_CACHE=1 to extend the same warm path to /lib/bare/ (bundle resolution hot paths). Hit, miss, and per-prefix counters appear under warmReadCache in /proc/bare_os/metrics_live.json (and the coalesced ctx.bareOsReadProcMetricsLive() view) when the cache is enabled. After live replication or policy changes, call ctx.bareOsInvalidateWarmReadCaches(reason) (or rely on ctx.bareOsVfsBatchWrite when batch put paths touch bin/ or lib/bare/) so operators do not read stale bytes from warm entries. BARE_OS_VFS_WARM_CACHE_PREFIX_INVALIDATE=1 evicts /bin, /etc, /lib, /usr, or personal prefixes when replicated core lengths increase (see metrics_live.replicationLive.warmPrefixInvalidate). BARE_OS_VFS_WARM_CACHE_INVALIDATE_ON_REPLICATION=1 performs a full warm-cache clear via ctx.bareOsInvalidateWarmReadCaches('replication:core-length') on the same growth signal (surfaced under warmFullInvalidateOnReplication). Hyperswarm connection budgeting uses BARE_OS_SWARM_MAX_PEERS, BARE_OS_SWARM_MAX_CLIENT_CONNECTIONS, BARE_OS_SWARM_MAX_SERVER_CONNECTIONS, and BARE_OS_SWARM_MAX_PARALLEL (surfaced on /proc/bare_os/swarm connectionBudget and disk.os replication_operator_sketch schema 4). ctx.bareOsSyscall('nanosleep', { tv_sec, tv_nsec }) and bridge getsockopt/setsockopt (SO_KEEPALIVE, TCP_NODELAY) are documented in /proc/bare_os/syscalls.json (POSIX profile 1.0.11*).\n\n2.6 COPY AND MOVE\n\n- cp — -R/-r recursive copy; follows the same marker convention (skips copying .bareos_empty as a separate “file” where appropriate).\n- mv — Hyperdrive has no atomic rename; the general case is copy-tree + vfs.rm on the source. A single regular file to a non-directory destination uses a two-phase write (stage as *.bare-os-mv-tmp. in the resolved destination directory, write destination, remove stage, unlink** source) so a failed destination write does not remove the source (see POSIX declared profile <../docs/architecture/POSIX_DECLARED_PROFILE.md>).\n\n3. SHELL LISTS, PIPELINES, AND BUILTINS (PACKAGES/BARE-OS-BOOTER/LIB/SHELL.JS)\n\n!Shell evaluation pipeline <../docs/images/shell-pipeline.png>\n\nTop-level syntax: the line is split on ; into separate lists (semicolons inside compound blocks do not end the outer statement). if then [ else ] fi uses the same && / || / pipeline rules inside the condition and each branch; the condition is true when the last evaluated command in that &&/|| list exits 0. while list; do list; done and for name in words ; do list; done repeat the body while respecting BARE_OS_SHELL_LOOP_MAX. case word in pattern) list ;; … esac matches the first pattern (token-safe); patterns support | alternation and fnmatch-style *`, ?, and […] (excluding | branches handled separately). Branch count is capped by BARE_OS_SHELL_CASE_MAX_BRANCHES. Each list is an AND-OR chain: pipelines separated by && or ||, evaluated left-to-right with POSIX-style short-circuiting (ctx.exitCode — treat missing as 0). Within a pipeline, |`** connects stages as before (simulated stdin between utilities).\n\nBackground / jobs (subset vs SUSv4): a trailing & on a top-level list runs that list asynchronously (microtask). jobs lists recent jobs (including Stopped when suspend-job was used); fg awaits the selected (or latest) job; wait awaits one job by id (or %id) or all background jobs; with BARE_OS_SHELL_POSIX_MODE=1, wait -n waits for any pending job (Promise.race) and exits 0 when none remain. bg clears Stopped and re-queues the job (logical resume within the single-session runtime). trap -l / trap -p / trap CMD SIG use ctx.shellTrapHandlers (delivery still maps through ctx.bareOsSendSignal for synthetic PIDs). This is not IEEE Std 1003.1 job control: there is no set -m monitor mode, no real process groups or SIGTSTP from the host kernel, and background jobs use jobControlModel: 'logical_no_fork' (see /proc/bare_os/process_table.json jobControlSemantics). Unsupported operations fail with explicit stderr messages (fg: no such job, wait: no such job, bg: no stopped jobs, …) rather than silent no-ops.\n\nHere-string / here-document: <<< word feeds the expanded word as stdin to the first command in the pipeline. A line that ends with << DELIMITER (optional '...' / \"...\" around the delimiter) collects following lines from readLine('> ') until a line equals DELIMITER, then uses that body as stdin ($ expansion is skipped for a single-quoted delimiter name).\n\nPipeline limits: simulated pipe capture is bounded. Defaults: BARE_OS_PIPELINE_MAX_BYTES (2 MiB), BARE_OS_PIPELINE_MAX_LINES (50 000), BARE_OS_PIPELINE_MAX_STAGES (32). With BARE_OS_SHELL_STREAMING=1, effective byte and line caps are multiplied by BARE_OS_SHELL_STREAMING_MULT (default 4, max 16) so large captures remain bounded but less tight. Exceeding a limit fails the pipeline with exit status 1 and an error on stderr. Current caps and FIFO stats also surface in /proc/bare_os_quotas and ctx.bareOsRuntimeCaps.quotas. With BARE_OS_SHELL_PIPEFAIL, a pipeline’s status reflects the first failing stage (bash-like); default is POSIX-like last stage only.\n\nErrexit (subset): BARE_OS_SHELL_ERREXIT=1, set -e, or set -o errexit stops further top-level ;-separated commands after a non-zero exit (set +e / set +o errexit clears). The same flag now applies inside if then / else bodies and while / for loop bodies between semicolon-separated lists (POSIX-style: a failing command aborts the rest of that compound body). Condition expressions in if / while still evaluate without errexit stopping between predicate lists. This remains a declared subset, not full Issue 7 sh.\n\nCommand substitution (bounded): when BARE_OS_SHELL_CMDSUBST=1, words may contain $(…) (one level balanced, nesting depth capped). The inner line runs via execLine; console.log output becomes the substituted text, trimmed to BARE_OS_SHELL_CMDSUBST_MAX_BYTES (default 8192). This is not full POSIX sh command substitution.\n\nCaptured stdout (ctx.bareOsStdoutCaptured): stages whose console.log output is captured into the simulated pipe (or into a > / >> redirect) run with bareOsStdoutCaptured: true on the shallow ctx clone passed to runBinCommand (see bareOsPipelineChildCtx in shell.js). ls uses this to print one name per line in short format, similar to GNU ls when stdout is not a terminal, so grep, sort, and wc receive one entry per line. Each console.log call still becomes one output line (trailing newline added by the shell capture).\n\nexecLine nesting: host BARE_OS_EXEC_MAX_DEPTH (default 64) caps recursive execLine calls (e.g. cron, ExecStartPost); exceeding it fails with a clear error. Optional BARE_OS_EXEC_LINE_BUDGET_MS rejects further top-level execLine when cumulative session wall time exceeds the budget (surfaced in /proc/bare_os_resources).\n\nParameter expansion (subset): when BARE_OS_SHELL_PARAM_EXPANSION=1, words may use ${VAR:-word} (default if unset or empty) and ${VAR#prefix} (remove shortest prefix; prefix length bounded).\n\nParameter expansion V2 / V3: with BARE_OS_SHELL_PARAM_EXPANSION_V2, ${VAR:=word}, prefix/suffix stripping (##, #, %%, %), and related forms apply as documented in the environment appendix <../docs/reference/environment-and-posix-appendix.md>. With BARE_OS_SHELL_PARAM_EXPANSION_V3, ${VAR:+word} and ${VAR:?word} are enabled. Regression coverage lives in packages/bare-os-booter/test.js (expandWord param expansion v2 / v3).\n\nPathname expansion (globbing): after $ expansion and optional $(…), unquoted words are matched against the VFS using *`, ?, and […] (fnmatch-style). Matches are sorted in UTF-8 byte order. Single-quoted and double-quoted words suppress globbing (so echo '' prints a literal asterisk). Hidden dot-names are excluded unless BARE_OS_DOTGLOB=1. BARE_OS_GLOB_MAX_MATCHES (default 4096) caps total matches per word; BARE_OS_GLOB_IGNORE is a colon-separated list of patterns to skip. With BARE_OS_STRICT_POSIX=1, a glob that matches nothing fails the command (exit 1); otherwise the shell passes the pattern through literally (bash-like). set -f / set +f toggle BARE_OS_SHELL_NOGLOB in the session environment (disable or re-enable globbing). Optional brace expansion {a,b} on unquoted segments requires BARE_OS_SHELL_BRACE_EXPANSION=1. Tilde: ~ / ~/… expand to $HOME`* when the leading segment is unquoted.\n\nStderr redirection: 2> / 2>> redirect console.error for the command (same byte/line caps as stdout when captured for a pipe). 2>&1 merges stderr into the stdout capture stream so both appear in the simulated pipe input for the next stage (and in a stdout redirect when it is the last command in the list).\n\nLast exit status: after each full execLine evaluation, vfs.env.BARE_OS_EXIT_STATUS is updated (decimal string). Words expand $? and ${?} from that value (default 0 if unset), similar to POSIX $?.\n\nBeyond alias, unalias, cd, export, login, logout, exit:\n\n- unset — Removes variables from vfs.env; refuses readonly names (POSIX-style error).\n- readonly — Marks names readonly; readonly NAME=value sets and locks. Blocks export and leading assignments on readonly keys.\n- umask — With an argument, sets env.UMASK (octal string); without, prints the current mask (default 022 if unset).\n- set — Minimal support: set -f enables noglob (BARE_OS_SHELL_NOGLOB=1); set +f clears it. Other set options are rejected with a clear error.\n- : — No-op (exit status 0).\n- command — -v / -V: prints builtin name or resolved PATH location via resolveBinInPath. Otherwise runs runBinCommand with the remaining words (external commands only for that path).\n- type — type NAME reports builtin versus resolved /bin/... path or not found.\n\n~/.barerc remains restricted ( export, alias, unalias, comments only) — see Chapter 4 <04-the-booter-runtime.md>.\n\n4. BOOTER CTX HELPERS\n\n- ctx.runBinCommand(argv) — same resolution as the shell’s external dispatch: host delegates (git, curl, wget, systemctl / bare-initctl / journalctl) run first (see HTTP: curl and wget <../docs/reference/http-curl-and-wget.md>), then explicit paths, then *.js in $PWD, then PATH on the system drive only. Used by /bin/time to run another utility and report wall time. The shell may set ctx.bareOsStdoutCaptured** on the clone when stdout is captured (§3).\n- resolveBinInPath(ctx, name) in kernel-runner.js — used by command -v / type.\n- ctx.vfs.watch(logicalPath) — Hyperdrive-backed paths only; returns { watcher, destroy, … } when ctx.bareOsRuntimeCaps.features.vfsWatch is true (disable with host BARE_OS_VFS_WATCH=0).\n- ctx.bareOsBinWrite(Uint8Array|string) (optional) — raw output hook for NUL-terminated lines and binary-safe writes when host process.stdout.write is missing; used by printenv -0, find -print0, dirname -z, and tests (see bareOsEmitRaw in packages/bare-os-coreutils/lib/runtime.js).\n- ctx.bareOsIpc — in-memory FIFOs under /run/bare-os/ipc/<name>; when features.ipcRpcJson is true, pushJson, takeJson, and stats support bounded JSON envelopes (see bare-os-ipc.js). assignProcessGroup(channelName, pgid) / signalProcessGroup(pgid, signal) provide a setpgid / killpg analog for routing virtual signals across FIFO groups (not host OS process groups).\n- ctx.bareOsSubscribeBootEvent, ctx.bareOsEmitBootEvent, ctx.bareOsAwaitInitdUnits, ctx.bareOsSubscribeHdmsLifecycle — automation hooks (see Developer guide §2 <../developer-guide/02-the-context-object.md>).\n\n5. /BIN UTILITIES (CATALOG)\n\nSources: packages/bare-os-coreutils/src/<name>.js. Authoritative sorted list: packages/bare-os-coreutils/lib/commands.mjs (COREUTILS_COMMANDS), consumed by build.mjs. man(1) pages are kept in lockstep with that list: CI runs scripts/verify-man-coverage.mjs (every Tier-1 /bin name has merged JSON under kernel/share/man/ after npm run build -w bare-os-coreutils).\n\n5.1 FILESYSTEM AND LINKS\n\n> Key idea — mutate the personal tree: chmod, chown, touch, rm, and most writes target personal or HDMS paths; /bin on the system image stays read-only.\n\nWhen BARE_OS_VFS_UNION_PREFIXES overlays the personal drive on system paths, readlink checks the personal shadow (same as union readFile) before falling back to the system drive, so symlinks under $HOME-style unions resolve consistently.\n\n- mkdir — -p / --parents, -m MODE (octal; stored on .bareos_empty; directory lstat shows S_IFDIR with those bits). Errors include errno code when present (§2.2).\n- rmdir — Empty directories only (marker-aware).\n- rm — -r/-R/--recursive, -f/--force, -d/--dir (empty directory only), --.\n- cp — -R/-r/--recursive for trees; -u/--update, -v/--verbose, -p/--preserve (timestamps); -L/-P symlink follow.\n- mv — Multi-source → directory; recursive directory moves via copy + delete.\n- ln — Symbolic links only (-s): hard links are not supported on Hyperdrive entries.\n- stat — -c / --format= with %n %N %s %Y %A %U %G %u %g %F (see source for full set).\n- readlink — -n; output via console.log (newline behavior may differ from GNU).\n- getfacl / setfacl — POSIX-style view/edit of advisory ACLs stored in synthetic sidecars (/.bare_acl.json next to the target path’s directory; see kernel/etc/bare-os/vfs-sidecar-xattr-acl.example.json). setfacl updates JSON only; the VFS enforces advisory checks on open when ACL metadata is present.\n- basename — -a, -s / suffix operand.\n- dirname — Multiple paths; -z NUL-terminated output when host process.stdout.write exists.\n- mkfifo — /run/bare-os/ipc/NAME only; in-memory channel (readFile/writeFile/unlink).\n- ls — -l -a -1 -t -S -r, --sort= (time, size, none), --format=single-column, --color= (always, never, auto); honors LS_COLORS. One name per line when stdout is captured (pipelines).\n- dircolors — -p, -b; BARE_OS_DIRCOLORS merges at theme apply.\n- theme — list, current, set, apply — presets; persists in ~/.barerc.\n\n5.2 TEXT AND BINARY VIEWING\n\n> Key idea — engines, not forks: sed, awk, and grep run in-process JavaScript; large bodies live in *lib/-engine.js** prepended at build time.\n\n- cat — -n / -b, -A / -vET, - stdin operand; prefers host process.stdout.write when present (avoids extra log newline).\n- env — -i / --ignore-environment, NAME=value assignments, then utility via ctx.runBinCommand (temporarily swaps vfs.env / ctx.env).\n- touch — -a / -m, -d / -r; vfs.writeFile with explicit mtimeMs/ctimeMs (no separate atime).\n- cut — -d delimiter, -f field list (numeric and ranges).\n- tr — -d delete set, or set1 set2 mapping (byte/char oriented).\n- od — Hex-ish dump (fixed width); not full POSIX od flag matrix.\n- tee — -a append; duplicates stdin to files and stdout.\n- sed — Large subset — see §6.\n- awk — Substantial interpreter — see §7.\n- grep — -F, -i, -v, -w, -x, -n, -c, -l, -o, -m, -r/-R with --include, --exclude, --exclude-dir (glob count capped by BARE_OS_GREP_FILTER_MAX, default 32), -A/-B/-C, --color=never / always / auto, -e, -f, etc.; JS RegExp (not PCRE / full GNU).\n- base64 — -d/--decode, -w line wrap; decode uses bareOsEmitRaw when console.log would corrupt binary.\n- base32 — RFC 4648 encode/decode; decode path same raw-output contract as base64.\n- basenc — --base16 (hex), --base32 (RFC-style), and --base64 encode/decode.\n- realpath — -m/--canonicalize-missing; prints vfs.resolveLogical.\n- sha256sum — GNU-style lines via globalThis.crypto.subtle.digest('SHA-256', …).\n- sha1sum, sha512sum — Same line format when subtle.digest supports SHA-1 / SHA-512.\n- md5sum — Bundled lib/md5.js (no Web Crypto MD5).\n- sum — SysV default or -r BSD 16-bit checksum + 512-byte block counts.\n- uniq — -c, -d, -u on adjacent lines (sort input first for POSIX-style behavior).\n- paste — -d delimiter list, -s serial (one file’s lines joined per output row).\n- split — -l lines or -b bytes per chunk; output basename + POSIX-style multi-length a–z suffixes (aa…zz, then aaa, aab, …); max files BARE_OS_SPLIT_MAX_FILES ( getconf default 10000).\n- tac, rev — Reverse line order / reverse characters per line.\n- expand, unexpand — Uniform tab width (-t / -tN); spaces ↔ tabs.\n- fold — -w fixed column wrap (no word-aware reflow).\n- fmt — Simple paragraph reflow (-w); blank-line-separated paragraphs.\n- comm — Two sorted files; columns with -1/-2/-3 suppress.\n- join — -t, -1, -2 on sorted inputs; relational merge on join field.\n- pr — Minimal columnate / -n line numbers / -s separator.\n- yes — Repeated line until BARE_OS_YES_MAX_LINES ( getconf: default 100000); host may pass through from process.env.\n- shuf — In-memory shuffle; input line cap BARE_OS_SHUF_MAX_LINES (default 50000). Uses Math.random.\n- factor — Trial division; safe integers.\n- expr — Integers with *+ - / %, comparisons, string = / !=; not full POSIX expr**.\n- tsort — Topological sort; exits 1 on cycles.\n- numfmt — --to=iec (1024) or --to=si (1000) human scales.\n\n5.2A TTY TEXT EDITOR (EDIT / NANO)\n\n- edit — Full-screen in-terminal editor over ctx.vfs: multi-line buffer, search / goto / save-as, optional syntax highlighting. Requires a TTY (stdin.isTTY in src/edit.js); exits with a clear error if stdin is not a TTY. On exit, the TUI leaves alternate-screen mode (?1049l) when enabled (default), restoring the pre-editor terminal view; set BARE_EDIT_NO_ALTSCREEN to any non-empty value to use a full clear (2J) instead on terminals where alternate-screen misbehaves. Source: src/edit.js with preamble lib/edit-ansi.js, edit-highlight.js, edit-buffer.js, edit-key-parse.js, edit-tui.js.\n- nano — Same built artifact as edit (build.mjs maps nano → src/edit.js and the same preamble). /bin/nano is installed for muscle memory; the default shell alias nano → edit (see defaultShellAliases in shell.js) makes nano invoke that binary. man edit and man nano describe flags and keys.\n\n5.2A1 SESSION MONITOR (BARETOP)\n\n- baretop / btop — Full-screen htop-style terminal dashboard for session / operator state plus a logical process table from /proc/bare_os/process_table.json (schema 7 synthetic PIDs — not host OS PIDs). Pulls /proc/bare_os/metrics_live.json, ctx.bareOsReadProcMetricsLive, /proc/bare_os_resources / ctx.bareOsGetResourceStatus, pseudo /proc/meminfo / loadavg / cpuinfo, ctx.bareOsReadBareTopSnapshot (booter batch read of many */proc/bare_os/ mirrors), plus optional ctx.bareOsReadDelegateFairnessSnapshot, ctx.bareOsReadSubprocessBridgeSnapshot, ctx.bareOsHostStats. Eleven tabs: overview (sparklines, pipeline % bars, delegate histogram, health score, mem/load meters, tab strip), processes (sortable table, filter, JSON detail, optional ctx.bareOsSendSignal via k / F9), initd (filter /), network, features, diagnostics, operator, Pear, catalog, host ([ ] from catalog), keys. 1–9 jump first nine tabs; 0 = keys; host tab only from [ ]. Arrow keys scroll lists; F1/F5/F9 when the terminal sends standard function-key sequences; SIGWINCH / stdout resize redraw; optional suspend/resume hooks (bareOsRegisterSuspendHook). Themes BARE_TOP_THEME, BARE_TOP_MONO, BARE_TOP_FRAMES, BARE_TOP_INCREMENTAL, BARE_TOP_PROC_SORT, BARE_TOP_RING_CAP, man baretop for env list. Alternate-screen BARE_TOP_NO_ALTSCREEN. Shell aliases top / btop → baretop. Source: src/baretop.js + lib/baretop-snapshot.js, lib/baretop-ui-helpers.js, lib/baretop-tui.js (with edit-ansi.js, edit-key-parse.js**).\n\n5.2A1A OPERATOR PROC CATALOG (BARETOP PANELS)\n\nStable paths are also listed under /proc/bare_os/ in packages/bare-os-booter/lib/vfs.js. The snapshot batch keys (keep aligned with BARE_TOP_SNAPSHOT_PROC_ENTRIES in lib/baretop-snapshot.js and bareOsReadBareTopSnapshot in packages/bare-os-booter/index.js) include: index.json, version, host_os.json, debug.json, session_stats, quotas, capabilities (+ .json), seed_handshake, bootstrap, provenance, snapshot_hints.json, staging_slot, peer_health, pear_ipc.json, pear_ipc_health.json, pear_trust.json, replication, replication_backpressure.json, swarm, sync_window.json, hdms_health.json, hdms_hints.json, dht_status.json, udx_extended.json, ipc_backpressure.json, delegate_red.json, git_delegate_stats.json, git_lfs_pointer_stats.json, worker_budget.json, sandbox_profile.json, rlimits.json, extensions.json, initd_dag.json, boot_graph.json, process_table.json, syscalls.json, metrics.prom, protomux.json. Missing nodes show N/A per panel rather than failing the whole TUI.\n\n5.2A1B CONTRIBUTORS — BARE VS NODE BUILTINS\n\n/bin utilities are concatenated bundles evaluated as AsyncFunction — they must not static-import node:crypto, node:module, or other node: builtins Pear/Bare cannot resolve from a pear:// image. Use ctx.vfs, JSON.parse, and ctx.b4a only inside baretop. For background on the Bare module stack (bare-crypto, bare-module, etc.), see the Holepunch holepunch-repos tree (e.g. docs/05-BARE-RUNTIME.md) in a local Pear workspace; paths vary by checkout.\n\n5.2B HTTP CLIENTS (CURL / WGET)\n\ncurl and wget are booter-delegated CLIs, not coreutils engines. They implement Fetch-based subsets of the familiar tools; the /bin/curl and /bin/wget files on the system image exist for ls /bin / which parity and are stubs if ever executed without delegation.\n\n- Delegation order, fetch resolution, policy env — Reference — HTTP: curl and wget <../docs/reference/http-curl-and-wget.md>.\n- Flag parity — CLI_PARITY.md <../packages/bare-os-booter/CLI_PARITY.md>.\n- Online help — Chapter 10 — Manpages <10-manpages-and-online-help.md> (man curl, man wget).\n- Security / allowlists — Developer guide — Security and trust <../developer-guide/09-security-and-trust.md>.\n\n5.3 DISCOVERY AND MEASUREMENT\n\n> Key idea — bounded automation: find -exec, xargs, yes, and shuf carry hard caps so runaway scripts cannot allocate unbounded memory; see getconf -a and environment appendix <../docs/reference/environment-and-posix-appendix.md>.\n\n- find — -maxdepth, -mindepth, -depth, -name / -iname, -path, -regex (matches full path as a JavaScript regex), -type f/d/l, -empty, -exec / -ok utility … {} … ; (requires ctx.runBinCommand; capped by BARE_OS_FIND_EXEC_MAX, default 64; -ok runs only when BARE_OS_FIND_OK=1), -print0 (uses host process.stdout.write when available).\n- du — -k for 1024-byte blocks; otherwise 512-byte units; -h human-readable byte totals; -s acknowledged (one total per operand, same as default here).\n- cksum — POSIX / Open Group CRC + length + name (matches common cksum on BSD/macOS for the same bytes).\n- printf — Subset of printf(1) conversions (%s, %d, %o, %x, etc.).\n- logname — Prints LOGNAME / USER / guest.\n- time — Times ctx.runBinCommand for the rest of the line; prints real to stderr.\n- timeout — timeout [-s SIG] DURATION cmd … — runs cmd with a wall-clock cap via AbortSignal when BARE_OS_FEATURE_ABORT_TIMEOUT is advertised; on timeout exits 124 (or 128+N after kill when --foreground and signal delivery is supported). See man timeout.\n- tail — -n, -c, + offsets, -f/--follow ( vfs.watch when enabled, else poll; BARE_OS_TAIL_F_POLL_MS, BARE_OS_TAIL_F_MAX_ROUNDS); stdin and multi-file -f not supported.\n- head — -n, -c, -NUM.\n- sort — -n, -r, -u, -f, -k / -t, -c / -C (check ordered input), -s (stable), -o FILE (output path; place before operands), - stdin operand; clustered flags (e.g. -nru).\n- wc — -l, -w, -c (default: all three); - stdin.\n- date — -u, +FORMAT subset (%Y %m %d %H %M %S %s %z %a %b, %%).\n- test — -eq/-ne/-lt/-le/-gt/-ge (signed integers), -h/-L, -f/-d/-e, -z/-n, string = / !=.\n- df — Synthetic 1K-blocks row for Bare (-h human-readable); not real block devices. Optional scale hint from /proc/bare_os_quotas. Use --help for usage (-h is not help).\n- truncate — -s SIZE absolute length only; pads with zeros when growing.\n- unlink — Single operand; vfs.unlink.\n- install — [-m MODE] SOURCE DEST — copy one file and optional chmod.\n- sync — No-op success (no host flush hook).\n- dir, vdir — Delegate to ctx.runBinCommand(['ls','-C',…]) / ['ls','-l',…].\n- arch — PROCESSOR_ARCHITECTURE, MACHINE, or BARE_OS_ARCH; else unknown.\n- groups — GROUPS env or primary GROUP.\n- hostid — Eight hex digits from HOSTID or hash of BARE_OS_SESSION_ID.\n- nproc — Count processor: lines in /proc/cpuinfo or BARE_OS_NPROC override. --all accepted (same count here).\n- uptime — /proc/uptime and /proc/loadavg when present.\n- users, who — Session USER / LOGNAME; who prints a minimal table from env.\n\n5.4 GETCONF AND XARGS (BARE SUBSETS)\n\n- getconf — getconf NAME prints a value from a fixed static table plus live vfs.env overrides for cap names (PATH_MAX, _POSIX_VERSION, *BARE_OS_PIPELINE_, BARE_OS_FIND_EXEC_MAX, BARE_OS_XARGS_MAX_PROCS, BARE_OS_KERNEL_EXT_D_HOT_RELOAD, BARE_OS_VFS_HYPERBLOBS_DEDUP, …). getconf -a prints all known names (each name then value on the following line). Unknown names exit 1**.\n- xargs — Reads bareStdin(ctx); splits on whitespace or -0 null bytes; runs await ctx.runBinCommand([utility, …initial, …batch]) per batch. Flags: -0/--null, -n N/--max-args N (capped), -P N (parallel batches; cap min(N, BARE_OS_XARGS_MAX_PROCS, 32), default env cap 8), -I repl (substitute in utility argv; implies -n 1 unless -n is set). Hard limits on stdin size, token count, args per run, and invocations per process—see src/xargs.js.\n\nAll other commands from build.mjs not listed here follow the summaries in Chapter 6 <06-kernel-and-binaries.md> or their *src/.js** files.\n\nExports for tests / tools: splitTokensBySemicolon, splitTokensByAndOr (same module as tokenize).\n\n6. SED IMPLEMENTATION\n\nEngine: packages/bare-os-coreutils/lib/sed-engine.js (prepended before src/sed.js at build time).\n\nCLI: sed supports -n, -E/-r, -z (NUL-separated “lines”; max records BARE_OS_SED_NULL_MAX_RECORDS, default 100000), multiple -e, -f, and operands as files or stdin.\n\nBroadly supported: line addresses (#, $, /re/, ranges, first~step), s/// with common flags (g, p, digit), y///, d/D/p/P/n/N, hold space (h/H/g/G/x), b/t/:label, q, r/w, =, l, a/i/c (backslash forms). r reads paths via a preload scan + vfs.readFile; w appends via vfs.writeFile.\n\nNot guaranteed: full GNU sed extensions, every POSIX corner case (e.g. all s flag combinations, locale collation), or s delimiter edge cases identical to every implementation.\n\n7. AWK IMPLEMENTATION\n\nEngine: packages/bare-os-coreutils/lib/awk-engine.js (prepended before src/awk.js).\n\nCLI: -F, -v name=value (implemented as a synthetic BEGIN assignment), -f, program string, then optional input files (stdin if none).\n\nBroadly supported: BEGIN/END, regex and expression patterns, print/printf with redirection to files, if/while/for/for (i in arr), arrays, next/exit, many builtins (length, substr, index, split, sprintf, sub/gsub, match, int, tolower/toupper, rand/srand), ENVIRON[\"VAR\"], user-defined function.\n\nKnown limitations: / in expressions is always a regex literal in the lexer (division is ambiguous in real awk — use spaces or refactor); getline from files is incomplete; nextfile skips the rest of the current input file (Issue 7–shaped control flow; bounded like other loop rules); print to files is queued and flushed per statement batch — fine for typical scripts but not identical to every awk I/O timing. Not gawk-compatible for extensions.\n\n8. COREUTILS BUILD: PREAMBLE MAP\n\nbuild.mjs <../packages/bare-os-coreutils/build.mjs> concatenates:\n\n1. lib/runtime.js\n2. Optional extra libs from the preamble map: md5sum → lib/md5.js, sed → lib/sed-engine.js, awk → lib/awk-engine.js, jq → lib/jq-engine.js, man → lib/man-render.js, ls / dircolors → lscolors bundles, edit / nano → *lib/edit-.js** TUI stack\n3. src/<cmd>.js (nano uses src/edit.js)\n\nThere is still no import in *src/.js — large utilities are vendored as plain script chunks in lib/**.\n\n8.5 SHELL COOKBOOK (WITHOUT FULL POSIX SH)\n\nThe line shell does not support subshells, full sh grammar, or real background processes. Prefer these patterns:\n\n- Sequential steps — One execLine per line in rc / rc.d (trusted), or ; / && in the REPL.\n- Capture output — Pipelines and VAR=$(command) (when BARE_OS_SHELL_CMDSUBST=1) instead of POSIX command groups.\n- Conditionals — Bounded if / fi (see §3); for complex logic, call a /bin helper script on the system image.\n- Boot policy — denyExecLineBuiltins in boot.policy.json (v4) maps to BARE_OS_BOOT_POLICY_DENY_EXEC_LINE_BUILTINS to block specific builtins (e.g. login) on locked-down images.\n\n8.7 CAPABILITY WORD 8 — BARE-FS ERRNO ROWS, UNION WHITEOUT, FIFO METRICS\n\nStock docs add these guest-visible mappings and behaviors (bounded JSON / handbook only where noted):\n\n- ELOOP — Too many symlink hops when resolving a path on Hyperdrive-backed VFS.\n- ENOTEMPTY — Directory not empty on rmdir / rename that would clobber a non-empty tree.\n\nUnion mounts: document opaque vs transparent whiteout matrix when upper layers hide lower files; find -prune respects mount boundaries as in the kernel-extensions table.\n\nFIFO / /run: metrics schema v2 may include byte + message counts (operator-injected JSON); not a POSIX pipe implementation.\n\n/dev/zero: read coalescing cap is documentation-first for host-backed implementations.\n\n/bin/env -S: when BARE_OS_ENV_DASH_S=1, GNU-like split strings apply; see packages/bare-os-coreutils/src/env.js and kernel-extensions <../docs/reference/kernel-extensions.md>.\n\n9. WHERE TO READ NEXT\n\n- Chapter 6 — Kernel and /bin summary <06-kernel-and-binaries.md>\n- Chapter 4 — Shell and VFS routing <04-the-booter-runtime.md>\n- Chapter 10 — Manual pages (man) and online help <10-manpages-and-online-help.md>\n- Booter reference §12.6–12.9 <../docs/reference/package-bare-os-booter.md> and coreutils §12.10 <../docs/reference/package-bare-os-coreutils-and-ci.md#1210-package-bare-os-coreutils> — file-level inventory\n- bare-os-coreutils README <../packages/bare-os-coreutils/README.md> — build and command contract\n\nNext: Chapter 10 — Manual pages <10-manpages-and-online-help.md>\n\nRelated: Kernel extensions <../docs/reference/kernel-extensions.md> · Handbook home <README.md>\n\n_Experimental research software, not a production OS. Apache-2.0 — LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","09","posix","utilities","shell","and","vfs","style","builtins","alignment"],"seeAlso":[{"name":"handbook-10-manpages-and-online-help","section":7},{"name":"handbook-08-git-on-bare-os","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/09-posix-utilities-shell-and-vfs.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-10-manpages-and-online-help","section":7,"title":"Chapter 10 — Manual pages (man) and online help","synopsis":["man 7 handbook-10-manpages-and-online-help","Handbook chapter (plain text from handbook/10-manpages-and-online-help.md)"],"description":"CHAPTER 10 — MANUAL PAGES (MAN) AND ONLINE HELP\n\nTime to read: about 10 minutes. Prerequisites: Chapter 6 <06-kernel-and-binaries.md> (coreutils build), Chapter 7 <07-operations-and-development.md>.\n\nBare OS ships a man(1)-style viewer backed by a JSON manual database on the system Hyperdrive, not troff, mandoc, or groff. This matches the project’s model: utilities are AsyncFunction scripts, and documentation must load without a host typesetter.\n\nPURPOSE\n\n- Familiar UX: Users expect man ls, man -k pattern (apropos), and man -f name (whatis).\n- Shippable: Pages live at /share/man/man.json (staged from kernel/share/man/man.json), merged at build time from *packages/bare-os-coreutils/man/pages/.json**.\n- Verifiable: The build fails if any /bin command from lib/commands.mjs <../packages/bare-os-coreutils/lib/commands.mjs> lacks a page. Root pretest also runs scripts/verify-man-coverage.mjs against kernel/share/man/man.json so CI catches drift after catalog changes.\n\nSession environment: many boot knobs are *BARE_OS_** variables copied from the host (HTTP policy, IPC token/fan-out, TLS pin list, audit, boot trace, …). The canonical list is in developer-guide §2 — The context object <../developer-guide/02-the-context-object.md> and packages/bare-os-booter/CHANGELOG.md <../packages/bare-os-booter/CHANGELOG.md>.\n\nSECTIONS\n\n- 1 — User commands — every name in COREUTILS_COMMANDS, including man itself.\n- 1 — bare-os-shell — one manual for all interactive shell builtins (cd, export, …), so we do not maintain dozens of one-line stubs.\n- 7 — Handbook — every *handbook/.md file (including 00-preface.md, README.md, 01-introduction.md, …) is merged at build time as man(7) (POSIX “miscellaneous”). TOC: man handbook or man 7 bare-os-handbook (alias handbook). Per-file pages use names like handbook-00-preface, handbook-01-introduction, … mermaid** diagrams are omitted in the terminal view; open the Markdown in the repo for figures.\n- 7 — Developer guide — every *developer-guide/.md file is merged the same way. TOC: man devguide or man 7 bare-os-developer-guide (aliases developer-guide, devguide). Chapters: man devguide-01-two-runtimes-host-vs-image**, …\n\ngit is not a /bin script (it is delegated in the booter to git-cli.js), but it still has a section 1 page git in the same database.\n\nCLI SURFACE (/BIN/MAN)\n\n- man — Short usage and pointer to man -l.\n- man name — Show manual for name (any section if the name is unique, e.g. man ls or man handbook).\n- man 1 name / man 7 name — Require that section; fails if the page lives in another section (e.g. man 7 ls fails).\n- man -l — List every page under category headings (/bin, git/shell, handbook, developer guide), then name(section) alphabetically within each group.\n- man -k word — Apropos: pages whose keywords / title / name match word (substring, case-insensitive).\n- man -f name — Whatis: one-line name(section) - title for an exact name match.\n\nEnvironment\n\n- MANWIDTH — Wrap width for prose (default 72, minimum 40).\n\nExit status\n\n- 0 — Success (page shown or list empty for man -k with no matches).\n- 1 — Page not found or man.json missing on the system drive.\n- 2 — Invalid usage.\n\nJSON PAGE MODEL\n\nAuthoritative schema: packages/bare-os-coreutils/man/schema.json <../packages/bare-os-coreutils/man/schema.json>.\n\nEach man/pages/<name>.json describes one page:\n\n- name, section, title — NAME header.\n- synopsis — string array (usage lines).\n- description — multi-sentence DESCRIPTION.\n- options — { \"flag\": string, \"meaning\": string }[].\n- environment, files — optional string arrays.\n- exitStatus, diagnostics — optional string arrays.\n- seeAlso — { \"name\": string, \"section\": number }[].\n- bareOsNotes — optional string; POSIX / GNU divergence.\n- keywords — lowercase tokens for man -k.\n- aliases — optional alternate lookup names (e.g. sh-builtins → bare-os-shell).\n- stub — if true, man(1) adds a STATUS section stating the utility is intentionally bounded relative to Issue 7 (see BARE OS NOTES and handbook ch.9).\n- examples — optional array of { \"caption\"?: string, \"code\": string } (cheat.sh–style: short label + copy-paste command; code may use newlines for multi-line snippets). Rendered under an EXAMPLES heading after OPTIONS. bare-os-shell builtins may also carry per-builtin examples with the same shape.\n- descriptionMode — \"wrap\" (default) or \"preserve\". Handbook pages use preserve so line breaks and tables stay readable.\n\nman -k also indexes caption text from examples so searches like “clone” can surface git.\n\nThe merged man.json adds schemaVersion, generatedAt, pages, index (name → page index), and apropos (keyword → page indices) for fast lookup.\n\nBUILD PIPELINE\n\n1. npm run build -w bare-os-coreutils runs build.mjs, which calls scripts/build-man-db.mjs.\n2. build-man-db.mjs loads every man/pages/<cmd>.json for COREUTILS_COMMANDS, plus git.json and bare-os-shell.json, then invokes scripts/ingest-handbook-for-man.mjs for handbook chapters.\n3. ingest-handbook-for-man.mjs (see packages/bare-os-coreutils/scripts/ingest-handbook-for-man.mjs <../packages/bare-os-coreutils/scripts/ingest-handbook-for-man.mjs>) reads *handbook/.md, converts Markdown to plain text for the terminal: headings become spaced title lines, list items flatten, inline code/backticks and links are stripped to readable text, fenced blocks indent as literal text except mermaid fences (omitted). Each file becomes one man(7)** page with auto keywords.\n4. build-man-db.mjs validates the merged database, writes kernel/share/man/man.json, and mirrors to packages/bare-os-seeder/kernel/share/man/man.json.\n5. The seeder stages kernel/ recursively; kernel/share/... → /share/... on the system drive (packages/bare-os-seeder/index.js <../packages/bare-os-seeder/index.js>).\n6. /bin/man reads ctx.drive.get('/share/man/man.json'). There is no embedded fallback in v1 — the image must include the merged file.\n\nRELATIONSHIP TO HELP\n\n/bin/help prints a compact one-screen list of builtins and /bin names (including edit and nano)—fast orientation. man is the long-form reference: flags, exit status, EXAMPLES, and merged handbook / developer-guide chapters.\n\nUser story: help when you are exploring; man <cmd> before scripting; man handbook or man 7 handbook-00-preface when you want narrative docs inside the guest.\n\nAuthoring split: change help when builtins or binary names change; change man JSON when command behavior changes; change handbook/ for prose—rebuild coreutils to refresh man(7).\n\nAUTHORING WORKFLOW\n\n1. Narrative docs — edit *handbook/.md or developer-guide/.md*; run a coreutils build so ingest runs.\n2. Per-command pages — add or edit packages/bare-os-coreutils/man/pages/<name>.json.\n3. Run npm run build -w bare-os-coreutils (or node packages/bare-os-coreutils/scripts/build-man-db.mjs).\n4. New /bin commands: add name.json, lib/commands.mjs entry, and src/<name>.js — the build fails until the page exists.\n\nFUTURE WORK\n\n- Interactive PAGER (keypress paging on TTY) beyond PAGER=bare-slice section breaks.\n- man -w is implemented (prints /share/man/man.json); per-page anchor paths remain future work.\n- HTML export for Pear / browser shells.\n- Section 7 overview pages and i18n.\n\nRelated: Chapter 9 <09-posix-utilities-shell-and-vfs.md> · Handbook home <README.md> · CHANGELOG <../packages/bare-os-booter/CHANGELOG.md>\n\n_Experimental research software, not a production OS. Apache-2.0 — LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","10","manpages","and","online","help","manual","pages","man"],"seeAlso":[{"name":"handbook-11-kernel-program-and-research","section":7},{"name":"handbook-09-posix-utilities-shell-and-vfs","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/10-manpages-and-online-help.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-11-kernel-program-and-research","section":7,"title":"Chapter 11 — Kernel program, ecosystem, and non-goals","synopsis":["man 7 handbook-11-kernel-program-and-research","Handbook chapter (plain text from handbook/11-kernel-program-and-research.md)"],"description":"CHAPTER 11 — KERNEL PROGRAM, ECOSYSTEM, AND NON-GOALS\n\nTime to read: one pass. Prerequisites: Preface <00-preface.md>, Chapter 3 — Protocol <03-protocol-and-disk.md>.\n\nWHY THIS CHAPTER EXISTS\n\nBare OS sits at the intersection of Pear (packaging and desktop hosts), Bare (embedded-first JS runtime and modules), and Holepunch stacks (Hyperswarm, HyperDHT holepunch, Hyperdrive). This chapter names research directions and intentional limits so distributors know what the project will and will not become.\n\nECOSYSTEM MAP (LOCAL CLONES)\n\nIf you maintain a checkout of holepunch-repos <https://github.com/holepunchto> (or a mirror), useful adjacencies include:\n\n- Runtime / packaging — pear-runtime, pear-stage, pear-ipc — Host OTA, IPC, staging\n- Bare modules — bare-subprocess, bare-daemon, bare-kit, bare-storage — Optional delegates, worklets, storage policy\n- Transport — hyperdht (holepunch docs), hyperswarm, udx-native — NAT, relays, stream behavior\n\nNothing in that tree is the Bare OS kernel: our kernel remains /boot/init.js on the system Hyperdrive, executed by the booter.\n\nCAPABILITY WORDS (PROTOCOL)\n\nCapability words bits … bits11 (see packages/bare-os-protocol <../packages/bare-os-protocol/README.md>) advertise what the stock booter and seeder implement. BARE_OS_SEED_CAP_STRICT requires the seeder to cover every non-zero stock word. Capability words 6–11 checklists: docs/reference/feature-roadmap.md <../docs/reference/feature-roadmap.md>. Kernel program (200-item backlog): developer-guide/kernel-program.md <../developer-guide/kernel-program.md>; program batch B table lives in the same reference doc. Governance: developer-guide/adr/001-kernel-feature-bits-governance.md <../developer-guide/adr/001-kernel-feature-bits-governance.md>. Word 10 extends Pear/Bare–aligned seed RPCs, /proc JSON for that generation, boot policy v10, extension registry schema 7, telemetry schema 9 / OTel 7 / audit 7, and the Node→Bare module map in developer-guide/node-to-bare-modules.md <../developer-guide/node-to-bare-modules.md>.\n\nINTENTIONAL NON-GOALS\n\n- No hardware MMU kernel — no ring 0, no real fork; isolation is policy, caps, and host boundaries.\n- No full POSIX sh — line shell with bounded grammar; see Chapter 9 §8.5 <09-posix-utilities-shell-and-vfs.md>.\n- No single HTTP mirror as source of truth — image distribution is P2P-first; offline boot is optional LKG + local Corestore (BARE_OS_OFFLINE_LKG_BOOT).\n\nWHERE TO READ NEXT\n\n- Documentation home <../docs/README.md> — all trees, glossary, FAQ\n- Compatibility matrix <../docs/reference/compatibility-matrix.md> — versions in one place\n- Kernel extensions <../docs/reference/kernel-extensions.md> — feature / env / proc map\n- ADR 001 — Feature bit governance <../developer-guide/adr/001-kernel-feature-bits-governance.md>\n- Handbook home <README.md>\n\n_Experimental research software, not a production OS. Apache-2.0 — LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","11","kernel","program","and","research","ecosystem","non","goals"],"seeAlso":[{"name":"handbook-12-p2p-stack-and-posix-boundaries","section":7},{"name":"handbook-10-manpages-and-online-help","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/11-kernel-program-and-research.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"handbook-12-p2p-stack-and-posix-boundaries","section":7,"title":"Chapter 12 — P2P-native stack vs POSIX boundaries","synopsis":["man 7 handbook-12-p2p-stack-and-posix-boundaries","Handbook chapter (plain text from handbook/12-p2p-stack-and-posix-boundaries.md)"],"description":"CHAPTER 12 — P2P-NATIVE STACK VS POSIX BOUNDARIES\n\nBare OS ships a guest-facing POSIX-like layer (utilities, shell subset, logical fds, synthetic /proc) on top of a P2P-first substrate: Hyperdrive replication, Hyperswarm discovery, Protomux channels, and optional blind relay paths. This chapter maps those worlds so integrators know what is compatibility sugar and what is distributed systems reality.\n\nNON-GOALS (DECLARED)\n\nThe authoritative list lives in POSIX declared profile <../docs/architecture/POSIX_DECLARED_PROFILE.md> and the placeholder / closure baseline <../docs/audit/PLACEHOLDER_BASELINE.md>. In short: no real fork, no host kernel threads inside the guest image, no FIFOs on Hyperdrive (in-memory IPC and synthetic pipes instead), errno not bit-identical to Linux, and replication / /proc JSON treated as observability, not strong linearizability proofs.\n\nWhen a behavior is intentionally partial, the POSIX compliance matrix <../docs/reference/posix-compliance-matrix.json> and /proc/bare_os/syscalls.json schema carry the machine-readable contract.\n\nP2P STACK (WHAT ACTUALLY MOVES BYTES)\n\n| Concern | Primary mechanism | Guest-visible hints |\n| System image | Hyperdrive over Corestore; seed MBR + Protomux bare-os-v1 | /proc/bare_os/replication, metrics_live.replicationLive, ctx.bareOsReadReplicationOperatorJson |\n| Personal data | Second Hyperdrive (home, vault, /.bare-os) | Union paths, identity session, vault blobs |\n| Wire multiplexer | Protomux on encrypted streams | /proc/bare_os/protomux.json, extension registry when enabled |\n| Discovery / NAT | Hyperswarm + HyperDHT (host) | /proc/bare_os/swarm, dht_status.json, optional dhtAddressClassAllowlist env |\n| Operator RPC | Seed RPC allowlist + optional hrpc bridge | KERNEL_CONTRACT seed + ctx.bareOsHrpcRequest built-ins |\n\nOffline-first remains the default story: local Corestore opens the system drive; swarm fills gaps and pushes updates. Eventual consistency is honest: warm read caches, replication snapshots, and append-driven invalidation (when BARE_OS_VFS_WARM_CACHE_INVALIDATE_ON_APPEND is on) are best-effort hygiene, not a distributed filesystem guarantee.\n\nPOSIX SURFACE (WHAT SCRIPTS SHOULD RELY ON)\n\n- Utilities under /bin follow documented subsets; man and the matrix record gaps.\n- Shell — see Chapter 9 — POSIX utilities, shell, and VFS <09-posix-utilities-shell-and-vfs.md>; set -e / BARE_OS_SHELL_ERREXIT implement a narrow errexit subset, not full Issue 7 sh.\n- Syscalls — logical ctx.bareOsSyscall operations mirror /proc/bare_os/syscalls.json; socket bridge behavior is env-gated and bounded.\n\nCLOSURE CRITERIA\n\n- P0 / P1 items in PLACEHOLDER_BASELINE.md <../docs/audit/PLACEHOLDER_BASELINE.md> should be implemented or explicitly reclassified with a doc link.\n- P3 bundle/vendor markers are governed by *verify-bundle- and upstream bare-os-bare-libs rebuilds — not ad-hoc edits in kernel/lib/bare/bundles/**.\n\nFor maintainer automation (pretest generators, bundle order, seeder parity), see scripts/README.md <../scripts/README.md> — Maintainer: pretest generator runbook.\n\nSEE ALSO\n\n- Chapter 3 — Protocol and disk <03-protocol-and-disk.md>\n- Chapter 4 — The booter runtime <04-the-booter-runtime.md>\n- Chapter 9 — POSIX utilities, shell, and VFS <09-posix-utilities-shell-and-vfs.md>\n- Architecture: data flow <../docs/reference/architecture-data-flow.md>","descriptionMode":"preserve","options":[],"keywords":["handbook","bare-os","documentation","narrative","chapter","12","p2p","stack","and","posix","boundaries","native"],"seeAlso":[{"name":"handbook-11-kernel-program-and-research","section":7},{"name":"man","section":1}],"bareOsNotes":"Generated at build time from handbook/12-p2p-stack-and-posix-boundaries.md. Diagrams in ```mermaid blocks are omitted; open the Markdown in the repo for figures.","listCategory":"handbook"},{"name":"bare-os-developer-guide","section":7,"title":"Bare OS developer guide — index and reading order","synopsis":["man 7 bare-os-developer-guide","Developer guide chapter (developer-guide/README.md)"],"description":"BARE OS — DEVELOPER GUIDE\n\nWelcome. This guide is the how-to companion for writing software on and for Bare OS: scripts that run inside the replicated system image, utilities under /bin, the session kernel, and—when you need full JavaScript modules—the host Pear packages that implement the booter and seeder.\n\nThe documentation home <../docs/README.md> maps every tree plus the shared glossary <../docs/glossary.md>, FAQ <../docs/faq.md>, troubleshooting router <../docs/troubleshooting.md>, and contributing to docs <../docs/CONTRIBUTING-DOCS.md>. The handbook <../handbook/README.md> explains _why_ the system is shaped the way it is (Hyperdrive, two drives, swarm boot). The docs/reference <../docs/reference/README.md> inventory lists _where_ every file lives. The user manual <../users-manual/README.md> helps people run the system before they extend it. This guide focuses on _what you actually type_: entrypoint signatures, the ctx object, why import does not work in drive-resident scripts, and how the coreutils build turns sources into /bin commands.\n\nThis project is experimental research software. APIs described here follow the current code in packages/bare-os-booter and packages/bare-os-coreutils; when in doubt, read the cited paths.\n\nctx API versions: see packages/bare-os-booter/CHANGELOG.md <../packages/bare-os-booter/CHANGELOG.md> for bareOsCtxApiVersion history and booter alignment. TypeScript-oriented authors can reference lib/bare-os-ctx.d.ts <../packages/bare-os-booter/lib/bare-os-ctx.d.ts>.\n\nFeature-bit governance: ADR 001 — Kernel feature bit governance <adr/001-kernel-feature-bits-governance.md>.\n\nCapability map: docs/reference/kernel-capabilities-index.md <../docs/reference/kernel-capabilities-index.md>.\n\nContract checks: changing bareOsCtxApiVersion or stock kernel feature bits should keep scripts/verify-ctx-api-feature-bits.mjs green (invoked from root pretest).\n\nArchitecture contract (boundaries): docs/architecture/KERNEL_CONTRACT.md <../docs/architecture/KERNEL_CONTRACT.md> — booter vs guest image, disk.os RPC, boot step IDs.\n\nKernel source set: docs/reference/kernel-extensions.md <../docs/reference/kernel-extensions.md> — first-party paths (kernel/init.js, kernel/lib/boot, built /bin) vs vendored kernel/lib/bare/bundles (Holepunch IIFEs), CI allowlists, and seeder parity. Hand-authored code must stay free of incomplete markers; bundles are gated by verify-bundle-markers.mjs, verify-bundle-throws.mjs ( new Error messages with not implemented / abstract-base-class semantics — see docs/audit/bundle-throw-allowlist.json <../docs/audit/bundle-throw-allowlist.json>), and sanitize-bare-bundles.mjs. Prefer shrinking the throw allowlist via upstream bundle refreshes over silent drift.\n\nLocal Holepunch mirror: run npm run audit:holepunch-clones to refresh holepunch-clone-sync-report.json, holepunch-lockfile-drift.json, and NDJSON summaries (manifest names vs clones + workspace lockfile semver vs clone package.json). Root pretest runs verify-holepunch-clone-drift.mjs against basenames listed in docs/audit/holepunch-drift-repos.json (empty repos[] = no-op). Regenerate the maximal npm catalog with node scripts/gen-bare-holepunch-catalog.mjs (or npm run gen:bare-catalog), then npm run sync:bare-manifest — see scripts/README.md <../scripts/README.md>.\n\nON THIS PAGE\n\n- Who this is for <#who-this-is-for>\n- Reading order <#reading-order>\n- Related docs <#related-docs>\n\nWHO THIS IS FOR\n\n- You want to drop a hello.js on your personal drive and run it from the shell without misunderstanding the execution model.\n- You plan to add or change a /bin utility and need the no-import contract and build steps.\n- You are modifying the booter or seeder Pear apps and need to separate “host ESM” from “in-image AsyncFunction.”\n- You are debugging async function run(ctx, argv) or start(ctx) and need a map of ctx.\n\nREADING ORDER\n\n- 01 — Two runtimes: host vs in-image <01-two-runtimes-host-vs-image.md> — Pear/Node packages vs Hyperdrive JS evaluated with AsyncFunction; trust boundaries.\n- 02 — The context object (ctx) <02-the-context-object.md> — vfs, drive, console, identity hooks, execLine, runBinCommand, …\n- 03 — Kernel: /boot/init.js <03-kernel-boot-init.md> — async function start(ctx); readline loop; calling the shell.\n- 04 — User scripts and PATH resolution <04-user-scripts-and-path.md> — run(ctx, argv), shebangs, *.js in cwd, ./ paths, /bin.\n- 05 — Modules and import <05-modules-and-imports.md> — Why ESM does not apply to in-image scripts; bundling and alternatives.\n- 06 — Extending /bin (coreutils) <06-extending-bin-coreutils.md> — commands.mjs, build.mjs, preamble, man pages.\n- 07 — Apps beyond the shell <07-apps-beyond-the-shell.md> — What an “app” means here; initd, cron, git, custom kernels (overview).\n- 08 — Testing and debugging <08-testing-and-debugging.md> — npm test, Brittle, Pear dev, common failure modes.\n- 09 — Security and trust <09-security-and-trust.md> — System vs personal drive; eval boundaries.\n- 10 — Glossary and FAQ <10-glossary-and-faq.md> — Quick definitions; frequent questions.\n- 11 — Kernel + Pear cookbook <11-kernel-pear-cookbook.md> — Boot allowlist, timers, socket IPC, vfs.watch, HDMS hooks, Git-in-Pear, release metadata.\n- 12 — Bare modules and Pear ecosystem <12-bare-modules-and-pear-ecosystem.md> — ctx.bare, manifest, drive bundles, Holepunch bare-* mirror vs guaranteed keys.\n- 13 — Privacy, telemetry, and PII <13-privacy-telemetry-pii.md> — Scrub lists for NDJSON / OTel mirrors; non-secret posture.\n- Node → Bare module map <node-to-bare-modules.md> — Guest-safe replacements for *node: built-ins (bare-crypto, bare-module**, …).\n- bare-boot vs kernel phases <bare-boot-kernel-phase-alignment.md> — Conceptual map: Holepunch bare-boot stages vs stock kernel/init.js.\n- Kernel program (governed expansion) <kernel-program.md> — Governance, boot hooks, /proc/bare_os/kernel_program.json, Bare stack pointers, 200-item roadmap batches.\n- Naming conventions <naming-conventions.md> — First-party vs vendored trees, ctx / env / proc naming.\n- Naming migrations <naming-migrations.md> — Legacy aliases and deprecation windows for boot hooks and policy keys.\n- Architecture decision records (ADRs) <adr/README.md> — Contract decisions and templates.\n- Kernel doctor / kernel-explain conventions <kernel-explain-and-doctor-conventions.md> — Structured diagnostic output.\n\nRELATED DOCS\n\n- Handbook home <../handbook/README.md>\n- User manual <../users-manual/README.md>\n- Chapter 4 — Booter runtime <../handbook/04-the-booter-runtime.md>\n- Chapter 6 — Kernel and binaries <../handbook/06-kernel-and-binaries.md>\n- Chapter 7 — Operations and development <../handbook/07-operations-and-development.md>\n- Chapter 9 — POSIX utilities and shell <../handbook/09-posix-utilities-shell-and-vfs.md>\n- Chapter 11 — Kernel + Pear cookbook <11-kernel-pear-cookbook.md>\n- Chapter 12 — Bare modules and Pear ecosystem <12-bare-modules-and-pear-ecosystem.md>\n- bare-os-coreutils README <../packages/bare-os-coreutils/README.md>\n- bare-os-booter README <../packages/bare-os-booter/README.md>\n\n_License: Apache-2.0 — see LICENSE <../LICENSE>._","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","bare","os","index","and","reading","order"],"seeAlso":[{"name":"devguide-01-two-runtimes-host-vs-image","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/README.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","aliases":["developer-guide","devguide"],"listCategory":"devguide"},{"name":"devguide-01-two-runtimes-host-vs-image","section":7,"title":"Chapter 1 — Two runtimes: host (Pear/Node) vs in-image (AsyncFunction)","synopsis":["man 7 devguide-01-two-runtimes-host-vs-image","Developer guide chapter (developer-guide/01-two-runtimes-host-vs-image.md)"],"description":"CHAPTER 1 — TWO RUNTIMES: HOST (PEAR/NODE) VS IN-IMAGE (ASYNCFUNCTION)\n\nIf you only remember one thing from this guide, remember this: Bare OS runs two different kinds of JavaScript, and they follow different rules.\n\nTHE CONFUSION IN ONE SENTENCE\n\nYou might paste a file into your home directory on the personal Hyperdrive that starts with import fs from 'node:fs' and expect it to run like a Node script. It will not. That file is loaded as a string and executed with the JavaScript AsyncFunction constructor—not as an ES module. There is no module graph, no import resolution, and no automatic node_modules on the drive.\n\nThe booter and seeder Pear packages, by contrast, are normal ESM projects: they use import, npm dependencies, and Pear bundling. They run on the host and _host_ the environment that evaluates in-image code.\n\nWhen the bare-os npm module is available on that host, the booter may attach a read-only ctx.bareOsHostStats snapshot (loadavg, cpus, networkInterfaces, …)—still not a general “run Node in the image” escape hatch; see Chapter 2 <02-the-context-object.md>.\n\nMENTAL MODEL: WHO LOADS WHOM\n\n- Host code lives under packages/bare-os-booter/, packages/bare-os-seeder/, etc. It is trusted in the sense that you built or installed it; it opens Corestore, Hyperswarm, Hyperdrive, and constructs ctx.\n- In-image code is bytes on a drive (/boot/init.js, /bin/cat, ~/mytool.js). The booter reads those bytes as UTF-8 strings and passes them to new AsyncFunction(...) (see kernel-runner.js <../packages/bare-os-booter/lib/kernel-runner.js>).\n\nIN-IMAGE EXECUTION (THE ASYNCFUNCTION CONTRACT)\n\nTwo entry shapes matter:\n\n- async function start(ctx) — /boot/init.js on the system drive — ctx — runKernelFromSource wraps the source and calls start(ctx)\n- async function run(ctx, argv) (optional for user scripts) — /bin/ always; or a .js file resolved from the shell — ctx, argv (string array) — runScriptFromSource runs the file body, then awaits run(ctx, argv) if defined\n\nThe booter injects ctx and argv. Kernel start is required; for shell scripts, top-level statements may stand alone, or you may define run like /bin utilities. Top-level import is invalid in that evaluated string because the engine is not loading an ES module—it is compiling a function body.\n\nShebang lines (#!/usr/bin/env bare) are stripped before compile (stripShebang <../packages/bare-os-booter/lib/kernel-runner.js>) so the first token the parser sees is valid JavaScript.\n\nHOST EXECUTION (PEAR / NODE PACKAGES)\n\nWhen you edit packages/bare-os-booter/index.js, you are writing normal JavaScript for Node or Bare under Pear:\n\n- Use import Hyperdrive from 'hyperdrive'.\n- Add dependencies in package.json.\n- Use async I/O against real host APIs.\n\nWeb Encoding globals: some Bare/Pear builds do not define global TextEncoder / TextDecoder. Booter and in-image code should use b4a for UTF-8 instead (e.g. b4a.from(str, 'utf8'), b4a.toString(buf, 'utf8')), matching curl-cli.js <../packages/bare-os-booter/lib/curl-cli.js>. Relying on new TextEncoder() in booter lib/*.js can break at runtime (for example when statting or reading pseudo files under /proc or /sys).\n\nThis code creates ctx and passes it into the kernel. It does not run inside the simulated /bin environment unless you explicitly call runBinCommand(ctx, argv) with the same ctx the shell uses.\n\nTRUST: SYSTEM DRIVE VS PERSONAL DRIVE\n\n- The system drive is the replicated OS image: /boot, /bin, /etc, /share. You should treat its contents as integrity-checked by replication from peers you chose to trust (same discovery key / topic as the rest of the project).\n- The personal drive holds $HOME, /.bare, user files, crontab, etc. It is writable by the session. User scripts you write live here by default.\n\nA script you place in ~/exploit.js is your code; the booter will still AsyncFunction-evaluate it with full ctx power. That is convenient and dangerous—see Chapter 9 <09-security-and-trust.md>.\n\nHOST SOURCE POLICY (BARE-FIRST)\n\nPear-bundled booter and seeder runtime sources under packages/bare-os-booter/lib/ and packages/bare-os-seeder/lib/ must stay resolvable on Bare as well as Node: CI runs scripts/verify-pear-no-static-node-import.mjs <../scripts/verify-pear-no-static-node-import.mjs>, which rejects from 'node:…' imports, require('node:…'), and import('node:…') in those trees (with path-based exceptions). Use #host-fs, #host-path, and #host-fs-promises from package imports instead of bare fs / path specifiers. The only deliberate node:module usage today lives in bare-os-boot-manifest-sig.node.js (Node default entry for boot manifest verification); the bare export uses bare-os-boot-manifest-sig.bare.js. For guest-visible behavior, prefer Holepunch *bare-** modules per Node → Bare module map <node-to-bare-modules.md>.\n\nWHEN TO USE WHICH RUNTIME\n\n- Add a new /bin command shipped with the OS image — In-image pattern: coreutils src/*.js + build (Chapter 6)\n- One-off automation in your home directory — In-image script (top-level and/or optional run); no import (Chapters 4–5)\n- Change how networking, HDMS, or the REPL works — Host booter package (ESM)\n- Publish or replicate the system image — Host seeder package\n\nSEE ALSO\n\n- Chapter 2 — The context object <02-the-context-object.md>\n- Handbook — Booter runtime <../handbook/04-the-booter-runtime.md>\n- Handbook — Kernel and binaries <../handbook/06-kernel-and-binaries.md>\n\n← Developer guide home <README.md> · Context object → <02-the-context-object.md>","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","01","two","runtimes","host","vs","image","chapter","pear","node"],"seeAlso":[{"name":"devguide-02-the-context-object","section":7},{"name":"bare-os-developer-guide","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/01-two-runtimes-host-vs-image.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-02-the-context-object","section":7,"title":"Chapter 2 — The context object (ctx)","synopsis":["man 7 devguide-02-the-context-object","Developer guide chapter (developer-guide/02-the-context-object.md)"],"description":"CHAPTER 2 — THE CONTEXT OBJECT (CTX)\n\nEvery in-image entrypoint—start(ctx) for the kernel or run(ctx, argv) for commands—receives a single ctx object assembled by the booter before runKernelFromSource or runScriptFromSource runs. This chapter maps the fields you can rely on, how they behave, and where they are defined in source.\n\nAuthoritative construction happens in packages/bare-os-booter/index.js <../packages/bare-os-booter/index.js> inside executeKernel, then a few fields are replaced or augmented when the REPL session is created (readLine, console, execLine, writeScreen).\n\nON THIS PAGE\n\n- Design goal <#design-goal>\n- Stable fields (typical session) <#stable-fields-typical-session>\n- Fields introduced during command execution <#fields-introduced-during-command-execution>\n- What is not on ctx <#what-is-not-on-ctx>\n- Minimal patterns <#minimal-patterns>\n\nDESIGN GOAL\n\nctx is the narrow interface between:\n\n- the host (Hyperdrive handles, swarm, identity, stdio adapters), and\n- unprivileged-looking session code (kernel loop, /bin utilities, user scripts).\n\nIt is intentionally not a full Node process object. Think of it as the “syscall table” for Bare OS userland.\n\n!ctx capability wiring <../docs/images/ctx-hierarchy.png>\n\nCanonical booter boot steps before the kernel runs: vfs → ctx → repl → initd → kernel_invoke — see KERNEL_CONTRACT <../docs/architecture/KERNEL_CONTRACT.md> and bare-boot-kernel-phase-alignment <bare-boot-kernel-phase-alignment.md>.\n\nSTABLE FIELDS (TYPICAL SESSION)\n\nThe following are set on ctx before the kernel starts (unless noted as overwritten later):\n\n- bareOsCtxApiVersion — String semver for the documented ctx contract (e.g. 1.10.0). Bump in bare-os-ctx-api.js <../packages/bare-os-booter/lib/bare-os-ctx-api.js> when you make breaking changes to stable fields.\n- bareOsRuntimeCaps — Frozen snapshot from bare-os-runtime-caps.js <../packages/bare-os-booter/lib/bare-os-runtime-caps.js>: ctxApiVersion, simulated pipeline limits, pseudoFsPaths, and features (including jobControl, shellHereString, bootReadyPseudoFs, bootEventSubscribe, kernelEventSubscribe, keyBrokerHandleSketch, vfsChown, auditLog, initdRequiresWants, seederRpcExtended, bareCtxModules, bareDriveBundles, …).\n- bareOsPublishBootReady(patch) — Kernel-only: merge patch into the session boot-ready state exposed as /run/bare-os/boot.json and /run/bare-os/ready. The booter pre-seeds imageDigest, pearChannel, pearRelease from host env when set (see BARE_OS_IMAGE_DIGEST, BARE_OS_PEAR_CHANNEL, BARE_OS_PEAR_RELEASE, PEAR_CHANNEL).\n- bareOsSessionStats — Mutable { execLineCount, pipelineBytesTotal } mirrored in /proc/bare_os_session_stats.\n- bareOsBootStartedMs — Epoch milliseconds when the booter started building the session (used for synthetic /proc/uptime).\n- bareOsSkipRepl — true when BARE_OS_SKIP_REPL=1 (non-interactive stdin); kernels may shorten banners.\n- bareOsAdvertisedKernelCapabilityWords / bareOsSeedKernelCapabilityWords — Frozen maps of eleven uint32 masks (wire v2 semantic keys: primary, extendedSeedingPlatform, … hypercorePackHrpcLifecycle). Advertised values reflect stock masks minus env-disabled bits (e.g. crypto urandom); seed map mirrors last bare_os.capabilities handshake when present, else null. Always mask with >>> 0 when testing bits.\n- bareOsReadDelegateFairnessSnapshot() — Returns delegate inflight counts and per-minute rate-bucket sample (same data folded into /proc/bare_os/metrics_live.json schema 2).\n- bareOsReadSubprocessBridgeJobs() — Parses host BARE_OS_SUBPROCESS_BRIDGE_JOBS_JSON when the bridge is wired (hint-only; guest does not spawn).\n- bareOsReadSubprocessBridgeSnapshot() — Schema 2 object: jobs plus meta from BARE_OS_SUBPROCESS_BRIDGE_META_JSON (supportedSignals, cgroupRootHint, exitReasonCodes). Host BARE_OS_BARE_SUBPROCESS_BRIDGE / BARE_OS_BARE_SUBPROCESS_TIMEOUT_MS affect kernel-runner defaults for runBin when the bridge is enabled.\n- bareOsReadSnapshotHintsJson() — Same object as /proc/bare_os/snapshot_hints.json (seed RPC + optional bareOsSnapshotHandles on the interactive ctx), without a VFS read.\n- bareOsListMirrorMounts() — Lists /mirror/auxN paths for disk.auxiliaryDrives (read-only); aligns with /proc/mounts mirror rows for mirror-drive style workflows.\n- bareOsIsCtxMethodAllowed(name) — Boot policy v4: when BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS is set, returns whether name is in the allow list (kernels should call before sensitive ctx use).\n- bareOsEmitIpcAudit(ev) — When BARE_OS_IPC_AUDIT=1, appends a JSON line to audit.log (e.g. from mkfifo).\n- bareOsSystemRevision — Frozen { currentId, pendingId, slot } from host env (*BARE_OS_SYSTEM_REVISION_**) for Pear-style OTA hints.\n- bareOsRegisterSuspendHook / bareOsRegisterResumeHook — Register callbacks; bareOsInvokeSuspendHooks / bareOsInvokeResumeHooks run them (host may call around Bare.suspend / Bare.wakeup). The booter also registers bare-initd so units with stop/start paths run in reverse boot order on suspend and forward boot order on resume, aligned with the initd DAG.\n- bareOsRequestKernelReload() — Throws BARE_OS_KERNEL_RELOAD when BARE_OS_KERNEL_HOT_RELOAD=1 so the booter re-reads /boot/init.js.\n- bareOsRequestKernelProfileReload() — Throws BARE_OS_KERNEL_PROFILE_RELOAD when BARE_OS_KERNEL_PROFILE_WARM=1 (same booter loop as hot reload).\n- bareOsRunImageScript(path) — async — runs trusted JS from the system image; paths must be under /lib/bare-os/extensions/ (used by kernel.ext.d).\n- disk — Disk bundle used during boot (includes drives and helpers); advanced use\n- drive — System Hyperdrive (ctx.drive is the OS image: /bin, /boot, …)\n- personalDrive — Personal Hyperdrive (mutable per-user state; VFS maps $HOME to /.bare-os/home/<HOME-basename>/… and session /var/log to /.bare-os/var/log/<basename>/… so guest vs unlocked trees do not share the same keys)\n- vfs — Path layer: resolves logical paths, routes to system vs personal drive, implements mkdir, readFile, etc. See vfs.js <../packages/bare-os-booter/lib/vfs.js>\n- env — Shell environment object (HOME, PATH, USER, …), same object as vfs.env. Mutated by builtins (export, cd updates PWD, identity unlock updates user fields). After each execLine, BARE_OS_EXIT_STATUS holds the last command’s exit code as a decimal string (POSIX $? parity); use $? or ${?} in shell words for expansion.\n- b4a — b4a module (byte helpers); used to convert Hyperdrive buffers to strings\n- bare _(optional)_ — Frozen map of host-loaded (and optionally drive-bundled) npm modules for in-image use (ctx.bare.b4a, ctx.bare.protomux, …). Absent when BARE_OS_BARE_MODULES=0. See bare-module-manifest.json <../packages/bare-os-booter/lib/bare-module-manifest.json> and Chapter 12 <12-bare-modules-and-pear-ecosystem.md>.\n- topic — Topic key helper from protocol package (rarely needed in user scripts)\n- console — Initially the raw global; replaced with session-bound log/error that respect the REPL and fish-style UI\n- readLine — Placeholder async function; replaced with session readLine(prompt) that reads a line from stdin (or returns null when session ends)\n- writeScreen — REPL helper for screen-oriented output; starts as no-op, then wired\n- runHdms(argv) — Entry for hdms CLI when HDMS controller is active\n- onIdentityUnlocked / onIdentityGuest — Hooks for HDMS lifecycle (bootstrap nodes, teardown)\n- requestBooterExit(code) — Ends the session from /bin/exit or equivalent\n- applyUnlock / applyRegister / applyLogin / applyLogout / saveVault — Identity and vault operations used by login, logout, savevault\n- shellAliases — Populated when the shell loads default or ~/.barerc aliases\n- bareOsApplyTheme() / bareOsListThemes() — Re-apply BARE_OS_THEME / LS_COLORS / BARE_OS_DIRCOLORS to vfs.env (including BARE_OS_COLOR_DEPTH downgrades for *BARE_OS_COLOR_). Used by /bin/theme** and documented for custom tooling (see bare-os-theme-presets.js <../packages/bare-os-booter/lib/bare-os-theme-presets.js>).\n- runBinCommand(argv) — Runs a command with the same resolution rules as the interactive shell (used by time, xargs, and similar)\n- registerKernelShutdownHook(fn) — Register an async or sync function to run when the REPL session ends, before stopBareInitd and initd disposers. Pair with registerBareInitdDisposer(fn) in bare-initd.js <../packages/bare-os-booter/lib/bare-initd.js> when you need teardown after shutdown hooks but still inside stopBareInitd (intervals, sync cleanup).\n- bareOsSubscribeBootEvent(fn) / bareOsEmitBootEvent(ev) — Subscribe to or emit structured boot lifecycle events (same shape as BARE_OS_BOOT_TRACE=ndjson records). Phase records carry lifecycleSchemaVersion: 3 alongside telemetrySchemaVersion where applicable (see kernel extensions <../docs/reference/kernel-extensions.md>).\n- bareOsSubscribeKernelEvent(fn) / bareOsEmitKernelEvent(ev) — Namespaced kernel event bus (e.g. topic: 'boot.phase', bootStage); also mirrored to diagnostics subscribers with source: 'kernel'.\n- bareOsAcquireKeyHandle(hint?) — Key-broker sketch returning an opaque handle string (no raw key material in guest).\n- bareOsSubscribeHdmsLifecycle(fn) — After HDMS activate / before deactivate, run callbacks with { kind, labels? }.\n- bareOsAwaitInitdUnits(names, timeoutMs) — Resolves when all listed initd units are active (polls getBareServiceRuntime); returns false on timeout.\n- bareOsGetResourceStatus() — Returns a plain object snapshot (pipeline limits, exec depth, IPC stats(), session counters, swarm peer count)—mirrors /proc/bare_os_resources. Session may include execLineWallMsTotal.\n- bareOsReadProcMetricsLive() — Returns the same object as reading /proc/bare_os/metrics_live.json (coalesced; interval from BARE_OS_PROC_POLL_MS).\n- bareOsRegisterVirtualFile(name, reader, opts?) — Registers /run/bare-os/virtual/<name> content; reader may be a function or { read }; may return string or Uint8Array (sync or async). Optional opts: etag, mime (default text/plain), ttlMs (optional cache hint). Gated by runtime cap virtualRegisterFiles.\n- bareOsSandboxRunScript(source, argv?, opts?) — Runs script source with a restricted ctx (personal-drive writes only; identity/virtual registration disabled). Respects raceWithAbortAndTimeout opts. Disable with BARE_OS_SANDBOX_SCRIPT=0. See Chapter 9 <09-security-and-trust.md>.\n- bareOsBootFileSha256Hex(buf) — sha256 hex for boot manifest checks (BARE_OS_BOOT_MANIFEST + /etc/bare-os/boot.manifest.json on the stock kernel).\n- bareOsRegisterBootStepHook(step, fn) / bareOsInvokeBootStepHooks(ev) — Canonical boot hooks around stock kernel/init.js stages; ev includes step / legacy phase, when (before / after), label. The step key may be * or before:rc style. Legacy bareOsRegisterBootPhaseHook / bareOsInvokeBootPhaseHooks remain aliases.\n- bareOsInvalidateVirtualFile(name) / bareOsUpdateVirtualFileMeta(name, patch) — Virtual files under /run/bare-os/virtual/; patch may update etag / version.\n- bareOsRequestPearReload(opts?) — async — returns { requested, hint, env }; with { persistRequest: true } writes ~/.bare-os/pear-reload.request and may process.emit('bare-os:pear-reload', …) on Node.\n- bareOsVerifyBootManifestSignature(manifestBytes, signatureBytes, publicKeyHex?) — Ed25519 verify helper used when BARE_OS_BOOT_MANIFEST_SIGN=1; public key from arg or BARE_OS_BOOT_MANIFEST_PUBKEY_HEX.\n- bareOsRequestMirror(opts?) / bareOsExportPersonalSnapshot(opts?) — async host bridges returning { ok, hint }; on Node emit bare-os:mirror-request / bare-os:export-personal-snapshot.\n- bareOsPearIpcEmit(channel, payload) — boolean — forwards structured payload to the host when registered (bare-os:pear-ipc on Node). Align channel names with your pear-ipc <https://github.com/holepunchto/pear-ipc> consumer.\n- bareOsPearIpcRequest(channel, payload, opts?) — Promise<unknown> — correlates bareOsIpcReqId on payload; host must process.emit('bare-os:pear-ipc-response', { bareOsIpcReqId, result?, error? }) before opts.timeoutMs (default 30s).\n- bareOsEmitMirrorDriveHint(opts?) — Emits bare-os:mirror-drive-hint on the host with label, key, ts (mirror-drive–style operator hint).\n- bareOsRegisterKernelExtensionRecord(rec) — Appends { dropin, script } for /proc/bare_os/extensions.json when the stock kernel loads kernel.ext.d scripts.\n- bareOsDiagnosticsSubscribe(fn) / bareOsDiagnosticsEmit(ev) — When BARE_OS_DIAGNOSTICS_SUBSCRIBE=1, subscribe to structured booter/kernel diagnostics events (dev-oriented).\n- bareOsHostStats _(optional)_ — When the bare-os npm module loads on the host, a frozen snapshot: hostname, loadavg, cpus, networkInterfaces, optional memoryUsage, peerCount (swarm peers during session build), atMs.\n- httpFetch _(optional)_ — When the booter can build a policy-wrapped fetch, it sets this field; delegated curl / wget prefer resolveBareOsFetchFn, which uses ctx.httpFetch first, then ctx.bare.fetch (including /lib/bare/bundles merge, with .default unwrap), then globalThis.fetch. On hosts without native fetch, ensureBareFetchGlobals may install bare-fetch or bare-https. Optional HTTP allow/deny (BARE_OS_HTTP_ALLOWLIST, BARE_OS_HTTP_DENYLIST) and audit hooks when BARE_OS_AUDIT is on. See HTTP: curl and wget <../docs/reference/http-curl-and-wget.md>.\n\nKernel boot composition lives on the system image (/boot/init.js, /etc/bare-os/rc, /etc/bare-os/rc.d/, optional /etc/bare-os/rc.local, optional /etc/bare-os/kernel.d/ (same digit-prefix rules as rc.d), optional /etc/bare-os/profile / *rc.profile., /etc/bare-os/onboot), not on ctx—extend the image or hooks like registerKernelShutdownHook rather than adding boot fields to the context object. The booter seeds ctx.env from the host for BARE_OS_PIPELINE_, BARE_OS_SHELL_STREAMING, BARE_OS_SHELL_STREAMING_MULT, BARE_OS_SHELL_CMDSUBST, BARE_OS_SHELL_CMDSUBST_MAX_BYTES, boot profile / audit / IPC / HTTP policy keys (BARE_OS_IPC_CHANNEL_MAX_BYTES, …), BARE_OS_VFS_WATCH, BARE_OS_VFS_UNION_PREFIXES, BARE_OS_VFS_UNION_WRITE_DENY, BARE_OS_VFS_BIN_CACHE, BARE_OS_IMAGE_DIGEST, Pear channel fields, BARE_OS_BOOT_MANIFEST, BARE_OS_BOOT_MANIFEST_SIGN, BARE_OS_BOOT_MANIFEST_PUBKEY_HEX, BARE_OS_BOOT_POLICY, BARE_OS_SANDBOX_SCRIPT, BARE_OS_SANDBOX_WORKER, BARE_OS_INITD_MAX_PARALLEL, BARE_OS_INITD_JOURNAL_MAX_LINES, BARE_OS_URANDOM_CRYPTO, BARE_OS_TELEMETRY_NDJSON, BARE_OS_SEED_RPC_HANDSHAKE, BARE_OS_SEED_CAP_STRICT, BARE_OS_SEED_CAP_FAIL, BARE_OS_BLIND_BOOTSTRAP_URL, BARE_OS_BLIND_BOOTSTRAP_JSON, BARE_OS_MIRROR_READ_KEY, BARE_OS_FIND_EXEC_MAX, BARE_OS_YES_MAX_LINES, BARE_OS_SHUF_MAX_LINES, BARE_OS_SPLIT_MAX_FILES, BARE_OS_NPROC, TERM, COLORTERM, PEAR_CHANNEL, and the rest of the passthrough table in environment appendix §14 <../docs/reference/environment-and-posix-appendix.md#14-environment-variables-complete-list>; always sets BARE_OS_BOOT_PROFILE_RESOLVED and BARE_OS_SESSION_ID. When ctx.httpFetch handles curl, check optional init.bareOsCurlTls (insecure, caPem, pinnedSha256) for --cacert / -k* semantics.\n\nAfter createVfs <../packages/bare-os-booter/lib/vfs.js>, ctx.vfs.watch(logicalPath) returns a Hyperdrive watcher when BARE_OS_VFS_WATCH is not disabled. With BARE_OS_VFS_WATCH_PSEUDO=1, vfs.watch may also poll coalesced /proc/bare_os/metrics_live.json (interval from BARE_OS_PROC_POLL_MS). ctx.bareOsIpc exposes FIFO push/take (optional per-channel byte caps from BARE_OS_IPC_CHANNEL_MAX_BYTES), optional JSON-RPC pushJson/takeJson (max line size, optional RPC token), fanoutPublish/fanoutSubscribe, createDuplexBridge, duplexJsonRoundTrip (one JSON request / one JSON reply over a duplex side — useful for unit-to-unit or guest–helper protocols without pulling bare-rpc into /bin), assignProcessGroup/signalProcessGroup (synthetic setpgid/killpg analog for IPC routing), and stats (see bare-os-ipc.js <../packages/bare-os-booter/lib/bare-os-ipc.js>).\n\nWhen BARE_OS_KERNEL_EXT_D_HOT_RELOAD=1, the stock kernel may define ctx.bareOsReloadKernelExtDropinsSafe() to append-only load new kernel.ext.d scripts after boot (see handbook ch.6 <../handbook/06-kernel-and-binaries.md>).\n\nInitd / long-running services: prefer duplexJsonRoundTrip or pushJson/takeJson for structured messages with byte limits already enforced by IPC options. A dedicated bare-rpc dependency is optional on the host or in ctx.bare if you need richer framing; the stock image documents the FIFO-level building blocks only.\n\nAfter createKernelReplSession <../packages/bare-os-booter/lib/repl-session.js> returns:\n\n- ctx.execLine(line, opts?) runs a full shell line (tokenize, builtins, pipelines, /bin resolution). Optional opts: { signal?: AbortSignal, timeoutMs?: number } (deadline for the shell pipeline work).\n- ctx.readLine(prompt, opts?) prompts and reads user input; same optional opts for abort/timeout.\n- ctx.runBinCommand(argv, opts?) passes through abort/timeout to the delegated command runner.\n- ctx.vfs.readFile(path, opts?) and ctx.vfs.writeFile(path, buf, opts?) accept signal/timeoutMs in opts (writeFile merges with executable).\n- ctx.console is session-scoped.\n\n/run/bare-os/boot.json (via bareOsPublishBootReady) may include booterStages / legacy booterPhases: booter milestones (vfs, ctx, repl, initd, kernel_invoke) in addition to kernel stages / legacy phases from the stock kernel/init.js <../kernel/init.js>. subsystems.kernel.bootStages (and legacy bootPhases) list { label, bootStage } for each completed kernel boot stage, and subsystems.kernel.programProc may include schema: 2, programVersion: 2, bootDryRun.\n\nFIELDS INTRODUCED DURING COMMAND EXECUTION\n\nWhen the shell runs an external command (or a pipeline stage), it may pass a shallow clone of ctx with extra fields:\n\n- shellStdin — String body for simulated stdin (pipelines and < redirection)\n- bareOsStdoutCaptured — true when this command’s stdout is captured into the simulated pipe or a > / >> redirect (see bareOsPipelineChildCtx in shell.js <../packages/bare-os-booter/lib/shell.js>). ls uses this to print one name per line, matching common GNU behavior for non-terminal output.\n- exitCode — Utilities set ctx.exitCode for conditions (test, grep, …); the shell uses it for &&, logical OR lists, and ; sequencing (see shell.js <../packages/bare-os-booter/lib/shell.js>)\n\nAlways use the ctx passed into run, not a global, so pipeline stdin works.\n\nWHAT IS _NOT_ ON CTX\n\n- No require, no import helper—the in-image script is not a CommonJS or ESM module.\n- No automatic fetch guarantee—depends on host/Pear globals; do not rely on it for portable /bin utilities.\n- process may exist on Bare/Node hosts but do not depend on it for utilities meant to run identically under Pear; use ctx.console and ctx.env.\n- bare-initd control is not a ctx method: use /bin/systemctl (or journalctl; bare-initctl is a legacy alias), which the booter handles via delegation—same pattern as git / curl.\n\nMINIMAL PATTERNS\n\nLog a message\n\n async function run(ctx, argv) {\n ctx.console.log('argv:', argv.join(' '))\n }\n\nRead a file via VFS\n\n async function run(ctx, argv) {\n const buf = await ctx.vfs.readFile(argv[1] || 'README.md')\n if (!buf) {\n ctx.console.error('missing file')\n return\n }\n ctx.console.log(ctx.b4a.toString(buf))\n }\n\nRun another command programmatically\n\n async function run(ctx, argv) {\n await ctx.runBinCommand(['ls', '-la', ctx.env.HOME || '.'])\n }\n\nSelective /lib/bare warm-cache drop after manifest edits\n\nWhen an operator writes a new bare-module-manifest.json payload (same bytes as would be stored on the system drive), evict only the bundled ctxKey rows instead of flushing all of /bin + /lib/bare:\n\n async function run(ctx, argv) {\n const manifestBuf = await ctx.vfs.readFile('/lib/bare/bare-module-manifest.json')\n if (manifestBuf && typeof ctx.bareOsInvalidateWarmReadCachesFromBareManifestJson === 'function') {\n ctx.bareOsInvalidateWarmReadCachesFromBareManifestJson(manifestBuf)\n }\n }\n\nOn Pear, ctx.bare is populated from the booter’s embedded bare-module-manifest.data.mjs, not from readFile of pear://… paths. Updating /lib/bare/bare-module-manifest.json on the system drive still affects VFS warm-cache eviction for */lib/bare/bundles/ via the helpers above, but operators must re-stage the booter after npm run sync:bare-manifest to change which packages the Pear host import()**s. See Chapter 12 — Bare modules <12-bare-modules-and-pear-ecosystem.md> and PEAR-RUN.md <../PEAR-RUN.md>.\n\nRead the Protomux extension registry mirror (when BARE_OS_PROC_PROTOMUX_EXTENSIONS_REGISTRY is enabled on the booter):\n\n async function run(ctx) {\n if (typeof ctx.bareOsReadProtomuxExtensionsJson !== 'function') return\n const reg = ctx.bareOsReadProtomuxExtensionsJson()\n ctx.console.log(JSON.stringify(reg, null, 2))\n }\n\nSEE ALSO\n\n- Chapter 3 — Kernel <03-kernel-boot-init.md>\n- Chapter 4 — User scripts <04-user-scripts-and-path.md>\n- Handbook — Identity and vault <../handbook/05-identity-vault-and-hdms.md>\n\n← Two runtimes <01-two-runtimes-host-vs-image.md> · Kernel → <03-kernel-boot-init.md>","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","02","the","context","object","chapter"],"seeAlso":[{"name":"devguide-03-kernel-boot-init","section":7},{"name":"devguide-01-two-runtimes-host-vs-image","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/02-the-context-object.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-03-kernel-boot-init","section":7,"title":"Chapter 3 — Kernel: /boot/init.js and start(ctx)","synopsis":["man 7 devguide-03-kernel-boot-init","Developer guide chapter (developer-guide/03-kernel-boot-init.md)"],"description":"CHAPTER 3 — KERNEL: /BOOT/INIT.JS AND START(CTX)\n\nThe kernel in Bare OS is not a microkernel and not a scheduler. It is a JavaScript file on the system Hyperdrive at /boot/init.js, loaded as UTF-8 text and executed with runKernelFromSource in kernel-runner.js <../packages/bare-os-booter/lib/kernel-runner.js>. The booter expects a top-level:\n\n async function start(ctx) {\n // ...\n }\n\nThere is no argv at the kernel layer—the session’s command line is whatever the interactive user types after boot, handled through ctx.readLine and ctx.execLine.\n\nSource of truth: The file committed as kernel/init.js <../kernel/init.js> is the concatenation of sorted kernel/lib/boot/ <../kernel/lib/boot/> fragments and kernel/lib/init/init-main.js <../kernel/lib/init/init-main.js>. Run npm run bundle:kernel after edits; use npm run verify:init-bundle or full pretest to confirm the bundle matches. Never edit init.js directly—changes would be overwritten and CI will fail.\n\nWHAT THE STOCK KERNEL DOES\n\nThe repository’s default kernel (kernel/init.js <../kernel/init.js>, generated as above) is intentionally small:\n\n1. Print /etc/os-release and optional /etc/motd (errors logged, not fatal).\n2. Optional profile snippet /etc/bare-os/rc.profile.<name> when BARE_OS_BOOT_PROFILE or the first line of /etc/bare-os/profile names a safe profile string.\n3. Run /etc/bare-os/rc, then sorted digit-prefixed */etc/bare-os/rc.d/, then optional /etc/bare-os/rc.local, then sorted digit-prefixed /etc/bare-os/kernel.d/ (same naming rules as rc.d), then optional /etc/bare-os/kernel.ext.d/.json** extension lists (see Handbook ch.6 <../handbook/06-kernel-and-binaries.md>).\n4. Print session banner (from /etc/bare-os/banner, /etc/issue, or a built-in hint).\n5. If ctx.bareOsSkipRepl: run every non-empty, non-# line from BARE_OS_ONBOOT (newline-separated), or if that env is unset, the same from /etc/bare-os/onboot in file order, via execLine; then fall through to the loop (where readLine returns null immediately).\n6. Loop forever:\n- line = await ctx.readLine('')\n- If line == null, break (session end / EOF).\n- Skip empty lines.\n- status = await ctx.execLine(line) inside try/catch (console.error on failure).\n- If status === 'exit', break.\n\nSet BARE_OS_BOOT_TRACE=1 (or true) in the environment to log boot phase timings on stderr as [boot] phase: Nms. Use BARE_OS_BOOT_TRACE=json for one JSON object per phase ({\"phase\":\"…\",\"ms\":n}) on stderr. The same phases are also delivered to ctx.bareOsSubscribeBootEvent subscribers as NDJSON-shaped objects.\n\nBARE_OS_BOOT_PERF_DETAIL=1 collects per-stage wallMs and optional bare-hrtime monotonicNs samples into /run/bare-os/boot-perf.json (schema 2 when stages are present). BARE_OS_KERNEL_EXT_GRAPH=1 writes /run/bare-os/kernel-ext-graph.json after kernel.ext.d ordering (and probes whether bare-module-traverse can be imported on the host).\n\nKernel program boot hooks (see kernel-program.md <./kernel-program.md>): BARE_OS_BOOT_SAFE_MODE skips rc.d, kernel.ext.d, and onboot; BARE_OS_BOOT_TRANSACTION_JOURNAL appends phase NDJSON to /run/bare-os/boot-transaction.ndjson (each line includes a bootStage); BARE_OS_BOOT_CHECKPOINT refreshes /run/bare-os/boot-checkpoint.json after each phase (schema 2 adds bootStage). BARE_OS_BOOT_DRY_RUN skips trusted execLine and extension scripts; BARE_OS_BOOT_POLICY_PATH / policyFallbackPaths tier policy files; rollback marker + BARE_OS_BOOT_ROLLBACK_APPLY; kernel.d snippets may start with # ConditionEnvironment=KEY=VAL comment guards; bareOsPublishBootReady includes subsystems.kernel.bootPhases with bootStage labels. Extension drop-ins may use requires, after, and before for ordering alongside dependsOn. The booter emits additional *booter: phases (vfs, ctx, repl, initd, kernel_invoke) and records them under booterPhases in /run/bare-os/boot.json. BARE_OS_BOOT_ALLOWLIST=1 with /etc/bare-os/boot.allow restricts the first token of lines in trusted rc/onboot snippets. Inspect ctx.bareOsRuntimeCaps for pipeline limits, quotas, pseudo paths, and features (including httpDelegate, gitDelegate, systemctlDelegate, vfsWatch, ipcFanout**).\n\nBoot policy v5 (optional /etc/bare-os/boot.policy.json fields when BARE_OS_BOOT_POLICY=1): requireKernelCapabilitiesHostTransportDelegates and requireInitJsSha256 (64-char lowercase hex of raw /boot/init.js via ctx.bareOsBootFileSha256Hex). BARE_OS_KERNEL_PROFILE_WARM=1 enables ctx.bareOsRequestKernelProfileReload() for a warm start(ctx) re-run without dropping the swarm session (same machinery as hot reload).\n\nOptional BARE_OS_KERNEL_SELFTEST=1 runs built-in checks after boot snippets. Set BARE_OS_SELFTEST_FORMAT=tap for TAP on ctx.console.error (session stderr, not the host’s raw globalThis.console), or junit for a single-line XML testsuite on the same sink—matching how runKernelSelftest binds the harness. You can pass { signal, timeoutMs } as a second argument to ctx.execLine, ctx.readLine, ctx.runBinCommand, and VFS readFile/writeFile for bounded waits—see Chapter 2 <02-the-context-object.md>.\n\nSo the “OS personality” is mostly the shell (execShellLine behind execLine) plus /bin.\n\nWHY READLINE USES AN EMPTY PROMPT STRING\n\nThe stock kernel passes '' as the prompt. The actual prompt rendering (fish-style or plain) is owned by the REPL session implementation in repl-session.js <../packages/bare-os-booter/lib/repl-session.js>. If you build a custom kernel, you can pass a different prompt string, but many sessions ignore it in favor of their own UI.\n\nUSING EXECLINE VS CALLING RUNBINCOMMAND DIRECTLY\n\n- await ctx.execLine('ls -la') — Full shell semantics: tokenization, aliases, builtins (cd, export, …), ; / && / logical-OR lists, pipelines, redirections, then /bin\n- await ctx.runBinCommand(['ls', '-la']) — Direct utility invocation—no shell parsing, no aliases\n\nUse execLine when you want users to type natural shell commands from your kernel loop. Use runBinCommand when you already have an argv array and want to avoid re-parsing.\n\nSESSION TERMINATION\n\n- The exit builtin (or /bin/exit) ultimately calls ctx.requestBooterExit(code), which forces readLine to return null on subsequent calls and ends the loop.\n- BARE_OS_SKIP_REPL=1 makes readLine return null immediately—useful for non-interactive smoke tests. Pair with BARE_OS_ONBOOT (one or more newline-separated lines) or /etc/bare-os/onboot so the stock kernel runs trusted execLine snippets before idle exit.\n\nCUSTOM KERNELS: PRACTICAL TIPS\n\n1. Keep the loop async—never block on synchronous host APIs that might hang the Pear app.\n2. Catch errors around execLine so a typo does not tear down the whole session unless you want that.\n3. Do not assume import—the kernel source is the same AsyncFunction model as /bin (Chapter 1).\n4. To add startup services, prefer hooks already wired in the booter (startBareInitd) or a small kernel that calls runBinCommand after banner—see Chapter 7 <07-apps-beyond-the-shell.md>.\n5. To run code when the session ends, use ctx.registerKernelShutdownHook(fn) (runs before initd disposers); see Chapter 2 — ctx <02-the-context-object.md>.\n6. After login, ~/.barerc is reloaded automatically via applyUnlockedEnv—see Handbook — Identity <../handbook/05-identity-vault-and-hdms.md>. The stock init.js does not re-print the boot banner; use onIdentityUnlocked or a custom kernel loop if you want that.\n\nREPLACING THE KERNEL IN THE IMAGE\n\nKernel text is staged from the repo’s kernel/ tree when you run the seeder (or copied into packages/bare-os-seeder/kernel/ for Pear). After editing kernel/init.js, re-seed or rebuild the vendored tree so peers receive the new /boot/init.js.\n\nSEE ALSO\n\n- Chapter 2 — ctx <02-the-context-object.md>\n- Chapter 4 — User scripts <04-user-scripts-and-path.md>\n- Handbook — Kernel and binaries <../handbook/06-kernel-and-binaries.md>\n\n← Context object <02-the-context-object.md> · User scripts → <04-user-scripts-and-path.md>","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","03","kernel","boot","init","chapter","and","start"],"seeAlso":[{"name":"devguide-04-user-scripts-and-path","section":7},{"name":"devguide-02-the-context-object","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/03-kernel-boot-init.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-04-user-scripts-and-path","section":7,"title":"Chapter 4 — User scripts and PATH resolution","synopsis":["man 7 devguide-04-user-scripts-and-path","Developer guide chapter (developer-guide/04-user-scripts-and-path.md)"],"description":"CHAPTER 4 — USER SCRIPTS AND PATH RESOLUTION\n\nThis chapter is the practical “how do I run my own .js file?” guide. Resolution logic lives in runBinCommand in kernel-runner.js <../packages/bare-os-booter/lib/kernel-runner.js>; the shell calls that function for non-builtin commands.\n\nTHE ENTRYPOINT CONTRACT (AGAIN)\n\nThe booter evaluates your file as the body of an async function with parameters ctx and argv. Top-level statements run first (like a small Node script). Optionally, define a top-level run for the same contract as /bin utilities:\n\n async function run(ctx, argv) {\n // argv[0] is conventionally the script name or command word\n }\n\nThe booter wraps the file body in:\n\n new AsyncFunction(\n 'ctx',\n 'argv',\n source + '\\nif (typeof run === \"function\") await run(ctx, argv)\\n'\n )\n\nIf run exists, it is awaited after the rest of the file. /bin commands always define run; home-directory scripts may use top-level code only (e.g. console.log(...)).\n\nRESOLUTION ORDER (SIMPLIFIED)\n\nWhen the user types a command, roughly:\n\n1. Git delegation — If the command is git (and not ./git), the booter runs the hosted git CLI instead of /bin/git bytes.\n2. Path with slash — If argv[0] contains /, treat as a path: resolve via ctx.vfs, read bytes from the routed drive, evaluate as script.\n3. Ends with .js — Resolve cmd as a logical path (e.g. foo.js in $PWD), read from VFS if found, evaluate.\n4. PATH search — For each directory in $PATH (default /bin), try unixPathResolve(dir, cmd) on the system drive only; first hit wins.\n\nImplications:\n\n- ./my.js and /home/user/my.js use VFS (personal or system as appropriate).\n- hello.js in the current directory is tried before /bin if the file exists on the routed drive.\n- ls resolves to /bin/ls on the system drive (unless shadowed by a same-named *.js in cwd—know this edge case).\n\nSHEBANG\n\nA leading line like #!/usr/bin/env bare is stripped before compilation. It is for human readers and future tooling; the booter does not exec a binary interpreter—it always uses AsyncFunction.\n\nSTDIN IN PIPELINES\n\nThe shell does not give your script a POSIX fd 0. For pipeline stages, stdin is simulated: the shell captures console.log output from the left stage as a string and passes ctx.shellStdin on a cloned ctx to the right stage. Utilities that want stdin read bareStdin(ctx) from the coreutils prelude—but user scripts on the home drive do not get that prelude unless you copy the helper into your file.\n\nMinimal stdin read in a user script:\n\n async function run(ctx, argv) {\n const stdin = typeof ctx.shellStdin === 'string' ? ctx.shellStdin : ''\n ctx.console.log('got bytes:', stdin.length)\n }\n\nENVIRONMENT AND CD\n\n- ctx.env is the same object mutated by export and cd (via vfs.chdir and PWD).\n- Paths like ~/doc are expanded by the VFS when you use vfs.readFile and friends—prefer ctx.vfs over raw drive access for user-level scripts.\n\nGIT AND SPECIAL CASES\n\n- Prefer the git command for version control; it is not the same as evaluating /bin/git as JS.\n- command -v / type use resolveBinInPath (system drive PATH only) plus builtin tables.\n\nDEBUGGING “NOT FOUND”\n\n1. unknown command: foo — Not in PATH on system drive and not a resolvable *.js / path.\n2. not found: ./foo.js — VFS could not read the path (typo, wrong drive, or missing file).\n3. Silent failure with stack in console.error — Runtime error inside run; fix the script logic.\n\nSEE ALSO\n\n- Chapter 5 — Modules <05-modules-and-imports.md>\n- Chapter 6 — Extending /bin <06-extending-bin-coreutils.md>\n- Handbook — POSIX utilities <../handbook/09-posix-utilities-shell-and-vfs.md>\n\n← Kernel <03-kernel-boot-init.md> · Modules → <05-modules-and-imports.md>","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","04","user","scripts","and","path","chapter","resolution"],"seeAlso":[{"name":"devguide-05-modules-and-imports","section":7},{"name":"devguide-03-kernel-boot-init","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/04-user-scripts-and-path.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-05-modules-and-imports","section":7,"title":"Chapter 5 — Modules, import, and packaging (the honest version)","synopsis":["man 7 devguide-05-modules-and-imports","Developer guide chapter (developer-guide/05-modules-and-imports.md)"],"description":"CHAPTER 5 — MODULES, IMPORT, AND PACKAGING (THE HONEST VERSION)\n\nThis chapter answers the most common disappointment: “Why can’t I use import in my Bare OS script?”\n\nSHORT ANSWER\n\nIn-image scripts (/boot/init.js, /bin/*, ~/tool.js) are executed as AsyncFunction bodies, not as ES modules. The JavaScript engine never runs the ESM loader for those strings. Therefore:\n\n- import x from 'y' is a syntax error in that context (top-level import is only valid in modules).\n- require is likewise unavailable unless the host injected a global (do not rely on it for portable utilities).\n\nHOW /BIN UTILITIES STILL SHARE CODE\n\nThe bare-os-coreutils build concatenates:\n\n1. lib/runtime.js (shared helpers: bareStdin, mode formatting, …)\n2. Optional preamble files (sed-engine.js, awk-engine.js, man-render.js)\n3. src/<name>.js (must contain only async function run and helpers in the same string—no import)\n\nSo “modules” become one compiled file on the drive. That is the supported pattern for shared logic in tier-1 utilities.\n\nPATTERNS THAT WORK FOR USER AND KERNEL CODE\n\n1. INLINE HELPERS\n\nFor small scripts, define functions above run:\n\n function double(n) {\n return n * 2\n }\n async function run(ctx, argv) {\n ctx.console.log(String(double(21)))\n }\n\n2. COPY-PASTE PRELUDE SNIPPETS\n\nYou may copy minimal helpers (e.g. stdin reader) from runtime.js <../packages/bare-os-coreutils/lib/runtime.js> into your script. Keep the license header in mind if you redistribute.\n\n3. LOAD ANOTHER FILE FROM THE DRIVE (ADVANCED)\n\nYou _can_ readFile a second script as a string and… you should not eval arbitrary untrusted content. For your own modules stored as ~/lib/helpers.js, a pattern is:\n\n- Store function bodies only or data (JSON), not full import syntax.\n- Or concatenate at build time on the host before uploading to Hyperdrive.\n\nThere is no built-in import() dynamic loader wired to Hyperdrive in the stock booter.\n\n4. HOST-SIDE BUNDLING\n\nIf you generate a single bundle.js on your laptop with esbuild/rollup and upload it to ~/bundle.js, that file can use no external import at runtime because everything is already bundled. This is the closest to “npm on device” without changing the booter.\n\nHOST PACKAGES (BOOTER / SEEDER): FULL ESM\n\nWhen you edit packages/bare-os-booter/index.js, you are in module land:\n\n import { runBinCommand } from './lib/kernel-runner.js'\n\nUse this for new protocols, drive encryption, alternate kernels, etc. This is not the same as writing /bin/foo.\n\nCTX.BARE — HOLEPUNCH-STYLE MODULES WITHOUT IMPORT\n\nWhen BARE_OS_BARE_MODULES is not disabled, the booter exposes ctx.bare: a frozen object whose keys are defined by bare-module-manifest.json <../packages/bare-os-booter/lib/bare-module-manifest.json>. Each entry names an npm package and a stable ctxKey (for example b4a, protomux, compactEncoding).\n\nHost resolution: the booter uses dynamic import() for each entry. Optional packages that fail to load (for example native-only modules on the wrong host) are skipped without aborting boot.\n\nDrive bundles (trusted image): the system image may include /lib/bare/manifest.json and */lib/bare/bundles/.js. Those scripts are IIFE bundles built by bare-os-bare-libs. The booter executes them with Function in the same trust class as seeded /bin utilities and copies values into ctx.bare only for keys not already set by the host. Set BARE_OS_BARE_DRIVE_BUNDLES=0** to skip this step.\n\nHardening: set BARE_OS_BARE_MODULES=0 to omit ctx.bare entirely (the property is absent on ctx). Runtime caps bareCtxModules and bareDriveBundles mirror these toggles.\n\nFull ecosystem context: Chapter 12 — Bare modules and Pear ecosystem <12-bare-modules-and-pear-ecosystem.md>.\n\nPEAR AND BARE GLOBALS\n\nUnder Pear/Bare, some globals (e.g. Bare) may exist for host exit and lifecycle. In-image utilities should still prefer ctx for I/O to stay consistent when the same script pattern is tested under different harnesses. Prefer *ctx.bare. over relying on Bare-specific package side effects when you need bare-url / bare-path** on the Pear runtime.\n\nFAQ CORNER\n\nCan I add dynamic import to the booter for user scripts?\nPossible in theory (resolve specifiers from Hyperdrive) but not implemented, and it raises security and package format questions (where do dependencies live?).\n\nCan I put node_modules on my personal drive?\nEven if you replicated bytes, the in-image loader would not resolve them as Node does. You would need a host or kernel change to load from that tree.\n\nSEE ALSO\n\n- Chapter 12 — Bare modules and Pear ecosystem <12-bare-modules-and-pear-ecosystem.md>\n- Chapter 6 — Extending /bin <06-extending-bin-coreutils.md>\n- Chapter 9 — Security <09-security-and-trust.md>\n- bare-os-coreutils README <../packages/bare-os-coreutils/README.md>\n\n← User scripts <04-user-scripts-and-path.md> · Extending /bin → <06-extending-bin-coreutils.md>","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","05","modules","and","imports","chapter","import","packaging","the","honest","version"],"seeAlso":[{"name":"devguide-06-extending-bin-coreutils","section":7},{"name":"devguide-04-user-scripts-and-path","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/05-modules-and-imports.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-06-extending-bin-coreutils","section":7,"title":"Chapter 6 — Extending /bin (bare-os-coreutils)","synopsis":["man 7 devguide-06-extending-bin-coreutils","Developer guide chapter (developer-guide/06-extending-bin-coreutils.md)"],"description":"CHAPTER 6 — EXTENDING /BIN (BARE-OS-COREUTILS)\n\nShipping a new command in the system image means adding it to bare-os-coreutils, rebuilding, and re-seeding so /bin/<name> exists on the Hyperdrive. This is the only supported path for first-class OS utilities with shared prelude code.\n\nTHE CONTRACT (NON-NEGOTIABLE)\n\nEach command source under packages/bare-os-coreutils/src/<name>.js must:\n\n- Define async function run(ctx, argv).\n- Contain no top-level import or export—the file is concatenated into a single script string for AsyncFunction loading.\n\nShared helpers live in packages/bare-os-coreutils/lib/ and are prepended at build time, not imported. bare-os-lscolors lives in packages/bare-os-lscolors/ as a small workspace package so bare-os-booter can import it under Pear (cross-package paths into bare-os-coreutils resolve to unsupported pear://dev/... URLs).\n\nCHECKLIST FOR A NEW COMMAND FOO\n\n1. Implement packages/bare-os-coreutils/src/foo.js.\n2. Register the name in packages/bare-os-coreutils/lib/commands.mjs (COREUTILS_COMMANDS—keep sorted).\n3. Add a man page packages/bare-os-coreutils/man/pages/foo.json (build fails if missing).\n4. Optional: seed examples via scripts/seed-man-pages.mjs or edit JSON directly.\n5. Optional preamble: if foo needs a large engine file (or several helpers, like edit / nano with *lib/edit-.js), add to preamble** in build.mjs <../packages/bare-os-coreutils/build.mjs>:\n\n const preamble = {\n md5sum: ['md5.js'],\n sed: ['sed-engine.js'],\n awk: ['awk-engine.js'],\n jq: ['jq-engine.js'],\n man: ['man-render.js'],\n foo: ['foo-engine.js']\n }\n\n6. Build\n\n npm run build -w bare-os-coreutils\n\nThis runs build-man-db.mjs (manual database) and writes kernel/bin/foo plus the seeder mirror.\n\n7. Re-seed / replicate so peers get the new /bin/foo.\n\nWHAT GETS CONCATENATED\n\nFrom build.mjs <../packages/bare-os-coreutils/build.mjs>:\n\n runtime.js + [preamble files...] + src/foo.js → kernel/bin/foo\n\nruntime.js begins with a BARE_OS_BIN_API version comment (e.g. */ BARE_OS_BIN_API 1.0.0 /). Staged kernel/bin/ must contain that string so scripts/verify-kernel-seeder-parity.mjs <../../scripts/verify-kernel-seeder-parity.mjs> can catch drift; hand-written stubs (systemctl, journalctl**) carry the same pragma.\n\nruntime.js defines helpers like bareStdin, listing time formatting, etc.—read it before reimplementing utilities.\n\nEXIT STATUS\n\nPOSIX-ish utilities set ctx.exitCode (number) when they want a non-zero status. The shell uses ctx.exitCode for &&, ||, and ; lists; utilities such as grep and test set it for conditions.\n\nTESTS\n\nAdd or extend tests under packages/bare-os-booter/test.js using runBinCommand with a Hyperdrive that has the built /bin/foo bytes—follow existing grep, ls, cat patterns.\n\nDOCUMENTATION\n\n- Update man page JSON (required by build).\n- Optional: handbook chapter 9 cross-links for POSIX alignment.\n- Optional: TypeScript shapes in packages/bare-os-booter/lib/bare-os-ctx.d.ts <../packages/bare-os-booter/lib/bare-os-ctx.d.ts> (BareOsKernelContext, BareOsBinRun) for host-side editors.\n\nSEE ALSO\n\n- Chapter 5 — Modules <05-modules-and-imports.md>\n- Chapter 8 — Testing <08-testing-and-debugging.md>\n- kernel/README.md <../kernel/README.md>\n\n← Modules <05-modules-and-imports.md> · Apps beyond shell → <07-apps-beyond-the-shell.md>","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","06","extending","bin","coreutils","chapter","bare"],"seeAlso":[{"name":"devguide-07-apps-beyond-the-shell","section":7},{"name":"devguide-05-modules-and-imports","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/06-extending-bin-coreutils.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-07-apps-beyond-the-shell","section":7,"title":"Chapter 7 — “Apps” beyond the shell (what is realistic today)","synopsis":["man 7 devguide-07-apps-beyond-the-shell","Developer guide chapter (developer-guide/07-apps-beyond-the-shell.md)"],"description":"CHAPTER 7 — “APPS” BEYOND THE SHELL (WHAT IS REALISTIC TODAY)\n\nBare OS does not have an app store, sandboxed widgets, or a second GUI runtime inside the image. An application here is usually:\n\n- a workflow built from the shell, /bin tools, and files on the personal drive; or\n- a custom kernel + utilities; or\n- a host Pear app that changes boot behavior.\n\nThis chapter orients you without over-promising.\n\nTHE DEFAULT “APP”: SHELL + /BIN + GIT\n\nMost user goals are met by:\n\n- Scripts in $HOME (run(ctx, argv)).\n- Pipelines and redirection (simulated stdin/stdout).\n- git for repositories on the VFS (see Handbook ch.8 <../handbook/08-git-on-bare-os.md>).\n\nThat is the intended application platform for end users.\n\nINITD AND BACKGROUND FLAVOR\n\nThe booter registers initd-style disposers via bare-initd.js <../packages/bare-os-booter/lib/bare-initd.js>. The stock system uses this lightly (e.g. kernel logger). Extending this usually means host booter changes: register a start function during executeKernel, not from arbitrary /bin scripts.\n\nRead bare-initd.js <../packages/bare-os-booter/lib/bare-initd.js> before adding long-running tasks—teardown must be explicit (stopBareInitd).\n\nCRON AND TIMERS\n\nbare-cron reads /etc/bare-os/crontab on the system image (if present), then the user’s ~/.crontab on the personal drive; invalid lines are logged and skipped. crontab installs/lists/removes the user file (requires login). Timer drop-ins under *~/.config/bare-os/timers/.timer ([Timer] OnCalendar= + ExecLine=**) merge into the same minute scheduler. See Handbook ch.4 <../handbook/04-the-booter-runtime.md> and Developer guide ch.11 <11-kernel-pear-cookbook.md>.\n\nSocket-shaped activation: initd unit drop-ins can set SocketActivationIpc=<fifo-name> so a service’s start() runs when something first readFiles that logical FIFO under /run/bare-os/ipc/ (see bare-initd.js).\n\nHDMS AND /MNT\n\nAfter identity unlock, optional HDMS mounts may appear under /mnt. Utilities use ctx.vfs; HDMS integration is advanced and covered narratively in the handbook (identity + HDMS chapter). User scripts should prefer vfs.readFile / writeFile over hard-coding drive objects.\n\nREPLACING THE KERNEL\n\nA heavier “app” might ship a different /boot/init.js—for example a menu-driven UI using readLine or a non-interactive worker when BARE_OS_SKIP_REPL=1. You still have the single JavaScript realm per session; there is no fork into a second Bare process from inside the image.\n\nWHEN YOU ACTUALLY NEED A NEW PEAR APP\n\nIf you need multiple OS images, custom networking, or native addons not suitable for AsyncFunction utilities, create a new Pear application that embeds or forks the booter pattern—this is host development (Chapter 1), not /bin development.\n\nSEE ALSO\n\n- Chapter 3 — Kernel <03-kernel-boot-init.md>\n- Handbook — Booter runtime <../handbook/04-the-booter-runtime.md>\n- Handbook — Identity, vault, HDMS <../handbook/05-identity-vault-and-hdms.md>\n\n← Extending /bin <06-extending-bin-coreutils.md> · Testing → <08-testing-and-debugging.md>","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","07","apps","beyond","the","shell","chapter","what","realistic","today"],"seeAlso":[{"name":"devguide-08-testing-and-debugging","section":7},{"name":"devguide-06-extending-bin-coreutils","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/07-apps-beyond-the-shell.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-08-testing-and-debugging","section":7,"title":"Chapter 8 — Testing and debugging","synopsis":["man 7 devguide-08-testing-and-debugging","Developer guide chapter (developer-guide/08-testing-and-debugging.md)"],"description":"CHAPTER 8 — TESTING AND DEBUGGING\n\nBare OS development mixes Node (fast iteration, Hyperdrive in tests), Bare (identity crypto and Pear parity), and Pear (production-like bundling). This chapter maps how tests are organized and how to debug in-image code.\n\nWORKSPACE TESTS\n\nFrom the repo root:\n\n npm ci\n npm test\n\npretest mirrors root package.json scripts.pretest: npm run build -w bare-os-coreutils, npm run build -w bare-os-bare-libs, verify-kernel-seeder-parity, verify-ctx-api-feature-bits, verify-kernel-capabilities-contract, verify-kernel-capabilities-word-6 … -word-11, verify-ctx-dts, validate-example-schemas, verify-doc-links, verify-man-coverage, verify-compat-matrix, verify-pear-no-static-node-import, smoke:bare-manifest — so *kernel/bin/, kernel/lib/bare, kernel/share/man/man.json, packages/bare-os-seeder/kernel/, ctx semver / feature words through bits11, capability contracts, bare-os-ctx.d.ts parity, schema examples, Tier-1 man** coverage, doc links, and the compatibility matrix stay aligned before workspace tests.\n\nKernel self-test: with BARE_OS_KERNEL_SELFTEST=1, the stock kernel runs built-in checks (including /proc/bare_os_resources, /proc/bare_os_features, and /proc/bare_os/index.json). Use BARE_OS_SELFTEST_FORMAT=tap for CI-friendly stderr.\n\nKernel hot reload (dev): with BARE_OS_KERNEL_HOT_RELOAD=1, a custom kernel may call ctx.bareOsRequestKernelReload() to throw a controlled reload: the booter re-fetches /boot/init.js and runs start(ctx) again without tearing down the swarm session.\n\nKernel profile warm reload: with BARE_OS_KERNEL_PROFILE_WARM=1, ctx.bareOsRequestKernelProfileReload() uses the same re-invocation loop (distinct error code for policy clarity).\n\nSeed RPC contract: packages/bare-os-protocol lists RPC short names in lib/seed-rpc-methods.js; channel.js rejects unknown methods with bare_os.rpc_unknown_method and wrong modules with bare_os.rpc_wrong_module. packages/bare-os-protocol/test.js asserts the registry stays non-empty.\n\nCI MARKER SCOPE (FIRST-PARTY VS VENDORED BUNDLES)\n\nTwo complementary gates apply; neither is a blanket ban on the word “implement” in the whole repo:\n\n| Script | Scope | Intent |\n| scripts/verify-runtime-no-incomplete-markers.mjs | Hand-authored kernel/init.js (generated bundle), kernel/lib/init/, kernel/lib/boot/, *kernel/bin/.js, packages/bare-os-booter/ (excluding test.js and paths in docs/audit/runtime-marker-excludes.json) | No TODO / FIXME / HACK / XXX or throw new Error(\"Not implemented\")** in runtime booter/kernel sources. |\n| scripts/verify-bundle-markers.mjs | *kernel/lib/bare/bundles/.js only | Vendored Holepunch IIFEs: block incomplete-looking substrings unless the basename is allowlisted in docs/audit/bundle-marker-allowlist.json (policy: keep allowlist empty; fix via upstream bumps or scripts/sanitize-bare-bundles.mjs**). |\n| scripts/verify-bundle-throws.mjs | Same bundles | Same idea for throw new Error(\"…not implemented…\")-style messages; allowlist docs/audit/bundle-throw-allowlist.json stays empty by policy. |\n\npackages/bare-os-coreutils and packages/bare-os-protocol are not scanned by verify-runtime-no-incomplete-markers today—still avoid shipping incomplete markers in shipped src/ paths. Test files may use mocks and stub URLs; production syscall bridges use explicit ENOTSUP / ENOSYS returns instead of placeholder throws.\n\nSee also docs/audit/PLACEHOLDER_BASELINE.md <../docs/audit/PLACEHOLDER_BASELINE.md> and packages/bare-os-bare-libs/README.md <../packages/bare-os-bare-libs/README.md> § Bundle health, markers, and upstream closure.\n\nBRITTLE: BRITTLE-NODE VS BRITTLE-BARE\n\n- brittle-node runs most of packages/bare-os-booter/test.js—Hyperdrive, VFS, shell tokenizer, runBinCommand against real /bin bytes on disk (includes second-word (bits2) contract checks: @reboot / jitter parsing, param expansion v2, /proc stubs).\n- brittle-bare runs test.identity.js and protocol tests that need the Bare runtime (e.g. bare-crypto native pieces).\n- npm run test:bare (repo root) runs protocol tests plus the booter’s test:bare script (test.identity.js, test.bare-smoke.js) and seeder tests — a lighter Bare-native smoke path than the full brittle-node test.js harness.\n\nCold boot / ctx.bare: parallel readFile for drive /lib/bare bundles is capped by BARE_OS_BARE_STDLIB_RESOLVE_CONCURRENCY (1–32, default 4) in bare-os-ctx-bare.js; merge order stays deterministic.\n\nDiagnostics: with BARE_OS_DIAGNOSTICS_SUBSCRIBE=1, ctx.bareOsDiagnosticsSubscribe receives structured booter events (phase timing, optional kernel echoes) for local debugging—do not enable in untrusted production shells.\n\nCI installs Bare globally for parity (see .github/workflows/ci.yml). If identity tests fail locally, ensure bare is installed and on PATH.\n\nDEBUGGING USER SCRIPTS AND UTILITIES\n\n1. ctx.console.log / error — Primary visibility; errors from AsyncFunction compilation are caught in runScriptFromSource and printed with a short stack snippet.\n2. Isolate — Run a one-line shell command: command node is not available; use runBinCommand from a tiny test or invoke your script path directly.\n3. Compare with known-good — Copy the pattern from packages/bare-os-booter/test.js (readBuiltBin, put /bin/ls, etc.).\n\nPEAR DEV WORKFLOW\n\nUse the root scripts (see README <../README.md>):\n\n- npm run os:seeder and npm run os:booter (separate terminals) after ensure-pear-node-modules.\n\nPear uses bundled node_modules; if resolution fails, run node scripts/ensure-pear-node-modules.mjs as documented in scripts/README.md.\n\nCI-STYLE KERNEL CHECKS\n\n- BARE_OS_KERNEL_SELFTEST=1 — stock kernel/init.js <../kernel/init.js> runs a short execLine checklist after boot snippets.\n- BARE_OS_SELFTEST_FORMAT=tap — same self-test emits TAP lines on stderr (for parsers in CI).\n- node scripts/verify-kernel-seeder-parity.mjs — after a coreutils build, asserts kernel/ and packages/bare-os-seeder/kernel/ match and every *kernel/bin/ file includes BARE_OS_BIN_API (root pretest** runs this).\n\nCOMMON FAILURE MODES\n\n- unknown command — Name not on system PATH and not a resolvable *.js\n- invalid manual database — Forgot to build coreutils after changing commands list\n- kernel/bin missing BARE_OS_BIN_API pragma — Rebuild coreutils or add pragma to hand-maintained *kernel/bin/** stubs\n- Identity test skips / fails on Node only — Expected—run under brittle-bare\n- Session exits immediately — BARE_OS_SKIP_REPL=1 or readLine returns null\n\nMEDIA (FFMPEG / FFPROBE) AND SANDBOXING\n\n*mediaproc: BARE_OS_BIN_WORKER_OFFLOAD routes ffmpeg and ffprobe through bare-thread when enabled. Keep input paths inside the two-drive VFS (no host path escapes), cap wall time with BARE_OS_BIN_WORKER_WALL_MS, and treat media tools as delegated compute**: never pass untrusted filter graphs from guest scripts without a capability review. See kernel-extensions.md <../docs/reference/kernel-extensions.md> for worker class bits.\n\nSEE ALSO\n\n- Handbook ch.7 — Operations <../handbook/07-operations-and-development.md>\n- bare-os-booter README <../packages/bare-os-booter/README.md>\n\n← Apps beyond shell <07-apps-beyond-the-shell.md> · Security → <09-security-and-trust.md>","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","08","testing","and","debugging","chapter"],"seeAlso":[{"name":"devguide-09-security-and-trust","section":7},{"name":"devguide-07-apps-beyond-the-shell","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/08-testing-and-debugging.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-09-security-and-trust","section":7,"title":"Chapter 9 — Security and trust (developer mindset)","synopsis":["man 7 devguide-09-security-and-trust","Developer guide chapter (developer-guide/09-security-and-trust.md)"],"description":"CHAPTER 9 — SECURITY AND TRUST (DEVELOPER MINDSET)\n\nBare OS is research software. It is not a hardened multi-tenant OS. Still, developers should understand what is trusted and what full ctx power implies.\n\nSYSTEM DRIVE TRUST MODEL\n\nThe system Hyperdrive is the OS image. You normally obtain it by replicating from peers that share the project’s discovery topology (see handbook protocol chapters). The codebase assumes you trust that image the same way you would trust an installer ISO from a vendor you chose.\n\n/bin and /boot bytes are executed as JavaScript. A malicious seeder could ship hostile /bin scripts. Mitigation is social and operational: use keys and peers you trust, verify releases, run your own seeder for development.\n\nBoot snippet tightening: with BARE_OS_BOOT_ALLOWLIST=1, the stock kernel only runs lines from trusted rc, rc.d, rc.local, kernel.d, and onboot whose first shell token appears in /etc/bare-os/boot.allow (plus builtins such as export, cd, :). Pair with BARE_OS_BOOT_STRICT=1 to exit the session on the first disallowed or failing line.\n\nBoot manifest integrity: BARE_OS_BOOT_MANIFEST=1 makes the stock kernel compare /etc/bare-os/boot.manifest.json to an expected digest (ctx.bareOsBootFileSha256Hex). BARE_OS_BOOT_MANIFEST_SIGN=1 adds Ed25519 verification of the raw manifest bytes against /etc/bare-os/boot.manifest.sig, using ctx.bareOsVerifyBootManifestSignature and BARE_OS_BOOT_MANIFEST_PUBKEY_HEX (64 hex chars). Rotation is operational: ship a new public key in host env and a matching signature file on the system image. This does not replace image trust—you still choose peers and seed sources carefully.\n\nSeed capability attestation (optional): the seeder may answer bare_os.capability_attestation with JSON from host env BARE_OS_SEED_CAPABILITY_ATTESTATION_JSON (for example a distro or hyper-multisig bundle). The guest does not verify signatures; operators verify on the host or out-of-band. BARE_OS_BIN_WORKER_OFFLOAD is a reserved gate for future isolated /bin execution—stock paths remain in-process unless a host integration supplies a worker bridge.\n\nAudit: BARE_OS_AUDIT=1 logs execLine activity to /var/log/bare-os/audit.log. BARE_OS_AUDIT_JSON=1 uses JSON lines with auditSchemaVersion: 2 on execLine, delegate, and httpFetch records; BARE_OS_AUDIT_REDACT=1 (or true) masks common secret-like VAR=value patterns; BARE_OS_AUDIT_REDACT=TOKEN,PASSWORD masks named keys.\n\nDelegated HTTP: when the booter sets ctx.httpFetch from the host fetch, BARE_OS_HTTP_ALLOWLIST and BARE_OS_HTTP_DENYLIST restrict http/https URLs for curl/wget (host-pattern globs). Failed checks throw before the request; with audit on, allow/deny outcomes can be logged.\n\nHost CLI delegates: git, curl, wget, and systemctl-family commands can be restricted with BARE_OS_DELEGATE_ALLOW (comma list; empty = all). Optional per-minute caps use BARE_OS_DELEGATE_MAX_PER_MIN and per-kind *BARE_OS_DELEGATE__MAX_PER_MIN. With BARE_OS_AUDIT=1, BARE_OS_DELEGATE_AUDIT_ONLY=1 logs delegate invocations and skips the host run (exit 0**) for audit-only environments.\n\nDNS allowlist: BARE_OS_DNS_ALLOWLIST optionally constrains http(s) hostnames for curl/wget before fetch (suffix wildcard *.example.com** supported).\n\nDNSSEC: the stock guest does not validate DNSSEC; resolvers and TLS stacks on the host own DNSSEC, DANE, and related policy. Do not infer DNS security properties from Bare OS delegate behavior alone.\n\nIPC JSON-RPC: when BARE_OS_IPC_RPC_TOKEN is set, pushJson payloads must include matching bareOsIpcToken or the push throws. Line size is capped (BARE_OS_IPC_JSON_MAX_BYTES, default 256 KiB).\n\nSandboxed scripts: ctx.bareOsSandboxRunScript(source, argv?, opts?) runs in-image JS with a restricted ctx: writes are limited to the personal namespace (same routing rules as isPersonalRoute), and identity / vault / virtual-file registration hooks are disabled. Disable entirely with BARE_OS_SANDBOX_SCRIPT=0. BARE_OS_SANDBOX_WORKER=1 prefers bare-worker when the host provides it, else defers on a fresh microtask; neither path is a hardware isolate. For documented stronger separation, operators may compose Holepunch cross-worker / bare-bundle-evaluate patterns (see comments in packages/bare-os-booter/lib/bare-os-sandbox.js). This remains not a guaranteed security boundary—treat sandboxing as a trust reducer.\n\nWebAssembly and native FFI (policy): a future guest WASM runtime must map imports to capability-gated ctx.vfs / IPC surfaces only—never raw host syscalls. Native bare-addon loading belongs on the Pear host with explicit allowlists; the replicated system image should not ship unsigned addons. Pair WASM/FFI plans with boot.policy.json denyKernelSyscalls / allowedCtxMethods and treat both as experimental until a dedicated ADR lands.\n\nProvenance: /proc/bare_os_provenance (and /proc/bare_os/provenance) combines boot manifest digest, optional signing flags, and Pear channel hints for operators (see kernel extensions <../docs/reference/kernel-extensions.md>).\n\nPear trust summary (operator): /proc/bare_os/pear_trust.json reflects optional host JSON from BARE_OS_PEAR_TRUST_JSON (e.g. multisig-link style metadata). The guest does not verify multisig or Pear channel signatures—operators validate on the host or out-of-band.\n\nPear IPC allowlist: when boot.policy.json sets allowedPearIpcChannels, the stock kernel copies it to BARE_OS_BOOT_POLICY_PEAR_IPC_CHANNELS so ctx.bareOsPearIpcEmit only forwards listed channels.\n\nDocumented bare-subprocess bridge: feature bit BARE_OS_FEATURE2_BARE_SUBPROCESS_BRIDGE names an optional, default-off host integration pattern using Holepunch bare-subprocess <https://github.com/holepunchto/bare-subprocess> for long-running delegated commands with a message bridge back to ctx. Stock images do not enable it unless a distributor wires env + allowlists explicitly. Capability word 5 adds bareOsReadSubprocessBridgeSnapshot with optional cgroupRootHint / signal lists from BARE_OS_SUBPROCESS_BRIDGE_META_JSON — these are host-supplied hints only; the guest must not treat them as a Linux security boundary.\n\nPERSONAL DRIVE AND USER SCRIPTS\n\nAnything you can write to $HOME can be executed if you run it—and you are the typical author. If you download a script from the network into your home directory and execLine it, you have effectively eval’d untrusted code with access to:\n\n- ctx.vfs (read/write personal tree),\n- identity hooks (if exposed through crafted shell lines),\n- runBinCommand (invoke all bundled utilities).\n\nThe stock shell does not sandbox run. Treat drive-resident JS like shell scripts with superpowers.\n\nWHY “ADD DYNAMIC IMPORT FROM THE INTERNET” IS DANGEROUS\n\nLoading modules from Hyperdrive or HTTP sounds convenient but creates:\n\n- Supply chain exposure (mutable remote code),\n- Ambiguous versioning (no lockfile on device),\n- Larger attack surface in the booter.\n\nThe project’s conservative stance: bundle on the host or ship utilities in the system image after review.\n\nGUEST VS UNLOCKED IDENTITY\n\nDefault guest sessions have predictable HOME=/home/guest and no Ed25519 identity. Login unlocks /.bare/account and changes ctx.vfs.env (user, home, keys). Applications that handle secrets should never log passphrases or raw keys; use existing login / logout flows.\n\npear.multisig.json metadata (signer list + quorum) is validated by the same shape predicate in bare-os-protocol (seeder hint) and the bundled guest helper bareOsPearMultisigShapeOk in kernel/lib/boot/00-pear-multisig-shape.js; keep those files aligned when changing rules.\n\nREPORTING ISSUES\n\nSecurity vulnerabilities in this repo should be reported through the project’s normal channels (maintainer contact / GitHub security advisories if enabled). Do not open public issues with exploit details until coordinated disclosure.\n\nSEE ALSO\n\n- Blind relay / P2P hardening (proc defaults) <../docs/security/blind-relay-p2p-hardening.md>\n- Handbook — Blueprints / trust <../handbook/02-blueprints.md>\n- Chapter 5 — Modules <05-modules-and-imports.md>\n\n← Testing <08-testing-and-debugging.md> · Glossary → <10-glossary-and-faq.md>","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","09","security","and","trust","chapter","mindset"],"seeAlso":[{"name":"devguide-10-glossary-and-faq","section":7},{"name":"devguide-08-testing-and-debugging","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/09-security-and-trust.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-10-glossary-and-faq","section":7,"title":"Chapter 10 — Glossary and FAQ","synopsis":["man 7 devguide-10-glossary-and-faq","Developer guide chapter (developer-guide/10-glossary-and-faq.md)"],"description":"CHAPTER 10 — GLOSSARY AND FAQ\n\nQuick reference and repeated questions. Canonical term definitions (single source of truth for cross-tree vocabulary) live in docs/glossary.md <../docs/glossary.md>; this chapter keeps developer-centric expansions and FAQ answers that assume you are editing /bin or the booter.\n\nGLOSSARY\n\n- AsyncFunction — Object.getPrototypeOf(async function () {}).constructor — used to compile in-image JS strings with parameters ctx / argv\n- Booter — Pear/Node app (bare-os-booter) that joins Hyperswarm, replicates drives, builds ctx, runs kernel\n- Coreutils — bare-os-coreutils package — builds /bin scripts from src/*.js + prelude\n- ctx — Context object passed to start and run; see Chapter 2 <02-the-context-object.md>\n- ctx.bare — Frozen map of curated npm modules for in-image scripts (manifest + optional /lib/bare bundles); Chapter 12 <12-bare-modules-and-pear-ecosystem.md>\n- Guest — Pre-login session identity (BARE_OS_IDENTITY=guest)\n- Hyperdrive — P2P writable/readable filesystem keyed by discovery secret\n- In-image — Code whose source bytes live on system or personal drive and are eval’d via AsyncFunction\n- Kernel — /boot/init.js — async function start(ctx)\n- Personal drive — Per-session mutable Hyperdrive; $HOME, /.bare, user files\n- Seeder — Pear/Node app that stages kernel/ into system Hyperdrive and serves MBR\n- System drive — Replicated OS image (/bin, /boot, /etc, …)\n- VFS — Virtual file system layer routing paths to drives + HDMS mounts\n- IPC fan-out — bareOsIpc.fanoutPublish / fanoutSubscribe — multi-subscriber copies (bounded); disable with BARE_OS_IPC_FANOUT=0\n- HTTP policy — Optional BARE_OS_HTTP_ALLOWLIST / BARE_OS_HTTP_DENYLIST applied when the booter wraps ctx.httpFetch\n- booterPhases — Milestones recorded in /run/bare-os/boot.json (vfs, ctx, repl, initd, kernel_invoke) alongside kernel phases\n- ~/.barerc — Personal shell init: export, alias, theme <preset>; parsed by loadBarerc. Builtin barerc reload reapplies without logout.\n- BARE_OS_THEME — Active color preset name; /bin/theme, ~/.barerc, and ctx.bareOsApplyTheme() refresh *BARE_OS_COLOR_ and usually LS_COLORS**.\n- LS_COLORS — GNU-style colon-separated map consumed by ls --color; optional file via BARE_OS_DIRCOLORS and dircolors.\n- BARE_OS_COLOR_DEPTH — truecolor (default), 256, or 16 / ansi — downgrades truecolor sequences in *BARE_OS_COLOR_** for the fish REPL only.\n\nFAQ\n\nWhy doesn’t import work in my ~/script.js?\nIn-image scripts are not ES modules. Use inlining, bundling on the host, or the coreutils concat build. See Chapter 5 <05-modules-and-imports.md>.\n\nHow do I use npm packages on the device?\nFor packages listed in bare-module-manifest.json, use ctx.bare.<key> from run / start (see Chapter 12 <12-bare-modules-and-pear-ecosystem.md>). Otherwise bundle on the host, or add code to the booter package with normal npm deps.\n\nWhat’s the difference between execLine and runBinCommand?\nexecLine runs the shell (aliases, builtins, pipelines). runBinCommand runs argv directly. See Chapter 3 <03-kernel-boot-init.md>.\n\nHow do I add a command to /bin?\nFollow Chapter 6 <06-extending-bin-coreutils.md>: src/foo.js, commands.mjs, man/pages/foo.json, build.\n\nCan I run TypeScript?\nNot natively on the drive. Compile to JS on the host, then ship the output.\n\nWhere is stdin for pipelines?\nShell sets ctx.shellStdin on a cloned context. Read it as a string. Coreutils use bareStdin(ctx) from prelude—user scripts must implement their own or copy the snippet. Chapter 4 <04-user-scripts-and-path.md>.\n\nHow do I exit the session from code?\nCall ctx.requestBooterExit(code) (same as exit builtin / /bin/exit).\n\nDoes ctx.exitCode control the host process exit?\nThe host exit code is managed by the booter after the kernel returns; utilities set ctx.exitCode for POSIX semantics inside the session. See booter executeKernel return path.\n\nWhat about Web APIs (fetch, localStorage)?\nNot part of the Bare OS contract for in-image code. Pear/Bare may provide some globals on the host; do not rely on them for portable /bin tools. When Node provides fetch, the booter may set ctx.httpFetch with outbound policy—see Chapter 2 <02-the-context-object.md>.\n\nWhat is bareOsSandboxRunScript?\nA reserved API that throws until a worker/isolate story lands; see Chapter 9 <09-security-and-trust.md>.\n\nHow do I match my host terminal to Bare OS colors?\nUse theme list / theme set <name> in the guest, then import the matching files under docs/themes <../docs/themes/README.md> (Alacritty, Warp, iTerm2). Host TERM and COLORTERM are passed through for capability detection.\n\nSEE ALSO\n\n- Canonical glossary <../docs/glossary.md>\n- Documentation FAQ <../docs/faq.md>\n- Developer guide home <README.md>\n- Handbook home <../handbook/README.md>\n- File-level reference <../docs/reference/README.md>\n\n← Security <09-security-and-trust.md> · Developer guide home <README.md>","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","10","glossary","and","faq","chapter"],"seeAlso":[{"name":"devguide-11-kernel-pear-cookbook","section":7},{"name":"devguide-09-security-and-trust","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/10-glossary-and-faq.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-11-kernel-pear-cookbook","section":7,"title":"Chapter 11 — Kernel extensions and Pear workflows","synopsis":["man 7 devguide-11-kernel-pear-cookbook","Developer guide chapter (developer-guide/11-kernel-pear-cookbook.md)"],"description":"CHAPTER 11 — KERNEL EXTENSIONS AND PEAR WORKFLOWS\n\nThis chapter ties the Hyperdrive-resident kernel (kernel/init.js <../kernel/init.js>), ctx <./02-the-context-object.md>, and Pear/Bare distribution patterns together.\n\nBOOT COMPOSITION\n\n1. Stock phases — os-release, motd, optional rc.profile.*, rc, rc.d, rc.local, kernel.d, banner, onboot (non-interactive), optional self-test.\n2. Strict boot — BARE_OS_BOOT_STRICT=1 stops on first execLine error in trusted snippets.\n3. Allowlist — BARE_OS_BOOT_ALLOWLIST=1 plus /etc/bare-os/boot.allow <../kernel/etc/bare-os/boot.allow.example> restricts the first word of each line in those snippets (builtins like export and cd stay allowed).\n\nINIT, TIMERS, AND SOCKETS\n\n- bare-initd — User drop-ins under ~/.config/bare-os/units/<name>.unit support SocketActivationIpc=<fifo>; the unit’s start runs after the first byte is read on that logical FIFO under /run/bare-os/ipc/…. Optional IdleSec=N (with stop) stops the unit after N seconds without further IPC traffic; optional fragments ~/.config/bare-os/units.d/<name>/*.conf merge before ~/.config/bare-init/units/ overrides. ReadinessPath= may be exec:<execLine> for a bounded readiness gate. ConditionPathExists= skips start when a VFS path is missing; AssertPathExists= fails the unit when missing (systemd-like, bounded absolute paths). ConditionPathIsDirectory= / AssertPathIsDirectory= do the same for directories (via vfs.lstat). Inspect the live DAG at /proc/bare_os/initd_graph.json (same payload as initd_dag.json, optional dot field).\n- Timers — Files in ~/.config/bare-os/timers/.timer (max 8) with a [Timer] section: either OnCalendar= (five cron fields) + ExecLine= on the same minute tick as ~/.crontab, or EveryMs= (1000–86400000) + ExecLine= on a fixed setInterval, or OnInactiveSec= to run after the last timer-triggered finish plus an idle gap (one-shot or repeating; Persistent= keeps state across sessions where implemented). Optional JitterSec= spreads the first (or periodic) execLine within 0…N seconds. Copy from /etc/bare-os/timers/.timer.example on the system image when present.\n- System cron — Optional image file /etc/bare-os/crontab (see crontab.example <../kernel/etc/bare-os/crontab.example>) is merged with user crontab entries. Lines may use @reboot + command (once per bare-cron start) and optional JitterSec=N prefix on the command for calendar lines.\n\nOBSERVABILITY\n\n- ctx.bareOsSubscribeBootEvent — Same structured events as BARE_OS_BOOT_TRACE=ndjson (phase, ms, sessionId); the booter also emits *booter: phases (vfs, ctx, repl, initd, kernel_invoke**).\n- /proc/bare_os_quotas — Pipeline limits, BARE_OS_EXEC_MAX_DEPTH, IPC caps, session stats.\n- /proc/bare_os_resources / ctx.bareOsGetResourceStatus() — Unified snapshot for operators.\n- /proc/bare_os_features — Documented kernel-feature words bits, bits2, bits3, bits4, bits5 (see bare-os-protocol exports).\n- /proc/bare_os/net_summary.json — Coalesced swarm / seed RPC hints for operators (topic, peer count, staging slot, replication queue, snapshot / firewall stats when present).\n- ctx.vfs.watch(path) — Hyperdrive-backed watch when BARE_OS_VFS_WATCH is not 0; returns { watcher, destroy, … }. With BARE_OS_VFS_WATCH_PSEUDO=1, may watch coalesced /proc/bare_os/metrics_live.json.\n\nPEAR / GIT / HTTP\n\n- Mirror-drive hints — ctx.bareOsEmitMirrorDriveHint({ label?, key? }) emits bare-os:mirror-drive-hint on Node-style hosts for mirror-drive–style workflows (labels/keys only; trust boundaries unchanged).\n- Release metadata — Host can set BARE_OS_PEAR_CHANNEL, BARE_OS_PEAR_RELEASE, and BARE_OS_IMAGE_DIGEST; they appear in /run/bare-os/boot.json.\n- ctx.bareOsRequestPearReload() — Returns hints and env strings; the host pear-runtime / pear-runtime-updater must perform any real reload. A successful host reload can swap the Pear booter bundle so a new bare-module-manifest.data.mjs (from npm run sync:bare-manifest at staging time) takes effect; ctx.bareOsRequestPearReload does not rewrite ctx.bare in-process—expect a new guest boot for an updated host import list. Drive-only edits to /lib/bare/bare-module-manifest.json still merge bundles from the image without re-staging Pear.\n- ctx.bareOsPearUpdaterDelegate() (async, bareOsCtxApiVersion 1.32.0+) — Surfaces non-secret updater state without bundling pear-runtime-updater in the stock booter. Host options: set BARE_OS_PEAR_UPDATER_SNAPSHOT_JSON to a JSON string for a fixed operator snapshot, or BARE_OS_PEAR_UPDATER_MODULE to an ESM URL/path whose default export (or getPearUpdaterState / bareOsPearUpdaterSnapshot) is an async function returning a plain object (for example { version, updating, updated } mirroring your PearRuntimeUpdater instance). See bare-os-pear-updater-bridge.js <../packages/bare-os-booter/lib/bare-os-pear-updater-bridge.js>.\n\nSYSTEM REVISION AND INITD (OTA-FRIENDLY ORDERING)\n\nHost env BARE_OS_SYSTEM_REVISION_ID, BARE_OS_SYSTEM_REVISION_PENDING, and BARE_OS_SYSTEM_SLOT surface as ctx.bareOsSystemRevision and in /proc/bare_os/provenance. For Pear OTA flows, gate user units on pending work: e.g. ConditionPathExists= on a host-written marker file, or After= a unit whose ReadinessPath= checks /proc/bare_os/provenance JSON (parse in a small exec: gate). Combine with ctx.bareOsRequestPearReload() so the host applies the new bundle before initd restarts dependents.\n- git-pear — /bin/git-pear help documents Git-in-Pear (gip-transport, gip-remote, git+pear:// remotes).\n- HTTP — Delegated curl / wget resolve fetch via ctx.httpFetch (policy-wrapped when the booter supplies it), then ctx.bare.fetch from host BARE_OS_BARE_MODULES and drive /lib/bare/bundles, then globalThis.fetch. ensureBareFetchGlobals may install bare-fetch or bare-https when no native fetch exists. BARE_OS_HTTP_ALLOWLIST, BARE_OS_HTTP_DENYLIST, BARE_OS_DNS_ALLOWLIST, and BARE_OS_TLS_PIN_SHA256 (and init.bareOsCurlTls for curl) narrow outbound access. Canonical doc: HTTP: curl and wget <../docs/reference/http-curl-and-wget.md>.\n\nBUILDING THE IMAGE\n\n- From the repo root, rebuild staged /bin utilities: node packages/bare-os-coreutils/build.mjs.\n- Keep kernel/ <../kernel/> and packages/bare-os-seeder/kernel/ <../packages/bare-os-seeder/kernel/> identical (node scripts/verify-kernel-seeder-parity.mjs).\n- Pear staging: use pear-build / app manifests in your Pear project; align pear.json channels with BARE_OS_PEAR_* env vars on the boot host.\n\nHDMS HOOKS\n\nUse ctx.bareOsSubscribeHdmsLifecycle to run logic when extra drives mount after unlock (kind: 'activate', labels) or before guest teardown (kind: 'deactivate').","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","11","kernel","pear","cookbook","chapter","extensions","and","workflows"],"seeAlso":[{"name":"devguide-12-bare-modules-and-pear-ecosystem","section":7},{"name":"devguide-10-glossary-and-faq","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/11-kernel-pear-cookbook.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-12-bare-modules-and-pear-ecosystem","section":7,"title":"Chapter 12 — Bare modules, ctx.bare, and the Pear ecosystem","synopsis":["man 7 devguide-12-bare-modules-and-pear-ecosystem","Developer guide chapter (developer-guide/12-bare-modules-and-pear-ecosystem.md)"],"description":"CHAPTER 12 — BARE MODULES, CTX.BARE, AND THE PEAR ECOSYSTEM\n\nThis chapter ties together *Holepunch bare- packages, the Pear host runtime, and how Bare OS exposes a curated subset to in-image** scripts.\n\nTIERS OF ACCESS (IMAGE, PEAR EMBED, HOST, MIRROR)\n\n1. /lib/bare (system image, primary) — bare-os-bare-libs builds one IIFE per manifest row into kernel/lib/bare/bundles/ (mirrored on the seeded Hyperdrive). It also copies bare-module-manifest.json into kernel/lib/bare/. manifest.json lists successful bundles; stale *bundles/.js files are pruned on each successful build. At boot, drive bundles run first (unless BARE_OS_BARE_DRIVE_BUNDLES=0**).\n\n2. Pear booter (bare-module-manifest.data.mjs) — The stock booter package ships packages/bare-os-booter/lib/bare-module-manifest.json (normative JSON, edited or synced from the catalog) and a generated sibling bare-module-manifest.data.mjs that export default the same object. Under pear run, import.meta.url is pear://…; bare-fs cannot open pear: URLs passed as URL instances because normalization uses bare-url.fileURLToPath ( file: only). Therefore loadBareModuleManifest() reads the embedded .data.mjs on Pear so the manifest stays in the traced module graph. On file: dev checkouts it prefers the JSON on disk (live edits) and falls back to the embedded copy if the file is missing. Regenerate .data.mjs with npm run sync:bare-manifest or node scripts/generate-bare-module-manifest-data.mjs; CI runs npm run verify:manifest-data.\n\n3. ctx.bare (host fallback) — Unless BARE_OS_BARE_HOST_IMPORTS=0, the booter then import()s any manifest packages still missing after drive merge—typically native or Bare-only packages that could not be bundled, or when the image is older than the manifest. Set BARE_OS_BARE_HOST_IMPORTS=0 for a fully image-local ctx.bare (no Pear host node_modules participation). Disable all ctx.bare with BARE_OS_BARE_MODULES=0. Manifest rows may include optional tier (core vs extended) and risk (low, medium, high) for distributor policy; the build honors tier via BARE_OS_BUNDLE_TIER.\n\nBoot cold path / stdlib budget: the stock booter measures drive merge + host import() resolution for ctx.bare and sets BARE_OS_BOOT_BARE_STDLIB_RESOLUTION_MS before the guest starts. Operators may set BARE_OS_BOOT_BUDGET_MS_BARE_STDLIB to log boot-perf.json / stderr warnings when resolution exceeds the budget; combine with BARE_OS_BUNDLE_TIER=core (or a smaller manifest) to shrink cold I/O. Use node scripts/kernel-microbench.mjs for regression-shaped timings (not a literal Pear cold boot).\n\n4. The full mirror (discoverability) — A local checkout of Holepunch repos (for example holepunchto_repos under your Pear tooling tree) lists on the order of 150+ repositories whose names start with bare-. Many are native addons, platform-specific (mobile, GUI, FFmpeg, …), or developer tools. The manifest can list them for ctx.bare, but only rows that bundle cleanly become real drive IIFEs; the rest rely on host import or stubs until you trim the manifest.\n\nMAINTENANCE WORKFLOW\n\n- Holepunch catalog (maximal npm set) — From the repo root:\n\n npm run gen:bare-catalog\n npm run sync:bare-manifest\n npm install\n\nThis refreshes docs/bare-holepunch-catalog.json <../docs/bare-holepunch-catalog.json> (every *holepunchto/bare- repo plus npm latest, minus scripts/bare-catalog-overrides.json <../scripts/bare-catalog-overrides.json>), then merges published packages into bare-module-manifest.json <../packages/bare-os-booter/lib/bare-module-manifest.json> and replaces booter optionalDependencies from that catalog (anything not includedInBooter is dropped). CI runs npm run gen:bare-catalog:check so the committed catalog’s entries (and source**) stay in sync with live npm/GitHub.\n\nscripts/bare-ctx-import-overrides.json <../scripts/bare-ctx-import-overrides.json> adjusts a few packages for ctx.bare / esbuild: namespace exports (*export: ), bare-node-runtime/global** as a side-effect entry, etc. Edit this when npm packages have no default export or need a subpath.\n\n- Add or remove a ctx.bare entry by hand — Edit the manifest and booter dependencies / optionalDependencies as needed. The bundle field in the manifest is legacy metadata; bare-os-bare-libs attempts every row. Prefer the catalog + sync path for *bare- rows so ctxKey** and semver ranges stay consistent.\n\n- Refresh /lib/bare on the image — From the repo root:\n\n npm run build -w bare-os-bare-libs\n\nOptional BARE_OS_BUNDLE_TIER=core builds only manifest rows with \"tier\": \"core\" (default tier when omitted). Use all or unset for the full catalog.\n\nThen re-run the seeder so kernel/lib/bare/ is copied into the Hyperdrive (the seeder invokes this build automatically when running from a file: URL). Check manifest.json → bundleStats after a build for how many IIFEs succeeded vs stub-only.\n\n- Node vs Pear/Bare — On Node, buildBareCtxObjectFromHost skips manifest rows with nativeHint: true so optional Bare-native packages are not import()’d (avoids stray failures and unhandled rejections from addons). On Pear/Bare, the full manifest is loaded in parallel.\n\n- Pear — Continue to use node scripts/ensure-pear-node-modules.mjs packages/bare-os-booter before pear run so hoisted node_modules resolve like npm (see PEAR-RUN.md <../PEAR-RUN.md>). After any manifest or catalog edit, run npm run sync:bare-manifest before pear stage so bare-module-manifest.data.mjs matches the JSON.\n\n- Local Holepunch clone inventory — After editing the manifest or before a release, run npm run audit:holepunch-clones to refresh docs/audit/holepunch-clone-sync-report.json <../docs/audit/holepunch-clone-sync-report.json> against BARE_OS_HOLEPUNCH_CLONES_ROOT. To fail CI when selected clones lag origin/main, list their directory names in docs/audit/holepunch-drift-repos.json <../docs/audit/holepunch-drift-repos.json> and set BARE_OS_HOLEPUNCH_DRIFT_CHECK=1 (see scripts/README.md <../scripts/README.md>).\n\nRUNTIME CAPS\n\nctx.bareOsRuntimeCaps.features includes bareCtxModules, bareDriveBundles, and bareHostImportsForCtx so kernels can see whether host fallbacks are enabled.\n\nPEAR IPC CHANNEL REGISTRY\n\nctx.bareOsPearIpcEmit(channel, payload) is a host bridge for pear-ipc <https://github.com/holepunchto/pear-ipc>-style messaging. Well-known channel strings are listed in packages/bare-os-booter/lib/bare-os-pear-ipc-registry.js and mirrored as JSON under /proc/bare_os/pear_ipc.json (and the flat /proc/bare_os_pear_ipc_registry alias) so operators and kernels share one vocabulary for reload, mirror, and telemetry hints.\n\nctx.bareOsPearIpcRequest(channel, payload, { timeoutMs? }) correlates bareOsIpcReqId on payload and awaits process.emit('bare-os:pear-ipc-response', { bareOsIpcReqId, result?, error? }) on Node-style hosts. Use for request/response pairs alongside bareOsPearIpcEmit.\n\nMirror-drive hints: ctx.bareOsEmitMirrorDriveHint({ label?, key? }) emits bare-os:mirror-drive-hint for Holepunch-style snapshot workflows (see kernel extensions <../docs/reference/kernel-extensions.md>).\n\nBlind-peer style hint: ctx.bareOsEmitBlindPeerHint(payload) forwards a capped JSON object on Pear IPC as bare_os_blind_peer_hint (topic/key material stays opaque strings; the guest does not verify blind-relay crypto).\n\nHost-only eval probe: ctx.bareOsHostCapability('bundleEvaluate') is true when the host advertises BARE_OS_HOST_BUNDLE_EVALUATE=1, documenting an optional cross-worker <https://github.com/holepunchto/cross-worker> / bare-bundle-evaluate <https://github.com/holepunchto/bare-bundle-evaluate> path. Actual evaluation still happens outside the guest VFS trust boundary.\n\nbare-fetch content encodings (Capability word 6 doc alignment) — When the host fetch implementation is Holepunch bare-fetch, Content-Encoding negotiation may include br and zstd in addition to gzip depending on platform support. In-image scripts should not assume a fixed encoding list; treat Accept-Encoding as host-defined. SPDX license identifiers on catalog rows (when present) are metadata for distributors, not a runtime guarantee inside the guest.\n\nSEE ALSO\n\n- Chapter 5 — Modules and import <05-modules-and-imports.md>\n- Chapter 2 — The context object <02-the-context-object.md>\n- Handbook — Booter runtime <../handbook/04-the-booter-runtime.md>\n- packages/bare-os-bare-libs/README.md <../packages/bare-os-bare-libs/README.md>\n\n← Kernel + Pear cookbook <11-kernel-pear-cookbook.md> · Modules and import → <05-modules-and-imports.md>","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","12","bare","modules","and","pear","ecosystem","chapter","the"],"seeAlso":[{"name":"devguide-13-privacy-telemetry-pii","section":7},{"name":"devguide-11-kernel-pear-cookbook","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/12-bare-modules-and-pear-ecosystem.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-13-privacy-telemetry-pii","section":7,"title":"Privacy, telemetry, and PII (Capability word 10)","synopsis":["man 7 devguide-13-privacy-telemetry-pii","Developer guide chapter (developer-guide/13-privacy-telemetry-pii.md)"],"description":"PRIVACY, TELEMETRY, AND PII (CAPABILITY WORD 10)\n\nBare OS telemetry is operator-controlled and bounded. Guests must treat every field as potentially visible to hosts, log sinks, and replicated drives.\n\nFIELDS TO SCRUB OR NEVER EMIT\n\nWhen building custom NDJSON / OTel mirrors or Pear-side aggregators, treat these as PII or secret-adjacent unless you have an explicit retention policy:\n\n- Identity: BARE_OS_SESSION_ID, BARE_OS_PUBLIC_KEY, device or account ids from Pear, HDMS vault labels that name people.\n- Network: full URLs with query strings, raw IP addresses paired with timestamps, DHT bootstrap strings copied from operator clipboards.\n- Crypto / auth: TLS session keys, Hypercore secret keys, multisig payloads, BARE_OS_LKG_SYSTEM_KEY_HEX, any TOKEN or SECRET env values.\n- Paths: home directory absolute paths on the host when they include real usernames (prefer basenames already used in $HOME mapping).\n- Capability word 8 fields: sessionForkGeneration, vaultRotateCount, multisig / trust-graph ids surfaced as pointers, OIDC publishing URLs, subprocess uidGidMapHint, RocksDB / sidecar manifest pointers — treat as operator metadata; scrub before cross-tenant export.\n- Capability word 9 fields: bareModuleCryptoStagingProbeId, bareModuleProbeClass, Pear stage / appling / updater / radio / wakeups sketches from *BARE_OS__JSON** env mirrors, SOCKS / HTTP proxy map keys (host-only interpretation) — treat as deployment fingerprinting; scrub or bucket before multi-tenant export.\n- Capability word 10 fields: pearInspectLoggerTlsProbeId, bareRpcProbeClass, Pear doctor / workshop / RTI / user-dirs sketches, Bare logger tap payloads, mTLS proxy map keys, thread-pool telemetry JSON — treat as operator metadata; scrub before cross-tenant export.\n- Capability word 11 fields: hypercorePackHrpcLifecycleProbeId, hypercore replicate budget / drive graph / protomux backpressure / Pear matrix / bundle preload / HRPC allowlist / sidecar cap / git LFS / net QoS / storage tier / indexer catchup / multisig quorum / relay geo sketches — operator hints only; no secret material in stock paths.\n\nStock emitters avoid logging env wholesale; /proc/self/environ omits secret-like keys. Prefer hashed or bucketed counters (e.g. pairing backoff counts) over raw payloads.\n\nGDPR / SUBPROCESSORS (OPERATOR TEMPLATE)\n\nOperators running Bare OS as part of a service should maintain a subprocessor list (who processes telemetry, drive replication, Pear runtime updates, HDMS pairing) and tie it to retention policies. The stock tree does not ship legal text; use this section as a checklist when filling DPA / privacy policy annexes.\n\nSCHEMA VERSIONS\n\n- NDJSON lifecycle / telemetry: see BARE_OS_LIFECYCLE_SCHEMA_VERSION (10 in stock tree) and rows in docs/reference/compatibility-matrix.md <../docs/reference/compatibility-matrix.md>.\n- OTel-inspired lines: otlSchemaVersion: 7, example kernel/etc/bare-os/otel-jsonl.example.json <../kernel/etc/bare-os/otel-jsonl.example.json>, schema docs/schemas/otel-bare-os-jsonl.schema.json <../docs/schemas/otel-bare-os-jsonl.schema.json>.\n- Audit JSON: auditSchemaVersion: 7 (delegate depth / Capability word 9–10 RPC classes); optional requestSmugglingClass remains default none in stock emitters where applicable.\n\nRELATED\n\n- Kernel extensions env table <../docs/reference/kernel-extensions.md>\n- Security and trust <09-security-and-trust.md>","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","13","privacy","telemetry","pii","and","capability","word"],"seeAlso":[{"name":"devguide-bare-boot-kernel-phase-alignment","section":7},{"name":"devguide-12-bare-modules-and-pear-ecosystem","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/13-privacy-telemetry-pii.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-bare-boot-kernel-phase-alignment","section":7,"title":"bare-boot vs stock kernel/init.js phases (alignment)","synopsis":["man 7 devguide-bare-boot-kernel-phase-alignment","Developer guide chapter (developer-guide/bare-boot-kernel-phase-alignment.md)"],"description":"BARE-BOOT VS STOCK KERNEL/INIT.JS PHASES (ALIGNMENT)\n\nHolepunch bare-boot stages an application on disk and hands off to a runtime. Bare OS kernel/init.js is a session kernel on the system Hyperdrive: it configures the guest shell environment, merges boot.policy.json, runs rc.d, kernel.d, and BARE_OS_ONBOOT lines.\n\nROUGH MAPPING (CONCEPTUAL ONLY)\n\n- Resolve entry / bundle — Booter peer wait + drive open — Network / Corestore; optional offline LKG skips peer wait.\n- Materialize files — /boot/init.js load — Kernel bytes from system drive.\n- Apply policy — boot.policy.json merge — Phases skipped, env keys, feature-bit gates, extension deny/pins (v6).\n- Run hooks — rc.local, rc.d, kernel.d, onboot — Ordered snippets; initd starts after boot-ready publishing (booter side).\n- Hand off to app — REPL or SKIP_REPL exit — Not a single “main”; kernel stays in readline unless non-interactive.\n\nThis table is for documentation alignment only — bare-boot is not vendored into the guest image. Prefer Pear IPC and delegate registries for host-specific startup.\n\nSEE ALSO\n\n- KERNEL_CONTRACT — booter boot steps <../docs/architecture/KERNEL_CONTRACT.md>\n- Kernel boot <03-kernel-boot-init.md>\n- Handbook ch. 6 — Kernel and binaries <../handbook/06-kernel-and-binaries.md>\n- bare-subprocess signal → exit <https://github.com/holepunchto/bare-subprocess> (host runtime; compare with ctx subprocess bridge snapshot in kernel-capabilities-index.md <../docs/reference/kernel-capabilities-index.md>)","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","bare","boot","kernel","phase","alignment","stock","init","phases"],"seeAlso":[{"name":"devguide-kernel-explain-and-doctor-conventions","section":7},{"name":"devguide-13-privacy-telemetry-pii","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/bare-boot-kernel-phase-alignment.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-kernel-explain-and-doctor-conventions","section":7,"title":"Kernel doctor and kernel-explain conventions","synopsis":["man 7 devguide-kernel-explain-and-doctor-conventions","Developer guide chapter (developer-guide/kernel-explain-and-doctor-conventions.md)"],"description":"KERNEL DOCTOR AND KERNEL-EXPLAIN CONVENTIONS\n\nStock /bin/kernel-doctor, /bin/kernel-explain, and related tools should emit structured, stable objects for operators:\n\n- Prefer JSON with a top-level schema integer and kind string (boot, vfs, policy, extension, …).\n- Human-oriented message plus machine code (stable identifier, SCREAMING_SNAKE or dotted namespace).\n- Never include secrets (keys, tokens, raw vault bytes); redact paths under personal drive if policy requires.\n\nWhen adding a new diagnostic surface, update handbook, users-manual troubleshooting, and docs/reference proc maps.","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","kernel","explain","and","doctor","conventions"],"seeAlso":[{"name":"devguide-kernel-program","section":7},{"name":"devguide-bare-boot-kernel-phase-alignment","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/kernel-explain-and-doctor-conventions.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-kernel-program","section":7,"title":"Kernel program (governed expansion)","synopsis":["man 7 devguide-kernel-program","Developer guide chapter (developer-guide/kernel-program.md)"],"description":"KERNEL PROGRAM (GOVERNED EXPANSION)\n\nThis document is the governance anchor for the stock kernel expansion: acceptance criteria, traceability to Holepunch Bare stacks (no Node node:* built-ins in guest paths), and operator-facing env and /proc hooks.\n\nIdentifier policy: naming-conventions.md <naming-conventions.md>, naming-migrations.md <naming-migrations.md>, naming-alias-matrix.md <../docs/reference/naming-alias-matrix.md>.\n\nACCEPTANCE CRITERIA (GLOBAL)\n\n1. Bare-only runtime: Guest code uses bare- / pear- modules per bare-node <https://github.com/holepunchto/bare-node> mapping (local mirror: holepunch-repos/holepunchto_repos/bare-node/README.md).\n2. Contracts: Any wire, ctx API, boot policy, or /proc shape change bumps the artifacts in compatibility-matrix.md <../docs/reference/compatibility-matrix.md>.\n3. Docs: Each workstream updates feature-roadmap.md <../docs/reference/feature-roadmap.md>, kernel-extensions.md <../docs/reference/kernel-extensions.md>, and the relevant handbook / users-manual / schema files.\n4. Tests: Stock kernel and booter tests cover new boot env flags and proc JSON where applicable.\n\nPROGRAM VERSION\n\n| Artifact | Value |\n| Proc schema | 2 (see /proc/bare_os/kernel_program.json) |\n| programVersion | 2 |\n| Primary proc path | /proc/bare_os/kernel_program.json |\n| Legacy filename (same payload) | /proc/bare_os/giant_phase_program.json |\n| Flat underscore alias | /proc/bare_os_kernel_program.json / /proc/bare_os_giant_phase_program.json |\n\nBACKLOG BATCHES (200 ITEMS)\n\nTwo batches of 100 items each (200 rows total) are tracked in feature-roadmap.md <../docs/reference/feature-roadmap.md> under Kernel program backlog — batch A and batch B.\n\nHighlights shipped in-tree:\n\n- Boot: named bootStage on transaction journal lines and boot checkpoints (schema 2); BARE_OS_BOOT_DRY_RUN; policyFallbackPaths merge; BARE_OS_BOOT_POLICY_PATH; rollback skips via /run/bare-os/boot-rollback.marker + BARE_OS_BOOT_ROLLBACK_APPLY; requireBootBundleSha256Hex + BARE_OS_BOOT_BUNDLE_DIGEST_HEX; BARE_OS_REQUIRE_CTX_API_MIN / BARE_OS_BOOT_ABI_STRICT; initdAdmission → initd env hints; # ConditionEnvironment= / # AssertEnvironment= guards in kernel.d snippets; bootPhases detail on bareOsPublishBootReady.\n- Booter: /run/bare-os/services.json seed; optional BARE_OS_LOADER_AUDIT → /run/bare-os/loader-audit.ndjson; bareOsEmitKernelEvent / bareOsSubscribeKernelEvent; bareOsAcquireKeyHandle (opaque key broker sketch); operatorSketches in /proc/bare_os/kernel_program.json (env JSON).\n- Binaries: kernel-boot-diff, kernel-preflight, kernel-triage, kernel-manifest-validate, kernel-fsck, kernel-home-snapshot (VFS home-tree manifest walker; see packages/bare-os-coreutils/src/kernel-home-snapshot.js); kernel/lib/bare/shell-completion.json generated from commands.mjs.\n- CI: verify-kernel-program-proc-schema.mjs, verify-kernel-program-roadmap-table.mjs, fuzz-boot-policy-json.mjs, kernel-program-release-gate.mjs, kernel-microbench.mjs (multi-suite microbenches: syscall — repeated buildBareOsSyscallsProcJson + JSON.stringify; vfs — adds warmReplicationPathClassify for warm-cache / replication path sketches; see scripts/README.md <../scripts/README.md>).\n\nENVIRONMENT HOOKS (STOCK KERNEL + BOOTER)\n\n| Variable | Purpose |\n| BARE_OS_BOOT_SAFE_MODE | 1 / true — skip rc.d, kernel.ext.d, and onboot after policy merge (recovery-oriented). |\n| BARE_OS_BOOT_TRANSACTION_JOURNAL | 1 / true / ndjson — append boot phase records to /run/bare-os/boot-transaction.ndjson when ctx.vfs supports it. |\n| BARE_OS_BOOT_CHECKPOINT | 1 / true — write /run/bare-os/boot-checkpoint.json after each boot phase (schema 2 includes bootStage). |\n| BARE_OS_BOOT_DRY_RUN | 1 / true — parse boot snippets; skip trusted execLine and kernel.ext.d script execution (CI). |\n| BARE_OS_BOOT_POLICY_PATH | Optional absolute path under /etc/bare-os/ for the primary policy file (default /etc/bare-os/boot.policy.json). |\n| BARE_OS_BOOT_ROLLBACK_APPLY | 1 — merge skipPhases / denyBootPhases from /run/bare-os/boot-rollback.marker JSON when present. |\n| BARE_OS_BOOT_BUNDLE_DIGEST_HEX | Operator-supplied hex digest matched against optional policy requireBootBundleSha256Hex. |\n| BARE_OS_REQUIRE_CTX_API_MIN | Minimum ctx.bareOsCtxApiVersion semver; fails when BARE_OS_BOOT_ABI_STRICT or strict boot policy is on. |\n| BARE_OS_BOOT_ABI_STRICT | 1 — exit boot when ABI min is not satisfied. |\n| BARE_OS_LOADER_AUDIT | 1 — append kernel extension loads to /run/bare-os/loader-audit.ndjson. |\n| BARE_OS_KERNEL_PROGRAM_PROC_JSON | Optional override JSON merged into the kernel program proc snapshot (bounded; non-secret). |\n| BARE_OS_GIANT_PHASE_PROGRAM_JSON | Legacy alias for the same override (non-secret). |\n\nSketches under operatorSketches also honor legacy env names where documented (for example BARE_OS_GP2_NET_DELEGATE_SKETCH_JSON, BARE_OS_OTEL_RESOURCE_ATTRS_GP2_JSON) alongside the preferred BARE_OS_NET_DELEGATE_SKETCH_JSON and BARE_OS_OTEL_RESOURCE_ATTRS_KERNEL_JSON.\n\nKERNEL.EXT.D DROP-IN EXTENSIONS\n\nIn addition to scripts, id, dependsOn, and signaturePointer, drop-ins may set:\n\n- requires — string array, merged into dependsOn (same semantics).\n- after — extension ids that must load before this drop-in (appended to dependsOn).\n- before — extension ids that must load after this drop-in (those ids gain a dependency on this drop-in’s id).\n\nWith BARE_OS_KERNEL_EXT_GRAPH=1, the stock kernel writes /run/bare-os/kernel-ext-graph.json after ordering (shape in docs/schemas/kernel-ext-graph.example.json <../docs/schemas/kernel-ext-graph.example.json>).\n\nBATCH A TRACEABILITY (SUMMARY)\n\nItems 1–100 map to the first approved plan (boot graph, journal, safe mode, extension ordering, module policy, process/IPC, VFS, networking, security, telemetry, upgrades, dev UX, benchmarks). Implementation status:\n\n- Shipped in tree: boot safe mode, transaction journal, checkpoints, before/after/requires for kernel.ext.d, /proc/bare_os/kernel_program.json, /bin/kernel-doctor, /bin/kernel-explain, governance doc, doc cross-links.\n- Framework / operator hooks: remaining items are tracked via env-driven proc sketches, boot policy versions, and feature-roadmap.md <../docs/reference/feature-roadmap.md>.\n\nSEE ALSO\n\n- 03-kernel-boot-init.md <./03-kernel-boot-init.md>\n- 02-the-context-object.md <./02-the-context-object.md>\n- node-to-bare-modules.md <./node-to-bare-modules.md> — import maps, bare-module, manifest / dual-target notes\n- Handbook ch.11 — Kernel program <../handbook/11-kernel-program-and-research.md>","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","kernel","program","governed","expansion"],"seeAlso":[{"name":"devguide-naming-conventions","section":7},{"name":"devguide-kernel-explain-and-doctor-conventions","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/kernel-program.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-naming-conventions","section":7,"title":"Naming conventions (first-party vs vendored)","synopsis":["man 7 devguide-naming-conventions","Developer guide chapter (developer-guide/naming-conventions.md)"],"description":"NAMING CONVENTIONS (FIRST-PARTY VS VENDORED)\n\nThis repository distinguishes first-party Bare OS sources from vendored third-party trees. Governance wording rules and identifier style apply differently in each.\n\nFIRST-PARTY TREES\n\nSubject to kernel program <kernel-program.md> vocabulary, CI terminology checks (scripts/verify-banned-terminology.mjs), and the alias matrix (Naming alias matrix <../docs/reference/naming-alias-matrix.md>):\n\n- packages/bare-os-booter/, packages/bare-os-protocol/, packages/bare-os-coreutils/, packages/bare-os-seeder/ (except its vendored subtree below)\n- kernel/ except kernel/lib/bare/\n- docs/, handbook/, developer-guide/, users-manual/, scripts/\n\nPrefer boot stage / boot step / capability word language in new prose and APIs. When renaming symbols, keep deprecated aliases until the published deprecation window ends (see Naming migrations <naming-migrations.md>).\n\nVENDORED EXCEPTION\n\nkernel/lib/bare/ (mirrored under packages/bare-os-seeder/kernel/lib/bare/) is vendored. It may contain legacy English tokens, upstream identifiers, and MIME-adjacent strings. The terminology verifier skips this subtree entirely.\n\nENVIRONMENT VARIABLES\n\n- Prefix operational flags with BARE_OS_.\n- Prefer _BOOT_SKIP_STAGES over legacy _BOOT_SKIP spellings where both exist; document aliases in the naming alias matrix.\n\nCTX METHODS\n\n- New APIs use bareOs… camelCase on the injected context object.\n- Canonical boot hook names: bareOsRegisterBootStepHook, bareOsInvokeBootStepHooks, bareOsEmitBareBootStepHint. Legacy …BootPhase… methods remain as thin wrappers.\n\n/PROC AND WIRE-VISIBLE PATHS\n\n- Do not remove legacy proc filenames or JSON keys without a versioned alias period. Internal variable names may use neutral wording while on-disk names stay stable.\n\nEXTENSION AND CAPABILITY IDENTIFIERS\n\n- Use stable string keys aligned with packages/bare-os-protocol capability documentation and docs/schemas/ where applicable.","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","naming","conventions","first","party","vendored"],"seeAlso":[{"name":"devguide-naming-migrations","section":7},{"name":"devguide-kernel-program","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/naming-conventions.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-naming-migrations","section":7,"title":"Naming and contract migrations","synopsis":["man 7 devguide-naming-migrations","Developer guide chapter (developer-guide/naming-migrations.md)"],"description":"NAMING AND CONTRACT MIGRATIONS\n\nThis page tracks non-breaking renames and compatibility paths. Handbook, user manual, and reference docs should stay aligned when entries here change.\n\nBOOT HOOK API (CTX)\n\n| Canonical (preferred) | Legacy alias | Notes |\n| bareOsRegisterBootStepHook(step, fn) | bareOsRegisterBootPhaseHook(phase, fn) | Same matching rules; step and phase are the same string keyspace. |\n| bareOsInvokeBootStepHooks(ev) | bareOsInvokeBootPhaseHooks(ev) | Event objects may include phase, step, and when; hooks match on phase / when:phase as before. |\n| bareOsEmitBareBootStepHint(payload) | bareOsEmitBareBootPhaseHint(payload) | Accepts step or phase in payload; host event name unchanged for listeners. |\n\nDeprecation: legacy names remain supported; no removal date is set until downstream consumers migrate.\n\nBOOT POLICY JSON\n\n| Canonical key(s) | Legacy alias(es) |\n| skipBootStages, denyBootStages | skipPhases, denyBootPhases |\n| bootStagesRequireProcIndexMinSchema | bootPhasesRequireProcIndexMinSchema |\n| bootStagesRequireLifecycleMinSchema | bootPhasesRequireLifecycleMinSchema |\n\nMerge logic accepts both names; first-party docs should cite canonical keys only.\n\nBOOT READY / JOURNAL PAYLOADS\n\n- bareOsPublishBootReady may expose both stages / phases and bootStages / bootPhases mirrors for consumers. Prefer stages / bootStages in new code.\n\nBOOT TRACE JSON (BARE_OS_BOOT_TRACE=JSON)\n\n- Schema bootTraceSchemaVersion: 2 adds canonical step alongside stage and legacy phase (mirror). Parsers should prefer step.\n\nCI GATES\n\n- npm run pretest runs bundle:kernel, verify-banned-terminology, verify-naming-alias-matrix, verify-feature-roadmap-canonical, verify-no-new-giant-phase-identifiers, compatibility matrix checks, and contract verifiers. Changing bareOsCtxApiVersion or capability bits requires updating the linked scripts and docs listed in the root package.json pretest chain.","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","naming","migrations","and","contract"],"seeAlso":[{"name":"devguide-node-to-bare-modules","section":7},{"name":"devguide-naming-conventions","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/naming-migrations.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"},{"name":"devguide-node-to-bare-modules","section":7,"title":"Node built-ins → Bare / Pear modules (guest-safe)","synopsis":["man 7 devguide-node-to-bare-modules","Developer guide chapter (developer-guide/node-to-bare-modules.md)"],"description":"NODE BUILT-INS → BARE / PEAR MODULES (GUEST-SAFE)\n\nFIRST-PARTY KERNEL SOURCES VS VENDORED IIFE BUNDLES\n\nFirst-party “no incomplete markers” policy applies only to hand-authored runtime JavaScript scanned by scripts/verify-runtime-no-incomplete-markers.mjs:\n\n- kernel/init.js <../kernel/init.js> (generated — see below)\n- kernel/lib/init/init-main.js <../kernel/lib/init/init-main.js>\n- kernel/lib/boot/*.js <../kernel/lib/boot/> (boot fragments prepended into init.js)\n- kernel/bin/*.js <../kernel/bin/> (hand-written /bin shims and helpers staged to the image)\n- packages/bare-os-booter/index.js <../packages/bare-os-booter/index.js> and packages/bare-os-booter/lib/*.js <../packages/bare-os-booter/lib/> (trusted host booter)\n\nExcluded from that scan: everything under kernel/lib/bare/bundles/ (and the seeder mirror). Those files are upstream IIFE bundles from packages/bare-os-bare-libs <../packages/bare-os-bare-libs>. They may contain Node-compat patterns such as abstract stream base classes that throw not implemented when subclasses omit hooks. Governance is separate:\n\n- scripts/verify-bundle-markers.mjs + docs/audit/bundle-marker-allowlist.json <../docs/audit/bundle-marker-allowlist.json>\n- scripts/verify-bundle-throws.mjs + docs/audit/bundle-throw-allowlist.json <../docs/audit/bundle-throw-allowlist.json>\n\nSee also docs/audit/PLACEHOLDER_BASELINE.md <../docs/audit/PLACEHOLDER_BASELINE.md> and kernel/lib/bare/README.md <../kernel/lib/bare/README.md>.\n\nBundle refresh governance (maintainers): after changing Holepunch pins or kernel/lib/bare/manifest.json, run npm run gen:bare-catalog (or :check), npm run build -w bare-os-bare-libs, npm run bundle:kernel, then node scripts/verify-kernel-seeder-parity.mjs. Optional: npm run audit:holepunch-clones and node scripts/verify-holepunch-clone-drift.mjs when local clones under BARE_OS_HOLEPUNCH_CLONES_ROOT track upstream. Release checklist runs report-holepunch-lockfile-drift.mjs and clone drift verification.\n\nkernel/init.js is generated: run node scripts/bundle-kernel-init.mjs after editing kernel/lib/boot/*.js or kernel/lib/init/init-main.js. scripts/verify-kernel-seeder-parity.mjs checks that the file matches that recipe and that kernel/ matches packages/bare-os-seeder/kernel/ byte-for-byte.\n\nBare OS guest code (kernel /boot/init.js, /bin utilities running in the Pear/Bare host) must not rely on Node’s *node: built-in specifiers. Use Holepunch bare- packages (local clones under holepunchto <https://github.com/holepunchto>) instead. Validate kernel/lib/bare/manifest.json with kernel-manifest-validate; optional per-row dualTarget*: bare-only | dual | host-delegate-only for extension policy; import-map templates live beside package.json on trusted images (see kernel-program.md <./kernel-program.md>).\n\n- node:crypto — bare-crypto <https://github.com/holepunchto/bare-crypto> — host sets BARE_OS_BARE_CRYPTO_VERSION for boot policy requireBareCryptoMin.\n- node:module / createRequire — bare-module <https://github.com/holepunchto/bare-module>, bare-module-resolve <https://github.com/holepunchto/bare-module-resolve> — boot policy may list denyBareModuleSpecifierPatterns.\n- node:fs — bare-fs <https://github.com/holepunchto/bare-fs> — guest uses ctx.vfs for the image.\n- node:path — bare-path <https://github.com/holepunchto/bare-path>\n- node:url — bare-url <https://github.com/holepunchto/bare-url>\n- node:net / node:tls — bare-net <https://github.com/holepunchto/bare-net>, bare-tls <https://github.com/holepunchto/bare-tls>, bare-tcp <https://github.com/holepunchto/bare-tcp>\n- node:http / node:https — bare-http1 <https://github.com/holepunchto/bare-http1>, bare-https <https://github.com/holepunchto/bare-https>; ctx may expose wrapped fetch.\n- node:worker_threads — bare-worker <https://github.com/holepunchto/bare-worker>, bare-thread <https://github.com/holepunchto/bare-thread>\n- node:diagnostics_channel — bare-diagnostics-channel <https://github.com/holepunchto/bare-diagnostics-channel>\n- WebSockets / WS upgrade paths — bare-ws <https://github.com/holepunchto/bare-ws> — pair with bare-http1 / bare-tls for gateways; see handbook ch.11 / transport table in kernel-extensions.md <../docs/reference/kernel-extensions.md>.\n- Inspector-style probes (non-secret) — bare-inspect <https://github.com/holepunchto/bare-inspect> — boot policy maxPearInspectDepth caps nested inspect hints merged from boot.policy.json.\n- RPC-style delegates — bare-rpc <https://github.com/holepunchto/bare-rpc> — boot policy denyBareRpcMethodPatterns can deny method-class patterns before they reach guest-visible ctx probes.\n\nStock /bin/openssl is a stub that points integrators at bare-crypto (see packages/bare-os-coreutils/src/openssl.js <../../packages/bare-os-coreutils/src/openssl.js>).\n\nSee also kernel-extensions.md <../docs/reference/kernel-extensions.md>, handbook ch.11 <../handbook/11-kernel-program-and-research.md>, and CI verify-pear-no-static-node-import.mjs.\n\nWord 11 (hypercore / pack / HRPC lifecycle): stock boot policy may pin bare-pack / bare-addon-policy (and related) versions via host env keys surfaced in boot.policy.json v11; Hypercore/replication-heavy guests should prefer Holepunch *bare- modules over Node node: for the same capability areas as in the table above (see bits11 / BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_HRPC_LIFECYCLE* in compatibility-matrix.md <../docs/reference/compatibility-matrix.md>).","descriptionMode":"preserve","options":[],"keywords":["developer","devguide","develop","script","asyncfunction","ctx","bare-os","guide","node","to","bare","modules","built","ins","pear","guest","safe"],"seeAlso":[{"name":"devguide-naming-migrations","section":7},{"name":"man","section":1},{"name":"bare-os-handbook","section":7}],"bareOsNotes":"Generated at build time from developer-guide/node-to-bare-modules.md. Mermaid diagrams omitted in terminal; see repo Markdown for figures.","listCategory":"devguide"}],"index":{"arch":0,"awk":1,"baretop":2,"btop":3,"base32":4,"base64":5,"basename":6,"basenc":7,"cat":8,"chgrp":9,"chmod":10,"chown":11,"cksum":12,"clear":13,"comm":14,"cmp":15,"cp":16,"crontab":17,"curl":18,"cut":19,"date":20,"dd":21,"df":22,"diff":23,"dir":24,"dirname":25,"dircolors":26,"du":27,"edit":28,"echo":29,"env":30,"exit":31,"expand":32,"expr":33,"factor":34,"false":35,"find":36,"fmt":37,"fold":38,"getconf":39,"getfacl":40,"git-pear":41,"grep":42,"groups":43,"head":44,"hdms":45,"help":46,"hostid":47,"hostname":48,"iconv":49,"id":50,"install":51,"join":52,"kill":53,"kernel-boot-diff":54,"kernel-doctor":55,"kernel-explain":56,"kernel-fsck":57,"kernel-home-snapshot":58,"kernel-manifest-validate":59,"kernel-preflight":60,"kernel-triage":61,"jq":62,"ln":63,"link":64,"logger":65,"login":66,"logout":67,"logname":68,"ls":69,"man":70,"md5sum":71,"mkdir":72,"mkfifo":73,"mktemp":74,"mount":75,"mv":76,"nano":77,"nl":78,"nohup":79,"nproc":80,"numfmt":81,"od":82,"openssl":83,"oidc-publish":84,"paste":85,"patch":86,"pathchk":87,"pr":88,"printenv":89,"printf":90,"procstat":91,"ps":92,"pwd":93,"readlink":94,"realpath":95,"rev":96,"rm":97,"rmdir":98,"savevault":99,"sed":100,"seq":101,"setfacl":102,"sha1sum":103,"sha256sum":104,"sha512sum":105,"sh":106,"shuf":107,"sleep":108,"sort":109,"split":110,"ssh-keygen":111,"stat":112,"sum":113,"sync":114,"tar":115,"tac":116,"tail":117,"tee":118,"test":119,"theme":120,"time":121,"timeout":122,"touch":123,"tr":124,"truncate":125,"true":126,"tsort":127,"tty":128,"ulimit":129,"uname":130,"uniq":131,"unlink":132,"umount":133,"unexpand":134,"uptime":135,"users":136,"vdir":137,"wc":138,"wget":139,"which":140,"who":141,"whoami":142,"xattr":143,"xargs":144,"yes":145,"bare-cron":146,"bare-os-ctx-bare":147,"bare-os-shell":148,"sh-builtins":148,"systemctl":149,"bare-initctl":149,"git":150,"bare-os-handbook":151,"handbook":151,"bare-os-handbook-index":151,"handbook-00-preface":152,"handbook-01-introduction":153,"handbook-02-blueprints":154,"handbook-03-protocol-and-disk":155,"handbook-04-the-booter-runtime":156,"handbook-05-identity-vault-and-hdms":157,"handbook-06-kernel-and-binaries":158,"handbook-07-operations-and-development":159,"handbook-08-git-on-bare-os":160,"handbook-09-posix-utilities-shell-and-vfs":161,"handbook-10-manpages-and-online-help":162,"handbook-11-kernel-program-and-research":163,"handbook-12-p2p-stack-and-posix-boundaries":164,"bare-os-developer-guide":165,"developer-guide":165,"devguide":165,"devguide-01-two-runtimes-host-vs-image":166,"devguide-02-the-context-object":167,"devguide-03-kernel-boot-init":168,"devguide-04-user-scripts-and-path":169,"devguide-05-modules-and-imports":170,"devguide-06-extending-bin-coreutils":171,"devguide-07-apps-beyond-the-shell":172,"devguide-08-testing-and-debugging":173,"devguide-09-security-and-trust":174,"devguide-10-glossary-and-faq":175,"devguide-11-kernel-pear-cookbook":176,"devguide-12-bare-modules-and-pear-ecosystem":177,"devguide-13-privacy-telemetry-pii":178,"devguide-bare-boot-kernel-phase-alignment":179,"devguide-kernel-explain-and-doctor-conventions":180,"devguide-kernel-program":181,"devguide-naming-conventions":182,"devguide-naming-migrations":183,"devguide-node-to-bare-modules":184},"apropos":[{"kw":"arch","pageRef":0},{"kw":"bare-os","pageRef":0},{"kw":"coreutils","pageRef":0},{"kw":"awk","pageRef":1},{"kw":"pattern","pageRef":1},{"kw":"field","pageRef":1},{"kw":"script","pageRef":1},{"kw":"scanning","pageRef":1},{"kw":"and","pageRef":1},{"kw":"processing","pageRef":1},{"kw":"language","pageRef":1},{"kw":"print","pageRef":1},{"kw":"column","pageRef":1},{"kw":"1","pageRef":1},{"kw":"separator","pageRef":1},{"kw":"sum","pageRef":1},{"kw":"numbers","pageRef":1},{"kw":"in","pageRef":1},{"kw":"first","pageRef":1},{"kw":"lines","pageRef":1},{"kw":"matching","pageRef":1},{"kw":"re","pageRef":1},{"kw":"baretop","pageRef":2},{"kw":"bare-os","pageRef":2},{"kw":"coreutils","pageRef":2},{"kw":"btop","pageRef":3},{"kw":"bare-os","pageRef":3},{"kw":"coreutils","pageRef":3},{"kw":"base32","pageRef":4},{"kw":"bare-os","pageRef":4},{"kw":"coreutils","pageRef":4},{"kw":"base64","pageRef":5},{"kw":"bare-os","pageRef":5},{"kw":"coreutils","pageRef":5},{"kw":"basename","pageRef":6},{"kw":"bare-os","pageRef":6},{"kw":"coreutils","pageRef":6},{"kw":"strip","pageRef":6},{"kw":"directory","pageRef":6},{"kw":"and","pageRef":6},{"kw":"suffix","pageRef":6},{"kw":"from","pageRef":6},{"kw":"pathnames","pageRef":6},{"kw":"basenc","pageRef":7},{"kw":"bare-os","pageRef":7},{"kw":"coreutils","pageRef":7},{"kw":"cat","pageRef":8},{"kw":"bare-os","pageRef":8},{"kw":"coreutils","pageRef":8},{"kw":"concatenate","pageRef":8},{"kw":"and","pageRef":8},{"kw":"print","pageRef":8},{"kw":"files","pageRef":8},{"kw":"stdout","pageRef":8},{"kw":"several","pageRef":8},{"kw":"number","pageRef":8},{"kw":"lines","pageRef":8},{"kw":"use","pageRef":8},{"kw":"nl","pageRef":8},{"kw":"here-string","pageRef":8},{"kw":"via","pageRef":8},{"kw":"echo","pageRef":8},{"kw":"pipe","pageRef":8},{"kw":"chgrp","pageRef":9},{"kw":"bare-os","pageRef":9},{"kw":"coreutils","pageRef":9},{"kw":"change","pageRef":9},{"kw":"file","pageRef":9},{"kw":"group","pageRef":9},{"kw":"ownership","pageRef":9},{"kw":"set","pageRef":9},{"kw":"by","pageRef":9},{"kw":"name","pageRef":9},{"kw":"chmod","pageRef":10},{"kw":"mode","pageRef":10},{"kw":"permission","pageRef":10},{"kw":"octal","pageRef":10},{"kw":"symbolic","pageRef":10},{"kw":"change","pageRef":10},{"kw":"file","pageRef":10},{"kw":"bits","pageRef":10},{"kw":"recursive-ish","pageRef":10},{"kw":"run","pageRef":10},{"kw":"find","pageRef":10},{"kw":"per","pageRef":10},{"kw":"user","pageRef":10},{"kw":"all","pageRef":10},{"kw":"read","pageRef":10},{"kw":"owner","pageRef":10},{"kw":"write","pageRef":10},{"kw":"chown","pageRef":11},{"kw":"bare-os","pageRef":11},{"kw":"coreutils","pageRef":11},{"kw":"change","pageRef":11},{"kw":"file","pageRef":11},{"kw":"owner","pageRef":11},{"kw":"and","pageRef":11},{"kw":"group","pageRef":11},{"kw":"only","pageRef":11},{"kw":"numeric","pageRef":11},{"kw":"ids","pageRef":11},{"kw":"cksum","pageRef":12},{"kw":"bare-os","pageRef":12},{"kw":"coreutils","pageRef":12},{"kw":"write","pageRef":12},{"kw":"file","pageRef":12},{"kw":"checksums","pageRef":12},{"kw":"and","pageRef":12},{"kw":"sizes","pageRef":12},{"kw":"checksum","pageRef":12},{"kw":"verify","pageRef":12},{"kw":"pipeline","pageRef":12},{"kw":"clear","pageRef":13},{"kw":"bare-os","pageRef":13},{"kw":"coreutils","pageRef":13},{"kw":"the","pageRef":13},{"kw":"terminal","pageRef":13},{"kw":"screen","pageRef":13},{"kw":"wipe","pageRef":13},{"kw":"comm","pageRef":14},{"kw":"bare-os","pageRef":14},{"kw":"coreutils","pageRef":14},{"kw":"cmp","pageRef":15},{"kw":"bare-os","pageRef":15},{"kw":"coreutils","pageRef":15},{"kw":"cp","pageRef":16},{"kw":"bare-os","pageRef":16},{"kw":"coreutils","pageRef":16},{"kw":"copy","pageRef":16},{"kw":"files","pageRef":16},{"kw":"file","pageRef":16},{"kw":"into","pageRef":16},{"kw":"directory","pageRef":16},{"kw":"preserve","pageRef":16},{"kw":"implied","pageRef":16},{"kw":"if","pageRef":16},{"kw":"implemented","pageRef":16},{"kw":"crontab","pageRef":17},{"kw":"bare-os","pageRef":17},{"kw":"coreutils","pageRef":17},{"kw":"user","pageRef":17},{"kw":"manipulation","pageRef":17},{"kw":"list","pageRef":17},{"kw":"jobs","pageRef":17},{"kw":"install","pageRef":17},{"kw":"from","pageRef":17},{"kw":"file","pageRef":17},{"kw":"remove","pageRef":17},{"kw":"all","pageRef":17},{"kw":"curl","pageRef":18},{"kw":"bare-os","pageRef":18},{"kw":"coreutils","pageRef":18},{"kw":"cut","pageRef":19},{"kw":"bare-os","pageRef":19},{"kw":"coreutils","pageRef":19},{"kw":"out","pageRef":19},{"kw":"selected","pageRef":19},{"kw":"fields","pageRef":19},{"kw":"of","pageRef":19},{"kw":"each","pageRef":19},{"kw":"line","pageRef":19},{"kw":"by","pageRef":19},{"kw":"delimiter","pageRef":19},{"kw":"characters","pageRef":19},{"kw":"date","pageRef":20},{"kw":"bare-os","pageRef":20},{"kw":"coreutils","pageRef":20},{"kw":"display","pageRef":20},{"kw":"or","pageRef":20},{"kw":"set","pageRef":20},{"kw":"and","pageRef":20},{"kw":"time","pageRef":20},{"kw":"rfc-ish","pageRef":20},{"kw":"output","pageRef":20},{"kw":"epoch","pageRef":20},{"kw":"seconds","pageRef":20},{"kw":"dd","pageRef":21},{"kw":"bare-os","pageRef":21},{"kw":"coreutils","pageRef":21},{"kw":"df","pageRef":22},{"kw":"bare-os","pageRef":22},{"kw":"coreutils","pageRef":22},{"kw":"diff","pageRef":23},{"kw":"bare-os","pageRef":23},{"kw":"coreutils","pageRef":23},{"kw":"dir","pageRef":24},{"kw":"bare-os","pageRef":24},{"kw":"coreutils","pageRef":24},{"kw":"dirname","pageRef":25},{"kw":"bare-os","pageRef":25},{"kw":"coreutils","pageRef":25},{"kw":"return","pageRef":25},{"kw":"directory","pageRef":25},{"kw":"portion","pageRef":25},{"kw":"of","pageRef":25},{"kw":"a","pageRef":25},{"kw":"pathname","pageRef":25},{"kw":"parent","pageRef":25},{"kw":"path","pageRef":25},{"kw":"compose","pageRef":25},{"kw":"with","pageRef":25},{"kw":"basename","pageRef":25},{"kw":"dircolors","pageRef":26},{"kw":"ls_colors","pageRef":26},{"kw":"color","pageRef":26},{"kw":"du","pageRef":27},{"kw":"bare-os","pageRef":27},{"kw":"coreutils","pageRef":27},{"kw":"estimate","pageRef":27},{"kw":"file","pageRef":27},{"kw":"space","pageRef":27},{"kw":"usage","pageRef":27},{"kw":"sizes","pageRef":27},{"kw":"under","pageRef":27},{"kw":"cwd","pageRef":27},{"kw":"human","pageRef":27},{"kw":"if","pageRef":27},{"kw":"supported","pageRef":27},{"kw":"edit","pageRef":28},{"kw":"bare-os","pageRef":28},{"kw":"coreutils","pageRef":28},{"kw":"echo","pageRef":29},{"kw":"bare-os","pageRef":29},{"kw":"coreutils","pageRef":29},{"kw":"write","pageRef":29},{"kw":"arguments","pageRef":29},{"kw":"to","pageRef":29},{"kw":"standard","pageRef":29},{"kw":"output","pageRef":29},{"kw":"literal","pageRef":29},{"kw":"no","pageRef":29},{"kw":"newline","pageRef":29},{"kw":"if","pageRef":29},{"kw":"-n","pageRef":29},{"kw":"supported","pageRef":29},{"kw":"env","pageRef":30},{"kw":"bare-os","pageRef":30},{"kw":"coreutils","pageRef":30},{"kw":"set","pageRef":30},{"kw":"the","pageRef":30},{"kw":"environment","pageRef":30},{"kw":"for","pageRef":30},{"kw":"command","pageRef":30},{"kw":"invocation","pageRef":30},{"kw":"print","pageRef":30},{"kw":"run","pageRef":30},{"kw":"with","pageRef":30},{"kw":"override","pageRef":30},{"kw":"exit","pageRef":31},{"kw":"bare-os","pageRef":31},{"kw":"coreutils","pageRef":31},{"kw":"the","pageRef":31},{"kw":"shell","pageRef":31},{"kw":"or","pageRef":31},{"kw":"booter","pageRef":31},{"kw":"session","pageRef":31},{"kw":"leave","pageRef":31},{"kw":"with","pageRef":31},{"kw":"status","pageRef":31},{"kw":"from","pageRef":31},{"kw":"script","pageRef":31},{"kw":"expand","pageRef":32},{"kw":"bare-os","pageRef":32},{"kw":"coreutils","pageRef":32},{"kw":"expr","pageRef":33},{"kw":"bare-os","pageRef":33},{"kw":"coreutils","pageRef":33},{"kw":"factor","pageRef":34},{"kw":"bare-os","pageRef":34},{"kw":"coreutils","pageRef":34},{"kw":"false","pageRef":35},{"kw":"bare-os","pageRef":35},{"kw":"coreutils","pageRef":35},{"kw":"return","pageRef":35},{"kw":"value","pageRef":35},{"kw":"force","pageRef":35},{"kw":"failure","pageRef":35},{"kw":"in","pageRef":35},{"kw":"pipeline","pageRef":35},{"kw":"tests","pageRef":35},{"kw":"find","pageRef":36},{"kw":"directory","pageRef":36},{"kw":"walk","pageRef":36},{"kw":"search","pageRef":36},{"kw":"files","pageRef":36},{"kw":"by","pageRef":36},{"kw":"name","pageRef":36},{"kw":"glob","pageRef":36},{"kw":"directories","pageRef":36},{"kw":"only","pageRef":36},{"kw":"max","pageRef":36},{"kw":"depth","pageRef":36},{"kw":"or","pageRef":36},{"kw":"names","pageRef":36},{"kw":"fmt","pageRef":37},{"kw":"bare-os","pageRef":37},{"kw":"coreutils","pageRef":37},{"kw":"fold","pageRef":38},{"kw":"bare-os","pageRef":38},{"kw":"coreutils","pageRef":38},{"kw":"getconf","pageRef":39},{"kw":"bare-os","pageRef":39},{"kw":"coreutils","pageRef":39},{"kw":"get","pageRef":39},{"kw":"configuration","pageRef":39},{"kw":"values","pageRef":39},{"kw":"path","pageRef":39},{"kw":"length","pageRef":39},{"kw":"limit","pageRef":39},{"kw":"list","pageRef":39},{"kw":"known","pageRef":39},{"kw":"names","pageRef":39},{"kw":"and","pageRef":39},{"kw":"getfacl","pageRef":40},{"kw":"bare-os","pageRef":40},{"kw":"coreutils","pageRef":40},{"kw":"git-pear","pageRef":41},{"kw":"bare-os","pageRef":41},{"kw":"coreutils","pageRef":41},{"kw":"grep","pageRef":42},{"kw":"search","pageRef":42},{"kw":"regex","pageRef":42},{"kw":"pattern","pageRef":42},{"kw":"filter","pageRef":42},{"kw":"matching","pageRef":42},{"kw":"utility","pageRef":42},{"kw":"recursive","pageRef":42},{"kw":"feel","pageRef":42},{"kw":"each","pageRef":42},{"kw":"file","pageRef":42},{"kw":"case","pageRef":42},{"kw":"insensitive","pageRef":42},{"kw":"invert","pageRef":42},{"kw":"lines","pageRef":42},{"kw":"without","pageRef":42},{"kw":"fixed","pageRef":42},{"kw":"string","pageRef":42},{"kw":"no","pageRef":42},{"kw":"count","pageRef":42},{"kw":"matches","pageRef":42},{"kw":"only","pageRef":42},{"kw":"filenames","pageRef":42},{"kw":"multiple","pageRef":42},{"kw":"patterns","pageRef":42},{"kw":"groups","pageRef":43},{"kw":"bare-os","pageRef":43},{"kw":"coreutils","pageRef":43},{"kw":"head","pageRef":44},{"kw":"bare-os","pageRef":44},{"kw":"coreutils","pageRef":44},{"kw":"copy","pageRef":44},{"kw":"the","pageRef":44},{"kw":"first","pageRef":44},{"kw":"part","pageRef":44},{"kw":"of","pageRef":44},{"kw":"files","pageRef":44},{"kw":"10","pageRef":44},{"kw":"lines","pageRef":44},{"kw":"n","pageRef":44},{"kw":"stdin","pageRef":44},{"kw":"hdms","pageRef":45},{"kw":"hyperswarm","pageRef":45},{"kw":"map","pageRef":45},{"kw":"distributed","pageRef":45},{"kw":"store","pageRef":45},{"kw":"when","pageRef":45},{"kw":"booter","pageRef":45},{"kw":"wires","pageRef":45},{"kw":"otherwise","pageRef":45},{"kw":"help","pageRef":46},{"kw":"summary","pageRef":46},{"kw":"builtins","pageRef":46},{"kw":"commands","pageRef":46},{"kw":"bare","pageRef":46},{"kw":"os","pageRef":46},{"kw":"quick","pageRef":46},{"kw":"index","pageRef":46},{"kw":"then","pageRef":46},{"kw":"deep","pageRef":46},{"kw":"dive","pageRef":46},{"kw":"hostid","pageRef":47},{"kw":"bare-os","pageRef":47},{"kw":"coreutils","pageRef":47},{"kw":"hostname","pageRef":48},{"kw":"bare-os","pageRef":48},{"kw":"coreutils","pageRef":48},{"kw":"set","pageRef":48},{"kw":"or","pageRef":48},{"kw":"print","pageRef":48},{"kw":"show","pageRef":48},{"kw":"host","pageRef":48},{"kw":"iconv","pageRef":49},{"kw":"bare-os","pageRef":49},{"kw":"coreutils","pageRef":49},{"kw":"id","pageRef":50},{"kw":"bare-os","pageRef":50},{"kw":"coreutils","pageRef":50},{"kw":"return","pageRef":50},{"kw":"user","pageRef":50},{"kw":"identity","pageRef":50},{"kw":"who","pageRef":50},{"kw":"am","pageRef":50},{"kw":"i","pageRef":50},{"kw":"numerically","pageRef":50},{"kw":"install","pageRef":51},{"kw":"bare-os","pageRef":51},{"kw":"coreutils","pageRef":51},{"kw":"join","pageRef":52},{"kw":"bare-os","pageRef":52},{"kw":"coreutils","pageRef":52},{"kw":"kill","pageRef":53},{"kw":"bare-os","pageRef":53},{"kw":"coreutils","pageRef":53},{"kw":"kernel-boot-diff","pageRef":54},{"kw":"bare-os","pageRef":54},{"kw":"coreutils","pageRef":54},{"kw":"kernel-doctor","pageRef":55},{"kw":"bare-os","pageRef":55},{"kw":"coreutils","pageRef":55},{"kw":"kernel-explain","pageRef":56},{"kw":"bare-os","pageRef":56},{"kw":"coreutils","pageRef":56},{"kw":"kernel-fsck","pageRef":57},{"kw":"bare-os","pageRef":57},{"kw":"coreutils","pageRef":57},{"kw":"kernel-home-snapshot","pageRef":58},{"kw":"bare-os","pageRef":58},{"kw":"coreutils","pageRef":58},{"kw":"kernel-manifest-validate","pageRef":59},{"kw":"bare-os","pageRef":59},{"kw":"coreutils","pageRef":59},{"kw":"kernel-preflight","pageRef":60},{"kw":"bare-os","pageRef":60},{"kw":"coreutils","pageRef":60},{"kw":"kernel-triage","pageRef":61},{"kw":"bare-os","pageRef":61},{"kw":"coreutils","pageRef":61},{"kw":"jq","pageRef":62},{"kw":"json","pageRef":62},{"kw":"query","pageRef":62},{"kw":"filter","pageRef":62},{"kw":"jqjs","pageRef":62},{"kw":"command-line","pageRef":62},{"kw":"processor","pageRef":62},{"kw":"language","pageRef":62},{"kw":"subset","pageRef":62},{"kw":"pretty-print","pageRef":62},{"kw":"field","pageRef":62},{"kw":"slurp","pageRef":62},{"kw":"array","pageRef":62},{"kw":"compact","pageRef":62},{"kw":"ln","pageRef":63},{"kw":"bare-os","pageRef":63},{"kw":"coreutils","pageRef":63},{"kw":"link","pageRef":63},{"kw":"files","pageRef":63},{"kw":"symlink","pageRef":63},{"kw":"hard","pageRef":63},{"kw":"if","pageRef":63},{"kw":"supported","pageRef":63},{"kw":"link","pageRef":64},{"kw":"hardlink","pageRef":64},{"kw":"bare-os","pageRef":64},{"kw":"coreutils","pageRef":64},{"kw":"logger","pageRef":65},{"kw":"bare-os","pageRef":65},{"kw":"coreutils","pageRef":65},{"kw":"login","pageRef":66},{"kw":"identity","pageRef":66},{"kw":"passphrase","pageRef":66},{"kw":"begin","pageRef":66},{"kw":"a","pageRef":66},{"kw":"session","pageRef":66},{"kw":"on","pageRef":66},{"kw":"the","pageRef":66},{"kw":"system","pageRef":66},{"kw":"unlock","pageRef":66},{"kw":"existing","pageRef":66},{"kw":"register","pageRef":66},{"kw":"new","pageRef":66},{"kw":"logout","pageRef":67},{"kw":"session","pageRef":67},{"kw":"end","pageRef":67},{"kw":"save","pageRef":67},{"kw":"vault","pageRef":67},{"kw":"hint","pageRef":67},{"kw":"logname","pageRef":68},{"kw":"bare-os","pageRef":68},{"kw":"coreutils","pageRef":68},{"kw":"return","pageRef":68},{"kw":"the","pageRef":68},{"kw":"user","pageRef":68},{"kw":"s","pageRef":68},{"kw":"login","pageRef":68},{"kw":"name","pageRef":68},{"kw":"ls","pageRef":69},{"kw":"list","pageRef":69},{"kw":"directory","pageRef":69},{"kw":"dir","pageRef":69},{"kw":"contents","pageRef":69},{"kw":"long","pageRef":69},{"kw":"hidden","pageRef":69},{"kw":"one","pageRef":69},{"kw":"per","pageRef":69},{"kw":"line","pageRef":69},{"kw":"multiple","pageRef":69},{"kw":"paths","pageRef":69},{"kw":"man","pageRef":70},{"kw":"manual","pageRef":70},{"kw":"help","pageRef":70},{"kw":"documentation","pageRef":70},{"kw":"apropos","pageRef":70},{"kw":"whatis","pageRef":70},{"kw":"cheat","pageRef":70},{"kw":"examples","pageRef":70},{"kw":"display","pageRef":70},{"kw":"on-line","pageRef":70},{"kw":"pages","pageRef":70},{"kw":"open","pageRef":70},{"kw":"page","pageRef":70},{"kw":"handbook","pageRef":70},{"kw":"toc","pageRef":70},{"kw":"section","pageRef":70},{"kw":"7","pageRef":70},{"kw":"chapter","pageRef":70},{"kw":"by","pageRef":70},{"kw":"all","pageRef":70},{"kw":"narrow","pageRef":70},{"kw":"terminal","pageRef":70},{"kw":"md5sum","pageRef":71},{"kw":"bare-os","pageRef":71},{"kw":"coreutils","pageRef":71},{"kw":"mkdir","pageRef":72},{"kw":"bare-os","pageRef":72},{"kw":"coreutils","pageRef":72},{"kw":"make","pageRef":72},{"kw":"directories","pageRef":72},{"kw":"one","pageRef":72},{"kw":"dir","pageRef":72},{"kw":"parents","pageRef":72},{"kw":"mkfifo","pageRef":73},{"kw":"bare-os","pageRef":73},{"kw":"coreutils","pageRef":73},{"kw":"make","pageRef":73},{"kw":"fifo","pageRef":73},{"kw":"special","pageRef":73},{"kw":"files","pageRef":73},{"kw":"create","pageRef":73},{"kw":"a","pageRef":73},{"kw":"named","pageRef":73},{"kw":"ipc","pageRef":73},{"kw":"channel","pageRef":73},{"kw":"mktemp","pageRef":74},{"kw":"bare-os","pageRef":74},{"kw":"coreutils","pageRef":74},{"kw":"mount","pageRef":75},{"kw":"bare-os","pageRef":75},{"kw":"coreutils","pageRef":75},{"kw":"mv","pageRef":76},{"kw":"bare-os","pageRef":76},{"kw":"coreutils","pageRef":76},{"kw":"move","pageRef":76},{"kw":"or","pageRef":76},{"kw":"rename","pageRef":76},{"kw":"files","pageRef":76},{"kw":"into","pageRef":76},{"kw":"dir","pageRef":76},{"kw":"nano","pageRef":77},{"kw":"bare-os","pageRef":77},{"kw":"coreutils","pageRef":77},{"kw":"nl","pageRef":78},{"kw":"bare-os","pageRef":78},{"kw":"coreutils","pageRef":78},{"kw":"line","pageRef":78},{"kw":"numbering","pageRef":78},{"kw":"utility","pageRef":78},{"kw":"number","pageRef":78},{"kw":"all","pageRef":78},{"kw":"lines","pageRef":78},{"kw":"nohup","pageRef":79},{"kw":"bare-os","pageRef":79},{"kw":"coreutils","pageRef":79},{"kw":"run","pageRef":79},{"kw":"command","pageRef":79},{"kw":"hangup","pageRef":79},{"kw":"is","pageRef":79},{"kw":"a","pageRef":79},{"kw":"no-op","pageRef":79},{"kw":"in","pageRef":79},{"kw":"bare","pageRef":79},{"kw":"os","pageRef":79},{"kw":"utility","pageRef":79},{"kw":"no","pageRef":79},{"kw":"real","pageRef":79},{"kw":"sighup","pageRef":79},{"kw":"guest","pageRef":79},{"kw":"nproc","pageRef":80},{"kw":"bare-os","pageRef":80},{"kw":"coreutils","pageRef":80},{"kw":"numfmt","pageRef":81},{"kw":"bare-os","pageRef":81},{"kw":"coreutils","pageRef":81},{"kw":"od","pageRef":82},{"kw":"bare-os","pageRef":82},{"kw":"coreutils","pageRef":82},{"kw":"octal","pageRef":82},{"kw":"dump","pageRef":82},{"kw":"hex","pageRef":82},{"kw":"vibe","pageRef":82},{"kw":"openssl","pageRef":83},{"kw":"bare-os","pageRef":83},{"kw":"coreutils","pageRef":83},{"kw":"oidc-publish","pageRef":84},{"kw":"bare-os","pageRef":84},{"kw":"coreutils","pageRef":84},{"kw":"paste","pageRef":85},{"kw":"bare-os","pageRef":85},{"kw":"coreutils","pageRef":85},{"kw":"patch","pageRef":86},{"kw":"bare-os","pageRef":86},{"kw":"coreutils","pageRef":86},{"kw":"pathchk","pageRef":87},{"kw":"bare-os","pageRef":87},{"kw":"coreutils","pageRef":87},{"kw":"check","pageRef":87},{"kw":"pathname","pageRef":87},{"kw":"portability","pageRef":87},{"kw":"portable","pageRef":87},{"kw":"path","pageRef":87},{"kw":"pr","pageRef":88},{"kw":"bare-os","pageRef":88},{"kw":"coreutils","pageRef":88},{"kw":"printenv","pageRef":89},{"kw":"bare-os","pageRef":89},{"kw":"coreutils","pageRef":89},{"kw":"print","pageRef":89},{"kw":"environment","pageRef":89},{"kw":"variables","pageRef":89},{"kw":"one","pageRef":89},{"kw":"variable","pageRef":89},{"kw":"all","pageRef":89},{"kw":"printf","pageRef":90},{"kw":"bare-os","pageRef":90},{"kw":"coreutils","pageRef":90},{"kw":"format","pageRef":90},{"kw":"and","pageRef":90},{"kw":"print","pageRef":90},{"kw":"no","pageRef":90},{"kw":"newline","pageRef":90},{"kw":"procstat","pageRef":91},{"kw":"bare-os","pageRef":91},{"kw":"coreutils","pageRef":91},{"kw":"ps","pageRef":92},{"kw":"bare-os","pageRef":92},{"kw":"coreutils","pageRef":92},{"kw":"pwd","pageRef":93},{"kw":"bare-os","pageRef":93},{"kw":"coreutils","pageRef":93},{"kw":"return","pageRef":93},{"kw":"working","pageRef":93},{"kw":"directory","pageRef":93},{"kw":"name","pageRef":93},{"kw":"where","pageRef":93},{"kw":"am","pageRef":93},{"kw":"i","pageRef":93},{"kw":"readlink","pageRef":94},{"kw":"bare-os","pageRef":94},{"kw":"coreutils","pageRef":94},{"kw":"print","pageRef":94},{"kw":"symbolic","pageRef":94},{"kw":"link","pageRef":94},{"kw":"targets","pageRef":94},{"kw":"symlink","pageRef":94},{"kw":"target","pageRef":94},{"kw":"realpath","pageRef":95},{"kw":"bare-os","pageRef":95},{"kw":"coreutils","pageRef":95},{"kw":"rev","pageRef":96},{"kw":"bare-os","pageRef":96},{"kw":"coreutils","pageRef":96},{"kw":"rm","pageRef":97},{"kw":"bare-os","pageRef":97},{"kw":"coreutils","pageRef":97},{"kw":"remove","pageRef":97},{"kw":"files","pageRef":97},{"kw":"file","pageRef":97},{"kw":"tree","pageRef":97},{"kw":"rmdir","pageRef":98},{"kw":"bare-os","pageRef":98},{"kw":"coreutils","pageRef":98},{"kw":"remove","pageRef":98},{"kw":"empty","pageRef":98},{"kw":"directories","pageRef":98},{"kw":"dir","pageRef":98},{"kw":"savevault","pageRef":99},{"kw":"vault","pageRef":99},{"kw":"encrypt","pageRef":99},{"kw":"backup","pageRef":99},{"kw":"snapshot","pageRef":99},{"kw":"of","pageRef":99},{"kw":"personal","pageRef":99},{"kw":"drive","pageRef":99},{"kw":"encrypted","pageRef":99},{"kw":"sed","pageRef":100},{"kw":"stream","pageRef":100},{"kw":"edit","pageRef":100},{"kw":"substitute","pageRef":100},{"kw":"editor","pageRef":100},{"kw":"first","pageRef":100},{"kw":"per","pageRef":100},{"kw":"line","pageRef":100},{"kw":"global","pageRef":100},{"kw":"in-place","pageRef":100},{"kw":"if","pageRef":100},{"kw":"supported","pageRef":100},{"kw":"print","pageRef":100},{"kw":"5","pageRef":100},{"kw":"only","pageRef":100},{"kw":"delete","pageRef":100},{"kw":"blank","pageRef":100},{"kw":"lines","pageRef":100},{"kw":"seq","pageRef":101},{"kw":"bare-os","pageRef":101},{"kw":"coreutils","pageRef":101},{"kw":"print","pageRef":101},{"kw":"sequences","pageRef":101},{"kw":"of","pageRef":101},{"kw":"numbers","pageRef":101},{"kw":"1","pageRef":101},{"kw":"10","pageRef":101},{"kw":"step","pageRef":101},{"kw":"setfacl","pageRef":102},{"kw":"bare-os","pageRef":102},{"kw":"coreutils","pageRef":102},{"kw":"sha1sum","pageRef":103},{"kw":"bare-os","pageRef":103},{"kw":"coreutils","pageRef":103},{"kw":"sha256sum","pageRef":104},{"kw":"bare-os","pageRef":104},{"kw":"coreutils","pageRef":104},{"kw":"sha512sum","pageRef":105},{"kw":"bare-os","pageRef":105},{"kw":"coreutils","pageRef":105},{"kw":"sh","pageRef":106},{"kw":"bare-os","pageRef":106},{"kw":"coreutils","pageRef":106},{"kw":"shuf","pageRef":107},{"kw":"bare-os","pageRef":107},{"kw":"coreutils","pageRef":107},{"kw":"sleep","pageRef":108},{"kw":"bare-os","pageRef":108},{"kw":"coreutils","pageRef":108},{"kw":"suspend","pageRef":108},{"kw":"execution","pageRef":108},{"kw":"for","pageRef":108},{"kw":"an","pageRef":108},{"kw":"interval","pageRef":108},{"kw":"pause","pageRef":108},{"kw":"seconds","pageRef":108},{"kw":"sort","pageRef":109},{"kw":"bare-os","pageRef":109},{"kw":"coreutils","pageRef":109},{"kw":"lines","pageRef":109},{"kw":"lexicographic","pageRef":109},{"kw":"numeric","pageRef":109},{"kw":"unique","pageRef":109},{"kw":"split","pageRef":110},{"kw":"bare-os","pageRef":110},{"kw":"coreutils","pageRef":110},{"kw":"ssh-keygen","pageRef":111},{"kw":"bare-os","pageRef":111},{"kw":"coreutils","pageRef":111},{"kw":"stat","pageRef":112},{"kw":"bare-os","pageRef":112},{"kw":"coreutils","pageRef":112},{"kw":"display","pageRef":112},{"kw":"file","pageRef":112},{"kw":"status","pageRef":112},{"kw":"metadata","pageRef":112},{"kw":"sum","pageRef":113},{"kw":"bare-os","pageRef":113},{"kw":"coreutils","pageRef":113},{"kw":"sync","pageRef":114},{"kw":"bare-os","pageRef":114},{"kw":"coreutils","pageRef":114},{"kw":"tar","pageRef":115},{"kw":"bare-os","pageRef":115},{"kw":"coreutils","pageRef":115},{"kw":"tac","pageRef":116},{"kw":"bare-os","pageRef":116},{"kw":"coreutils","pageRef":116},{"kw":"tail","pageRef":117},{"kw":"bare-os","pageRef":117},{"kw":"coreutils","pageRef":117},{"kw":"copy","pageRef":117},{"kw":"the","pageRef":117},{"kw":"last","pageRef":117},{"kw":"part","pageRef":117},{"kw":"of","pageRef":117},{"kw":"a","pageRef":117},{"kw":"file","pageRef":117},{"kw":"lines","pageRef":117},{"kw":"follow","pageRef":117},{"kw":"vibe","pageRef":117},{"kw":"bare","pageRef":117},{"kw":"poll","pageRef":117},{"kw":"manually","pageRef":117},{"kw":"tee","pageRef":118},{"kw":"bare-os","pageRef":118},{"kw":"coreutils","pageRef":118},{"kw":"duplicate","pageRef":118},{"kw":"standard","pageRef":118},{"kw":"input","pageRef":118},{"kw":"copy","pageRef":118},{"kw":"stdout","pageRef":118},{"kw":"to","pageRef":118},{"kw":"file","pageRef":118},{"kw":"test","pageRef":119},{"kw":"bare-os","pageRef":119},{"kw":"coreutils","pageRef":119},{"kw":"evaluate","pageRef":119},{"kw":"a","pageRef":119},{"kw":"condition","pageRef":119},{"kw":"file","pageRef":119},{"kw":"exists","pageRef":119},{"kw":"directory","pageRef":119},{"kw":"string","pageRef":119},{"kw":"equal","pageRef":119},{"kw":"theme","pageRef":120},{"kw":"colors","pageRef":120},{"kw":"prompt","pageRef":120},{"kw":"time","pageRef":121},{"kw":"bare-os","pageRef":121},{"kw":"coreutils","pageRef":121},{"kw":"a","pageRef":121},{"kw":"simple","pageRef":121},{"kw":"command","pageRef":121},{"kw":"wall","pageRef":121},{"kw":"timeout","pageRef":122},{"kw":"bare-os","pageRef":122},{"kw":"coreutils","pageRef":122},{"kw":"run","pageRef":122},{"kw":"command","pageRef":122},{"kw":"with","pageRef":122},{"kw":"bounded","pageRef":122},{"kw":"wall","pageRef":122},{"kw":"time","pageRef":122},{"kw":"kill","pageRef":122},{"kw":"long","pageRef":122},{"kw":"job","pageRef":122},{"kw":"after","pageRef":122},{"kw":"5s","pageRef":122},{"kw":"touch","pageRef":123},{"kw":"bare-os","pageRef":123},{"kw":"coreutils","pageRef":123},{"kw":"change","pageRef":123},{"kw":"file","pageRef":123},{"kw":"timestamps","pageRef":123},{"kw":"or","pageRef":123},{"kw":"create","pageRef":123},{"kw":"files","pageRef":123},{"kw":"empty","pageRef":123},{"kw":"refresh","pageRef":123},{"kw":"mtime","pageRef":123},{"kw":"tr","pageRef":124},{"kw":"bare-os","pageRef":124},{"kw":"coreutils","pageRef":124},{"kw":"translate","pageRef":124},{"kw":"or","pageRef":124},{"kw":"delete","pageRef":124},{"kw":"characters","pageRef":124},{"kw":"uppercase","pageRef":124},{"kw":"chars","pageRef":124},{"kw":"truncate","pageRef":125},{"kw":"bare-os","pageRef":125},{"kw":"coreutils","pageRef":125},{"kw":"true","pageRef":126},{"kw":"bare-os","pageRef":126},{"kw":"coreutils","pageRef":126},{"kw":"return","pageRef":126},{"kw":"value","pageRef":126},{"kw":"always","pageRef":126},{"kw":"success","pageRef":126},{"kw":"tsort","pageRef":127},{"kw":"bare-os","pageRef":127},{"kw":"coreutils","pageRef":127},{"kw":"tty","pageRef":128},{"kw":"bare-os","pageRef":128},{"kw":"coreutils","pageRef":128},{"kw":"return","pageRef":128},{"kw":"user","pageRef":128},{"kw":"s","pageRef":128},{"kw":"terminal","pageRef":128},{"kw":"name","pageRef":128},{"kw":"am","pageRef":128},{"kw":"i","pageRef":128},{"kw":"a","pageRef":128},{"kw":"ulimit","pageRef":129},{"kw":"bare-os","pageRef":129},{"kw":"coreutils","pageRef":129},{"kw":"uname","pageRef":130},{"kw":"bare-os","pageRef":130},{"kw":"coreutils","pageRef":130},{"kw":"return","pageRef":130},{"kw":"operating","pageRef":130},{"kw":"system","pageRef":130},{"kw":"name","pageRef":130},{"kw":"kernel-ish","pageRef":130},{"kw":"info","pageRef":130},{"kw":"uniq","pageRef":131},{"kw":"bare-os","pageRef":131},{"kw":"coreutils","pageRef":131},{"kw":"unlink","pageRef":132},{"kw":"bare-os","pageRef":132},{"kw":"coreutils","pageRef":132},{"kw":"umount","pageRef":133},{"kw":"bare-os","pageRef":133},{"kw":"coreutils","pageRef":133},{"kw":"unexpand","pageRef":134},{"kw":"bare-os","pageRef":134},{"kw":"coreutils","pageRef":134},{"kw":"uptime","pageRef":135},{"kw":"bare-os","pageRef":135},{"kw":"coreutils","pageRef":135},{"kw":"users","pageRef":136},{"kw":"bare-os","pageRef":136},{"kw":"coreutils","pageRef":136},{"kw":"vdir","pageRef":137},{"kw":"bare-os","pageRef":137},{"kw":"coreutils","pageRef":137},{"kw":"wc","pageRef":138},{"kw":"bare-os","pageRef":138},{"kw":"coreutils","pageRef":138},{"kw":"word","pageRef":138},{"kw":"line","pageRef":138},{"kw":"and","pageRef":138},{"kw":"byte","pageRef":138},{"kw":"or","pageRef":138},{"kw":"character","pageRef":138},{"kw":"count","pageRef":138},{"kw":"lines","pageRef":138},{"kw":"words","pageRef":138},{"kw":"bytes","pageRef":138},{"kw":"stdin","pageRef":138},{"kw":"only","pageRef":138},{"kw":"wget","pageRef":139},{"kw":"bare-os","pageRef":139},{"kw":"coreutils","pageRef":139},{"kw":"which","pageRef":140},{"kw":"bare-os","pageRef":140},{"kw":"coreutils","pageRef":140},{"kw":"locate","pageRef":140},{"kw":"a","pageRef":140},{"kw":"command","pageRef":140},{"kw":"resolve","pageRef":140},{"kw":"on","pageRef":140},{"kw":"path","pageRef":140},{"kw":"who","pageRef":141},{"kw":"bare-os","pageRef":141},{"kw":"coreutils","pageRef":141},{"kw":"whoami","pageRef":142},{"kw":"bare-os","pageRef":142},{"kw":"coreutils","pageRef":142},{"kw":"display","pageRef":142},{"kw":"effective","pageRef":142},{"kw":"user","pageRef":142},{"kw":"id","pageRef":142},{"kw":"xattr","pageRef":143},{"kw":"bare-os","pageRef":143},{"kw":"coreutils","pageRef":143},{"kw":"xargs","pageRef":144},{"kw":"bare-os","pageRef":144},{"kw":"coreutils","pageRef":144},{"kw":"construct","pageRef":144},{"kw":"argument","pageRef":144},{"kw":"lists","pageRef":144},{"kw":"and","pageRef":144},{"kw":"invoke","pageRef":144},{"kw":"utility","pageRef":144},{"kw":"pass","pageRef":144},{"kw":"lines","pageRef":144},{"kw":"as","pageRef":144},{"kw":"arguments","pageRef":144},{"kw":"one","pageRef":144},{"kw":"per","pageRef":144},{"kw":"run","pageRef":144},{"kw":"workaround","pageRef":144},{"kw":"for","pageRef":144},{"kw":"complex","pageRef":144},{"kw":"scripts","pageRef":144},{"kw":"yes","pageRef":145},{"kw":"bare-os","pageRef":145},{"kw":"coreutils","pageRef":145},{"kw":"cron","pageRef":146},{"kw":"scheduler","pageRef":146},{"kw":"bare-initd","pageRef":146},{"kw":"timer","pageRef":146},{"kw":"crontab","pageRef":146},{"kw":"bare-cron","pageRef":146},{"kw":"bare","pageRef":146},{"kw":"os","pageRef":146},{"kw":"minute","pageRef":146},{"kw":"unit","pageRef":146},{"kw":"list","pageRef":146},{"kw":"user","pageRef":146},{"kw":"line","pageRef":146},{"kw":"five-field","pageRef":146},{"kw":"bare_os_bare_modules","pageRef":147},{"kw":"bare_os_bare_drive_bundles","pageRef":147},{"kw":"ctx.bare","pageRef":147},{"kw":"bare-module-manifest","pageRef":147},{"kw":"bare-os-bare-libs","pageRef":147},{"kw":"bare-os-ctx-bare","pageRef":147},{"kw":"ctx","pageRef":147},{"kw":"bare","pageRef":147},{"kw":"library","pageRef":147},{"kw":"and","pageRef":147},{"kw":"drive","pageRef":147},{"kw":"bundles","pageRef":147},{"kw":"shell","pageRef":148},{"kw":"builtin","pageRef":148},{"kw":"cd","pageRef":148},{"kw":"export","pageRef":148},{"kw":"alias","pageRef":148},{"kw":"bare-os-shell","pageRef":148},{"kw":"sh-builtins","pageRef":148},{"kw":"bare","pageRef":148},{"kw":"os","pageRef":148},{"kw":"interactive","pageRef":148},{"kw":"builtins","pageRef":148},{"kw":"pipeline","pageRef":148},{"kw":"simulated","pageRef":148},{"kw":"redirect","pageRef":148},{"kw":"out","pageRef":148},{"kw":"append","pageRef":148},{"kw":"use","pageRef":148},{"kw":"for","pageRef":148},{"kw":"children","pageRef":148},{"kw":"temp","pageRef":148},{"kw":"var","pageRef":148},{"kw":"one","pageRef":148},{"kw":"command","pageRef":148},{"kw":"bare-initd","pageRef":149},{"kw":"initctl","pageRef":149},{"kw":"service","pageRef":149},{"kw":"supervisor","pageRef":149},{"kw":"cron","pageRef":149},{"kw":"systemd","pageRef":149},{"kw":"systemctl","pageRef":149},{"kw":"control","pageRef":149},{"kw":"systemd-like","pageRef":149},{"kw":"subset","pageRef":149},{"kw":"list","pageRef":149},{"kw":"units","pageRef":149},{"kw":"restart","pageRef":149},{"kw":"scheduler","pageRef":149},{"kw":"tail","pageRef":149},{"kw":"errors","pageRef":149},{"kw":"git","pageRef":150},{"kw":"version control","pageRef":150},{"kw":"repository","pageRef":150},{"kw":"clone","pageRef":150},{"kw":"commit","pageRef":150},{"kw":"isomorphic-git","pageRef":150},{"kw":"bare","pageRef":150},{"kw":"os","pageRef":150},{"kw":"front-end","pageRef":150},{"kw":"new","pageRef":150},{"kw":"repo","pageRef":150},{"kw":"status","pageRef":150},{"kw":"over","pageRef":150},{"kw":"http","pageRef":150},{"kw":"needs","pageRef":150},{"kw":"remote","pageRef":150},{"kw":"fetch","pageRef":150},{"kw":"config","pageRef":150},{"kw":"local","pageRef":150},{"kw":"log","pageRef":150},{"kw":"one","pageRef":150},{"kw":"line","pageRef":150},{"kw":"handbook","pageRef":151},{"kw":"bare-os","pageRef":151},{"kw":"documentation","pageRef":151},{"kw":"narrative","pageRef":151},{"kw":"chapter","pageRef":151},{"kw":"bare","pageRef":151},{"kw":"os","pageRef":151},{"kw":"table","pageRef":151},{"kw":"contents","pageRef":151},{"kw":"and","pageRef":151},{"kw":"reading","pageRef":151},{"kw":"order","pageRef":151},{"kw":"bare-os-handbook","pageRef":151},{"kw":"of","pageRef":151},{"kw":"handbook","pageRef":152},{"kw":"bare-os","pageRef":152},{"kw":"documentation","pageRef":152},{"kw":"narrative","pageRef":152},{"kw":"chapter","pageRef":152},{"kw":"00","pageRef":152},{"kw":"preface","pageRef":152},{"kw":"why","pageRef":152},{"kw":"bare","pageRef":152},{"kw":"exists","pageRef":152},{"kw":"handbook-00-preface","pageRef":152},{"kw":"os","pageRef":152},{"kw":"handbook","pageRef":153},{"kw":"bare-os","pageRef":153},{"kw":"documentation","pageRef":153},{"kw":"narrative","pageRef":153},{"kw":"chapter","pageRef":153},{"kw":"01","pageRef":153},{"kw":"introduction","pageRef":153},{"kw":"what","pageRef":153},{"kw":"bare","pageRef":153},{"kw":"handbook-01-introduction","pageRef":153},{"kw":"1","pageRef":153},{"kw":"os","pageRef":153},{"kw":"is","pageRef":153},{"kw":"handbook","pageRef":154},{"kw":"bare-os","pageRef":154},{"kw":"documentation","pageRef":154},{"kw":"narrative","pageRef":154},{"kw":"chapter","pageRef":154},{"kw":"02","pageRef":154},{"kw":"blueprints","pageRef":154},{"kw":"architecture","pageRef":154},{"kw":"and","pageRef":154},{"kw":"trust","pageRef":154},{"kw":"handbook-02-blueprints","pageRef":154},{"kw":"2","pageRef":154},{"kw":"handbook","pageRef":155},{"kw":"bare-os","pageRef":155},{"kw":"documentation","pageRef":155},{"kw":"narrative","pageRef":155},{"kw":"chapter","pageRef":155},{"kw":"03","pageRef":155},{"kw":"protocol","pageRef":155},{"kw":"and","pageRef":155},{"kw":"disk","pageRef":155},{"kw":"mbr","pageRef":155},{"kw":"swarmdisk","pageRef":155},{"kw":"handbook-03-protocol-and-disk","pageRef":155},{"kw":"3","pageRef":155},{"kw":"handbook","pageRef":156},{"kw":"bare-os","pageRef":156},{"kw":"documentation","pageRef":156},{"kw":"narrative","pageRef":156},{"kw":"chapter","pageRef":156},{"kw":"04","pageRef":156},{"kw":"the","pageRef":156},{"kw":"booter","pageRef":156},{"kw":"runtime","pageRef":156},{"kw":"ctx","pageRef":156},{"kw":"vfs","pageRef":156},{"kw":"shell","pageRef":156},{"kw":"kernel","pageRef":156},{"kw":"services","pageRef":156},{"kw":"handbook-04-the-booter-runtime","pageRef":156},{"kw":"4","pageRef":156},{"kw":"handbook","pageRef":157},{"kw":"bare-os","pageRef":157},{"kw":"documentation","pageRef":157},{"kw":"narrative","pageRef":157},{"kw":"chapter","pageRef":157},{"kw":"05","pageRef":157},{"kw":"identity","pageRef":157},{"kw":"vault","pageRef":157},{"kw":"and","pageRef":157},{"kw":"hdms","pageRef":157},{"kw":"handbook-05-identity-vault-and-hdms","pageRef":157},{"kw":"5","pageRef":157},{"kw":"handbook","pageRef":158},{"kw":"bare-os","pageRef":158},{"kw":"documentation","pageRef":158},{"kw":"narrative","pageRef":158},{"kw":"chapter","pageRef":158},{"kw":"06","pageRef":158},{"kw":"kernel","pageRef":158},{"kw":"and","pageRef":158},{"kw":"binaries","pageRef":158},{"kw":"bin","pageRef":158},{"kw":"utilities","pageRef":158},{"kw":"handbook-06-kernel-and-binaries","pageRef":158},{"kw":"6","pageRef":158},{"kw":"handbook","pageRef":159},{"kw":"bare-os","pageRef":159},{"kw":"documentation","pageRef":159},{"kw":"narrative","pageRef":159},{"kw":"chapter","pageRef":159},{"kw":"07","pageRef":159},{"kw":"operations","pageRef":159},{"kw":"and","pageRef":159},{"kw":"development","pageRef":159},{"kw":"release","pageRef":159},{"kw":"handbook-07-operations-and-development","pageRef":159},{"kw":"7","pageRef":159},{"kw":"handbook","pageRef":160},{"kw":"bare-os","pageRef":160},{"kw":"documentation","pageRef":160},{"kw":"narrative","pageRef":160},{"kw":"chapter","pageRef":160},{"kw":"08","pageRef":160},{"kw":"git","pageRef":160},{"kw":"on","pageRef":160},{"kw":"bare","pageRef":160},{"kw":"os","pageRef":160},{"kw":"handbook-08-git-on-bare-os","pageRef":160},{"kw":"8","pageRef":160},{"kw":"handbook","pageRef":161},{"kw":"bare-os","pageRef":161},{"kw":"documentation","pageRef":161},{"kw":"narrative","pageRef":161},{"kw":"chapter","pageRef":161},{"kw":"09","pageRef":161},{"kw":"posix","pageRef":161},{"kw":"utilities","pageRef":161},{"kw":"shell","pageRef":161},{"kw":"and","pageRef":161},{"kw":"vfs","pageRef":161},{"kw":"style","pageRef":161},{"kw":"builtins","pageRef":161},{"kw":"alignment","pageRef":161},{"kw":"handbook-09-posix-utilities-shell-and-vfs","pageRef":161},{"kw":"9","pageRef":161},{"kw":"posix-style","pageRef":161},{"kw":"handbook","pageRef":162},{"kw":"bare-os","pageRef":162},{"kw":"documentation","pageRef":162},{"kw":"narrative","pageRef":162},{"kw":"chapter","pageRef":162},{"kw":"10","pageRef":162},{"kw":"manpages","pageRef":162},{"kw":"and","pageRef":162},{"kw":"online","pageRef":162},{"kw":"help","pageRef":162},{"kw":"manual","pageRef":162},{"kw":"pages","pageRef":162},{"kw":"man","pageRef":162},{"kw":"handbook-10-manpages-and-online-help","pageRef":162},{"kw":"handbook","pageRef":163},{"kw":"bare-os","pageRef":163},{"kw":"documentation","pageRef":163},{"kw":"narrative","pageRef":163},{"kw":"chapter","pageRef":163},{"kw":"11","pageRef":163},{"kw":"kernel","pageRef":163},{"kw":"program","pageRef":163},{"kw":"and","pageRef":163},{"kw":"research","pageRef":163},{"kw":"ecosystem","pageRef":163},{"kw":"non","pageRef":163},{"kw":"goals","pageRef":163},{"kw":"handbook-11-kernel-program-and-research","pageRef":163},{"kw":"non-goals","pageRef":163},{"kw":"handbook","pageRef":164},{"kw":"bare-os","pageRef":164},{"kw":"documentation","pageRef":164},{"kw":"narrative","pageRef":164},{"kw":"chapter","pageRef":164},{"kw":"12","pageRef":164},{"kw":"p2p","pageRef":164},{"kw":"stack","pageRef":164},{"kw":"and","pageRef":164},{"kw":"posix","pageRef":164},{"kw":"boundaries","pageRef":164},{"kw":"native","pageRef":164},{"kw":"handbook-12-p2p-stack-and-posix-boundaries","pageRef":164},{"kw":"p2p-native","pageRef":164},{"kw":"vs","pageRef":164},{"kw":"developer","pageRef":165},{"kw":"devguide","pageRef":165},{"kw":"develop","pageRef":165},{"kw":"script","pageRef":165},{"kw":"asyncfunction","pageRef":165},{"kw":"ctx","pageRef":165},{"kw":"bare-os","pageRef":165},{"kw":"guide","pageRef":165},{"kw":"bare","pageRef":165},{"kw":"os","pageRef":165},{"kw":"index","pageRef":165},{"kw":"and","pageRef":165},{"kw":"reading","pageRef":165},{"kw":"order","pageRef":165},{"kw":"bare-os-developer-guide","pageRef":165},{"kw":"developer","pageRef":166},{"kw":"devguide","pageRef":166},{"kw":"develop","pageRef":166},{"kw":"script","pageRef":166},{"kw":"asyncfunction","pageRef":166},{"kw":"ctx","pageRef":166},{"kw":"bare-os","pageRef":166},{"kw":"guide","pageRef":166},{"kw":"01","pageRef":166},{"kw":"two","pageRef":166},{"kw":"runtimes","pageRef":166},{"kw":"host","pageRef":166},{"kw":"vs","pageRef":166},{"kw":"image","pageRef":166},{"kw":"chapter","pageRef":166},{"kw":"pear","pageRef":166},{"kw":"node","pageRef":166},{"kw":"devguide-01-two-runtimes-host-vs-image","pageRef":166},{"kw":"1","pageRef":166},{"kw":"in-image","pageRef":166},{"kw":"developer","pageRef":167},{"kw":"devguide","pageRef":167},{"kw":"develop","pageRef":167},{"kw":"script","pageRef":167},{"kw":"asyncfunction","pageRef":167},{"kw":"ctx","pageRef":167},{"kw":"bare-os","pageRef":167},{"kw":"guide","pageRef":167},{"kw":"02","pageRef":167},{"kw":"the","pageRef":167},{"kw":"context","pageRef":167},{"kw":"object","pageRef":167},{"kw":"chapter","pageRef":167},{"kw":"devguide-02-the-context-object","pageRef":167},{"kw":"2","pageRef":167},{"kw":"developer","pageRef":168},{"kw":"devguide","pageRef":168},{"kw":"develop","pageRef":168},{"kw":"script","pageRef":168},{"kw":"asyncfunction","pageRef":168},{"kw":"ctx","pageRef":168},{"kw":"bare-os","pageRef":168},{"kw":"guide","pageRef":168},{"kw":"03","pageRef":168},{"kw":"kernel","pageRef":168},{"kw":"boot","pageRef":168},{"kw":"init","pageRef":168},{"kw":"chapter","pageRef":168},{"kw":"and","pageRef":168},{"kw":"start","pageRef":168},{"kw":"devguide-03-kernel-boot-init","pageRef":168},{"kw":"3","pageRef":168},{"kw":"js","pageRef":168},{"kw":"developer","pageRef":169},{"kw":"devguide","pageRef":169},{"kw":"develop","pageRef":169},{"kw":"script","pageRef":169},{"kw":"asyncfunction","pageRef":169},{"kw":"ctx","pageRef":169},{"kw":"bare-os","pageRef":169},{"kw":"guide","pageRef":169},{"kw":"04","pageRef":169},{"kw":"user","pageRef":169},{"kw":"scripts","pageRef":169},{"kw":"and","pageRef":169},{"kw":"path","pageRef":169},{"kw":"chapter","pageRef":169},{"kw":"resolution","pageRef":169},{"kw":"devguide-04-user-scripts-and-path","pageRef":169},{"kw":"4","pageRef":169},{"kw":"developer","pageRef":170},{"kw":"devguide","pageRef":170},{"kw":"develop","pageRef":170},{"kw":"script","pageRef":170},{"kw":"asyncfunction","pageRef":170},{"kw":"ctx","pageRef":170},{"kw":"bare-os","pageRef":170},{"kw":"guide","pageRef":170},{"kw":"05","pageRef":170},{"kw":"modules","pageRef":170},{"kw":"and","pageRef":170},{"kw":"imports","pageRef":170},{"kw":"chapter","pageRef":170},{"kw":"import","pageRef":170},{"kw":"packaging","pageRef":170},{"kw":"the","pageRef":170},{"kw":"honest","pageRef":170},{"kw":"version","pageRef":170},{"kw":"devguide-05-modules-and-imports","pageRef":170},{"kw":"5","pageRef":170},{"kw":"developer","pageRef":171},{"kw":"devguide","pageRef":171},{"kw":"develop","pageRef":171},{"kw":"script","pageRef":171},{"kw":"asyncfunction","pageRef":171},{"kw":"ctx","pageRef":171},{"kw":"bare-os","pageRef":171},{"kw":"guide","pageRef":171},{"kw":"06","pageRef":171},{"kw":"extending","pageRef":171},{"kw":"bin","pageRef":171},{"kw":"coreutils","pageRef":171},{"kw":"chapter","pageRef":171},{"kw":"bare","pageRef":171},{"kw":"devguide-06-extending-bin-coreutils","pageRef":171},{"kw":"6","pageRef":171},{"kw":"bare-os-coreutils","pageRef":171},{"kw":"developer","pageRef":172},{"kw":"devguide","pageRef":172},{"kw":"develop","pageRef":172},{"kw":"script","pageRef":172},{"kw":"asyncfunction","pageRef":172},{"kw":"ctx","pageRef":172},{"kw":"bare-os","pageRef":172},{"kw":"guide","pageRef":172},{"kw":"07","pageRef":172},{"kw":"apps","pageRef":172},{"kw":"beyond","pageRef":172},{"kw":"the","pageRef":172},{"kw":"shell","pageRef":172},{"kw":"chapter","pageRef":172},{"kw":"what","pageRef":172},{"kw":"realistic","pageRef":172},{"kw":"today","pageRef":172},{"kw":"devguide-07-apps-beyond-the-shell","pageRef":172},{"kw":"7","pageRef":172},{"kw":"is","pageRef":172},{"kw":"developer","pageRef":173},{"kw":"devguide","pageRef":173},{"kw":"develop","pageRef":173},{"kw":"script","pageRef":173},{"kw":"asyncfunction","pageRef":173},{"kw":"ctx","pageRef":173},{"kw":"bare-os","pageRef":173},{"kw":"guide","pageRef":173},{"kw":"08","pageRef":173},{"kw":"testing","pageRef":173},{"kw":"and","pageRef":173},{"kw":"debugging","pageRef":173},{"kw":"chapter","pageRef":173},{"kw":"devguide-08-testing-and-debugging","pageRef":173},{"kw":"8","pageRef":173},{"kw":"developer","pageRef":174},{"kw":"devguide","pageRef":174},{"kw":"develop","pageRef":174},{"kw":"script","pageRef":174},{"kw":"asyncfunction","pageRef":174},{"kw":"ctx","pageRef":174},{"kw":"bare-os","pageRef":174},{"kw":"guide","pageRef":174},{"kw":"09","pageRef":174},{"kw":"security","pageRef":174},{"kw":"and","pageRef":174},{"kw":"trust","pageRef":174},{"kw":"chapter","pageRef":174},{"kw":"mindset","pageRef":174},{"kw":"devguide-09-security-and-trust","pageRef":174},{"kw":"9","pageRef":174},{"kw":"developer","pageRef":175},{"kw":"devguide","pageRef":175},{"kw":"develop","pageRef":175},{"kw":"script","pageRef":175},{"kw":"asyncfunction","pageRef":175},{"kw":"ctx","pageRef":175},{"kw":"bare-os","pageRef":175},{"kw":"guide","pageRef":175},{"kw":"10","pageRef":175},{"kw":"glossary","pageRef":175},{"kw":"and","pageRef":175},{"kw":"faq","pageRef":175},{"kw":"chapter","pageRef":175},{"kw":"devguide-10-glossary-and-faq","pageRef":175},{"kw":"developer","pageRef":176},{"kw":"devguide","pageRef":176},{"kw":"develop","pageRef":176},{"kw":"script","pageRef":176},{"kw":"asyncfunction","pageRef":176},{"kw":"ctx","pageRef":176},{"kw":"bare-os","pageRef":176},{"kw":"guide","pageRef":176},{"kw":"11","pageRef":176},{"kw":"kernel","pageRef":176},{"kw":"pear","pageRef":176},{"kw":"cookbook","pageRef":176},{"kw":"chapter","pageRef":176},{"kw":"extensions","pageRef":176},{"kw":"and","pageRef":176},{"kw":"workflows","pageRef":176},{"kw":"devguide-11-kernel-pear-cookbook","pageRef":176},{"kw":"developer","pageRef":177},{"kw":"devguide","pageRef":177},{"kw":"develop","pageRef":177},{"kw":"script","pageRef":177},{"kw":"asyncfunction","pageRef":177},{"kw":"ctx","pageRef":177},{"kw":"bare-os","pageRef":177},{"kw":"guide","pageRef":177},{"kw":"12","pageRef":177},{"kw":"bare","pageRef":177},{"kw":"modules","pageRef":177},{"kw":"and","pageRef":177},{"kw":"pear","pageRef":177},{"kw":"ecosystem","pageRef":177},{"kw":"chapter","pageRef":177},{"kw":"the","pageRef":177},{"kw":"devguide-12-bare-modules-and-pear-ecosystem","pageRef":177},{"kw":"developer","pageRef":178},{"kw":"devguide","pageRef":178},{"kw":"develop","pageRef":178},{"kw":"script","pageRef":178},{"kw":"asyncfunction","pageRef":178},{"kw":"ctx","pageRef":178},{"kw":"bare-os","pageRef":178},{"kw":"guide","pageRef":178},{"kw":"13","pageRef":178},{"kw":"privacy","pageRef":178},{"kw":"telemetry","pageRef":178},{"kw":"pii","pageRef":178},{"kw":"and","pageRef":178},{"kw":"capability","pageRef":178},{"kw":"word","pageRef":178},{"kw":"devguide-13-privacy-telemetry-pii","pageRef":178},{"kw":"10","pageRef":178},{"kw":"developer","pageRef":179},{"kw":"devguide","pageRef":179},{"kw":"develop","pageRef":179},{"kw":"script","pageRef":179},{"kw":"asyncfunction","pageRef":179},{"kw":"ctx","pageRef":179},{"kw":"bare-os","pageRef":179},{"kw":"guide","pageRef":179},{"kw":"bare","pageRef":179},{"kw":"boot","pageRef":179},{"kw":"kernel","pageRef":179},{"kw":"phase","pageRef":179},{"kw":"alignment","pageRef":179},{"kw":"stock","pageRef":179},{"kw":"init","pageRef":179},{"kw":"phases","pageRef":179},{"kw":"devguide-bare-boot-kernel-phase-alignment","pageRef":179},{"kw":"bare-boot","pageRef":179},{"kw":"vs","pageRef":179},{"kw":"js","pageRef":179},{"kw":"developer","pageRef":180},{"kw":"devguide","pageRef":180},{"kw":"develop","pageRef":180},{"kw":"script","pageRef":180},{"kw":"asyncfunction","pageRef":180},{"kw":"ctx","pageRef":180},{"kw":"bare-os","pageRef":180},{"kw":"guide","pageRef":180},{"kw":"kernel","pageRef":180},{"kw":"explain","pageRef":180},{"kw":"and","pageRef":180},{"kw":"doctor","pageRef":180},{"kw":"conventions","pageRef":180},{"kw":"devguide-kernel-explain-and-doctor-conventions","pageRef":180},{"kw":"kernel-explain","pageRef":180},{"kw":"developer","pageRef":181},{"kw":"devguide","pageRef":181},{"kw":"develop","pageRef":181},{"kw":"script","pageRef":181},{"kw":"asyncfunction","pageRef":181},{"kw":"ctx","pageRef":181},{"kw":"bare-os","pageRef":181},{"kw":"guide","pageRef":181},{"kw":"kernel","pageRef":181},{"kw":"program","pageRef":181},{"kw":"governed","pageRef":181},{"kw":"expansion","pageRef":181},{"kw":"devguide-kernel-program","pageRef":181},{"kw":"developer","pageRef":182},{"kw":"devguide","pageRef":182},{"kw":"develop","pageRef":182},{"kw":"script","pageRef":182},{"kw":"asyncfunction","pageRef":182},{"kw":"ctx","pageRef":182},{"kw":"bare-os","pageRef":182},{"kw":"guide","pageRef":182},{"kw":"naming","pageRef":182},{"kw":"conventions","pageRef":182},{"kw":"first","pageRef":182},{"kw":"party","pageRef":182},{"kw":"vendored","pageRef":182},{"kw":"devguide-naming-conventions","pageRef":182},{"kw":"first-party","pageRef":182},{"kw":"vs","pageRef":182},{"kw":"developer","pageRef":183},{"kw":"devguide","pageRef":183},{"kw":"develop","pageRef":183},{"kw":"script","pageRef":183},{"kw":"asyncfunction","pageRef":183},{"kw":"ctx","pageRef":183},{"kw":"bare-os","pageRef":183},{"kw":"guide","pageRef":183},{"kw":"naming","pageRef":183},{"kw":"migrations","pageRef":183},{"kw":"and","pageRef":183},{"kw":"contract","pageRef":183},{"kw":"devguide-naming-migrations","pageRef":183},{"kw":"developer","pageRef":184},{"kw":"devguide","pageRef":184},{"kw":"develop","pageRef":184},{"kw":"script","pageRef":184},{"kw":"asyncfunction","pageRef":184},{"kw":"ctx","pageRef":184},{"kw":"bare-os","pageRef":184},{"kw":"guide","pageRef":184},{"kw":"node","pageRef":184},{"kw":"to","pageRef":184},{"kw":"bare","pageRef":184},{"kw":"modules","pageRef":184},{"kw":"built","pageRef":184},{"kw":"ins","pageRef":184},{"kw":"pear","pageRef":184},{"kw":"guest","pageRef":184},{"kw":"safe","pageRef":184},{"kw":"devguide-node-to-bare-modules","pageRef":184},{"kw":"built-ins","pageRef":184},{"kw":"guest-safe","pageRef":184}]}
Reference in New Issue View Git Blame Copy Permalink