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(agents): refresh AGENTS.md and add .mso/KNOWLEDGE.md for #154-#162 (#164)

Abdurrahman Fakhrul68c4dae0e27c
diff --git a/.gitignore b/.gitignore
index 61ebc750..a219687e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -21,7 +21,10 @@ os-browser/*
!os-browser/package.json
!os-browser/package-lock.json
convex-backend/
-.mso/
+# Runtime/orchestration under .mso/ stays local (must not dirty update).
+# Fleet durable knowledge is the exception and is tracked.
+.mso/**
+!.mso/KNOWLEDGE.md
# RASMIC repo-local orchestration memory/evidence is runtime state. It must survive
# locally but must not make the MSO source checkout dirty and block `mso update`.
.agent/
diff --git a/.mso/KNOWLEDGE.md b/.mso/KNOWLEDGE.md
new file mode 100644
index 00000000..73bd67e5
--- /dev/null
+++ b/.mso/KNOWLEDGE.md
@@ -0,0 +1,60 @@
+# MSO — Knowledge
+
+Short durable facts for fleet agents. Routing/policy lives in `AGENTS.md` and `CLAUDE.md`. Do not treat this file as a changelog.
+
+## Ownership
+
+- Owner bot: **mso**; reports to **manef** / fleet ops; Linear **RAH** / MSO project.
+- GitHub SSOT: `rahmanef63/mso` branch `main`.
+
+## Stack
+
+- Next.js 16 + React 19 + TypeScript.
+- Next was bumped 16.4.0 → 16.4.2 for RCE advisories (#147).
+
+## Dual hosts (do not conflate)
+
+- **Grok box cache:** its own public host (portable docs use `mso-grok.example.com`; the real name lives in operator config) → `/home/box/mso` on `:4005`, store `/home/box/.mso`, tunnel `809d494c`.
+- **Laptop/WSL live cockpit:** historically the operator's own cockpit host (portable docs use `mso.example.com`), tunnel `8ed1ad29`. Agents must **not** change that tunnel or instance unless Rahman asks.
+
+Passwords, approved devices, and builds are **not** shared across hosts.
+
+## Coding path
+
+- Heavy coding on Rahman's laptop only under `~/agent-work/mso/` via `opencode2 --auto`.
+- Never edit live project folders (`~/projects/**`) or the live WSL MSO checkout.
+- No Cursor cloud agents (Rahman 2026-10-22).
+
+## Boundaries
+
+- Local commit OK.
+- Push, PR, merge, production secrets, new accounts, billing, and real client data need Rahman GO **in his own words** (agent-relayed OK does not count).
+- Design/product: decide the best recommendation and proceed with local commits.
+
+## Role split
+
+- **SI-Coder (sc)** = vault, redaction, credential lifecycle.
+- **MSO** = cockpit / MCP host.
+- **connectors-gateway** = edge.
+
+## Knowledge freshness
+
+- Code last push ~2026-10-27 (tip includes #162).
+- `AGENTS.md` was stale since 2026-10-18 until this update.
+- This file created 2026-10-28.
+
+## Recent landed product facts
+
+Compact facts agents need; cite PR numbers, do not re-litigate:
+
+- #154 live agent activity row + env-tunable turn budgets
+- #155 PolyForm Noncommercial license
+- #156–#159 dependency bumps
+- #160 one Convex provider with a project dimension (closes #152); no dual `convex` / `convex-cloud` cards
+- #161 Settings update: one cue, no toast / floating badge
+- #162 antislop: no em dashes in user-visible copy
+- Also since the AGENTS refresh window: #147 Next security; #146/#148 Composio Connect keys → `connect.composio.dev/mcp`; #150 demo logins; #151 provider picker; Orca MCP bridge + systemd `WorkingDirectory` fix
+
+## Optional WIP
+
+- Unpushed local worktrees may exist on the Grok box under `/workspace` (forge / mobile / QA). Do not invent details you cannot verify from this machine.
diff --git a/AGENTS.md b/AGENTS.md
index f5f039da..89d5dc83 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,6 +4,8 @@
before changing MSO. This file gives non-Claude agents the minimum routing needed to avoid
re-discovering the same failure patterns.
+Volatile host, ownership, and freshness facts live in [`.mso/KNOWLEDGE.md`](./.mso/KNOWLEDGE.md).
+
## Systematic implementation default
For debugging, integrations, refactors, deployments, and MCP work, use this loop:
@@ -34,6 +36,15 @@ For debugging, integrations, refactors, deployments, and MCP work, use this loop
Before adding another adapter/facade/barrel, read [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) and run `node scripts/check-architecture.mjs`. The architecture policy is ratcheted: transports share `lib/capabilities`, cross-layer DTOs live in `lib/contracts`, host calls use narrow `lib/host/*-api.ts`, generic apps use AppShell directly, and workflow persistence belongs to `lib/workflow`. Do not raise a ratchet just to make a change pass. Exact MCP catalog facts are generated with `node scripts/gen-mcp-catalog.mjs`; never hand-copy the current tool list into reference docs.
+
+## Hosts / dual-instance
+
+MSO has **two separate hosts**. Do not conflate them:
+
+- **Grok box cache** and the **laptop/WSL live cockpit** are different deployments, each with its own operator host (portable docs use `mso-grok.example.com` and `mso.example.com`), passwords, approved devices, builds, and tunnels.
+- Never retarget the laptop cockpit tunnel or change that live instance from box work unless Rahman asks.
+- Current tunnel IDs, store paths, and ports are volatile: read `.mso/KNOWLEDGE.md`. Do not hard-code guessed host facts into new docs.
+
## Repository and worktree policy
- The repository root resolved by `git rev-parse --show-toplevel` on `main` is the **canonical MSO checkout and release SSOT for this installation**.
@@ -51,6 +62,16 @@ Before adding another adapter/facade/barrel, read [`docs/ARCHITECTURE.md`](./doc
- Demo/review runtimes may have hidden internal checkouts, but they do not become a second source
of truth and must not be presented as another MSO project.
+
+## Agent-work coding path (Rahman laptop / fleet)
+
+When coding on Rahman's laptop for fleet work:
+
+- Work **only** under `~/agent-work/mso/` (separate clone). Never edit `~/projects/**` or the live WSL MSO checkout.
+- Prefer `opencode2 --auto` inside that clone. Do **not** use Cursor cloud agents (Rahman 2026-10-22).
+- Local commits are OK. Push, PR, and merge need Rahman GO in his own words (agent-relayed OK does not count).
+- This install's parallel coding/review worktrees under `~/.cache/mso-worktrees/` remain valid; they are not a substitute for the fleet `~/agent-work/mso/` path on the laptop.
+
## Install and update requests
When a user asks an agent to "install MSO from this repo" or "update MSO", do not invent a parallel
@@ -75,6 +96,28 @@ Agents *using* MSO over MCP start from [`docs/AGENT-BOOTSTRAP.md`](./docs/AGENT-
and official skill `mso-agent-bootstrap`, not by jumping to `exec_run`.
+
+## Integrations / Convex
+
+- There is **one** Convex provider with a **project dimension** (#160 / closes #152).
+- Do **not** reintroduce dual `convex` / `convex-cloud` cards, dual registry rows, or operations that 404 on self-hosted Convex.
+- Provider UI and infra code must treat cloud vs self-hosted as a dimension of one provider, not two providers.
+
+## Composio Connect
+
+- Composio Connect API keys (`ck_…`) route to `connect.composio.dev/mcp` (#146 / #148).
+- Validate Connect keys at the Connect MCP endpoint; do not assume the older platform MCP host for `ck_` keys.
+
+## Agent UI
+
+- One live agent activity row per turn; turn budgets are env-tunable (#154).
+- Settings update cue is a **single in-Settings signal** (Updates nav badge + Software update section). Do not bring back a new-version toast or dock-adjacent floating badge (#161).
+- User-visible copy must **not** use em dashes (U+2014). Antislop R-02 is a hard gate (#162).
+
+## License
+
+- The repository is under **PolyForm Noncommercial** (#155). Read `LICENSE` before reintroducing or asserting any other license claim in docs, UI, or packaging.
+
## Cognitive-runtime work
- The LLM provider is replaceable. Do not solve MSO agent quality by hard-coding one vendor's hidden
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 8feaa9cd..df0d264a 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -6,15 +6,11 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh
## 2026-10-28
-**Fixed**
-
-- `design` keep snap assist inside the R-10 glass dose cap
-
**Docs**
-- `design` audit glassmorphism per screen against antislop R-10
-- `design` transcribe the existing MSO design direction
-- `agents` point every coding agent at the antislop filter
+- `agents` use a placeholder host in the knowledge refresh
+- `agents` refresh AGENTS.md and add .mso/KNOWLEDGE.md for #154-#162
+- `antislop` design direction, agent pointer, and the R-10 glass audit (#163)
## 2026-10-27