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.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
feat(shell): Docs app, a state-aware dock, and quicklinks back to the owner
Rahmaneb06cd9c2edd
diff --git a/app/os-root.tsx b/app/os-root.tsxindex 6d7f06fb..7f7040b4 100644--- a/app/os-root.tsx+++ b/app/os-root.tsx@@ -15,7 +15,7 @@ import { AppearanceProvider } from "@/lib/appearance";import { QuicklinksProvider } from "@/lib/quicklinks";import "@/features/os-shell/integrations"; // side-effect: lock guard + Quick Look + DnD wiringimport { OsApiProvider } from "@/lib/os-api";-import { AuthGate, SessionProvider, type SessionStatus } from "@/features/auth";+import { AuthGate, SessionProvider, useSession, type SessionStatus } from "@/features/auth";import { useInstalledApps, useDisabledIds } from "@/features/app-store";// Inside the auth boundary so it can read the owner's installed runtime apps and@@ -26,16 +26,31 @@ import { useInstalledApps, useDisabledIds } from "@/features/app-store";function Shell() {const dynamic = useInstalledApps();const disabled = useDisabledIds();+ const { status } = useSession();const manifest: ShellManifest = useMemo(() => {const off = new Set(disabled);+ const apps = [...BUILTIN_APPS, ...dynamic].filter((app) => !off.has(app.id));+ // The shell looks identical signed in or out, but it is NOT the same thing:+ // signed out every host call is mock, so most apps are showing fixtures. The+ // one app that explains that — and offers the two real next steps, sign in or+ // install your own — is Docs, so it gets promoted to the front of the dock and+ // the mobile quick row while signed out. Signed in it drops back to its normal+ // place; by then you are on your own box and the docs are just reference.+ const ordered =+ status === "out"+ ? [+ ...apps.filter((a) => a.id === "docs").map((a) => ({ ...a, pinned: true })),+ ...apps.filter((a) => a.id !== "docs"),+ ]+ : apps;return {brand: TOPSIDE_BRAND,- apps: [...BUILTIN_APPS, ...dynamic].filter((app) => !off.has(app.id)),+ apps: ordered,features: TOPSIDE_FEATURES.filter((f) => !off.has(f.id)),persistKey: TOPSIDE_PERSIST_KEY,capabilities: topsideCapabilities,};- }, [dynamic, disabled]);+ }, [dynamic, disabled, status]);return <AppShell manifest={manifest} />;}diff --git a/frontend/slices/docs/app.tsx b/frontend/slices/docs/app.tsxnew file mode 100644index 00000000..a3ab7973--- /dev/null+++ b/frontend/slices/docs/app.tsx@@ -0,0 +1,106 @@+"use client";++import { ArrowUpRight, BookOpen, Github, LogIn, Rocket } from "lucide-react";+import { AppFrame, openWindow } from "@/features/os-shell";+import { useSession } from "@/features/auth";+import { Button } from "@/components/ui/button";+import { DEEPER, INSTALL_GUIDE, REPO, START_HERE, type DocLink } from "./links";++// Docs window. The header is the ONE part that changes with session state: a+// signed-out visitor is browsing mock data and the most useful thing to offer is+// the way in (sign-in) and the way out (install your own). Signed in, that row+// would be noise — you are already in, on your own box.+export default function DocsApp() {+ const { status } = useSession();+ const signedOut = status === "out";++ return (+ <AppFrame>+ <div className="h-full overflow-y-auto p-5">+ <header className="mb-5">+ <h1 className="text-lg font-semibold tracking-tight">Manef Shell OS docs</h1>+ <p className="mt-1 text-sm text-muted-foreground">+ {signedOut+ ? "You are signed out, so this shell is showing mock data. Sign in to reach the real host, or install MSO on a server of your own."+ : "Reference for this instance, its CLI, and the slices it is built from."}+ </p>+ </header>++ {signedOut ? (+ <div className="mb-6 flex flex-wrap gap-2">+ <Button size="sm" onClick={() => openWindow("os-settings", "Settings")}>+ <LogIn className="size-4" aria-hidden />+ Sign in+ </Button>+ <Button size="sm" variant="outline" asChild>+ <a href={INSTALL_GUIDE.href}>+ <Rocket className="size-4" aria-hidden />+ Install your own+ </a>+ </Button>+ <Button size="sm" variant="outline" asChild>+ <a href={REPO} target="_blank" rel="noopener noreferrer">+ <Github className="size-4" aria-hidden />+ GitHub+ </a>+ </Button>+ </div>+ ) : null}++ <Row link={INSTALL_GUIDE} icon={Rocket} featured />++ <Section title="Start here" links={START_HERE} />+ <Section title="Going deeper" links={DEEPER} />+ </div>+ </AppFrame>+ );+}++function Section({ title, links }: { title: string; links: DocLink[] }) {+ return (+ <section className="mt-6">+ <h2 className="mb-2 text-xs font-medium uppercase tracking-widest text-muted-foreground">{title}</h2>+ <ul className="space-y-1.5">+ {links.map((l) => (+ <li key={l.href}>+ <Row link={l} icon={BookOpen} />+ </li>+ ))}+ </ul>+ </section>+ );+}++function Row({+ link,+ icon: Icon,+ featured,+}: {+ link: DocLink;+ icon: typeof BookOpen;+ featured?: boolean;+}) {+ // The install guide is same-origin (this instance serves /install), so it is a+ // plain navigation. Everything else is github.com and opens in a new tab —+ // losing the shell to read a markdown file would be a bad trade.+ const external = link.href.startsWith("http");+ return (+ <a+ href={link.href}+ {...(external ? { target: "_blank", rel: "noopener noreferrer" } : {})}+ className={+ "group flex items-start gap-3 rounded-lg border p-3 transition-colors hover:bg-accent " ++ (featured ? "border-primary/40 bg-primary/5" : "border-border")+ }+ >+ <Icon className="mt-0.5 size-4 shrink-0 text-muted-foreground" aria-hidden />+ <span className="min-w-0 flex-1">+ <span className="flex items-center gap-1 text-sm font-medium">+ {link.title}+ <ArrowUpRight className="size-3.5 shrink-0 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100" aria-hidden />+ </span>+ <span className="mt-0.5 block text-xs leading-relaxed text-muted-foreground">{link.desc}</span>+ </span>+ </a>+ );+}diff --git a/frontend/slices/docs/docs.test.ts b/frontend/slices/docs/docs.test.tsnew file mode 100644index 00000000..8ceecc0c--- /dev/null+++ b/frontend/slices/docs/docs.test.ts@@ -0,0 +1,54 @@+import { readFileSync } from "node:fs";+import { describe, expect, it } from "vitest";+import { DEEPER, INSTALL_GUIDE, REPO, START_HERE } from "./links";++// Read the sources rather than importing the barrels: `@/features/os-shell` pulls+// the whole React shell, which a node-env unit test has no business booting.+const read = (rel: string) => readFileSync(new URL(rel, import.meta.url), "utf8");++describe("docs app", () => {+ it("is registered in the shell so it can reach the dock", () => {+ const manifest = read("../os-shell/shell.manifest.ts");+ expect(manifest).toContain('import { docsApp } from "@/features/docs"');+ expect(manifest).toContain('withSlug(docsApp, "docs")');+ // noDock would hide it from the one surface a signed-out visitor looks at.+ expect(read("./index.ts")).not.toContain("noDock");+ });++ it("is promoted while signed out, so the menu matches the state", () => {+ const osRoot = read("../../../app/os-root.tsx");+ expect(osRoot).toContain('status === "out"');+ expect(osRoot).toContain('a.id === "docs"');+ });++ it("leads with the install guide this instance serves itself", () => {+ // Same-origin on purpose: it must work for a visitor who cannot reach GitHub.+ expect(INSTALL_GUIDE.href).toBe("/install");+ expect(START_HERE[0].href).toBe(REPO);+ });++ it("points every external link at the real repo", () => {+ for (const l of [...START_HERE, ...DEEPER]) {+ expect(l.href.startsWith(REPO) || l.href.startsWith("/")).toBe(true);+ expect(l.title.length).toBeGreaterThan(0);+ expect(l.desc.length).toBeGreaterThan(0);+ }+ });+});++describe("quicklinks defaults", () => {+ it("are the owner's accounts, not the project's docs", async () => {+ // The four GitHub file URLs that used to seed here now live in the Docs app.+ // A shortcut rail that ships the project's own documentation is a second,+ // worse copy of Docs — and leaves the owner nowhere to put their own links.+ const src = await import("node:fs").then((fs) =>+ fs.readFileSync(new URL("../../../lib/quicklinks/store.tsx", import.meta.url), "utf8"),+ );+ const defaults = src.slice(src.indexOf("const DEFAULTS"), src.indexOf("type Ctx"));+ expect(defaults).not.toContain("/blob/main/");+ expect(defaults).not.toContain("github.com/rahmanef63/mso");+ for (const host of ["github.com", "linkedin.com", "instagram.com"]) {+ expect(defaults).toContain(host);+ }+ });+});diff --git a/frontend/slices/docs/index.ts b/frontend/slices/docs/index.tsnew file mode 100644index 00000000..f11b9c0e--- /dev/null+++ b/frontend/slices/docs/index.ts@@ -0,0 +1,13 @@+import { BookOpen } from "lucide-react";+import type { AppDescriptor } from "@/features/os-shell";++// Barrel: the app layer imports only this. The window is lazy-loaded via `load`+// so the docs bundle is deferred until the window opens.+export const docsApp: AppDescriptor = {+ id: "docs",+ title: "Docs",+ icon: BookOpen,+ gradient: "linear-gradient(160deg,#38bdf8,#0369a1)",+ load: () => import("./app"),+ defaultSize: { w: 620, h: 560 },+};diff --git a/frontend/slices/docs/links.ts b/frontend/slices/docs/links.tsnew file mode 100644index 00000000..ec4c168b--- /dev/null+++ b/frontend/slices/docs/links.ts@@ -0,0 +1,34 @@+// Every link the Docs app shows, in one place. These used to be the DEFAULT+// quicklinks — but quicklinks are the owner's own shortcuts, and shipping four+// GitHub file URLs in that slot meant a fresh install's "personal" links were+// really the project's docs. Docs live here; quicklinks went back to being the+// owner's (see lib/quicklinks/store.ts).+export const REPO = "https://github.com/rahmanef63/mso";+const blob = (p: string) => `${REPO}/blob/main/${p}`;++export type DocLink = { title: string; desc: string; href: string };++// Shown first and on its own: the one page you can send to someone who has no+// account and no idea what MSO is. It is served by this very instance at+// /install, so it works even for a visitor who cannot reach github.com.+export const INSTALL_GUIDE: DocLink = {+ title: "Install on your own server",+ desc: "No login needed — requirements, the one-line installer, and the device-pairing step.",+ href: "/install",+};++export const START_HERE: DocLink[] = [+ { title: "GitHub repository", desc: "Source, issues, releases.", href: REPO },+ { title: "Install reference", desc: "Full server setup, TLS/VPN, updates and rollback.", href: blob("docs/INSTALL.md") },+ { title: "CLI reference", desc: "Every `mso` command, generated from its own --help.", href: blob("docs/CLI.md") },+ { title: "Security model", desc: "What a session can reach, and how to bound it.", href: blob("SECURITY.md") },+];++export const DEEPER: DocLink[] = [+ { title: "Architecture", desc: "How the shell, slices and host API fit together.", href: blob("docs/ARCHITECTURE.md") },+ { title: "Managed apps", desc: "Running Hermes and OpenClaw under MSO.", href: blob("docs/MANAGED-APPS.md") },+ { title: "Development", desc: "Local setup, slice conventions, tests.", href: blob("docs/DEVELOPMENT.md") },+ { title: "Troubleshooting", desc: "Common install, build and deploy failures.", href: blob("docs/TROUBLESHOOTING.md") },+ { title: "FAQ", desc: "What MSO is and, more usefully, what it is not.", href: blob("docs/FAQ.md") },+ { title: "Slice catalog", desc: "Every slice, what it owns, and its state.", href: blob("docs/SLICE-CATALOG.md") },+];diff --git a/frontend/slices/docs/slice.json b/frontend/slices/docs/slice.jsonnew file mode 100644index 00000000..623faf4c--- /dev/null+++ b/frontend/slices/docs/slice.json@@ -0,0 +1,27 @@+{+ "$schema": "https://resource.rahmanef.com/slice-schema.json",+ "slug": "docs",+ "version": "0.1.0",+ "category": "ui",+ "kind": "full",+ "title": "Docs — in-shell documentation index",+ "description": "OS app that indexes this instance's documentation: the public /install guide it serves itself, the GitHub repo, the CLI reference, the security model and the deeper architecture docs. Session-aware: a signed-out visitor also gets Sign in / Install your own / GitHub actions, since a signed-out shell is running on mock data and those are the only two useful next steps. Holds the links that used to ship as default quicklinks, so quicklinks can go back to being the owner's own shortcuts.",+ "namespace": "@/features/docs",+ "registers": ["registry"],+ "audit": [],+ "frontend": {+ "slicePath": "frontend/slices/docs",+ "configExport": "docsApp"+ },+ "deps": {+ "npm": ["lucide-react"],+ "shadcn": ["button"],+ "env": [],+ "peers": [+ { "slug": "os-shell", "range": "^0.1", "reason": "renders as a window app" },+ { "slug": "auth", "range": "^0.1", "reason": "reads session status to show the signed-out actions" }+ ]+ },+ "license": "MIT",+ "tags": ["os", "docs", "onboarding", "ui"]+}diff --git a/frontend/slices/os-shell/shell.manifest.ts b/frontend/slices/os-shell/shell.manifest.tsindex 5f561890..0cdc167b 100644--- a/frontend/slices/os-shell/shell.manifest.ts+++ b/frontend/slices/os-shell/shell.manifest.ts@@ -18,6 +18,7 @@ import { assistantApp } from "@/features/assistant";import { hermesApp, openclawApp } from "@/features/managed-apps";import { osSettingsApp } from "@/features/os-settings";import { quicklinksApp } from "@/features/quicklinks";+import { docsApp } from "@/features/docs";import { themeQuickPickerFeature } from "./theme-quick-picker";import { CamoufoxMark, HermesMark, OpenClawMark } from "./brand-marks";@@ -60,6 +61,9 @@ export const BUILTIN_APPS: AppDescriptor[] = [withSlug(withMark(hermesApp, HermesMark), "hermes"),withSlug(withMark(openclawApp, OpenClawMark), "openclaw"),withSlug(quicklinksApp, "links"),+ // Docs is deliberately dockable, not noDock: for a signed-out visitor it is the+ // only app that explains what they are looking at and how to get their own.+ withSlug(docsApp, "docs"),pin(withSlug(osSettingsApp, "settings")),];diff --git a/lib/quicklinks/store.tsx b/lib/quicklinks/store.tsxindex da065f18..08fc60c1 100644--- a/lib/quicklinks/store.tsx+++ b/lib/quicklinks/store.tsx@@ -21,13 +21,22 @@ export type Quicklink = { id: string; title: string; url: string };const KEY = "mso:quicklinks";// Seed for a fresh visitor (localStorage/server-synced edits win once present).-// Keep defaults generic: the public demo should not look connected to a real-// personal account or private server.+//+// These are the INSTANCE OWNER'S links, not the project's. They used to be four+// GitHub file URLs, which made a personal shortcut rail into a second, worse copy+// of the docs — those moved to the Docs app (`@/features/docs`), which is where a+// visitor looking for documentation actually goes.+//+// ⚠️ If you installed MSO on your own server, change these — they are the+// maintainer's accounts, not yours. They are all that is here so the list is one+// edit, and nothing else in the codebase reads them.const DEFAULTS: Quicklink[] = [- { id: "repo", title: "MSO GitHub", url: "https://github.com/rahmanef63/mso" },- { id: "docs", title: "Install docs", url: "https://github.com/rahmanef63/mso/blob/main/docs/INSTALL.md" },- { id: "demo", title: "Demo script", url: "https://github.com/rahmanef63/mso/blob/main/docs/DEMO-SCRIPT.md" },- { id: "security", title: "Security policy", url: "https://github.com/rahmanef63/mso/blob/main/SECURITY.md" },+ { id: "gh", title: "GitHub", url: "https://github.com/rahmanef63" },+ { id: "li", title: "LinkedIn", url: "https://www.linkedin.com/in/rahmanfakhrul" },+ { id: "ig", title: "Instagram", url: "https://www.instagram.com/rahmanef_" },+ { id: "x", title: "X", url: "https://x.com/rahmanef" },+ { id: "yt", title: "YouTube", url: "https://www.youtube.com/@rahmanef" },+ { id: "tt", title: "TikTok", url: "https://www.tiktok.com/@rahmanef" },];type Ctx = {