@agentikos/omega-os 0.1.0

package/omega/Agentik_SSOT/audits/uiuxaudit.yaml

@@ -0,0 +1,61 @@
+# uiuxaudit — Quality Arsenal definition for OmegaOS.
+# Compact + structured: the Gestalt-Popper shell lives in omega_engine.audit_arsenal;
+# this file supplies only the domain — gather tools, phases, falsification rules.
+
+id: uiuxaudit
+domain: design
+question: "Is the interface BEAUTIFUL — does every page speak one coherent visual language?"
+weight: 1.0
+threshold: 85
+
+applies_to:
+  roles: [worker]
+  changed: ["*.tsx", "*.jsx", "*.css", "*.html", "*.vue"]
+
+# GATHER — design has no reliable deterministic linter; the agentic pass does the work.
+# (No gather tool catches a 1px hierarchy break or a rogue color used for the wrong intent.)
+gather: []
+
+# PHASES — the agentic falsification pass investigates each. Art-director scrutiny.
+phases:
+  - id: hinge-component
+    checks: "Identify the single UI element whose quality defines the product's perceived quality (primary table, hero, or main creation form); if it looks generic, nothing else matters."
+  - id: color-system
+    checks: "Rogue colors used outside the design tokens, semantic misuse (destructive red on non-destructive actions), and text/background pairs failing WCAG AA contrast."
+  - id: typography-hierarchy
+    checks: "Rogue font sizes/weights outside the type scale, broken h1>h2>h3 visual descent, competing bold weights, body text inconsistent across pages."
+  - id: spacing-rhythm
+    checks: "Padding/margin/gap values off the base unit, inconsistent component internal padding, shadcn Card double-padding, broken page-level vertical rhythm."
+  - id: component-anatomy
+    checks: "Buttons/inputs/cards/modals/tables — every variant present, every state (hover/focus/active/disabled/loading) present, consistent across all instances."
+  - id: cross-page-coherence
+    checks: "Every page feels designed by the same hand on the same day — same layout width, same header height, same pattern for delete/loading/empty/success everywhere."
+  - id: visual-hierarchy
+    checks: "Exactly one dominant primary CTA per page, subordinate secondaries, no dead zone where the user does not know what to do, cognitive load under threshold."
+  - id: interaction-states
+    checks: "Every interactive element has hover/focus/active/disabled feedback; loading/error/empty states exist and use one consistent pattern app-wide."
+  - id: responsive-fidelity
+    checks: "At 375/768/1024/1280px — no horizontal overflow, body text >=16px on mobile, touch targets >=44px, layout adapts rather than merely shrinking."
+  - id: accessibility-as-design
+    checks: "Semantic HTML, logical Tab order, visible focus rings, labels associated to inputs, prefers-reduced-motion respected, focus management on modal open/close."
+  - id: design-smells
+    checks: "AI-generic tells — gradient abuse, rounded-3xl on everything, shadow soup, mixed icon libraries, default unmodified Tailwind tokens, competing primary buttons."
+  - id: dark-mode-integrity
+    checks: "Dark mode complete on every component/state, no hardcoded text-black/bg-white, borders visible on dark bg, contrast re-verified, no flash of wrong mode."
+  - id: copy-microcopy
+    checks: "Action-oriented button labels, no placeholder-as-label, human error messages that suggest a fix, encouraging empty-state copy, consistent voice."
+  - id: brand-expression
+    checks: "Cover the logo — is the brand still identifiable? Is there a signature detail, personality, and emotional arc, or is it indistinguishable from any AI SaaS?"
+  - id: functional-bug
+    checks: "A pixel-perfect element that does not work is worse than an ugly one that does — data not rendering, no-op buttons, broken features behind the polish."
+
+falsification: >
+  Every design element is a CLAIM — falsify it. A heading claims to be most
+  important: is it actually most prominent? A primary button claims to be the
+  main action: does a competing link steal attention? Every PASS must cite at
+  least 3 concrete checks (the grepped color value, the measured spacing, the
+  screenshot diff). Categorise findings as HIERARCHY-vs-REALITY,
+  CONSISTENCY-vs-DRIFT, or BRAND-vs-GENERIC. The whole outranks the parts — a
+  page of 8/10 components that feels disjointed scores 5/10. Bias toward FAIL.
+
+fix_loop: true

package/omega/Agentik_SSOT/mcp/mcp-catalog.yaml

@@ -0,0 +1,136 @@
+# Omega OS — MCP / plugin catalog.
+#
+# The installer's 40-mcp step reads this file to present the install checklist.
+# Maintained by the connection-educator (Agentik_Orchestration/educators/).
+# Secrets are referenced by name only — never stored here.
+
+version: 1
+
+catalog:
+  - id: filesystem
+    name: Filesystem
+    description: Sandboxed local file access
+    category: core
+    install: { method: npx, package: "@modelcontextprotocol/server-filesystem" }
+    recommended: true
+
+  - id: git
+    name: Git
+    description: Read/inspect git repositories
+    category: core
+    install: { method: npx, package: "@modelcontextprotocol/server-git" }
+    recommended: true
+
+  - id: github
+    name: GitHub
+    description: Issues, pull requests, repos
+    category: dev
+    install: { method: npx, package: "@modelcontextprotocol/server-github" }
+    secrets: [GITHUB_TOKEN]
+    recommended: true
+
+  - id: composio
+    name: Composio
+    description: 250+ app integrations behind one MCP server
+    category: integrations
+    install: { method: npx, package: "@composio/mcp" }
+    secrets: [COMPOSIO_API_KEY]
+    recommended: true
+
+  - id: higgsfield
+    name: Higgsfield
+    description: Image and video generation
+    category: media
+    install: { method: npx, package: "@higgsfield/mcp" }
+    secrets: [HIGGSFIELD_API_KEY]
+    recommended: false
+
+  - id: playwright
+    name: Playwright
+    description: Browser automation — powers the verifier's runtime audits
+    category: testing
+    install: { method: npx, package: "@playwright/mcp" }
+    recommended: true
+
+  - id: context7
+    name: Context7
+    description: Live, version-accurate library documentation
+    category: dev
+    install: { method: npx, package: "@upstash/context7-mcp" }
+    recommended: true
+
+  - id: fetch
+    name: Fetch
+    description: Fetch and convert web content
+    category: core
+    install: { method: npx, package: "@modelcontextprotocol/server-fetch" }
+    recommended: true
+
+  - id: memory
+    name: Memory
+    description: Persistent knowledge-graph memory
+    category: core
+    install: { method: npx, package: "@modelcontextprotocol/server-memory" }
+    recommended: false
+
+  - id: sequential-thinking
+    name: Sequential Thinking
+    description: Structured multi-step reasoning
+    category: reasoning
+    install: { method: npx, package: "@modelcontextprotocol/server-sequential-thinking" }
+    recommended: false
+
+  - id: notion
+    name: Notion
+    description: Read/write Notion pages and databases
+    category: docs
+    install: { method: npx, package: "@notionhq/notion-mcp-server" }
+    secrets: [NOTION_TOKEN]
+    recommended: false
+
+  - id: slack
+    name: Slack
+    description: Post and read Slack messages
+    category: comms
+    install: { method: npx, package: "@modelcontextprotocol/server-slack" }
+    secrets: [SLACK_BOT_TOKEN]
+    recommended: false
+
+  - id: linear
+    name: Linear
+    description: Issues and project management
+    category: project
+    install: { method: npx, package: "@linear/mcp" }
+    secrets: [LINEAR_API_KEY]
+    recommended: false
+
+  - id: sentry
+    name: Sentry
+    description: Error monitoring and traces
+    category: observability
+    install: { method: npx, package: "@sentry/mcp-server" }
+    secrets: [SENTRY_AUTH_TOKEN]
+    recommended: false
+
+  - id: postgres
+    name: Postgres
+    description: Query a PostgreSQL database
+    category: data
+    install: { method: npx, package: "@modelcontextprotocol/server-postgres" }
+    secrets: [DATABASE_URL]
+    recommended: false
+
+  - id: brave-search
+    name: Brave Search
+    description: Web search
+    category: search
+    install: { method: npx, package: "@modelcontextprotocol/server-brave-search" }
+    secrets: [BRAVE_API_KEY]
+    recommended: false
+
+# Claude Code plugin marketplace — the installer also queries the marketplace
+# (the plugins offered in the Claude desktop app under Connectors -> Customize)
+# and appends them to this checklist, so a fresh VPS can adopt the full suite.
+claude_code_plugins:
+  source: marketplace
+  offer_all: true

package/omega/Agentik_SSOT/rules/constitution.md

@@ -0,0 +1,44 @@
+# The Omega OS Constitution
+
+> The rules every agent at every level inherits. Provider-neutral. Compiled into
+> each provider's native rule format by `omega sync`.
+
+## The Prime Principle
+
+**Completion is derived, never declared.** No agent may assert that its own work
+is finished. A task is finished only when the engine computes it — from
+observable, immutable events, verified by an independent third party that ran
+the real flow.
+
+## The Three Laws
+
+1. **First Law — code lies, only runtime tells the truth.** Before any
+   conclusion, observe actual runtime behaviour: logs, traces, test output,
+   screenshots. When code and runtime disagree, runtime wins.
+
+2. **Second Law — be a researcher, not a sycophant.** Challenge a flawed premise
+   before acting. Find root causes, not symptoms. Push back with reasoning.
+   Be skeptical of your own conclusions — ask what would falsify them.
+
+3. **Third Law — challenge, decide, proceed.** A dispatched agent never stalls
+   waiting for a human. State the corrected premise, pick the best path, execute,
+   report after. The only legal stop is a terminal task state with evidence.
+
+## The Karpathy Principles
+
+- **Think before coding** — surface assumptions and trade-offs explicitly.
+- **Simplicity first** — the minimum that solves the problem; nothing speculative.
+- **Surgical changes** — every changed line traces to the request.
+- **Goal-driven execution** — define the success check, loop until it passes.
+
+## The Verification Rule
+
+A task may reach `VERIFIED` only if the audit gate passed — including a **runtime
+audit** that started the real system and exercised the real flow. "It builds" is
+not "it works". 92% is not done; only 100% is done.
+
+## Scope & Safety
+
+- An agent edits only the files in its declared scope (`spec.scope.files_owned`).
+- Destructive or irreversible actions require explicit authorization.
+- Secrets never enter the git-tracked tree, logs, or prompts.

package/omega/Agentik_SSOT/schemas/event.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentik-os.dev/schemas/event.schema.json",
+  "title": "Omega OS Event",
+  "description": "An immutable fact in the append-only event log — the single source of truth. Never mutated, never deleted.",
+  "type": "object",
+  "required": ["id", "task_id", "type", "ts"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique event id (uuid hex)."
+    },
+    "task_id": {
+      "type": "string",
+      "description": "The task this event belongs to."
+    },
+    "type": {
+      "type": "string",
+      "description": "The event type. Task-lifecycle types drive the reducer.",
+      "enum": [
+        "task.created",
+        "task.dispatched",
+        "task.started",
+        "task.claimed_done",
+        "task.verifying",
+        "task.verified",
+        "task.rejected",
+        "task.completed",
+        "task.failed",
+        "task.heartbeat",
+        "scope.joinable"
+      ]
+    },
+    "ts": {
+      "type": "number",
+      "description": "Epoch seconds when the event was appended."
+    },
+    "payload": {
+      "type": "object",
+      "description": "Event-specific data (e.g. failure reason, audit score).",
+      "default": {}
+    }
+  }
+}

package/omega/Agentik_SSOT/schemas/task.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentik-os.dev/schemas/task.schema.json",
+  "title": "Omega OS Task",
+  "description": "A unit of execution at any level of the graph. `state` is DERIVED by folding the task's events — it is never authored by an agent.",
+  "type": "object",
+  "required": ["id", "kind", "role", "spec"],
+  "additionalProperties": false,
+  "properties": {
+    "id":        { "type": "string" },
+    "parent_id": { "type": ["string", "null"], "description": "The owning scope's task id." },
+    "kind": {
+      "type": "string",
+      "enum": ["dispatcher", "executor", "verifier"],
+      "description": "dispatcher owns a scope; executor does bounded work; verifier runs the audit gate."
+    },
+    "role": {
+      "type": "string",
+      "description": "aisb | oracle | manager | worker | audit | <autonomous-agent-role>"
+    },
+    "spec": { "type": "object", "description": "The brief." },
+    "state": {
+      "type": "string",
+      "enum": ["pending", "dispatched", "running", "claimed_done", "verifying", "verified", "rejected", "completed", "failed"],
+      "description": "DERIVED — reduce_task(events_for(id)). Cached for convenience; events are authoritative."
+    },
+    "lifecycle": {
+      "type": "string",
+      "enum": ["ephemeral", "persistent"],
+      "default": "ephemeral",
+      "description": "persistent = an autonomous agent."
+    },
+    "trigger": {
+      "type": ["object", "null"],
+      "description": "What wakes the task. Null for mission tasks; set for autonomous agents.",
+      "required": ["type"],
+      "properties": {
+        "type":   { "type": "string", "enum": ["cron", "event", "webhook", "channel"] },
+        "config": { "type": "object" }
+      }
+    },
+    "budget": {
+      "type": "object",
+      "description": "Bounds the task — no infinite loops, no infinite hangs.",
+      "properties": {
+        "max_iterations":       { "type": "integer", "minimum": 1, "default": 3 },
+        "deadline_epoch":       { "type": ["number", "null"] },
+        "heartbeat_interval_s": { "type": "integer", "minimum": 1, "default": 120 }
+      }
+    },
+    "provider":  { "type": ["string", "null"], "description": "Resolved by the model router." },
+    "iteration": { "type": "integer", "minimum": 0, "default": 0 }
+  }
+}

package/omega/Agentik_Tools/README.md

@@ -0,0 +1,42 @@
+# Agentik_Tools — the "/Applications" folder
+
+> **Nature:** third-party installs · **Lifecycle:** installer-managed · **Git:** not versioned (manifest only)
+
+Everything installed from outside Omega OS lives here — modelled on the macOS
+`/Applications` folder. Open this block over SSH and you see every third-party
+tool, and nothing else. It is the answer to "installing things on Ubuntu is a
+mess": there is exactly one place a tool can go.
+
+```
+Agentik_Tools/
+├── bin/          symlinks — the ONLY directory added to PATH
+├── knowledge/    the RAG ENGINE — vector engine, embedding tooling (third-party)
+├── <mcp-id>/     each installed MCP server (composio, playwright, …)
+└── <tool>/       any other external tool (n8n, ollama, …)
+```
+
+## The registry
+
+`registry.json` (created by the installer) is the manifest of what is installed:
+name, version, install path, source, invoke command. It is the **only** part of
+this block that is git-tracked — the tool payloads are not. On a new machine the
+bootstrap reads `registry.json` and reinstalls exactly the same set, same
+versions. That is what makes the system reproducible.
+
+## RAG — only the engine lives here
+
+The RAG **engine** (vector store, embedding tooling) is third-party software, so
+it lives in `knowledge/`. The rest of the RAG system lives elsewhere, by nature:
+the **index/corpus** is mutating runtime state → `Agentik_Runtime/`; the
+**router + strategies** are orchestration logic → `Agentik_Orchestration/`; the
+**thresholds + CRAG config** are truth → `Agentik_SSOT/`.
+
+## Install a tool
+
+```bash
+omega tool install <name>     # installs into Agentik_Tools/<name>/, registers it,
+                              # exposes it to every provider via the SSOT
+omega tool list | update | remove
+```
+
+There is no other install path — so a tool cannot be put in the wrong place.

package/omega/Agentik_Tools/registry.json

@@ -0,0 +1,15 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "pdfgen",
+      "version": "1.0.0",
+      "path": "Agentik_Tools/pdfgen/",
+      "invoke": "Agentik_Tools/pdfgen/bin/pdfgen",
+      "purpose": "Branded PDF generation — whitepaper / audit / marketing / doc templates, themes agentik/dafnck/one-life.",
+      "used_by": ["omega_engine.report"],
+      "source": "agentik-pdf",
+      "installedAt": ""
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@agentikos/omega-os",
+  "version": "0.1.0",
+  "description": "Omega OS — installable agentic operating system with verified-completion orchestration. Event-sourced engine, 8-block rack, autonomous agents, MCP.",
+  "bin": {
+    "omega-os": "bin/omega-os.js"
+  },
+  "files": [
+    "bin/",
+    "install.sh",
+    "bootstrap/",
+    "omega/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentik-os/OmegaOS.git"
+  },
+  "keywords": [
+    "agentic",
+    "orchestration",
+    "ai-agents",
+    "autonomous-agents",
+    "claude",
+    "mcp",
+    "event-sourcing"
+  ],
+  "author": "Agentik OS"
+}