DOCUMENTATION

This page reflects the current implementation of MARIA OS (MARIA CODE). It connects doctrine → build → operations in one language, so teams can run a self-evolving loop with reproducible evidence.

Overview (MARIA CODE vs MARIA OS)

One philosophy, two products: personal developer execution (MARIA CODE) and enterprise organizational intelligence OS (MARIA OS).

MARIA is a Structural AGI operating system designed to explicitly model the structure of the world and organizations—OS, rules, flows, and causality—and to help you design, change, and invent those structures.

MARIA CODE: personal developer execution platform (CLI + slash commands).

MARIA OS: enterprise OS layer for organizational intelligence (doctor → decide → execute → verify → learn), designed for governed operation and local execution by default (LOCAL_MODE-aligned).

The goal is not “plausible answers,” but structures that are reproducible, operable, and evolvable. That is why this repo is designed as an OS across code (src/), configuration (config/), and doctrine & operations (docs/).

Enterprise quick links

/enterprise — MARIA OS Playground + overview

/enterprise/assessment — readiness assessment to deploy MARIA OS

Sign-in is required for Playground and Assessment (Google / GitHub).

The core loop (EVOLVE)

doctor diagnoses the system with evidence.

Parent MARIA decides with deterministic gates and approvals.

Agents execute with Envelopes and produce Artifacts.

GateReport → DoctorDelta verifies and updates memory safely.

Universe / EVOLVE / doctor (what makes MARIA OS “enterprise”)

Not “more AI” — an operating system that keeps decisions reproducible, auditable, and improving.

Universe (long-term memory with structure)

Universe is not “logs.” It is an organized memory shelf where every run is recorded as Events, distilled into Lessons, and stabilized as Procedures.

Work is issued as an Envelope (objective, constraints, boundaries, required tests, stop conditions). Outcomes are stored as Artifacts linked back to the Envelope — including failures.

doctor (diagnosis with evidence, not vibes)

doctor does not merely say “there is a problem.” It explains which boundaries are touched, what evidence supports the diagnosis, and what the expected blast radius is.

The same inputs should yield the same conclusions. Enterprise diagnosis must not “wobble.”

EVOLVE (safe improvement as a mechanism)

EVOLVE is the loop that makes improvement continuous: diagnose → decide → execute → verify → learn.

Adoption is gated by deterministic rules (safe/guarded/risky). When stakes are high, MARIA OS asks for approval with context and rollback conditions.

Verification produces a GateReport. Only after improvement is confirmed do we write back long-term memory (DoctorDelta).

Enterprise default: local execution

Enterprise deployments assume local-first execution (LOCAL_MODE-aligned) to keep data boundaries and audit trails under control. When in doubt, do not hardcode environment differences — absorb via config/loaders and keep evidence.

Principles (Structural AGI doctrine)

Essence before Solution / Safety by Structure / Human-first — plus enterprise requirements: determinism, traceability, and explicit gates.

Core principles

Essence before Solution: define “what structural problem is this?” in 1–3 lines before discussing solutions.
Safety by Structure: safety must be enforced by boundaries, responsibilities, detection, redundancy, and fail-safe design—not by “good intentions.”
Human-first: AI extends humans; final decisions and accountability remain with humans.

Enterprise principles (non-negotiable)

Determinism: same state → same conclusion (especially for doctor and gates).
Traceability: every decision must be explainable and link back to evidence and boundaries.
Explicit gates: safe/guarded/risky classification + approval when needed, with rollback conditions.

Think in layers (recommended)

OS layer: what becomes “default” (values, boundaries, responsibilities)

Rules layer: decision criteria, allow/deny, exceptions

Process layer: workflows, reviews/approvals, operating loops

Implementation layer: code, config, tests, monitoring

Implementation rules (consistency & governance)

No heuristics: do not hardcode fuzzy judgments. Delegate ambiguity to an LLM layer (e.g. ai-proxy) with explicit contracts and logs.
If the flow exists, improve the system prompt/contract first.
If the flow does not exist, improve the flow before tuning prompts.

Architecture (where things live)

CLI + slash commands + manifest + config + docs work together as one OS.

Repo layout (as an OS)

src/: core implementation (CLI, commands, services, agents)
config/: OS-layer configuration (agents, domains, brain profiles)
docs/: doctrine & operations (meta layer)
tests/: Vitest suites (unit/integration/contract/e2e)

Command reliability model

Only READY commands are exposed to users. Readiness is mechanically enforced by the manifest.

Source of truth: /help and READY.manifest.json

Key capabilities (current implementation)

/develop: goal → spec → design → tasks → initial steps
/code: plan-first safe code generation (dry-run/rollback/git-guard)
/code-review: GitHub Code Review Universe helper (review diff + deliverables from webhook runId)
/doctor: project/OS health checks (entry to improvement loop)
/agents: design/run/monitor multi-agent squads
/knowledge: knowledge packs + HOT KNOWLEDGE + HITL operations
/image /video: multimodal generation for docs, demos, and design
/workflow/resume: safe pause/resume for long-running work

Enterprise implementation pointers (src/services/...)

doctor (diagnosis)

Main entry (LLM JSON diagnosis + deep mode): `src/services/doctor/ProjectDoctorService.ts`
Deterministic check runner (non-LLM checks): `src/services/doctor/DoctorCore.ts`

Universe (lifecycle + memory foundations)

Universe init/validate/versioning: `src/services/ecosystem/UniverseLifecycleService.ts`
Event sourcing (audit trail / replay): `src/services/memory-system/event-sourcing/*`
Universe OS POC (local-only store; enterprise aligned): `src/services/universe-os-poc/UniverseOsPocService.ts`

Boundary guard (Safety Court)

LLM-based boundary judgment (no heuristics in host code): `src/services/safety/BoundaryGuardService.ts`

Approval & authorization gates

Role policy gate (STOP / HITL required / required artifacts): `src/services/decision-os/RolePolicy.ts`
Command-level RBAC guard: `src/services/security/RBACCommandGuard.ts`
Autonomous plan policy + approval requirement: `src/services/autonomous-agent/security/PolicyEngine.ts`

Deterministic risk classification (safe/guarded/risky)

See `src/services/evolve-ecosystem/doctor-to-task-spec.ts`.

Universe prototypes (latest)

Concrete, auditable workflows that demonstrate what “Universe” means in practice.

GitHub Code Review Universe (prototype)

A comment-only PR reviewer that prioritizes auditability, consistency, and reproducibility.

Inputs: PR metadata + diff + repo context + config (YAML) + optional graph/doctor context
Outputs: inline findings + summary comment + ReviewReport + DecisionTrace + GateReport
Determinism: same inputs → same findings (idempotency marker to avoid duplicates)

Try it (developer commands)

Review a diff (local):

/code-review review --diff artifacts/pr.diff --repo acme/repo --pr 123 --base abc --head def --no-llm

Generate deliverables (from webhook runId):

/code-review deliver --run-id 12345678:abcd --repo acme/repo --pr 123 --tenant tenant_demo_a

Deliverables are generated under docs/deliverables/universe-github-code-review-spec-v1/<runId>/.

Recommended workflow (structure → build → evolve)

Enterprise flow: diagnosis-first, gated execution, and safe learning into Universe.

Fastest loop (recommended)

Structure: define OS/boundaries/responsibilities/failure modes first
Design: turn goals into spec/tasks with clear acceptance criteria
Build: /code in plan-only → apply (rollback/guard as default)
Diagnose: /doctor + quality gates to keep “evidence”
Sync: update docs/knowledge so the OS stays consistent

Enterprise loop (what “EVOLVE” means in practice)

doctor: produce a diagnosis with evidence (boundaries, blast radius, risk)
Decision: classify safe/guarded/risky; request approval when required
Envelope: issue an explicit work order (constraints, do-not-touch, required tests, stop conditions)
Execution: agents act as roles (implementation/testing/review/ops) and publish Artifacts
Verification: GateReport + rollback readiness; then DoctorDelta updates long-term memory

Developer quick start

# 1) List available commands (only READY are shown)
maria /help

# 2) Turn a goal into spec/design/tasks
maria /develop "<your goal>"

# 3) Preview first (safe-by-default)
maria /code "<what to build>" --plan-only

# 4) Apply (non-interactive if needed)
maria /code "<what to build>" --apply --yes --rollback on

# 5) Health check
maria /doctor

Specs (practical flags & contracts)

Details live in /help. This section highlights the “patterns” developers/operators use daily.

/code (generate → preview → apply)

Rule: start with plan-only, avoid risky ops, keep rollback available.

# Preview (safe default)
maria /code "requirements..." --plan-only

# Apply (non-interactive)
maria /code "requirements..." --apply --yes --rollback on

# Git-guarded (leave evidence)
maria /code "requirements..." --apply --yes --git-guard on --git-commit on

--plan-only / --dry-run

Preview diffs and align before applying

--rollback on|off

Control rollback strategy on failures

--interactive / --yes

Human review vs non-interactive execution

--git-guard / --git-commit

Safety gates + commit-level audit trail

/auto-dev (small & safe autonomous changes)

A non-breaking-first autonomous dev engine for small, test-driven changes.

# Example: limit scope and attempts
maria /auto-dev run --goal "small fix" --target-files "src/..." --max-attempts 2

For deterministic gates, copy config/templates/auto-dev.config.yaml into your project as auto-dev.config.yaml.

/workflow/resume (the resume contract)

For multi-day/week work: restores summary/artifacts/decisions and bridges to the next action (often /code).

# Resume latest (summary mode)
maria /workflow/resume --latest --rehydrate summary

# Resume a specific task id (and pass flags to /code)
maria /workflow/resume <taskId> --tests --fix --apply

Full spec: docs/RESUME_FUNCTION_DESIGN.md

Manifest (“only READY is exposed”)

Command exposure is mechanically enforced by contract (metadata/execute, dependencies, tests). Only READY is visible in /help.

Best practices: docs/BEST_PRACTICE/MANIFEST_BEST_PRACTICE.md

Enterprise governance (boundaries + approvals)

Enterprise operations depend on three explicit contracts: boundaries, role/permission gates, and approval/rollback conditions.

BoundaryGuard (Safety Court): evaluate output risk and decide allow / warn / block. Reference: `src/services/safety/BoundaryGuardService.ts`
Role policy gate: determines STOP/HITL and required artifacts/scopes. Reference: `src/services/decision-os/RolePolicy.ts`
RBAC command guard: centralized authorization for commands. Reference: `src/services/security/RBACCommandGuard.ts`
Deterministic risk labeling (safe/guarded/risky) for change planning. Reference: `src/services/evolve-ecosystem/doctor-to-task-spec.ts`

Rule of thumb: LLMs may propose. Adoption must be decided by deterministic gates and recorded as evidence.

Command catalog (auto-generated from READY.manifest.json)

This list is generated at build time from the current READY manifest.

Tip: /help is always the latest truth

For per-command details, run /help <command> in the CLI.

Enterprise: decision → deployment → operations (recommended starting points)

If you are adopting MARIA OS in an organization, start with diagnosis and governance surfaces before scaling agents.

Enterprise org doctor: `maria doctor-enterprise --models ...` (implementation: `src/cli/doctor-enterprise.ts`, service: `src/services/enterprise-os/EnterpriseOrgDoctorService.ts`)
Project doctor: `maria /doctor` (entry: `src/services/doctor/ProjectDoctorService.ts`)
BoundaryGuard: enforced boundary checks for enterprise outputs (reference: `src/services/safety/BoundaryGuardService.ts`)
Approval gates: role policy + RBAC command authorization (references: `src/services/decision-os/RolePolicy.ts`, `src/services/security/RBACCommandGuard.ts`)

For enterprise safety posture, prefer LOCAL_MODE-aligned execution and keep GateReport/DoctorDelta evidence for each change.

Current READY commands by category

Generated: 2025-12-22T04:35:48.729Z · Total: 39 · READY: 39

ai (6)

/agents

Design, run, and monitor multi-agent organizations (agent squads)

/evaluate

AI model evaluation and benchmarking

Usage: /evaluate [run|status|results|stop|assess] [--config <path>] [--dataset <path>] [--format <format>] [--compare-baseline] [--idea <text>] [--code <text>] [--file <path> ...] [--criteria <path>]

/factory

Factory AI OS helper – generate ASCII architecture diagrams from factory.yaml and related configs.

Usage: /factory diagram --project <id> [--view logical|components|agents] [--output <path>]

/l2r

🎯 Learning-to-Rank system with 44-dimension features and model training *GPU needed - Local LLM only (Pro+ members only)

/lora

LoRA profile & training job management (CLI: maria lora …)

Usage: maria lora <init|upload|train|status|rollback> [...]

/project-m

Project-m OS helper – generate ASCII architecture diagrams for multi-agent project teams.

Usage: /project-m [options]

analysis (2)

/ds

Analyze and improve data sources (SQL/NoSQL/CSV/VDB/GraphRAG) with a SQL-first workflow

/research

AI-powered research and analysis tools

Usage: /research <url|query>

auth (3)

/login

Usage: /login

/logout

Logout from MARIA CLI

Usage: /logout

/whoami

Show current authenticated user information

Usage: /whoami

business (1)

/biz

Business cockpit for CEO / COO / PM / Sales: plans, KPIs, budgets, and go-to-market workflows

code (1)

/code

Generate code with AI assistance

Usage: /code "prompt" [--plan-only|--sow] [--apply] [--dry-run] [--interactive] [--yes] [--max-files N] [--root DIR] [--rollback on|off] [--output names|summary|detail|diff] [--no-code] [--preview-lines N] [--verbose] [--only-attached] [--attach-mode strict|assist] [--max-attachments N] [--diff-lines N] [--diff-bytes N] [--diff-hunks N] [--confirm-overwrites <globs>] [--git-guard on|off] [--git-commit on|off] [--git-branch <name>] [--git-tag <name>] [--git-tag-prefix <pfx>] [--git-push on|off] [--git-push-remote <name>] [--allow-dotfiles]

configuration (2)

/init

Initialize project guidance and generate MARIA.md at repo root

Usage: /init

/setup

First-time setup wizard

Usage: /setup

conversation (1)

/clear

Clear conversation history

Usage: /clear [--mode display|session|all]

core (5)

/exit

Exit MARIA CLI

Usage: /exit

/feedback

Provide feedback and report issues

Usage: /feedback [bug|feature|support]

/help

Show command help and documentation

Usage: /help [command]

/update

Incremental codebase updates; refresh MARIA.md with latest changes

Usage: /update

/version

Show version information

Usage: /version

creative (1)

/novel

Serialized novel: dynamic characters + world, generate next chapter per theme (Universe-style)

Usage: /novel "theme" [--series <id|@path/to/series.json>] [--new-series] [--title <title>] [--lang <code>] [--format md|txt] [--genre <name>] [--plan-only] [--out <dir>] [--dir <dir>] [--envelope <jsonOr@path>] [--confirm]

development (2)

/auto-dev

Safe autonomous dev engine (Non-Breaking-first) for small, test-driven changes. Use /auto-dev inside MARIA

Usage: /auto-dev [run] [--job-name <name>] [--goal "<text>"] [--target-files "<file1,file2>"] [--max-attempts <n>] [--test-cmd "<cmd>"] [--build-cmd "<cmd>"] [--lint-cmd "<cmd>"] [--typecheck-cmd "<cmd>"] [--json] | extract-dataset [--since <date>] [--tag <text>] [--output <dir>] [--json]

/develop

Goal-driven development orchestrator (spec → design → tasks → initial code steps)

Usage: /develop "<goal>" [--spec <path> ...] [--context <path> ...] [--product <id>] [--mode <spec|plan|full>]

multimodal (2)

/image

Generate images with AI

Usage: /image "prompt" [--size 1024x1024] [--format png|webp|jpg] [--count N]

/video

Generate videos with AI

Usage: /video "prompt"

research (1)

/knowledge

Knowledge base management (Knowledge packs + HOT KNOWLEDGE + HITL)

Usage: /knowledge [install-packs|sync-packs] [--root <dir>] [--user-id <id>]

system (10)

/contact

Display contact information and support channels

Usage: /contact

/debug

Display debug information and system diagnostics

Usage: /debug [full|memory|performance|analyze|fix]

/disk

Disk usage and storage information

Usage: /disk [path]

/doctor

Project health doctor

Usage: /doctor

/env

Display environment information and variables

Usage: /env [filter]

/ping

Ping the system (latency and connectivity)

Usage: /ping

/processes

Display running processes and system information

Usage: /processes [maria|full]

/status

System health information

Usage: /status

/upgrade

Upgrade your subscription plan

Usage: /upgrade [starter|pro|ultra] [--compare]

/uptime

Display system and process uptime information

Usage: /uptime

workflow (2)

/akashic

Akashic document intelligence: scan/normalize/metadata+SQLite/index → ask with citations (supports DLQ requeue, ACL fail-closed, audit logs)

Usage: /akashic [scan|update] [--input <dir>] [--out <dir>] [--db <path>] [--llm] [--require-llm] [--enforce-acl] [--use-local-only] --confirm | /akashic ask --q <question> [--index <path>] [--top-k <n>] [--llm] [--use-local-only] | /akashic --envelope @docs/projects/akashic/envelopes/akashic-scan.example.json

/deliver

Generate delivery artifacts (DeliveryReport/Verification/Runbook/SaveReceipt) from a DeliveryOps Envelope

Usage: /deliver --envelope @path/to/envelope.json [--out docs|artifacts] [--templates <dir>] [--confirm]

Deployment & operations (priority)

Never commit secrets. Absorb env differences via config. Enterprise runs locally.

Secrets

Never commit secrets (API keys, OAuth credentials, JWT secrets).
Use Secret Manager (or equivalent) and avoid plaintext secrets in env/config files.

Common local auth issue (NextAuth JWE decryption)

If you see JWE decryption failed in JWT sessions, it is typically caused by a mismatched or rotated NEXTAUTH_SECRET.

Fix: keep the secret stable and clear old sessions (cookies/storage), then sign in again.

Enterprise execution policy

Enterprise runs locally (behavior aligned with LOCAL_MODE).

Do not hardcode environment differences. Absorb via config/loaders and keep evidence (logs/manifests).

Prefer deterministic safety rails: explicit boundaries, approval gates, and rollback conditions documented in the Envelope.

Local LLM Setup Guide (Ultra–Enterprise)

Run Ollama / LM Studio / vLLM on your own hardware (no cloud dependency) and connect MARIA to your local inference server.

Scope (important)

This guide targets the Local LLM Infrastructure feature for Ultra–Enterprise.
Enterprise is designed for local execution by default (behavior equivalent to LOCAL_MODE=1).

Start here (SSOT for config)

MARIA can auto-detect local inference servers, but for reliable operations you should explicitly set env vars.

# Prefer *_API_BASE (OpenAI-compatible base). *_API_URL is legacy compatibility (may be removed).
LMSTUDIO_API_BASE=http://localhost:1234/v1
OLLAMA_API_BASE=http://localhost:11434
VLLM_API_BASE=http://localhost:8000/v1

# Compatibility (deprecated)
# LMSTUDIO_API_URL=http://localhost:1234
# OLLAMA_API_URL=http://localhost:11434
# VLLM_API_URL=http://localhost:8000

# Recommended: force local mode (Enterprise-equivalent)
LOCAL_MODE=1

# Default provider/model (optional)
MARIA_PROVIDER=lmstudio   # or: ollama / vllm
MARIA_MODEL=gpt-oss-20b   # example (LM Studio)

Note: many slash commands can be overridden per-call via --provider / --model.

Ollama (install models, start server, verify)

Strengths: automatic model management (pull/list/run) and lightweight ops.

# 1) Start (skip if already running)
ollama serve

# 2) Pull models (examples)
ollama pull llama3.2:3b
ollama pull mistral:7b
ollama pull mixtral:8x7b
ollama pull deepseek-coder:6.7b
ollama pull phi3.5:3.8b

# 3) Confirm installation
ollama list

# 4) Verify API
curl http://localhost:11434/api/version
curl http://localhost:11434/api/tags

Large models (70B / 8x7B) depend heavily on GPU VRAM and system RAM. Start small (3B–7B), verify the pipeline, then scale up.

LM Studio (install models, start server, verify)

Strengths: GUI model management, GPU acceleration, and an OpenAI-compatible API (/v1).

# 1) (GUI) Download a model (e.g., gpt-oss-120b / gpt-oss-20b)
# 2) (GUI) Start Local Server in "OpenAI Compatible" mode (default: http://localhost:1234/v1)

# If you have the CLI (lms)
lms ls
lms server start

# Verify
curl http://localhost:1234/v1/models
curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lm-studio" \
  -d '{"model":"gpt-oss-20b","messages":[{"role":"user","content":"ping"}],"stream":false}'

vLLM (high-throughput, production-oriented)

Strengths: high-throughput serving / Tensor parallelism / Continuous batching / PagedAttention / Production-ready

# Example: start an OpenAI-compatible server (follow vLLM's setup guide for dependencies)
python -m vllm.entrypoints.openai.api_server \
  --model mistralai/Mistral-7B-Instruct-v0.2 \
  --host 0.0.0.0 \
  --port 8000

# Verify
curl http://localhost:8000/v1/models
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"mistralai/Mistral-7B-Instruct-v0.2","messages":[{"role":"user","content":"ping"}],"stream":false}'

MARIA uses VLLM_API_BASE (recommended) or VLLM_API_URL (compat) to locate the endpoint.

Use from MARIA (fastest path)

1) Set the `*_API_BASE` variables in `.env.local` or your shell environment

2) Explicitly pass provider/model per command for deterministic routing

# Example: run with LM Studio explicitly
maria /ceo --provider lmstudio --model gpt-oss-20b "Summarize the requirements"

# Example: run with Ollama explicitly
maria /ceo --provider ollama --model llama3.2:3b "Summarize the requirements"

If the local inference server is down, MARIA may attempt auto-detection/auto-start depending on the environment. For production ops, explicit env is recommended.

Next steps (how to stay aligned with “latest”)

Because the repository is not public, the safest “source of truth” is what the product exposes at runtime.

Runtime truth (recommended)

Use /help for the latest available commands (READY-only, manifest-backed).
Use this page’s Command catalog section (auto-generated at build time from the READY manifest).
For details on a specific command, run /help <command>.

Operator checklist (minimal)

Keep secrets out of Git; use a secret manager; keep NEXTAUTH_SECRET stable.
Prefer deterministic flows: preview → apply, and keep evidence (logs/manifests).
Enterprise policy: run locally (LOCAL_MODE-aligned); avoid heuristics; route ambiguity via LLM contracts.