User Guide

This guide covers the essential commands for navigating and interacting with the OopisOS environment. For a quick list of all commands, type help. For a detailed manual on a specific command, type man [command_name].

Essential Commands

Application Suite

OopisOS comes with several built-in applications that run in a full-screen, modal interface, providing a richer experience than standard command-line tools.

edit [file]

Opens the OopisOS text editor. It's a surprisingly capable editor with features like live Markdown and HTML preview (`Ctrl+P`), a formatting toolbar, and keyboard shortcuts for saving (`Ctrl+S`) and exiting (`Ctrl+O`).

paint [file.oopic]

Unleash your creativity with the character-based art editor. It features a full canvas, multiple tools (pencil, eraser, shapes), a color palette, and saves your work to the custom `.oopic` format.

chidi [path]

The AI Librarian. Point `chidi` at a directory of Markdown files (`.md`) to open a dedicated reading interface. Here, you can ask the AI to summarize documents, generate study questions, or perform a query across all loaded documents to find specific information.

adventure [file.json]

Launches the text adventure game engine. You can play the default built-in game or load your own custom adventures from a `.json` file.

Advanced Topics

Ready to wield true power? This section covers the tools that separate the administrators from the users.

Privilege Escalation: `sudo` and `visudo`

Not all users are created equal. Some tasks, like installing software or modifying critical system files, require the power of the `root` user. The `sudo` command is your key to borrowing that power, safely and temporarily.

sudo [command]

The `sudo` (superuser do) command executes a single command with `root` privileges. The first time you use `sudo`, you will be prompted for *your own* password to verify your identity. If successful, a timestamp is recorded, and you won't need to enter your password again for a set period (typically 15 minutes).

visudo

Who gets to use `sudo`? That's controlled by the /etc/sudoers file. You must **never** edit this file directly with `edit`. The `visudo` command is the only safe way to modify it. It opens the file in the editor but adds a lock to prevent multiple simultaneous edits and, more importantly, performs a syntax check on save to prevent you from locking yourself out of the system.

Permissions: Only the `root` user can run `visudo`.

# /etc/sudoers example
# Give the user 'admin' full root privileges
admin    ALL

# Allow anyone in the 'testers' group to run the 'reboot' command
%testers reboot
            

File Archival: `zip` and `unzip`

Manage collections of files by bundling them into a single archive.

zip [archive.zip] [path_to_zip]

Creates a simulated `.zip` archive containing the file or directory at the specified path. This is a recursive operation that preserves the directory structure within the archive.

unzip [archive.zip] [destination_path]

Extracts the contents of a `.zip` archive into the specified destination directory. If no destination is provided, it extracts to the current directory.

Developer Documentation

The OopisOS v3.0 "Keystone" release introduces a new, highly modular command architecture. This design is a core component of the system's stability and makes adding new commands a secure and straightforward process. This is a brief overview; for the full architectural document, please see /docs/developer.md.

The Command Contract

Adding a new command is a declarative process. Instead of writing boilerplate validation logic, you *declare* your command's requirements to the `CommandExecutor`. The executor enforces these rules *before* your command's core logic is ever run. This is a critical security and stability feature.

The contract is defined in a single object and includes:

• flagDefinitions: All flags the command accepts (e.g., `-v`, `--verbose`).
• argValidation: The number of arguments your command expects (e.g., min, max, exact).
• pathValidation: Which arguments are file paths and what type they should be (`file` or `directory`).
• permissionChecks: Which permissions (`read`, `write`, `execute`) the user must have on those paths.

Example: Creating a New Command

Here is the standard pattern for creating a new command file in /scripts/commands/.

// scripts/commands/mycommand.js
(() => {
    "use strict";

    const myCommandDefinition = {
        commandName: "mycommand",
        // 1. Define the contract
        argValidation: { exact: 1 },
        pathValidation: [{ argIndex: 0, options: { expectedType: 'file' } }],
        permissionChecks: [{ pathArgIndex: 0, permissions: ['read'] }],

        // 2. Write the core logic, trusting the context is pre-validated
        coreLogic: async (context) => {
            const { validatedPaths } = context;
            const pathInfo = validatedPaths[0]; // Guaranteed to be a valid, readable file.
            return { success: true, output: `File content: ${pathInfo.node.content}` };
        }
    };

    const description = "A brief summary for 'help'.";
    const helpText = "Usage: mycommand <file>...";

    // 3. Register it with the system
    CommandRegistry.register("mycommand", myCommandDefinition, description, helpText);
})();
            

After creating the file, simply add a <script> tag for it in index.html (after `registry.js` and before `commexec.js`), and your command will be available on the next boot.

Testing & Showcase Environment

A brand new OS can feel... empty. To combat this digital loneliness and give you something to immediately play with, we've included two very special scripts.

The World-Builder: `inflate.sh`

Think of this as the ultimate demo disk. A single command that terraforms your empty home directory into a bustling ecosystem of files, directories, and secrets, all designed for you to test, abuse, and explore.

Just run this command to create your new world:

The Gauntlet: `diag.sh`

This is our quality assurance department, packed into a single script. It's a relentless stress test that runs a barrage of commands to ensure the OS doesn't melt into a puddle of ones and zeros under pressure. It's a comprehensive suite that tests the entire v3.0 feature set, including the new administrative (`sudo`) and file management (`zip`/`unzip`) commands. It is the definitive way to confirm all systems are operational.

About & Credits

You've reached the end of the manual. If you're still reading, you're either a developer, a completionist, or hopelessly lost. In any case, here's the story behind the machine and the legal fine print that gives it its soul.

The Creators

OopisOS is the unlikely result of a caffeine-and-code-fueled fever dream, a collaboration between:

• Andrew Edmark (The Human Element, Chief Architect)
• Gemini (The AI Assistant, Humble Narrator, and Primary Cause of Bugs-Turned-Features)

The Social Contract (aka The Boring Legal Bit)

Yes, even a simulated OS in a browser tab needs a license. This one is special. It's an MIT license at its core, but with an extended preamble to acknowledge the beautiful weirdness of its creation. Here is the spirit of the agreement:

Preamble

This Software, OopisOS, represents a collaborative endeavor between human direction and artificial intelligence.

Copyright (c) 2025 Andrew Edmark (hereinafter referred to as the "Curator")

Authorship and Contribution Acknowledgment

This Software was developed by the Curator through a process of interactive collaboration with Google's Gemini, an artificial intelligence language model (the "AI Assistant"). The Curator provided the initial concepts, creative direction, iterative prompts, critical review, testing, and the selection of the final form of the Software. The AI Assistant, under the explicit direction and oversight of the Curator, contributed to the generation, drafting, and composition of portions of the code and associated documentation.

License Grant

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

• The above copyright notice, the Authorship and Contribution Acknowledgment, and this permission notice shall be included in all copies or substantial portions of the Software.

Disclaimer of Warranty

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS (INCLUDING THE CURATOR) OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.