The Command Codex

List information about the FILEs (the current directory by default).

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that ls cannot corrupt system state or bypass security boundaries.

Changes the current working directory of the shell to the specified directory. If no directory is given, it defaults to the current user's home directory.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (change_directory) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the cd command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Create the DIRECTORY(ies), if they do not already exist.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that mkdir cannot corrupt system state or bypass security boundaries.

Removes the DIRECTORY(ies), if they are empty.

Options & Flags:

• -p, --parents
• remove DIRECTORY and its ancestors. For instance,
• `rmdir -p a/b/c` is similar to `rmdir a/b/c a/b a`.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that rmdir cannot corrupt system state or bypass security boundaries.

Update the access and modification times of each FILE to the specified time, or the current time if no time is given. A FILE argument that does not exist is created empty.

Options & Flags:

• -d, --date=STRING
• Parse STRING and use it instead of current time (e.g., "1 day ago").
• -t STAMP
• Use [[CC]YY]MMDDhhmm[.ss] instead of current time.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that touch cannot corrupt system state or bypass security boundaries.

Copy SOURCE to DEST, or multiple SOURCE(s) to a DIRECTORY.

Options & Flags:

• -f, --force
• If a destination file cannot be opened, remove it and try again.
• -i, --interactive
• Prompt before overwriting an existing file.
• -p, --preserve
• Preserve the original file's mode, ownership, and timestamps.
• -r, -R, --recursive
• Copy directories and their contents recursively.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (confirm) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the cp command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Renames SOURCE to DESTINATION, or moves SOURCE(s) to DIRECTORY. If the last argument is an existing directory, the source file is moved into that directory.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that mv cannot corrupt system state or bypass security boundaries.

Renames a file from OLD_NAME to NEW_NAME within the current directory. This command does not move files across directories. For that, use 'mv'.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that rename cannot corrupt system state or bypass security boundaries.

Removes each specified file. By default, it does not remove directories. It refuses to remove '.' or '..' (the directory you are in, or its parent) and '/'. To delete a directory, name it: rm -r old_project

Options & Flags:

• -f, --force
• ignore nonexistent files and arguments, never prompt
• -i
• prompt before every removal
• -r, -R, --recursive
• remove directories and their contents recursively

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (confirm) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the rm command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The find utility recursively descends the directory tree for each path, evaluating an expression for each file.

Options & Flags:

• -name <pattern>
• File name matches shell pattern (e.g., "*.txt").
• -type <f|d>
• File is of type f (file) or d (directory).
• -perm <mode>
• File's permission bits are exactly mode (octal).
• -o
• OR; the preceding expression is logically OR'd with the following one.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (execute_commands) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the find command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Recursively displays the directory structure of a given path in a tree-like format. If no directory is specified, it lists the current directory.

Options & Flags:

• -d
• List directories only.
• -L level
• Descend only 'level' directories deep.
• -C
• Colour the names: directories blue, symlinks cyan, executables
• green. The colour codes travel with the text, so they end up in
• pipes and files too, same as the real thing.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that tree cannot corrupt system state or bypass security boundaries.

Summarize disk usage of the set of FILEs, recursively for directories. Sizes are displayed in 1K blocks by default.

Options & Flags:

• -h, --human-readable
• Print sizes in human readable format (e.g., 1K, 234M, 2G).
• -s, --summarize
• Display only a total for each argument, not for subdirectories.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that du cannot corrupt system state or bypass security boundaries.

Show information about the virtual file system, including total size, used space, available space, and the percentage of space used.

Options & Flags:

• -h, --human-readable
• Print sizes in powers of 1024 (e.g., 1K, 234M, 2G).

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that df cannot corrupt system state or bypass security boundaries.

Create a symbolic link named LINK_NAME which points to TARGET. Hard links are not supported.

Options & Flags:

• -s, --symbolic
• Make a symbolic link instead of a hard link. This is currently the only supported mode.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that ln cannot corrupt system state or bypass security boundaries.

Mounts a folder from the host computer into the FractalOS Virtual File System. This command is only available in portable mode (Desktop app). When executed, it will open a host folder selection dialog. All files inside the host folder will become readable and writable within FractalOS. Note: Python scripts executed within FractalOS cannot dynamically `open()` host files because the python environment is isolated. Standard commands like `cat`, `grep`, and the `editor` fully support host files.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (mount_host) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the mount command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Removes all files and subdirectories within the current user's home directory, resetting it to a clean slate. This is a destructive and irreversible operation that requires confirmation. For safety, this command cannot be run by the 'root' user.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (confirm) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the clearfs command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Manages .binder files, which are JSON files that group related project files together into sections. This allows for bulk operations on a set of files, even if they are in different directories.

Options & Flags:

• -s, --section <name>
• Specify a section name when adding files. Defaults to 'general'.
• SUB-COMMANDS:
• create <name>
• Creates a new, empty binder file.
• add <binder> <path>
• Adds a file or directory path to a binder. Use with -s to specify a section.
• list <binder>

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (execute_commands) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the binder command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The cat utility reads files sequentially, writing them to the standard output. The FILE operands are processed in command-line order. If FILE is a single dash ('-') or absent, cat reads from the standard input.

Options & Flags:

• -n, --number
• Number all output lines, starting with 1.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that cat cannot corrupt system state or bypass security boundaries.

Print the first 10 lines of each FILE to standard output. With no FILE, or when FILE is -, read standard input.

Options & Flags:

• -n, --lines=COUNT
• Print the first COUNT lines instead of the first 10.
• -c, --bytes=COUNT
• Print the first COUNT bytes.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that head cannot corrupt system state or bypass security boundaries.

Print the last 10 lines of each FILE to standard output. With no FILE, or when FILE is -, read standard input.

Options & Flags:

• -n, --lines=COUNT
• Output the last COUNT lines, instead of the last 10.
• -c, --bytes=COUNT
• Output the last COUNT bytes.
• -f, --follow
• Output appended data as the file grows.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that tail cannot corrupt system state or bypass security boundaries.

grep searches for PATTERNS in each FILE. A PATTERN is a regular expression.

Options & Flags:

• -i, --ignore-case
• Ignore case distinctions in patterns and input data.
• -v, --invert-match
• Invert the sense of matching, to select non-matching lines.
• -n, --line-number
• Prefix each line of output with the 1-based line number.
• -c, --count
• Suppress normal output; instead print a count of matching lines.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that grep cannot corrupt system state or bypass security boundaries.

sed is a stream editor. A stream editor is used to perform basic text transformations on an input stream (a file or input from a pipeline). This version supports simple substitution.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that sed cannot corrupt system state or bypass security boundaries.

The awk utility executes programs written in the awk programming language, which is specialized for textual data manipulation. A program consists of a series of patterns followed by actions. When input is read that matches a pattern, the corresponding action is executed.

Options & Flags:

• -F fs
• Define the input field separator to be the regular expression fs.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that awk cannot corrupt system state or bypass security boundaries.

Print selected parts of lines from each FILE to standard output. With no FILE, or when FILE is -, read standard input.

Options & Flags:

• -c, --characters=LIST
• Select only these characters. LIST is a comma-separated list of numbers and ranges (e.g., 1,3,5-7).
• -f, --fields=LIST
• Select only these fields. LIST is a comma-separated list of numbers and ranges.
• -d, --delimiter=DELIM
• Use DELIM instead of TAB for the field delimiter.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that cut cannot corrupt system state or bypass security boundaries.

Translate, squeeze, and/or delete characters from standard input, writing to standard output.

Options & Flags:

• -c, --complement
• Use the complement of SET1.
• -d, --delete
• Delete characters in SET1, do not translate.
• -s, --squeeze-repeats
• Replace each input sequence of a repeated character that is listed in SET1
• with a single occurrence of that character.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. tr operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Write sorted concatenation of all FILE(s) to standard output. With no FILE, or when FILE is -, read standard input. The command sorts lexicographically by default.

Options & Flags:

• -n, --numeric-sort
• Compare according to string numerical value.
• -r, --reverse
• Reverse the result of comparisons.
• -u, --unique
• Output only the first of an equal run.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that sort cannot corrupt system state or bypass security boundaries.

Filter adjacent matching lines from input, writing to output. Note: 'uniq' does not detect repeated lines unless they are adjacent. You may want to 'sort' the input first to group all identical lines.

Options & Flags:

• -c, --count
• Prefix lines by the number of occurrences.
• -d, --repeated
• Only print duplicate lines, one for each group.
• -u, --unique
• Only print lines that are not repeated.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that uniq cannot corrupt system state or bypass security boundaries.

Print newline, word, and byte counts for each FILE, and a total line if more than one FILE is specified. With no FILE, or when FILE is -, read standard input.

Options & Flags:

• -c, --bytes
• Print the byte counts.
• -l, --lines
• Print the newline counts.
• -w, --words
• Print the word counts.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that wc cannot corrupt system state or bypass security boundaries.

Write each FILE to standard output, with line numbers added to non-empty lines. With no FILE, or when FILE is -, read standard input.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that nl cannot corrupt system state or bypass security boundaries.

Write a random permutation of the input lines to standard output.

Options & Flags:

• -e, --echo
• treat each ARG as an input line
• -i, --input-range=LO-HI
• treat each number in range LO-HI as an input line
• -n, --head-count=COUNT
• output at most COUNT lines

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that shuf cannot corrupt system state or bypass security boundaries.

Output pieces of FILE separated by PATTERN(s) to files 'xx00', 'xx01', etc. In this version, PATTERN must be a line number.

Options & Flags:

• -f, --prefix=PREFIX
• Use PREFIX instead of 'xx' for the output file names.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that csplit cannot corrupt system state or bypass security boundaries.

The xargs utility reads space or newline delimited strings from standard input and executes the specified utility with the strings as arguments.

Options & Flags:

• -I replace-str
• Replace occurrences of replace-str in the utility and arguments
• with names read from standard input. This executes the utility
• once for each input line.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (execute_commands) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the xargs command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Compare files line by line. By default, it produces output in a context format.

Options & Flags:

• -u, --unified
• Output 3 lines of unified context. This is the most common format for creating patch files.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that diff cannot corrupt system state or bypass security boundaries.

patch takes a patch file containing a difference listing produced by the diff program and applies those differences to an original file, producing a patched version.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that patch cannot corrupt system state or bypass security boundaries.

Compare sorted files FILE1 and FILE2 line by line. With no options, produce three-column output. Column one contains lines unique to FILE1, column two contains lines unique to FILE2, and column three contains lines common to both files.

Options & Flags:

• -1
• Suppress column 1 (lines unique to FILE1).
• -2
• Suppress column 2 (lines unique to FILE2).
• -3
• Suppress column 3 (lines that appear in both files).

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that comm cannot corrupt system state or bypass security boundaries.

more is a filter for paging through text one screenful at a time. It allows you to view the contents of a file or piped command output page by page. Press SPACE or 'f' to advance to the next page, and 'q' to quit.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (page_output) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the more command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Less is a program similar to 'more', but it allows backward movement in the file as well as forward movement. It opens a full-screen pager to view the content.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (page_output) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the less command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The samwise command is the bridge to the AI Kernel. It has two primary modes: 1. **Agent Mode (Default):** A helpful assistant that answers questions. 2. **Autopilot Mode (--autopilot):** A kinetic driver (BoneAmanita) that EXECUTES tasks.

Options & Flags:

• -c, --chat
• Open an interactive, graphical chat session.
• -a, --autopilot
• Engage BoneAmanita Autopilot. The AI will DIRECTLY execute commands to
• fulfill your request. Use with caution.
• -f, --force
• Override Safety Interlocks. Allows the Autopilot to perform High Voltage
• actions (like mass deletion) without braking.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Mesh Transport Coordination: Checks local peer discovery state and RTC channel readiness before dispatching payloads.
3. Kinetic LLM Orchestration: Assembles system context, computes operation voltage safety scores, dispatches requests via ai_manager, and synthesizes output.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the samwise command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Writes the supplied text. After shell quoting, \n becomes a newline and \\ becomes a literal backslash. Other escapes are preserved. --literal disables this decoding and writes the argument exactly as received. Single-quote shell content to preserve its backslashes. With double-quoted shell content, double backslashes again for the shell layer.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that forge cannot corrupt system state or bypass security boundaries.

Manages project plans. By default, it operates on .planner files in the user's ~/.plans/ directory. When run as root, it manages system-wide projects in /etc/projects/.

Options & Flags:

• This command takes no options.
• SUB-COMMANDS
• create <name>
• Creates a new project plan.
• list
• Displays the status board for <project>. (This is the default action).
• add "<task>"
• Adds a new task to the plan.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (beep, execute_commands) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the planner command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Analyzes a set of files to describe their collective purpose and structure. It can be run on a directory path or accept a list of file paths from standard input (e.g., from `find` or `ls`).

Options & Flags:

• --mode <mode>
• The analysis mode ('code' or 'prose'). Defaults to 'code'.
• --summary
• Generate a single, concise paragraph summary instead of a detailed analysis.
• --ask "<question>"
• Ask a specific question about the provided files.
• --provider <name>
• Specify the AI provider (e.g., 'gemini', 'ollama'). Defaults to 'ollama'.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Kinetic LLM Orchestration: Assembles system context, computes operation voltage safety scores, dispatches requests via ai_manager, and synthesizes output.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the storyboard command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The remix command uses an AI to read two source files, understand the core ideas of each, and then generate a new, summarized article that synthesizes the information from both.

Options & Flags:

• -p, --provider <name>
• Specify the AI provider (e.g., 'gemini', 'ollama'). Defaults to 'ollama'.
• -m, --model <name>
• Specify the exact model name to use for the chosen provider.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Kinetic LLM Orchestration: Assembles system context, computes operation voltage safety scores, dispatches requests via ai_manager, and synthesizes output.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the remix command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Chidi is a powerful graphical tool that leverages a Large Language Model (LLM) to help you understand and interact with your files in FractalOS. It can summarize documents, suggest insightful questions, and answer your questions based on the content of the files you provide. When pointed at a .story directory, Chidi will provide a narrative summary of the project's history.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Kinetic LLM Orchestration: Assembles system context, computes operation voltage safety scores, dispatches requests via ai_manager, and synthesizes output.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the chidi command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Manages all aspects of a TTRPG character by creating a centralized binder and providing easy access to journals, quest logs, and character sheets.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (execute_commands) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the character command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Displays active peer nodes discovered on the FractalOS mesh network. Shows node IDs, remote usernames, transport layers (WebRTC, BroadcastChannel, WebSocket), round-trip ping latency, and shared capabilities (remote shell, p2p file transfer, multiplayer gaming).

Options & Flags:

• --ping, -p
• Actively ping all discovered nodes and display round-trip latency in ms.
• --json, -j
• Output raw JSON data for shell scripting and automation.
• --gui, -g
• Launch the interactive fullscreen Mesh Network Monitor TUI app.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (launch_app, peers_display, peers_info) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the peers command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Attach your local terminal to a remote FractalOS instance on the mesh network. Once attached, commands entered locally execute in the remote host's environment, with outputs streamed back in real time. Both host and client see commands in a shared pair-programming terminal session.

Options & Flags:

• -l, --list List discovered nodes available for attachment.
• -d, --detach Detach from the currently active remote session.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Mesh Transport Coordination: Checks local peer discovery state and RTC channel readiness before dispatching payloads.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (mesh_attach, mesh_attach_list, mesh_detach) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the attach command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Leaves the currently attached remote mesh terminal session and returns to the local terminal shell prompt.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Mesh Transport Coordination: Checks local peer discovery state and RTC channel readiness before dispatching payloads.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (mesh_detach) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the detach command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Displays a broadcast message across the terminals of all connected FractalOS mesh nodes. Reads from arguments or standard input.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Mesh Transport Coordination: Checks local peer discovery state and RTC channel readiness before dispatching payloads.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (mesh_wall) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the wall command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Sends a direct message to a specific FractalOS node across the mesh network, alerting the recipient terminal.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Mesh Transport Coordination: Checks local peer discovery state and RTC channel readiness before dispatching payloads.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (mesh_talk) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the talk command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Transfers files directly between FractalOS nodes over the mesh network (WebRTC / WebSockets / BroadcastChannel) without third-party cloud storage.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (mesh_file_pull, mesh_file_send) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the mesh_cp command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Dispatches sub-tasks, queries, or autopilot operations to a peer node's 'samwise' agent across the FractalOS distributed mesh network (via WebSockets, WebRTC, or BroadcastChannel).

Options & Flags:

• --autopilot, -a
• Executes the delegated prompt using BoneAmanita Autopilot mode on the remote node.
• --max-voltage, -v, -V <voltage>
• Specifies a strict voltage budget cap for the task. If remote planning exceeds
• this limit, the task will disengage without executing kinetic actions.
• --dry-run
• Generates and scores the remote plan with voltage audit, but does not execute
• any kinetic steps.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Mesh Transport Coordination: Checks local peer discovery state and RTC channel readiness before dispatching payloads.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (mesh_agent_delegate) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the mesh_agent command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The swarm command provides a high-level cockpit for multi-agent swarm operations across the FractalOS distributed mesh. It allows node operators to inspect and configure the node's voltage limits, physical hardware GPIO permissions, and provenance audit log.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Mesh Transport Coordination: Checks local peer discovery state and RTC channel readiness before dispatching payloads.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. swarm operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Transfers files directly between FractalOS nodes over the mesh network. Syntax and behavior are identical to 'mesh-cp'.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Mesh Transport Coordination: Checks local peer discovery state and RTC channel readiness before dispatching payloads.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. scp operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

A utility for network communication between FractalOS instances. It can send direct messages or set up a listener to receive them. -e, --exec (with -l) executes incoming messages as commands. WARNING: --exec is a security risk. Use with trusted peers only.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Mesh Transport Coordination: Checks local peer discovery state and RTC channel readiness before dispatching payloads.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (netcat_listen, netcat_send) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the nc command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Displays a list of all discovered FractalOS instances and their connection status, including your own instance ID. When given --mesh, prints detailed mesh node presence with latency and shared capabilities.

Options & Flags:

• --mesh, -m
• Displays full mesh node presence table with latency and capabilities.
• --ping, -p
• Measures round-trip ping latency to each peer.
• --gui, -g
• Launches the graphical Mesh Network Monitor app.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Mesh Transport Coordination: Checks local peer discovery state and RTC channel readiness before dispatching payloads.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (launch_app, netstat_display, peers_display) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the netstat command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Splits the active terminal pane into two horizontal (top and bottom) panes. Shortcut for 'split -h'.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. split_h operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Splits the active terminal pane into two vertical (left and right) panes. Shortcut for 'split -v'.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. split_v operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

The split command multiplexes the FractalOS terminal interface into multiple horizontal or vertical split panes with independent working directories, command histories, and output buffers.

Options & Flags:

• --vertical, -v
• Splits the current pane vertically (side-by-side, default).
• --horizontal, -h
• Splits the current pane horizontally (top and bottom).
• --command, -c <cmd>
• Automatically executes <cmd> inside the newly created pane upon creation.
• --list, -l
• Lists all currently active panes, their working directories, and active status.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (multiplexer_action) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the split command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Displays a list of all active terminal multiplexer panes, their identifiers, current working directories, and whether they are active or zoomed.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. panes operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Closes the specified terminal split pane (or the currently focused pane if omitted). When only one pane remains, it cannot be closed.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. close_pane operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Switches active input focus and working directory context to the specified terminal pane. Supports pane index (e.g. 'focus 2'), pane ID (e.g. 'focus pane-2'), or relative navigation ('focus next', 'focus prev').

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. focus operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Manages interactive TUI windows for overlay and desktop applications (Editor, Paint, Top, Adventure, Netgame, Peers, Chidi, etc.).

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (window_action) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the wm command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Executes the window utility.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. window operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Displays a real-time status summary of FractalOS system components, including working directory, active terminal panes, background jobs, connected mesh peers, audio mute status, AI agent state, and recent alerts.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Mesh Transport Coordination: Checks local peer discovery state and RTC channel readiness before dispatching payloads.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (status_action) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the status command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The login utility logs a new user into the system. If a password is not provided on the command line, the user will be prompted for one.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (login) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the login command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The logout utility terminates a session. If this is the last active session for the user, they will be returned to the Guest user session.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (logout) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the logout command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The su utility allows a user to run a new shell as another user. If a username is not provided, it defaults to 'root'. If a password is not provided on the command line, the user will be prompted for one interactively. To return to your original session, type 'logout'.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (su) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the su command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

sudo allows a permitted user to execute a command as the superuser (root), as specified by the security policy in the /etc/sudoers file. The user will be prompted for their own password to authenticate.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Security & Authority Verification: Validates user identity, group affiliations, or cryptographic credentials against system authority managers before proceeding.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (sudo_exec) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the sudo command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

visudo edits the sudoers file in a safe way. It launches the system editor and, upon saving, will perform a syntax check before applying

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (launch_app) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the visudo command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Prints the user name associated with the current effective user ID.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. whoami operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Print information about users who are currently logged in. This command lists all active sessions in the current user's stack, showing the order in which users were switched using the 'su' command.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. who operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Creates a new user account with the specified username. This command also creates a primary group with the same name and a home directory at /home/<username>. If run interactively, it will prompt for a new password. This command requires root privileges.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (sync_user_and_group_state, useradd) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the useradd command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Removes a user account from the system. This command requires root privileges.

Options & Flags:

• -r, --remove-home
• Remove the user's home directory.
• -f, --force
• Never prompt for confirmation, even if the user is logged in.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Security & Authority Verification: Validates user identity, group affiliations, or cryptographic credentials against system authority managers before proceeding.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (removeuser, sync_user_and_group_state) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the removeuser command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The passwd utility changes the password for the specified user account. If no username is provided, it changes the password for the current user. Running this command will begin an interactive prompt to enter the new password. A regular user may only change their own password. The super-user (root) may change the password for any account.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (passwd) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the passwd command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Modifies the properties of an existing user account. This command requires root privileges.

Options & Flags:

• -aG, --append-groups GROUP
• Add the user to the supplementary GROUP.
• -g, --gid GROUP
• Set the user's primary group.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Security & Authority Verification: Validates user identity, group affiliations, or cryptographic credentials against system authority managers before proceeding.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (sync_group_state) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the usermod command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Creates a new group with the specified name. This command can only be run by the root user. Group names cannot contain spaces.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Security & Authority Verification: Validates user identity, group affiliations, or cryptographic credentials against system authority managers before proceeding.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (sync_group_state) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the groupadd command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Deletes an existing group. You cannot delete the primary group of an existing user. This command can only be run by the root user.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Security & Authority Verification: Validates user identity, group affiliations, or cryptographic credentials against system authority managers before proceeding.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (sync_group_state) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the groupdel command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Print group memberships for each USERNAME. If USERNAME is omitted, the command prints the groups for the current user.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Security & Authority Verification: Validates user identity, group affiliations, or cryptographic credentials against system authority managers before proceeding.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. groups operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

The listusers command displays a list of all user accounts that currently exist on the system.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. listusers operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Automates the creation of a user group, a shared project directory (/home/project_<name>), and the assignment of appropriate permissions for collaborative work. It also automatically creates a project planner file inside the new directory. This command can only be run by the root user.

Options & Flags:

• -c, --create <name>
• The name for the new committee. This will be used for the group name and the project directory. (Required)
• -m, --members <user1>,<user2>...
• A comma-separated list of existing users to add to the new group. (Required)

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (sync_group_state) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the committee command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Changes the file mode bits (permissions) of each given file according to mode, which must be an octal number (e.g., 755, 644). Only the file's owner or the root user may change the mode of a file.

Options & Flags:

• -R, --recursive
• Change files and directories recursively.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that chmod cannot corrupt system state or bypass security boundaries.

Changes the user ownership of each given FILE to OWNER. This command can only be run by the root user.

Options & Flags:

• -R, -r, --recursive
• Operate on files and directories recursively.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that chown cannot corrupt system state or bypass security boundaries.

Changes the group ownership of each given FILE to GROUP. The user running the command must be root.

Options & Flags:

• -R, -r, --recursive
• Operate on files and directories recursively.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that chgrp cannot corrupt system state or bypass security boundaries.

The run command reads and executes commands from a file in the current shell environment. It is useful for automating tasks. Script arguments can be accessed within the script using $1, $2, etc. It also supports non-interactive password setting for commands like 'useradd' or 'sudo' by placing the required password(s) on the line(s) immediately following the command.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (execute_script) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the run command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

A testing utility that executes a given command string. It succeeds if the command fails. This is useful for writing automated test scripts.

Options & Flags:

• -z, --check-empty
• The check succeeds if the command produces no standard output, regardless of its success or failure.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. check_fail operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Echo the STRING(s) to standard output, followed by a newline.

Options & Flags:

• -e
• Enable interpretation of backslash escapes (e.g., \n for newline, \t for tab).

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. echo operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Write formatted data to standard output. Interprets backslash escapes and format specifiers.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. printf operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Does nothing and returns true (success).

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. true operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

The delay command pauses execution for the specified number of milliseconds. It is primarily used within scripts (executed via the 'run' command) to create timed sequences, demonstrations, or to wait for a background process.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (delay) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the delay command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Manages scheduled background tasks by modifying /etc/agenda.json. The AgendaDaemon process is responsible for executing these tasks.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that agenda cannot corrupt system state or bypass security boundaries.

The `alias` command allows you to create shortcuts for longer or more complex commands. - Running `alias` with no arguments prints the list of all current aliases. - With a name and value (e.g., `alias ll='ls -l'`), it creates or redefines an alias. - With only a name, it prints the value of that specific alias.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (sync_session_state) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the alias command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Removes each specified alias from the current session's list of defined aliases.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (sync_session_state) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the unalias command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Displays the command history list with line numbers.

Options & Flags:

• -c, --clear
• Clear the history list by deleting all entries.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Snapshot Tree Traversal: Traverses .story/ content-addressed blobs, updating commit manifests or rolling back VFS inodes.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. history operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Set or display environment variables. When run without arguments, it displays a list of all current environment variables. When a variable and value are provided, it sets or updates the variable.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (sync_session_state) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the set command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The unset command removes the specified environment variable(s). Once unset, a variable will no longer be available to commands or for expansion.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (sync_session_state) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the unset command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The clear utility clears the terminal screen of all previous output, moving the prompt to the top of the window.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (clear_screen) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the clear command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

ps displays information about a selection of the active processes, including background jobs and their current status (e.g., Running, Stopped).

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. ps operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Provides a dynamic, real-time view of the processes running in FractalOS. The top command opens a process viewer window listing all active background jobs and system processes. By default it docks side-by-side with the terminal. Press 'q' or 'Escape' to quit.

Options & Flags:

• -d, --dock
• Dock side-by-side with the shell terminal (default).
• -f, --float
• Open in a floating, movable window.
• --full
• Open in fullscreen overlay mode.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (launch_app) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the top command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The kill utility sends a signal to the specified processes or jobs. If no signal is specified, the TERM signal is sent, which requests a clean termination.

Options & Flags:

• -s, --signal <sigspec>
• Specify the signal to be sent. Common signals include TERM, KILL, and STOP.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (signal_job) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the kill command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Resumes one or more stopped background jobs, keeping them in the background. If no job_id is specified, the most recently stopped job is used. You can specify jobs by their job ID (e.g., %1) or their process ID (e.g., 1).

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (signal_job) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the bg command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Resumes a stopped or background job and brings it to the foreground, giving it control of the terminal. If no job_id is specified, the most recently backgrounded or stopped job is used.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (signal_job) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the fg command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Lists the background jobs that were started from the current terminal, along with their status (Running, Stopped) and command.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. jobs operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Print the current time, how long the system has been running since the web page was loaded, and the number of users currently logged on.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. uptime operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Displays the current time and date according to the system's clock. The output format is similar to the standard Unix date command. (Note: Setting the date is not supported in FractalOS).

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. date operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Base64 encode or decode FILE, or standard input, to standard output. With no FILE, or when FILE is -, read standard input.

Options & Flags:

• -d, --decode
• decode data

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that base64 cannot corrupt system state or bypass security boundaries.

The cksum utility calculates and writes to standard output a single line for each input file. The line consists of the CRC checksum of the file, the number of bytes in the file, and the name of the file. If no file is specified, cksum reads from standard input.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that cksum cannot corrupt system state or bypass security boundaries.

Encrypts or decrypts a file using a password. It uses a robust, salt-based key derivation function to protect against simple attacks.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that ocrypt cannot corrupt system state or bypass security boundaries.

Encrypts or decrypts the given FILE or standard input using a repeating XOR cipher with the provided KEY. The command is its own inverse; running it a second time with the same key will decrypt the content. This is a simple cipher and should not be used for serious security.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that xor cannot corrupt system state or bypass security boundaries.

zip is a compression and file packaging utility. It puts one or more files into a single zip archive. Directories are archived recursively. The resulting archive is base64-encoded to be stored as a text file.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that zip cannot corrupt system state or bypass security boundaries.

The unzip utility will extract files from a ZIP archive created by the 'zip' command. If a destination directory is specified, files will be extracted there; otherwise, they are extracted to the current directory.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that unzip cannot corrupt system state or bypass security boundaries.

fsck is used to check and optionally repair the virtual file system. It checks for orphaned nodes (files owned by non-existent users/groups), dangling symbolic links, and ensures every user has a home directory.

Options & Flags:

• --repair
• Attempt to repair any issues found. Orphaned nodes will be reassigned to root, and dangling links will be removed.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that fsck cannot corrupt system state or bypass security boundaries.

bc is a basic calculator that evaluates a mathematical expression provided as an argument or from standard input. It supports basic arithmetic operations (+, -, *, /) and parentheses for grouping. It also supports several mathematical functions like sqrt(), pow(), sin(), etc.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. bc operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Print the value of EXPRESSION to standard output. Supports basic arithmetic operators: +, -, *, /, % and parentheses for grouping. Each part of the expression must be separated by spaces.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. expr operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Manages the history of a project as a series of named "chapters" (snapshots). It's designed to be simple, safe, and intuitive.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Snapshot Tree Traversal: Traverses .story/ content-addressed blobs, updating commit manifests or rolling back VFS inodes.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the story command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The sync utility forces a write of all buffered file system data to the underlying persistent storage (IndexedDB in the browser). It is useful to ensure all changes are saved before a critical operation.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that sync cannot corrupt system state or bypass security boundaries.

Creates a JSON file containing a snapshot of the current system state, including the filesystem, users, groups, and session data. The backup includes a checksum for integrity verification. This command can only be run by the 'root' user.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (backup_data) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the backup command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Restores the FractalOS system from a backup file (.json). This operation is destructive and will overwrite your entire current system. The command will prompt you to select a backup file and confirm before proceeding. This command can only be run by the root user.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (trigger_restore_flow) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the restore command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The reset command completely wipes all system data from the browser, including the filesystem, user accounts, and all session data, restoring it to the default, initial state. This is a destructive factory reset operation and requires confirmation. This command can only be run by the root user.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (confirm, full_reset) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the reset command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Stops all running processes and restarts the FractalOS session by reloading the page.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (reboot) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the reboot command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Manages the system-wide, persistent message board located at /var/log/bulletin.md. Any user can post a message or list the contents, but only the root user can clear the board. Users in the 'towncrier' group can make official announcements.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that bulletin cannot corrupt system state or bypass security boundaries.

Sends a string <message> to the specified <job_id>'s message queue for inter-process communication.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (post_message) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the post_message command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Retrieves all pending string messages for the specified <job_id>. Once read, messages are removed from the queue. The output is a space-separated string of all messages.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (read_messages) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the read_messages command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Sends a notification alert to the FractalOS persistent status bar ticker and archives it into the system notification drawer.

Options & Flags:

• --info
• Information notification (default, blue).
• --success
• Success notification (green checkmark).
• --warn
• Warning notification (yellow alert).
• --error
• Error alert (red critical badge).

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (notify, status_action) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the notify command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Interacts with the system clipboard. Allows copying text to clipboard, pasting from clipboard, checking status, and piping shell output into clipboard.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (clipboard_action) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the clip command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Copies data from standard input or command arguments to the system clipboard, matching macOS / BSD pbcopy behavior.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (clipboard_action) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the pbcopy command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Outputs the contents of the system clipboard to standard output, matching macOS / BSD pbpaste behavior.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (clipboard_action) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the pbpaste command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Allows users to list, apply, or retrieve data for themes. Themes are stored as .json files in /etc/themes/.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (apply_theme) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the theme command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Engages or disengages a cinematic mode where all terminal output is displayed character by character, creating a dramatic, retro effect. Running the command without an argument toggles the current state.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (toggle_cinematic_mode) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the cinematic command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

A ritual is a performative act that prepares the system and the magician for magical workings. It is not one action, but a sequence of commands, sounds, and delays designed to create a sympathetic environment for the intended spellcraft. It turns mere execution into a deliberate act of will.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (execute_commands) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the ritual command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Plays a musical note or chord using the system synthesizer. Notes should be specified in standard notation (e.g., C4, F#5). Chords are space-separated notes within quotes. Duration is specified in notation like '4n' (quarter note) or '8n' (eighth note).

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (play_sound) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the play command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Plays a short, simple system tone through the emulated sound card. It's useful for getting auditory feedback in scripts or to signal the completion of a task.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (beep) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the beep command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The printscreen command captures the visible content of the terminal. In Image Mode (default), it generates a PNG image of the terminal and initiates a browser download. In Text Dump Mode, if an [output_file] is specified, it dumps the visible text content of the terminal to that file.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (capture_screenshot_png, dump_screen_text) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the printscreen command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Initiates a file upload from your local computer to the current directory in FractalOS by opening the browser's native file selection dialog. You can select multiple files to upload at once.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (trigger_upload_flow) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the upload command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Initiates a browser download for the specified FILE, allowing you to save it from the virtual file system to your computer's local hard drive.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (export_file) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the export command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Launches the FractalOS graphical text editor. - If a filepath is provided, it opens that file. - If the file does not exist, a new empty file will be created with that name upon saving. - If no filepath is given, it opens a new, untitled document.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (launch_app) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the edit command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Launches a character-based art editor. If a filename is provided, it will be opened. Files must have the '.oopic' extension.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (launch_app) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the paint command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Launches the FractalOS interactive fiction engine. When run without arguments, it starts the default built-in adventure. If a path to a valid JSON game file is provided, it will load that adventure instead.

Options & Flags:

• --create
• Launches the interactive adventure creation tool to build a new game file.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (launch_app, launch_interactive_app) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the adventure command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Launches a full-screen IDE for Fractal Basic. If a filename is provided, that file will be loaded into the editor buffer.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (launch_app) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the basic command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

The 'log' command serves as your personal, timestamped journal. - Quick Add Mode: Running 'log' with the -n flag creates a new entry. - Application Mode: Running 'log' with no arguments launches the graphical app.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (launch_app) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the log command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Executes the python utility.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that python cannot corrupt system state or bypass security boundaries.

Manages, validates, bundles, publishes, resolves dependencies, and installs community packages in FractalOS with integrity verification and security sandboxing. Packages are Python files defining the command interface: - metadata(): returns dict with name, version, description, author, license, wheels, dependencies, permissions - define_flags(): declares command line flags and aliases - run(args, flags, user_context, ...): execution entry point - man(...) and help(...): documentation

Options & Flags:

• -n, --dry-run
• Simulate packaging/publishing and preview the catalog entry without modifying files.
• -j, --json
• Output manifest, validation, dependency tree, audit report, or package bundle in JSON format.
• -e, --export <dir>
• Specify custom export directory for package publishing.
• -o, --out <file>
• Specify output destination file for 'pkg pack'.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Package Lifecycle Management: Performs SHA256 integrity checks, inspects permission scopes, and manages package nodes in /etc/packages/.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the pkg command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Interacts with hardware sensors, buttons, and actuators. In Portable Mode on a Raspberry Pi, communicates with physical hardware via Neutralino's OS bridge. In browser or virtual mode, provides a virtual bus with full sensor simulation and background monitoring.

Options & Flags:

• --trigger, -t
• Trigger condition for monitoring: 'change' (default), 'rising' (button press / low-to-high),
• or 'falling' (button release / high-to-low).
• --interval, -i
• Polling interval in milliseconds (default: 500ms).
• --action, -a
• Shell command string executed automatically when trigger condition fires.
• --mesh, -m

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Mesh Transport Coordination: Checks local peer discovery state and RTC channel readiness before dispatching payloads.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (gpio_monitor_list, gpio_monitor_start, gpio_monitor_stop, gpio_simulate) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the gpio command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Direct shortcut for Connect 4 in FractalOS. See 'man netgame' for full details.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. c4 operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Direct shortcut for Tic-Tac-Toe in FractalOS. See 'man netgame' for full details.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. ttt operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Runs peer-to-peer multiplayer turn-based terminal games across FractalOS nodes. Supports Connect 4 ('c4') and Tic-Tac-Toe ('ttt'). Can be played directly in shell mode with ANSI-rendered boards or in a graphical fullscreen TUI window. Also supports solo matches against an automated bot.

Options & Flags:

• --gui, -g
• Launches the game in a graphical TUI window.
• --bot, -b
• Plays locally against an automated bot.
• --local
• Plays local pass-and-play.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. Workspace State Resolution: Queries active pane or window context to coordinate layout geometry and active terminal viewport mapping.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (launch_app, mesh_game_action) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the netgame command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Rolls dice based on standard tabletop RPG notation (e.g., XdY+Z). It shows the individual rolls, the modifier, and the final total.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. roll operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

Displays a leaderboard of users based on the number of tasks they have completed using the 'planner' command. It's a fun way to track productivity!

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that score cannot corrupt system state or bypass security boundaries.

The cast command allows the user to perform magical spells that have tangible effects on the operating system's state.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (execute_commands) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the cast command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Displays a list of all available commands. If a command is specified, it displays a short usage summary for that command. For more detailed information, use 'man [command]'.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Follows standard Unix modularity and the single-responsibility principle. help operates cleanly as a composable pipeline component, handling input streams and exit statuses predictably.

man is the system's manual pager. It formats and displays the on-line manual page for a given command.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. State & Context Preparation: Binds execution context (working directory, environment variables, active user identity).
3. Effect Dispatch: Evaluates command operations and constructs declarative effect payload(s) (launch_app) for frontend fulfillment.
4. Frontend Fulfillment: Returns JSON result structure containing the declarative effect to effect_handler.js, triggering browser UI/audio execution.

Employs the Effect Contract Pattern (Decision D-002). By keeping presentation, audio, and DOM manipulation strictly decoupled in the JavaScript stage manager, the man command remains completely deterministic, sandboxed, and headlessly testable in pure Python.

Print the full filename of the current working directory.

Options & Flags:

• This command takes no options.

1. Input & Flag Parsing: The executor tokenizes arguments, matching defined flags (via define_flags() if configured) and isolating positional path or string targets.
2. VFS Path & Permission Validation: Interacts with filesystem.fs_manager to resolve paths, traverse inodes, and verify POSIX read, write, or execute permissions for user_context.
3. In-Memory Computation: Executes core logic synchronously or asynchronously within CPython 3.14 WebAssembly space.
4. Output Emission: Formats clean stdout string (with optional ANSI styling when requested) returned to the terminal output buffer.

Leverages centralized VFS authority (Tenet 1: Python is the Source of Truth). Centralizing inode manipulation and octal permission checks within filesystem.py ensures that pwd cannot corrupt system state or bypass security boundaries.