Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

docs(launch): define measurable MSO readiness contract

Rahmancdf2fe6d506c
diff --git a/CLAUDE.md b/CLAUDE.md
index 0497c49f..764f1889 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -220,6 +220,7 @@ to `resources/` (rr) and drive any project from one manifest:
## Rules in force
- **One canonical checkout; parallel work only through isolated hidden worktrees.**
+ The canonical `main` checkout is a **release/integration surface, not an agent scratchpad**. Automated source-changing work must happen in a task-owned hidden worktree; if canonical is dirty with another session's work, stop and preserve it rather than stashing, resetting, committing, merging or overwriting on that session's behalf. Only a release/integration step may advance canonical after the candidate and concurrent work are independently preserved and verified.
the current `git rev-parse --show-toplevel` checkout on `main` is the canonical release SSOT.
Never create task-specific `mso-*` siblings under `~/projects` and never let two
sessions share one worktree, `HEAD`, or index. If parallel work is necessary, use one
diff --git a/README.md b/README.md
index 69431894..f93f47e3 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
<h1 align="center">Manef Shell OS</h1>
-<p align="center"><strong>A workspace for your server. A runtime for your agents.</strong></p>
-<p align="center">Real terminals, project-aware AI, files and services — in one self-hosted workspace.</p>
-<p align="center"><a href="#see-it-work">Demo</a> · <a href="#install-or-update-mso-from-this-repo">Install</a> · <a href="./docs/COGNITIVE-RUNTIME.md">Agent runtime</a> · <a href="./docs/MCP-HOW-TO.md">Use MCP</a> · <a href="./docs/README.md">Docs</a></p>
+<p align="center"><strong>A self-hosted control plane for AI agents.</strong></p>
+<p align="center">Let agents work across your projects, tools, workflows and infrastructure while keeping context, permissions and execution evidence under your control.</p>
+<p align="center"><a href="#see-it-work">Demo</a> · <a href="./docs/QUICKSTART.md">First 10 minutes</a> · <a href="#install-or-update-mso-from-this-repo">Install</a> · <a href="./docs/LAUNCH-READINESS.md">Launch readiness</a> · <a href="./docs/README.md">Docs</a></p>
<p align="center"><a href="https://github.com/rahmanef63/mso/actions/workflows/ci.yml"><img alt="Tests and build" src="https://github.com/rahmanef63/mso/actions/workflows/ci.yml/badge.svg" /></a> <a href="https://github.com/rahmanef63/mso/actions/workflows/security-alerts.yml"><img alt="Actual open security findings" src="https://github.com/rahmanef63/mso/actions/workflows/security-alerts.yml/badge.svg" /></a></p>
## See it work
diff --git a/docs/AGENT-SECURITY.md b/docs/AGENT-SECURITY.md
new file mode 100644
index 00000000..bb7fa8f4
--- /dev/null
+++ b/docs/AGENT-SECURITY.md
@@ -0,0 +1,47 @@
+# Agent security launch contract
+
+> **Current-reference security extension.** [`SECURITY-ASSURANCE.md`](./SECURITY-ASSURANCE.md) remains the evidence authority for current scanners and claim boundaries. This document defines agent-specific abuse cases that must be proven before a stronger public launch label.
+
+## Principle
+
+The model is not an authorization boundary. Downstream tools enforce identity, scope, policy, confirmation and resource bounds on every call.
+
+## Tool risk classes
+
+| Class | Examples | Default control |
+|---|---|---|
+| Read | bounded status, metadata, project inspection | authenticated scope + rate/bounds + redaction |
+| Reversible write | draft/config changes with CAS/revision | write scope + stale-write protection + audit + verify |
+| High impact | shell, deploy, delete, credential/provider mutation | exec/owner scope + explicit policy/confirmation + audit + post-action verification |
+| Critical/external irreversible | broad destructive actions, identity/security boundary changes | dedicated bounded API, fresh confirmation/human review, deny generic fallback |
+
+## Abuse-case matrix
+
+The release security suite must include repeatable failures for:
+
+1. **Direct/indirect prompt injection** — retrieved web/docs/tool output cannot replace system/developer/tool policy.
+2. **Tool misuse** — persuasive model text cannot call a tool outside current scope/allowlist.
+3. **Privilege escalation** — Viewer/Operator/read/write identities cannot reach Owner/exec authority.
+4. **Data exfiltration** — secret-bearing files, credential stores, cookies and private tool results cannot leak through normal output, logs, artifacts or external tool arguments.
+5. **Memory poisoning** — untrusted observations retain provenance and cannot silently become high-authority durable instructions.
+6. **Cross-agent identity confusion** — Local Agent/A2A/subagent handoff does not widen the originating principal's authority.
+7. **Recursive/cascading failure** — depth, retry, runtime, token/cost and workflow bounds stop runaway delegation.
+8. **Stale approval/replay** — revision/CAS/one-time confirmation cannot be reused after target state changes.
+9. **Confused deputy** — downstream integrations enforce the intended user/connection/resource rather than accepting model-selected identity by implication.
+10. **Audit poisoning** — user/model-provided strings cannot forge successful audit/evidence status.
+
+## Memory admission target
+
+Durable memory should distinguish at minimum:
+
+- user-provided vs system-observed vs verified evidence;
+- principal/project scope;
+- confidence and provenance;
+- superseded/retracted state;
+- review/admission status for behavior-shaping procedural memory.
+
+Memory may recommend a route. It may never grant permissions, approve deletion, or override a failed authorization check.
+
+## Launch evidence
+
+A 10/10 agent-security claim requires the abuse matrix to run after material changes to models, prompts/instructions, tools, memory, retrieval, workflow policy or provider integrations. Failure is a release blocker for the affected authority class.
diff --git a/docs/DISASTER-RECOVERY.md b/docs/DISASTER-RECOVERY.md
new file mode 100644
index 00000000..0d6da3e4
--- /dev/null
+++ b/docs/DISASTER-RECOVERY.md
@@ -0,0 +1,39 @@
+# Disaster recovery contract
+
+> **Target and current boundary.** Local server-memory snapshots with checksum/restore rehearsal are useful, but a same-host partial snapshot is not disaster recovery. See [`MEMORY-SAFETY.md`](./MEMORY-SAFETY.md) for current implementation limits.
+
+## Stable launch target
+
+Use a 3-2-1 posture for critical MSO state:
+
+1. **Live copy** on the active installation.
+2. **Independent backup copy** that is not the live state tree.
+3. **Encrypted offsite/off-host copy** with separate failure domain and access controls.
+
+A backup counts only when its manifest states scope/completeness and a restore drill proves readable content.
+
+## Initial objectives
+
+| Objective | Public-beta target | Stable target |
+|---|---:|---:|
+| Critical-state RPO | ≤24 h | ≤4 h or explicitly configured |
+| Reference-installation RTO | ≤2 h | ≤60 min |
+| Restore drill | before beta + after backup format changes | at least monthly and after material storage changes |
+| Offsite copy | required | required |
+| Encryption | required for credential/private-session-bearing backup | required |
+
+These are product acceptance objectives, not current measured promises.
+
+## Backup set classes
+
+- **Critical identity/config:** enough to reconstruct approved configuration without publishing secrets.
+- **Memory/session/workflow evidence:** typed memory, durable session/archive sources, recipes/workflows and project evidence covered by the server-memory backup allowlist.
+- **Source/release metadata:** Git remote/source plus exact release/provenance information.
+- **External systems:** provider data stays owned by its provider and needs its own backup/export policy; MSO must not pretend a local snapshot covers it.
+- **Reinstallable cache/build data:** excluded unless needed for a specific forensic purpose.
+
+## Restore drill
+
+A passing drill starts in an isolated target, verifies backup manifest/checksums, restores without overwriting production, proves representative session/memory/workflow/config reads, records missing/excluded scope, and demonstrates the documented rebuild path to a healthy MSO runtime.
+
+No successful checksum alone proves the snapshot was complete.
diff --git a/docs/LAUNCH-QA.md b/docs/LAUNCH-QA.md
new file mode 100644
index 00000000..a5ae483a
--- /dev/null
+++ b/docs/LAUNCH-QA.md
@@ -0,0 +1,88 @@
+# MSO launch Q&A
+
+> Concise answers for launch conversations. Keep these aligned with current code and [`LAUNCH-READINESS.md`](./LAUNCH-READINESS.md). Do not upgrade a limitation into a promise.
+
+### 1. What is MSO?
+
+A self-hosted control plane where AI agents can work across your projects, tools, workflows and infrastructure while MSO keeps permissions, context and execution evidence under your control.
+
+### 2. Who is it for?
+
+Developers, technical operators and small trusted teams who run their own projects/servers and want agentic automation without handing the entire control plane to a hosted black box.
+
+### 3. What problem does it solve?
+
+Agent work is usually fragmented across chat history, terminals, repos, MCP tools, workflow products, provider credentials and deployment consoles. MSO gives those surfaces one identity, execution and evidence layer.
+
+### 4. Why is this not just n8n?
+
+n8n is a specialist workflow-automation product. MSO includes server-native workflows, but its primary boundary is broader: project-aware agent sessions, MCP/tools, host operations, memory/evidence and workflow execution share one permission/runtime model. MSO should not try to beat every n8n integration or editor feature.
+
+### 5. Why not just use a coding agent such as Codex or Claude Code?
+
+A coding agent is one reasoning/execution client. MSO is the self-hosted control plane it can connect to: projects, scoped tools, durable sessions, integrations, workflows, host operations and evidence survive beyond one model/client conversation.
+
+### 6. Is MSO actually an operating system?
+
+No. The OS metaphor is the workspace UI. MSO runs on an existing host and does not replace Linux, your VPS provider or the host's security model.
+
+### 7. Does MSO require one AI provider?
+
+No. The architecture is provider-neutral and supports configurable model/provider paths. A particular provider may expose different capabilities, costs or authentication methods.
+
+### 8. What is the difference between Project, Agent, Session and Workflow?
+
+- **Project:** the bounded code/work context.
+- **Agent:** a configured actor that can reason and use permitted capabilities.
+- **Session:** one durable conversation/execution history for an actor.
+- **Workflow:** an explicit reusable execution graph/process.
+
+Memory stores reusable knowledge/evidence; Organization maps people/agent seats and routing, rather than replacing those four concepts.
+
+### 9. What does MSO remember?
+
+MSO can preserve durable sessions, project memory, typed agent memory, workflow/recipe evidence and related knowledge. Retention and retrieval are bounded. “Stored” does not mean “automatically trusted”; provenance, review and poisoning resistance remain part of the memory-safety contract.
+
+### 10. Can an agent delete my server?
+
+Owner/exec authority is intentionally powerful, so MSO must be treated like SSH-equivalent automation for the service user. The product uses role/scope checks, path bounds, audit, confirmations and tool-specific policies, but no model should be treated as a security boundary. High-impact operations require system-enforced mediation and appropriate human approval.
+
+### 11. Where are credentials stored?
+
+Credentials use private server-side configuration/integration stores and private setup flows. They are not supposed to be pasted into prompts or emitted in normal metadata, logs or portable public source.
+
+### 12. Can two agents work at the same time?
+
+Yes, but source-changing tasks must use isolated worktrees and explicit ownership. Canonical `main` is the release/integration surface, not shared scratch space. The launch gate requires this to become tool-enforced, not merely documented.
+
+### 13. What happens if an agent crashes halfway through?
+
+Sessions/workflows keep durable state and evidence so work can be inspected or resumed. Side effects still depend on the external system involved, so idempotency, revision/CAS checks and explicit verification matter.
+
+### 14. Can I see exactly what an agent did?
+
+MSO records bounded workflow/session/action evidence and audits privileged actions. Sensitive values are intentionally redacted or excluded; an audit trail is evidence of actions, not unrestricted transcript/secret storage.
+
+### 15. If my VPS dies, can I recover everything?
+
+Not yet as a stable-product claim. MSO has local memory snapshots and isolated restore verification, but the current launch blocker is complete resumable coverage plus encrypted offsite recovery and a disaster-recovery drill.
+
+### 16. How secure is MSO?
+
+It has substantial first-party security gates and explicit privilege boundaries, but it has not established “100% secure” or third-party-audited status. Current public claims must distinguish tested controls from remaining posture gaps.
+
+### 17. How is a release proven?
+
+The intended chain is exact source SHA → type/lint/test/security checks → isolated production build → mandatory browser journeys → controlled integration/release → exact live SHA and asset/health verification. A push or successful unit test alone is not deployment proof.
+
+### 18. Is MSO production-ready?
+
+For the maintainer's own/internal technical use, many core paths are heavily exercised. The honest public label remains **Public Alpha / Developer Preview** until P0 concurrency, disaster recovery, measured onboarding, agentic-security and operational-SLO gates are satisfied.
+
+### 19. What is the killer demo?
+
+Pick one real project, let an agent inspect it with bounded reads, perform one isolated verified change using the project's tools/workflow, show the execution evidence, then resume/handoff the session. Do not demo every app in the shell.
+
+### 20. Why should I trust a self-hosted project with infrastructure access?
+
+You should not trust it blindly. Evaluate the boundaries and evidence: source is inspectable, credentials stay private, privileged actions are scoped/audited, releases are exact-SHA verified, and current limitations are published. The launch goal is verifiable control, not “trust the AI.”
diff --git a/docs/LAUNCH-READINESS.md b/docs/LAUNCH-READINESS.md
new file mode 100644
index 00000000..284ee845
--- /dev/null
+++ b/docs/LAUNCH-READINESS.md
@@ -0,0 +1,72 @@
+# MSO launch readiness contract
+
+> **Target, not a marketing score.** “10/10” means every acceptance gate below has current evidence. A planned feature, old screenshot, historical test, or clean-looking UI does not count. Current code/live state wins.
+
+MSO's launch thesis is intentionally narrow:
+
+> **MSO is a self-hosted control plane where AI agents safely work across your projects, tools, workflows, and infrastructure while preserving context and execution evidence.**
+
+The OS metaphor is presentation. The product is the control plane. Anything that does not strengthen that control plane is secondary.
+
+## Product boundary
+
+**Core:** Projects · Agent Sessions · Tools/MCP/Integrations · Workflows · Execution/Evidence.
+
+**Intelligence:** Memory · Learning/Recipes · Organization · Multi-agent/A2A.
+
+**Operations:** Server · Deployment · Backup/Recovery · Security · Observability.
+
+**Not the promise:** a Linux distribution, a VPS provider, a full enterprise IAM/SSO suite, a replacement for every specialist CI/PaaS/automation product, or a guarantee that an autonomous model is safe by itself.
+
+## 20 gates for a defensible 10/10
+
+| # | Dimension | 10/10 acceptance gate | Required evidence | Current launch blocker |
+|---|---|---|---|---|
+| 1 | Value proposition | One sentence explains category, user, job and trust boundary; 4/5 fresh technical users can repeat it accurately after 30 seconds. | README hero + 5-user comprehension receipt. | No external comprehension test yet. |
+| 2 | Problem clarity | Three primary pains and one end-to-end “killer journey” are explicit; every hero feature maps to one pain. | README/launch copy + demo script. | Feature breadth still competes with the story. |
+| 3 | Differentiation | Evidence-backed comparison explains when to use MSO vs specialist tools without claiming universal superiority. | Generated COMPARISON + dated sources. | Keep comparison freshness ≤90 days. |
+| 4 | Product scope | Core/Intelligence/Operations are the only top-level product tiers; non-goals are published and feature additions require a tier + user job. | This contract + architecture/docs index. | Existing surfaces still expose historical breadth. |
+| 5 | First-time UX | Fresh user reaches first verified useful agent action without editing source/config files; median ≤10 min, p90 ≤20 min on supported Linux baseline. | Fresh-machine timed onboarding runs ≥10. | No measured time-to-first-value cohort. |
+| 6 | Installation/onboarding | One supported production path is boring and deterministic: install → doctor → onboard → first action; failures name the broken layer and recovery. | Clean Ubuntu install matrix + screenshots/terminal receipts. | Cross-platform support exists but launch path is not yet measured as one funnel. |
+| 7 | Information architecture | A user can distinguish Project, Agent, Session, Workflow, Memory and Organization in one sentence each; primary navigation is task/role shaped. | IA glossary + usability test ≥80% first-try routing. | Concept density remains high. |
+| 8 | UI consistency | WCAG AA, no horizontal overflow, token/spacing consistency and no dead loading/error states across desktop, phone portrait and phone landscape/tablet. | Mandatory browser E2E + visual regression/axe receipts. | Coverage is strong but not yet one launch-wide visual baseline. |
+| 9 | CLI quality | Every core non-visual operation is discoverable from `mso --help`, uses stable exit semantics, structured output where automation needs it, and never silently widens authority. | CLI contract tests + generated CLI docs. | Keep parity and error UX under release gate. |
+| 10 | API/MCP architecture | UI/CLI/MCP delegate to the same domain authority; schemas/scopes/audit/concurrency metadata are stable and tested; no hidden “second implementation.” | Tool-contract, dispatch, API and parity tests. | Provider parity still expands over time. |
+| 11 | Agent model | Agent/Local Agent/Subagent/A2A boundaries are explicit; each has identity, scope, lifetime, handoff and cancellation semantics; no implicit authority inheritance. | Architecture + isolation/handoff tests. | Mental model still needs launch-level simplification. |
+| 12 | Memory / second brain | Memory has provenance, scope, review/admission, supersession/forget semantics, poisoning tests and visible coverage limits. No memory can authorize destructive cleanup. | Memory lifecycle/adversarial suite + UI coverage receipt. | JEV admission and full learning-coverage review remain incomplete. |
+| 13 | Backup / recovery | 3-2-1 posture for critical state: production + independent backup + encrypted offsite copy; restore drill proves RPO/RTO; local snapshot is complete or explicitly partial. | Encrypted offsite backup + isolated restore drill. | Current verified backup is local, partial, not offsite. |
+| 14 | Security model | Complete mediation in downstream tools, least privilege, tool risk classes, explicit approvals for high-impact actions, prompt-injection/memory-poisoning/exfiltration/privilege abuse tests. | SECURITY-ASSURANCE + agent abuse-case matrix + current alert inventory. | No third-party audit; some agentic threat gates still need dedicated launch evidence. |
+| 15 | Concurrency safety | Automated source mutation never leaves canonical `main` as a shared scratchpad: one task = one isolated worktree; release integration occurs only from clean, proven candidates. | Tool-enforced workspace lease + collision tests + protected main/ruleset evidence. | Current incident proved policy is not yet tool-enforced; GitHub rulesets list is empty. |
+| 16 | Release engineering | Exact SHA → full verify → isolated production build → browser E2E → integration queue/canary → rollback → exact live SHA/chunk health. Build/release is repeatable and no unique snowflake. | Release receipt per version. | Existing exact-SHA gates are strong; staged/canary policy still needs formal production evidence. |
+| 17 | Operational resilience | Published SLIs/SLOs, error-budget/change-freeze policy, disk/memory thresholds, alerting, restore/runbook ownership, and failure-mode drills. | SLO dashboard + alert/fire-drill receipts. | Disk pressure and capacity policy are not yet a complete product SLO. |
+| 18 | Documentation | Docs follow Tutorial / How-to / Reference / Explanation separation; one 10-minute tutorial is the canonical first route. | Docs map + link/check-doc gate + user completion test. | Excellent reference depth, but onboarding is still reference-heavy. |
+| 19 | Demoability | A reproducible ≤3-minute demo shows one project → agent/tool action → workflow/evidence → resume/handoff without secrets or hidden manual setup. | Recorded demo + script + clean fixture. | Existing demo is broad rather than one launch narrative. |
+| 20 | Launch readiness | Public beta only when all P0 gates are green, every known limitation is published, rollback/recovery is proven, and current main/live evidence matches the release claim. Stable label requires sustained SLO + recovery history. | Signed/dated release readiness receipt. | Public Alpha/Developer Preview remains the accurate label today. |
+
+## P0 before public beta
+
+1. **Enforce source concurrency**, not merely document it: isolated task worktrees, canonical-main mutation guard, clean integration authority, remote protection/ruleset/status checks. See [`SOURCE-CONCURRENCY.md`](./SOURCE-CONCURRENCY.md).
+2. **Complete disaster recovery**: complete resumable snapshot, encrypted offsite target, restore drill, explicit RPO/RTO. See [`DISASTER-RECOVERY.md`](./DISASTER-RECOVERY.md).
+3. **Agentic security launch suite**: prompt injection, tool misuse, privilege escalation, data exfiltration, memory poisoning, recursive/cascading failure and cross-agent identity tests. See [`AGENT-SECURITY.md`](./AGENT-SECURITY.md).
+4. **Measured onboarding**: fresh host, fresh user, no maintainer knowledge; record time-to-first-value and every manual intervention.
+5. **One killer journey** across README, Product Hunt, demo and onboarding.
+6. **SLO + operational policy**: availability/latency/failed-action/disk-pressure SLIs, error budget, change freeze and rollback policy. See [`RELIABILITY.md`](./RELIABILITY.md).
+
+## P1 before “stable”
+
+- Sustained SLO history across releases rather than one green release.
+- Recovery drill repeated from offsite backup.
+- Provider-native integrations meet one shared UX/AX/DX contract.
+- Memory admission/review is live, explainable and adversarially tested.
+- Role/task navigation has external usability evidence.
+- Human code-review posture or an explicit public solo-maintainer exception remains documented; do not fabricate review evidence.
+
+## Release decision rule
+
+A launch score is **evidence**, not averaging. One red P0 gate blocks the stronger launch label even if nineteen areas are excellent.
+
+Use separate states:
+
+`IMPLEMENTED → TESTED → INTEGRATED → RELEASED → VERIFIED-LIVE → OPERATED → HUMAN-VALIDATED`
+
+Never collapse them into “done.”
diff --git a/docs/PRODUCT_HUNT.md b/docs/PRODUCT_HUNT.md
index 144693fd..744d2f01 100644
--- a/docs/PRODUCT_HUNT.md
+++ b/docs/PRODUCT_HUNT.md
@@ -9,24 +9,19 @@ MSO — Manef Shell OS
## Tagline
-Manage your Linux server from any browser.
+Self-hosted control plane for AI agents
## Description
-MSO is an open-source, mobile-friendly visual shell for a Linux server you own. It combines
-Files, real PTY Terminal, Code with an integrated terminal, live metrics, a safe Service Center,
-cached package-update visibility, a remote Camoufox browser, device-scoped roles, media tools,
-optional BYOK Alfa AI, and managed Hermes/OpenClaw controls
-inside one private browser workspace.
+MSO is an open-source, self-hosted control plane for AI agents working across projects, tools, workflows and infrastructure. It combines project-aware agent sessions, scoped MCP/tools, native integrations, server-native workflows, files/terminal/service operations, memory and execution evidence behind one responsive browser/CLI/MCP runtime.
+
+The OS-style interface is the workspace metaphor, not the product boundary. MSO runs on a server you control and keeps provider credentials and privileged operations behind server-side identity, scope and approval rules.
## First comment draft
-I built MSO because managing a personal Linux server from a phone is still more awkward than
-it should be. SSH is powerful, but on mobile I kept jumping between terminal tabs, file
-transfer tools, metrics dashboards, docs and AI chat.
+I built MSO because useful agent work kept fragmenting across chat history, repositories, terminals, MCP tools, workflow apps, credentials and deployment consoles. I wanted one self-hosted control plane that could keep the project context, tool authority and execution evidence together.
-MSO is not a Linux distribution, desktop environment or VPS provider. "OS" is the interface
-metaphor: a responsive workspace over a server you already own.
+MSO is not a Linux distribution, VPS provider or a claim to replace every specialist automation product. "OS" is the interface metaphor; the product boundary is the agent control plane over infrastructure you already own.
It is owner-first, with live Viewer, Operator, and Owner roles assigned per approved device.
Owner remains shell-equivalent to the Linux service account; Operator is limited to bounded,
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
new file mode 100644
index 00000000..b1d4b7eb
--- /dev/null
+++ b/docs/QUICKSTART.md
@@ -0,0 +1,61 @@
+# First 10 minutes with MSO
+
+> This is the canonical **tutorial**: one path to first value. It deliberately does not explain every feature. For production hosting, use a supported Linux host and keep the raw app loopback-bound behind your chosen protected HTTPS/private-network path.
+
+## Goal
+
+Reach one verified, read-first agent action against a real project, then see the evidence you can resume later.
+
+## 1. Install and diagnose
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash
+mso doctor
+```
+
+Do not continue past an unexpected doctor failure. Fix the named layer first.
+
+## 2. Open MSO
+
+```bash
+mso web
+```
+
+Approve the device through the supported local/Owner flow if this browser is new. Treat Owner access like SSH-equivalent authority for the MSO service user.
+
+## 3. Connect one model/provider
+
+Open **Settings → Integrations / Models** and configure one supported provider through the private setup flow. Do not paste provider credentials into agent chat.
+
+## 4. Pick one project
+
+Use the Projects/Files surface or the CLI to identify a real project. Start read-only: inspect its status, current branch and recent work before asking an agent to edit anything.
+
+## 5. Run the first safe agent task
+
+From an MCP client or MSO agent, use a request shaped like:
+
+```text
+Check this project's current status and explain the highest-value next task.
+Do not change files, branches, services, deployments, credentials or external systems.
+```
+
+The first success criterion is not “the model answered.” It is that MSO resolved the project, used bounded reads, and produced inspectable execution evidence without widening authority.
+
+## 6. Make one isolated change
+
+For source-changing work, use one task-specific hidden worktree. Never use canonical `main` as a shared agent scratchpad. Inspect the diff and run the relevant tests before integration.
+
+## 7. Verify and resume
+
+Confirm the session/workflow evidence exists and can be resumed. A completed response is not equivalent to a tested, integrated, released or live-verified change.
+
+## Where next
+
+- **How to connect an AI client:** [`MCP-HOW-TO.md`](./MCP-HOW-TO.md)
+- **Install/repair/update:** [`INSTALL.md`](./INSTALL.md)
+- **Concepts and architecture:** [`ARCHITECTURE.md`](./ARCHITECTURE.md)
+- **Security boundaries:** [`SECURITY-ASSURANCE.md`](./SECURITY-ASSURANCE.md)
+- **Memory and retention:** [`MEMORY-SAFETY.md`](./MEMORY-SAFETY.md)
+- **Launch/stability gates:** [`LAUNCH-READINESS.md`](./LAUNCH-READINESS.md)
+- **Exact CLI reference:** [`CLI.md`](./CLI.md)
diff --git a/docs/README.md b/docs/README.md
index c771dac4..5c8f7df3 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -20,6 +20,13 @@ evidence and review freshness. The repository quality gate runs both automatical
| Document | Contract |
|---|---|
| [`../README.md`](../README.md) | Product overview and quickstart |
+| [`QUICKSTART.md`](./QUICKSTART.md) | Canonical first-10-minutes tutorial: install → doctor → provider → project → safe first agent action → evidence |
+| [`LAUNCH-READINESS.md`](./LAUNCH-READINESS.md) | 20 measurable product/launch gates, P0/P1 policy and truthful launch-label contract |
+| [`LAUNCH-QA.md`](./LAUNCH-QA.md) | Concise launch answers for category, competitors, agent concepts, security, memory, recovery and readiness |
+| [`SOURCE-CONCURRENCY.md`](./SOURCE-CONCURRENCY.md) | One-task-one-worktree, canonical integration authority, remote protection and concurrency acceptance tests |
+| [`AGENT-SECURITY.md`](./AGENT-SECURITY.md) | Agent-specific threat model, tool risk classes, abuse cases and memory-admission security contract |
+| [`DISASTER-RECOVERY.md`](./DISASTER-RECOVERY.md) | 3-2-1 target, RPO/RTO objectives, backup classes and restore-drill acceptance |
+| [`RELIABILITY.md`](./RELIABILITY.md) | Initial SLIs/SLO targets, error-budget policy, disk thresholds and release reliability contract |
| [`ARCHITECTURE.md`](./ARCHITECTURE.md) | Current runtime, shell, role, host, Agent/Local Agent/subagent, MCP and deployment architecture |
| [`GATEWAY.md`](./GATEWAY.md) | Provider-neutral gateway state, health, ownership, supervisor and deployment contract |
| [`COGNITIVE-RUNTIME.md`](./COGNITIVE-RUNTIME.md) | Provider-neutral MCP/session/context/tool-routing runtime and benchmark contract |
diff --git a/docs/RELIABILITY.md b/docs/RELIABILITY.md
new file mode 100644
index 00000000..2a8db5de
--- /dev/null
+++ b/docs/RELIABILITY.md
@@ -0,0 +1,48 @@
+# Reliability and launch SLO contract
+
+> **Targets, not current SLO claims.** The reference installation needs measured history before MSO can claim these objectives are achieved.
+
+## Initial SLIs
+
+Track at least:
+
+- public and loopback `/api/health` success rate and latency;
+- authenticated core-route success rate for project/session/tool/workflow reads;
+- privileged action success/refusal/error classification;
+- deployment success, rollback and exact-live-SHA convergence;
+- disk, memory and process saturation;
+- backup freshness/completeness/restore-drill age;
+- agent/workflow queue age and bounded failure/retry counts.
+
+## SLO targets
+
+For the maintainer reference production used as public evidence:
+
+- **Public-beta availability target:** 99.5% successful health checks per rolling 30 days.
+- **Stable availability target:** 99.9% per rolling 30 days, excluding documented planned maintenance only when users can distinguish it.
+- **Health latency target:** p95 <500 ms from the selected probe region under normal load.
+- **Release convergence:** supported release path reaches exact healthy live SHA or rolls back/fails closed; no ambiguous half-deployed success.
+- **Backup freshness:** within the configured RPO and no overdue restore drill.
+
+100% uptime is not the goal. The goal is explicit reliability that controls change velocity.
+
+## Error-budget/change policy
+
+- When the rolling error budget is healthy, normal feature releases may proceed after gates.
+- When exhausted, freeze nonessential feature releases and prioritize reliability/security/recovery work until exit criteria are met.
+- Security emergency fixes may proceed through an explicitly recorded exception with rollback evidence.
+
+## Capacity policy
+
+Disk pressure is a correctness concern because sessions, evidence, builds and Docker caches compete for the same host.
+
+- **<75%:** normal.
+- **75–85%:** warning; forecast growth and identify reclaimable caches.
+- **85–90%:** high; freeze nonessential cache growth/build churn and prepare reviewed cleanup/backup action.
+- **≥90%:** critical; alert Owner, preserve primary evidence, require previewed category-specific cleanup or capacity expansion. Never use age alone as proof that session/memory evidence is disposable.
+
+Thresholds are initial operator policy and should be calibrated from measured workload.
+
+## Release strategy
+
+Prefer reproducible automated builds, small isolated changes, exact-SHA evidence, staged/canary exposure when practical, and an explicit rollback path. A test pass, push, merge, deployment start and verified-live state are separate events.
diff --git a/docs/SOURCE-CONCURRENCY.md b/docs/SOURCE-CONCURRENCY.md
new file mode 100644
index 00000000..18efbe5d
--- /dev/null
+++ b/docs/SOURCE-CONCURRENCY.md
@@ -0,0 +1,50 @@
+# Source concurrency and integration contract
+
+> **Launch target.** Repository policy already requires isolated worktrees for parallel source work. Public-beta readiness requires the rule to be enforced by tooling and remote protection, not only by agent instructions.
+
+## Invariant
+
+`main` is the release/integration authority. It is never a shared agent scratchpad.
+
+```text
+user request
+ → workflow ownership
+ → isolated task worktree
+ → scoped commit(s)
+ → exact-SHA verification
+ → integration queue on latest main
+ → changed-base verification
+ → release
+ → live SHA verification
+```
+
+## Required behaviour
+
+1. Every source-changing automated workflow owns exactly one isolated hidden worktree.
+2. Two active workflows never share a Git index, worktree or branch.
+3. A dirty canonical checkout owned by another workflow is a **hard stop**, not an invitation to stash/reset/commit its work.
+4. Integration uses a clean latest `main`; candidate ancestry and remote head are revalidated immediately before integration.
+5. Candidate verification does not transfer automatically to a changed integration base. Relevant changed-base tests and the release gate run again.
+6. Only the integration/release authority advances canonical `main`.
+7. A worktree is removed only after unique tracked/untracked work is proven preserved and accounted for.
+8. Release evidence records candidate SHA, integrated SHA, deployed SHA and live SHA separately.
+
+## Remote protection target
+
+GitHub is code storage and a remote policy boundary; MSO/Batonly may remain the CI/CD executor. Protect `main` with a ruleset/branch policy that, where account/repository capabilities allow:
+
+- blocks force pushes and branch deletion;
+- requires the project's external status checks before integration;
+- requires the branch to be current with the integration head or uses a merge queue equivalent;
+- restricts direct updates to the designated integration identity;
+- keeps bypass narrow and auditable.
+
+As of the 2026-09-26 launch audit, the public GitHub rulesets collection for `rahmanef63/mso` returned empty. Branch-protection detail could not be read through the installed GitHub App because that integration lacks repository administration permission. Do not claim remote protection from that incomplete evidence.
+
+## Acceptance tests for 10/10
+
+- Simultaneous synthetic workflows attempt to mutate the same canonical project; only task-owned worktrees receive writes.
+- A workflow with an isolated-worktree classification cannot silently write source into canonical `main`.
+- A dirty canonical tree causes integration to fail without mutation.
+- Two independently green candidates are replayed against latest main; stale candidate evidence is not reused as release proof.
+- Remote policy rejects unauthorized direct/force update of `main`.
diff --git a/scripts/launch-readiness-contract.test.ts b/scripts/launch-readiness-contract.test.ts
new file mode 100644
index 00000000..814cd537
--- /dev/null
+++ b/scripts/launch-readiness-contract.test.ts
@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+const read = (file: string) => readFileSync(file, "utf8");
+
+describe("launch narrative and readiness SSOT", () => {
+ it("defines exactly twenty measurable launch dimensions and blocks score-by-averaging", () => {
+ const doc = read("docs/LAUNCH-READINESS.md");
+ const rows = [...doc.matchAll(/^\| (\d{1,2}) \|/gm)].map((match) => Number(match[1]));
+ expect(rows).toEqual(Array.from({ length: 20 }, (_, index) => index + 1));
+ expect(doc).toContain("Target, not a marketing score");
+ expect(doc).toContain("One red P0 gate blocks the stronger launch label");
+ expect(doc).toContain("IMPLEMENTED → TESTED → INTEGRATED → RELEASED → VERIFIED-LIVE → OPERATED → HUMAN-VALIDATED");
+ });
+
+ it("keeps the product category consistent across README and launch collateral", () => {
+ const readme = read("README.md");
+ const productHunt = read("docs/PRODUCT_HUNT.md");
+ expect(readme).toContain("A self-hosted control plane for AI agents.");
+ expect(productHunt).toContain("Self-hosted control plane for AI agents");
+ expect(readme).toContain("./docs/QUICKSTART.md");
+ expect(readme).toContain("./docs/LAUNCH-READINESS.md");
+ });
+
+ it("keeps the first-run tutorial narrow and read-first", () => {
+ const quickstart = read("docs/QUICKSTART.md");
+ expect(quickstart).toContain("First 10 minutes with MSO");
+ expect(quickstart).toContain("Do not change files, branches, services, deployments, credentials or external systems.");
+ expect(quickstart).toContain("Never use canonical `main` as a shared agent scratchpad");
+ });
+
+ it("states the canonical concurrency boundary for repository agents", () => {
+ const rules = read("CLAUDE.md");
+ expect(rules).toContain("release/integration surface, not an agent scratchpad");
+ expect(rules).toContain("must happen in a task-owned hidden worktree");
+ expect(rules).toContain("stop and preserve it rather than stashing, resetting, committing, merging or overwriting");
+ });
+
+ it("keeps launch answers honest about recovery and public readiness", () => {
+ const qa = read("docs/LAUNCH-QA.md");
+ expect(qa).toContain("Not yet as a stable-product claim");
+ expect(qa).toContain("Public Alpha / Developer Preview");
+ expect(qa).toContain("You should not trust it blindly");
+ });
+});