// read me first

Documentation.

Everything written down: a practical user guide for running MayteraOS, and the project's design docs and references, from the TLS stack and the Win16 translation layer to the AI tool-contract protocol.

Start here

User guide

Install and boot MayteraOS, find your way around the desktop, use the apps, talk to the AI assistant, run Win16 and DOS software, tune the system, troubleshoot.

docs/user-guide.html

Downloads

The installer ISO preview, the bootable UEFI disk image, and system requirements.

downloads.html

Changelog

The full development history, newest first, grouped by day and searchable.

changelog.html

Overview

Deployment & Architecture

How MayteraOS is built and deployed: the build pipeline, test virtual machines, and the boot disk layout.

docs/deploy-architecture.html

UI Style Guide

The authoritative CDE/Motif palette, typography, spacing and component specs for the desktop.

docs/ui-style-guide.html

Window Manager

Analysis of the userland compositor and window-management model.

docs/window-manager.html

UI Primitives

Plan for the shared beveled widget primitives used across every app.

docs/ui-primitives.html

Notifications

Design of the desktop notification subsystem.

docs/notifications.html

Settings

The Settings app overhaul plan.

docs/settings.html

Theming

Notes on additional theme directions beyond the default retro-UNIX look.

docs/theming.html

System & Networking

Hardening & Mitigations

What MayteraOS actually enforces today against exploitation: PIE, ASLR, W^X, stack canaries, SMEP/SMAP, syscall pointer validation and TLS certificate verification, each with its evidence and its gaps.

docs/hardening.html

TLS 1.2/1.3 Stack

The from-scratch TLS implementation: handshake, ciphers, record layer.

docs/tls.html

SSH Subsystem

Design of the SSH-2 client and server (curve25519, AES-GCM, RSA), at the protocol and architecture level.

docs/ssh.html

SSH Client Design

Design of the interactive SSH client.

docs/ssh-client.html

Web Browser

The browser engine: layout, CSS, HTTP/2, image decoding.

docs/browser.html

Security Audit

A high-level summary of the project's self-conducted security audit.

docs/security-audit.html

Compatibility & Apps

DOOM Port

Engineering notes from porting id Software's DOOM engine onto the native platform layer.

docs/doom.html

Python Support

Plan for running a Python interpreter as a Ring 3 user program.

docs/python.html

Python Progress

Progress log for the Python port.

docs/python-progress.html

Windows 3.x Compatibility

The NE loader and Win16 KERNEL/USER/GDI translation layer for real 16-bit programs you supply.

docs/win16.html

Win16 Assessment

Assessment of the scope and strategy for Windows 3.x support.

docs/win16-assessment.html

Word Processor Bring-up

A deep dive into running a user-supplied commercial Win16 word processor via the Win16 + OLE2 layers.

docs/word6.html

AI & Future

AI / LLM Contracts

The concept doc for the AI-to-OS integration: per-app tool contracts and capability tokens.

docs/llm-contracts.html

Self-Reprogrammable OS

Design for an OS the AI can extend from chat via a userland compiler.

docs/self-reprogrammable.html

Reference

Syscall Reference

The current syscall table, generated straight from the kernel dispatcher source so it cannot drift from what actually ships.

docs/syscalls.html

Licenses

Licenses and attribution for ported and third-party components.

docs/licenses.html

Deployment Notes

High-level notes on how builds are deployed and verified.

docs/deployment-notes.html