Refactor: add stable folder layout foundation

.gitignore

@@ -25,3 +25,7 @@ pnpm-debug.log*
 # Go build output
 tmp/
 bin/
+
+.cgcignore
+
+POSIX/

Backend/cmd/posix/main.go

@@ -0,0 +1,52 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	"moku-backend/internal/config"
+	"moku-backend/internal/database"
+	"moku-backend/internal/posixproj"
+)
+
+func main() {
+	command := "rebuild"
+	if len(os.Args) > 1 {
+		command = os.Args[1]
+	}
+
+	switch command {
+	case "rebuild":
+		if err := rebuildProjection(context.Background()); err != nil {
+			log.Fatalf("rebuild POSIX projection: %v", err)
+		}
+	default:
+		log.Fatalf("unsupported posix command %q (supported: rebuild)", command)
+	}
+}
+
+func rebuildProjection(ctx context.Context) error {
+	cfg := config.Load()
+
+	db, err := database.NewPostgres(cfg.PostgresURL)
+	if err != nil {
+		return fmt.Errorf("connect database: %w", err)
+	}
+	defer db.Close()
+
+	summary, err := posixproj.NewProjector(db, cfg.POSIXRoot).RebuildWithSummary(ctx)
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf(
+		"POSIX projection rebuilt from %s\n  total nodes: %d\n  directories: %d\n  files: %d\n",
+		cfg.POSIXRoot,
+		summary.TotalNodes,
+		summary.DirectoryCount,
+		summary.FileCount,
+	)
+	return nil
+}

Backend/db/migrations/000002_bootstrap_foundation.sql

@@ -0,0 +1,180 @@
+-- +goose Up
+
+CREATE TYPE instance_mode AS ENUM ('personal', 'organizational');
+CREATE TYPE instance_access AS ENUM ('local', 'remote');
+CREATE TYPE instance_protocol AS ENUM ('http', 'https');
+CREATE TYPE workspace_kind AS ENUM ('organization', 'department', 'team', 'project');
+CREATE TYPE membership_role AS ENUM ('owner', 'admin', 'member');
+
+CREATE TABLE IF NOT EXISTS installations (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  singleton BOOLEAN NOT NULL DEFAULT TRUE UNIQUE,
+  mode instance_mode NOT NULL,
+  access instance_access NOT NULL,
+  protocol instance_protocol NOT NULL DEFAULT 'http',
+  host TEXT NOT NULL,
+  is_bootstrapped BOOLEAN NOT NULL DEFAULT FALSE,
+  bootstrapped_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email TEXT NOT NULL,
+  display_name TEXT NOT NULL,
+  password_hash TEXT NOT NULL,
+  is_instance_admin BOOLEAN NOT NULL DEFAULT FALSE,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_users_email_unique ON users (LOWER(email));
+
+CREATE TABLE IF NOT EXISTS user_homes (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL UNIQUE REFERENCES users(id) ON DELETE CASCADE,
+  title TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+ALTER TABLE organizations
+  ADD COLUMN IF NOT EXISTS created_by_user_id UUID REFERENCES users(id) ON DELETE SET NULL;
+
+CREATE TABLE IF NOT EXISTS organization_memberships (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  organization_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  role membership_role NOT NULL DEFAULT 'member',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE (organization_id, user_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_organization_memberships_user_id ON organization_memberships (user_id);
+
+CREATE TABLE IF NOT EXISTS departments (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  organization_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  slug TEXT NOT NULL,
+  created_by_user_id UUID REFERENCES users(id) ON DELETE SET NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE (organization_id, slug)
+);
+
+CREATE INDEX IF NOT EXISTS idx_departments_organization_id ON departments (organization_id);
+
+CREATE TABLE IF NOT EXISTS teams (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  organization_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  department_id UUID REFERENCES departments(id) ON DELETE SET NULL,
+  name TEXT NOT NULL,
+  slug TEXT NOT NULL,
+  created_by_user_id UUID REFERENCES users(id) ON DELETE SET NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE (organization_id, slug)
+);
+
+CREATE INDEX IF NOT EXISTS idx_teams_organization_id ON teams (organization_id);
+CREATE INDEX IF NOT EXISTS idx_teams_department_id ON teams (department_id);
+
+CREATE TABLE IF NOT EXISTS team_memberships (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  team_id UUID NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  role membership_role NOT NULL DEFAULT 'member',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE (team_id, user_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_team_memberships_user_id ON team_memberships (user_id);
+
+CREATE TABLE IF NOT EXISTS projects (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  organization_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  department_id UUID REFERENCES departments(id) ON DELETE SET NULL,
+  team_id UUID REFERENCES teams(id) ON DELETE SET NULL,
+  name TEXT NOT NULL,
+  slug TEXT NOT NULL,
+  created_by_user_id UUID REFERENCES users(id) ON DELETE SET NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE (organization_id, slug)
+);
+
+CREATE INDEX IF NOT EXISTS idx_projects_organization_id ON projects (organization_id);
+CREATE INDEX IF NOT EXISTS idx_projects_department_id ON projects (department_id);
+CREATE INDEX IF NOT EXISTS idx_projects_team_id ON projects (team_id);
+
+CREATE TABLE IF NOT EXISTS project_memberships (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  role membership_role NOT NULL DEFAULT 'member',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE (project_id, user_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_project_memberships_user_id ON project_memberships (user_id);
+
+ALTER TABLE workspaces
+  ADD COLUMN IF NOT EXISTS kind workspace_kind NOT NULL DEFAULT 'organization',
+  ADD COLUMN IF NOT EXISTS created_by_user_id UUID REFERENCES users(id) ON DELETE SET NULL,
+  ADD COLUMN IF NOT EXISTS department_id UUID REFERENCES departments(id) ON DELETE SET NULL,
+  ADD COLUMN IF NOT EXISTS team_id UUID REFERENCES teams(id) ON DELETE SET NULL,
+  ADD COLUMN IF NOT EXISTS project_id UUID REFERENCES projects(id) ON DELETE SET NULL;
+
+CREATE INDEX IF NOT EXISTS idx_workspaces_department_id ON workspaces (department_id);
+CREATE INDEX IF NOT EXISTS idx_workspaces_team_id ON workspaces (team_id);
+CREATE INDEX IF NOT EXISTS idx_workspaces_project_id ON workspaces (project_id);
+
+-- +goose Down
+
+DROP INDEX IF EXISTS idx_workspaces_project_id;
+DROP INDEX IF EXISTS idx_workspaces_team_id;
+DROP INDEX IF EXISTS idx_workspaces_department_id;
+
+ALTER TABLE workspaces
+  DROP COLUMN IF EXISTS project_id,
+  DROP COLUMN IF EXISTS team_id,
+  DROP COLUMN IF EXISTS department_id,
+  DROP COLUMN IF EXISTS created_by_user_id,
+  DROP COLUMN IF EXISTS kind;
+
+DROP INDEX IF EXISTS idx_project_memberships_user_id;
+DROP TABLE IF EXISTS project_memberships;
+
+DROP INDEX IF EXISTS idx_projects_team_id;
+DROP INDEX IF EXISTS idx_projects_department_id;
+DROP INDEX IF EXISTS idx_projects_organization_id;
+DROP TABLE IF EXISTS projects;
+
+DROP INDEX IF EXISTS idx_team_memberships_user_id;
+DROP TABLE IF EXISTS team_memberships;
+
+DROP INDEX IF EXISTS idx_teams_department_id;
+DROP INDEX IF EXISTS idx_teams_organization_id;
+DROP TABLE IF EXISTS teams;
+
+DROP INDEX IF EXISTS idx_departments_organization_id;
+DROP TABLE IF EXISTS departments;
+
+DROP INDEX IF EXISTS idx_organization_memberships_user_id;
+DROP TABLE IF EXISTS organization_memberships;
+
+ALTER TABLE organizations
+  DROP COLUMN IF EXISTS created_by_user_id;
+
+DROP TABLE IF EXISTS user_homes;
+DROP INDEX IF EXISTS idx_users_email_unique;
+DROP TABLE IF EXISTS users;
+DROP TABLE IF EXISTS installations;
+
+DROP TYPE IF EXISTS membership_role;
+DROP TYPE IF EXISTS workspace_kind;
+DROP TYPE IF EXISTS instance_protocol;
+DROP TYPE IF EXISTS instance_access;
+DROP TYPE IF EXISTS instance_mode;

Backend/db/migrations/000003_installation_name.sql

@@ -0,0 +1,9 @@
+-- +goose Up
+
+ALTER TABLE installations
+  ADD COLUMN IF NOT EXISTS name TEXT NOT NULL DEFAULT '';
+
+-- +goose Down
+
+ALTER TABLE installations
+  DROP COLUMN IF EXISTS name;

Backend/db/migrations/000004_posix_nodes.sql

@@ -0,0 +1,45 @@
+-- +goose Up
+
+CREATE TYPE posix_node_kind AS ENUM ('directory', 'file');
+
+CREATE TABLE IF NOT EXISTS posix_nodes (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  path TEXT NOT NULL UNIQUE,
+  parent_path TEXT,
+  name TEXT NOT NULL,
+  depth INTEGER NOT NULL,
+  node_kind posix_node_kind NOT NULL,
+  logical_type TEXT NOT NULL DEFAULT 'generic',
+  file_role TEXT,
+  resource_id TEXT,
+  resource_name TEXT,
+  resource_slug TEXT,
+  installation_id TEXT,
+  organization_id TEXT,
+  organization_slug TEXT,
+  department_slug TEXT,
+  team_slug TEXT,
+  project_slug TEXT,
+  personal_slug TEXT,
+  content_json JSONB,
+  size_bytes BIGINT NOT NULL DEFAULT 0,
+  checksum TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_posix_nodes_parent_path ON posix_nodes (parent_path);
+CREATE INDEX IF NOT EXISTS idx_posix_nodes_logical_type ON posix_nodes (logical_type);
+CREATE INDEX IF NOT EXISTS idx_posix_nodes_project_slug ON posix_nodes (project_slug);
+CREATE INDEX IF NOT EXISTS idx_posix_nodes_department_slug ON posix_nodes (department_slug);
+CREATE INDEX IF NOT EXISTS idx_posix_nodes_team_slug ON posix_nodes (team_slug);
+
+-- +goose Down
+
+DROP INDEX IF EXISTS idx_posix_nodes_team_slug;
+DROP INDEX IF EXISTS idx_posix_nodes_department_slug;
+DROP INDEX IF EXISTS idx_posix_nodes_project_slug;
+DROP INDEX IF EXISTS idx_posix_nodes_logical_type;
+DROP INDEX IF EXISTS idx_posix_nodes_parent_path;
+DROP TABLE IF EXISTS posix_nodes;
+DROP TYPE IF EXISTS posix_node_kind;

Backend/docker-bake.hcl

@@ -23,14 +23,50 @@ target "dev-image" {
   tags     = ["${REGISTRY}/moku/work-backend:dev-${TAG}"]
 }
 
+target "prod-api" {
+  inherits = ["_app"]
+  target   = "runtime"
+  args = {
+    SERVICE_NAME = "api"
+  }
+  tags = ["moku/work-backend:local-prod-api"]
+}
+
+target "prod-worker" {
+  inherits = ["_app"]
+  target   = "runtime"
+  args = {
+    SERVICE_NAME = "worker"
+  }
+  tags = ["moku/work-backend:local-prod-worker"]
+}
+
+target "prod-api-image" {
+  inherits = ["_app"]
+  target   = "runtime"
+  args = {
+    SERVICE_NAME = "api"
+  }
+  tags = ["${REGISTRY}/moku/work-backend:prod-api-${TAG}"]
+}
+
+target "prod-worker-image" {
+  inherits = ["_app"]
+  target   = "runtime"
+  args = {
+    SERVICE_NAME = "worker"
+  }
+  tags = ["${REGISTRY}/moku/work-backend:prod-worker-${TAG}"]
+}
+
 group "local" {
-  targets = ["dev"]
+  targets = ["dev", "prod-api", "prod-worker"]
 }
 
 group "registry" {
-  targets = ["dev-image"]
+  targets = ["dev-image", "prod-api-image", "prod-worker-image"]
 }
 
 group "default" {
-  targets = ["dev"]
+  targets = ["dev", "prod-api", "prod-worker"]
 }

Backend/internal/bootstrap/service_test.go

@@ -0,0 +1,579 @@
+package bootstrap
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestEnsureBootstrapPOSIXSkeletonInitializesEmptyRoot(t *testing.T) {
+	rootPath := filepath.Join(t.TempDir(), "POSIX")
+	t.Setenv("POSIX_ROOT", rootPath)
+
+	if _, err := os.Stat(rootPath); !os.IsNotExist(err) {
+		t.Fatalf("expected isolated POSIX root to start absent, got err=%v", err)
+	}
+
+	service := NewService(nil, os.Getenv("POSIX_ROOT"))
+
+	err := service.ensureBootstrapPOSIXSkeleton(
+		InstallationRecord{
+			ID:             "installation-1",
+			Name:           "MangoPig",
+			Mode:           "personal",
+			Access:         "local",
+			Protocol:       "http",
+			Host:           "localhost",
+			IsBootstrapped: true,
+		},
+		AdminSummary{
+			ID:          "admin-1",
+			Email:       "ronald@example.com",
+			DisplayName: "Ronald",
+		},
+		namedRecord{ID: "org-1", Name: "Primary Organization", Slug: "primary-organization"},
+		namedRecord{ID: "dept-1", Name: "Primary Department", Slug: "primary-department"},
+		namedRecord{ID: "team-1", Name: "Primary Team", Slug: "primary-team"},
+		namedRecord{ID: "project-1", Name: "Primary Project", Slug: "primary-project"},
+	)
+	if err != nil {
+		t.Fatalf("ensure bootstrap POSIX skeleton: %v", err)
+	}
+
+	requiredPaths := []string{
+		filepath.Join(rootPath, "settings.json"),
+		filepath.Join(rootPath, "layout.json"),
+		filepath.Join(rootPath, "catalog", "packs"),
+		filepath.Join(rootPath, "catalog", "standalone"),
+		filepath.Join(rootPath, "departments", "department-primary-department", "settings.json"),
+		filepath.Join(rootPath, "departments", "department-primary-department", "users.json"),
+		filepath.Join(rootPath, "departments", "department-primary-department", "teams", "team-primary-team", "settings.json"),
+		filepath.Join(rootPath, "departments", "department-primary-department", "teams", "team-primary-team", "users.json"),
+		filepath.Join(rootPath, "projects", "project-primary-project", "settings.json"),
+		filepath.Join(rootPath, "projects", "project-primary-project", "home.json"),
+		filepath.Join(rootPath, "projects", "project-primary-project", "acl.json"),
+		filepath.Join(rootPath, "projects", "project-primary-project", "children"),
+		filepath.Join(rootPath, "projects", "project-primary-project", "tree"),
+		filepath.Join(rootPath, "users", "settings.json"),
+		filepath.Join(rootPath, "users", "data.json"),
+		filepath.Join(rootPath, "users", "personals"),
+		filepath.Join(rootPath, "users", "personals", "personal-ronald", "settings.json"),
+		filepath.Join(rootPath, "users", "personals", "personal-ronald", "layout.json"),
+		filepath.Join(rootPath, "users", "personals", "personal-ronald", "home.json"),
+		filepath.Join(rootPath, "users", "personals", "personal-ronald", "tree"),
+	}
+
+	for _, path := range requiredPaths {
+		if _, err := os.Stat(path); err != nil {
+			t.Fatalf("expected path to exist %s: %v", path, err)
+		}
+	}
+
+	settingsPayload := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, "settings.json"))
+	installationPayload, ok := settingsPayload["installation"].(map[string]any)
+	if !ok {
+		t.Fatalf("settings.json missing installation object: %#v", settingsPayload)
+	}
+	if installationPayload["name"] != "MangoPig" {
+		t.Fatalf("expected installation name MangoPig, got %#v", installationPayload["name"])
+	}
+	if installationPayload["isBootstrapped"] != true {
+		t.Fatalf("expected installation to be bootstrapped, got %#v", installationPayload["isBootstrapped"])
+	}
+
+	layoutPayload := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, "layout.json"))
+	homePayload, ok := layoutPayload["home"].(map[string]any)
+	if !ok {
+		t.Fatalf("layout.json missing home object: %#v", layoutPayload)
+	}
+	if homePayload["defaultProjectSlug"] != "primary-project" {
+		t.Fatalf("expected default project slug primary-project, got %#v", homePayload["defaultProjectSlug"])
+	}
+
+	projectSettings := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, "projects", "project-primary-project", "settings.json"))
+	if projectSettings["type"] != "project" {
+		t.Fatalf("expected project settings type project, got %#v", projectSettings["type"])
+	}
+
+	projectACL := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, "projects", "project-primary-project", "acl.json"))
+	if projectACL["inherits"] != true {
+		t.Fatalf("expected project acl to inherit by default, got %#v", projectACL["inherits"])
+	}
+
+	usersSettings := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, "users", "settings.json"))
+	if usersSettings["primaryAdminId"] != "admin-1" {
+		t.Fatalf("expected primary admin id admin-1, got %#v", usersSettings["primaryAdminId"])
+	}
+
+	personalSettings := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, "users", "personals", "personal-ronald", "settings.json"))
+	if personalSettings["type"] != "personal" {
+		t.Fatalf("expected personal settings type personal, got %#v", personalSettings["type"])
+	}
+	if personalSettings["name"] != "Ronald" {
+		t.Fatalf("expected personal name Ronald, got %#v", personalSettings["name"])
+	}
+	if personalSettings["slug"] != "ronald" {
+		t.Fatalf("expected personal slug ronald, got %#v", personalSettings["slug"])
+	}
+
+	personalHome := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, "users", "personals", "personal-ronald", "home.json"))
+	if personalHome["type"] != "personal-home" {
+		t.Fatalf("expected personal home type personal-home, got %#v", personalHome["type"])
+	}
+	if personalHome["title"] != "Ronald's Home" {
+		t.Fatalf("expected personal home title Ronald's Home, got %#v", personalHome["title"])
+	}
+}
+
+func TestCreateProjectHierarchyFolderOnDiskCreatesExpectedFolderShape(t *testing.T) {
+	rootPath := filepath.Join(t.TempDir(), "POSIX")
+	service := NewService(nil, rootPath)
+
+	err := service.ensureBootstrapPOSIXSkeleton(
+		InstallationRecord{ID: "installation-1", Name: "MangoPig", Mode: "personal", Access: "local", Protocol: "http", Host: "localhost", IsBootstrapped: true},
+		AdminSummary{ID: "admin-1", Email: "ronald@example.com", DisplayName: "Ronald"},
+		namedRecord{ID: "org-1", Name: "Primary Organization", Slug: "primary-organization"},
+		namedRecord{ID: "dept-1", Name: "Primary Department", Slug: "primary-department"},
+		namedRecord{ID: "team-1", Name: "Primary Team", Slug: "primary-team"},
+		namedRecord{ID: "project-1", Name: "Primary Project", Slug: "primary-project"},
+	)
+	if err != nil {
+		t.Fatalf("ensure bootstrap POSIX skeleton: %v", err)
+	}
+
+	createdPath, createdSlug, err := service.createProjectHierarchyFolderOnDisk("primary-project", "", "Design System")
+	if err != nil {
+		t.Fatalf("createProjectHierarchyFolderOnDisk root folder: %v", err)
+	}
+	if createdPath != "projects/project-primary-project/children/folder-design-system" {
+		t.Fatalf("unexpected created path: %s", createdPath)
+	}
+	if createdSlug != "design-system" {
+		t.Fatalf("unexpected created slug: %s", createdSlug)
+	}
+
+	createdFolderPath := filepath.Join(rootPath, "projects", "project-primary-project", "children", "folder-design-system")
+	for _, path := range []string{
+		filepath.Join(createdFolderPath, "folder.json"),
+		filepath.Join(createdFolderPath, "acl.json"),
+		filepath.Join(createdFolderPath, "children"),
+	} {
+		if _, err := os.Stat(path); err != nil {
+			t.Fatalf("expected path to exist %s: %v", path, err)
+		}
+	}
+
+	folderPayload := readJSONFileForTest[map[string]any](t, filepath.Join(createdFolderPath, "folder.json"))
+	if strings.TrimSpace(asStringForTest(folderPayload["id"])) == "" {
+		t.Fatalf("expected created folder to have stable id, got %#v", folderPayload["id"])
+	}
+	if folderPayload["name"] != "Design System" {
+		t.Fatalf("expected folder name Design System, got %#v", folderPayload["name"])
+	}
+	if folderPayload["slug"] != "design-system" {
+		t.Fatalf("expected folder slug design-system, got %#v", folderPayload["slug"])
+	}
+
+	nestedPath, nestedSlug, err := service.createProjectHierarchyFolderOnDisk("primary-project", createdPath, "Research")
+	if err != nil {
+		t.Fatalf("createProjectHierarchyFolderOnDisk nested folder: %v", err)
+	}
+	if nestedPath != "projects/project-primary-project/children/folder-design-system/children/folder-research" {
+		t.Fatalf("unexpected nested path: %s", nestedPath)
+	}
+	if nestedSlug != "research" {
+		t.Fatalf("unexpected nested slug: %s", nestedSlug)
+	}
+}
+
+func TestCreateProjectTreeFolderOnDiskCreatesExpectedFolderShape(t *testing.T) {
+	rootPath := filepath.Join(t.TempDir(), "POSIX")
+	service := NewService(nil, rootPath)
+
+	err := service.ensureBootstrapPOSIXSkeleton(
+		InstallationRecord{ID: "installation-1", Name: "MangoPig", Mode: "personal", Access: "local", Protocol: "http", Host: "localhost", IsBootstrapped: true},
+		AdminSummary{ID: "admin-1", Email: "ronald@example.com", DisplayName: "Ronald"},
+		namedRecord{ID: "org-1", Name: "Primary Organization", Slug: "primary-organization"},
+		namedRecord{ID: "dept-1", Name: "Primary Department", Slug: "primary-department"},
+		namedRecord{ID: "team-1", Name: "Primary Team", Slug: "primary-team"},
+		namedRecord{ID: "project-1", Name: "Primary Project", Slug: "primary-project"},
+	)
+	if err != nil {
+		t.Fatalf("ensure bootstrap POSIX skeleton: %v", err)
+	}
+
+	createdPath, createdSlug, err := service.createProjectTreeFolderOnDisk("primary-project", "", "Docs")
+	if err != nil {
+		t.Fatalf("createProjectTreeFolderOnDisk root folder: %v", err)
+	}
+	if createdPath != "projects/project-primary-project/tree/folder-docs" {
+		t.Fatalf("unexpected created path: %s", createdPath)
+	}
+	if createdSlug != "docs" {
+		t.Fatalf("unexpected created slug: %s", createdSlug)
+	}
+
+	createdFolderPath := filepath.Join(rootPath, "projects", "project-primary-project", "tree", "folder-docs")
+	for _, path := range []string{
+		filepath.Join(createdFolderPath, "folder.json"),
+		filepath.Join(createdFolderPath, "acl.json"),
+		filepath.Join(createdFolderPath, "children"),
+	} {
+		if _, err := os.Stat(path); err != nil {
+			t.Fatalf("expected path to exist %s: %v", path, err)
+		}
+	}
+
+	nestedPath, nestedSlug, err := service.createProjectTreeFolderOnDisk("primary-project", createdPath, "Research")
+	if err != nil {
+		t.Fatalf("createProjectTreeFolderOnDisk nested folder: %v", err)
+	}
+	if nestedPath != "projects/project-primary-project/tree/folder-docs/children/folder-research" {
+		t.Fatalf("unexpected nested path: %s", nestedPath)
+	}
+	if nestedSlug != "research" {
+		t.Fatalf("unexpected nested slug: %s", nestedSlug)
+	}
+}
+
+func TestRenameProjectHierarchyFolderOnDiskRenamesFolderShape(t *testing.T) {
+	rootPath := filepath.Join(t.TempDir(), "POSIX")
+	service := NewService(nil, rootPath)
+
+	err := service.ensureBootstrapPOSIXSkeleton(
+		InstallationRecord{ID: "installation-1", Name: "MangoPig", Mode: "personal", Access: "local", Protocol: "http", Host: "localhost", IsBootstrapped: true},
+		AdminSummary{ID: "admin-1", Email: "ronald@example.com", DisplayName: "Ronald"},
+		namedRecord{ID: "org-1", Name: "Primary Organization", Slug: "primary-organization"},
+		namedRecord{ID: "dept-1", Name: "Primary Department", Slug: "primary-department"},
+		namedRecord{ID: "team-1", Name: "Primary Team", Slug: "primary-team"},
+		namedRecord{ID: "project-1", Name: "Primary Project", Slug: "primary-project"},
+	)
+	if err != nil {
+		t.Fatalf("ensure bootstrap POSIX skeleton: %v", err)
+	}
+
+	createdPath, _, err := service.createProjectHierarchyFolderOnDisk("primary-project", "", "Design System")
+	if err != nil {
+		t.Fatalf("createProjectHierarchyFolderOnDisk root folder: %v", err)
+	}
+
+	nestedPath, _, err := service.createProjectHierarchyFolderOnDisk("primary-project", createdPath, "Research")
+	if err != nil {
+		t.Fatalf("createProjectHierarchyFolderOnDisk nested folder: %v", err)
+	}
+
+	previousPath, renamedPath, err := service.renameProjectHierarchyFolderOnDisk("primary-project", createdPath, "Platform Design")
+	if err != nil {
+		t.Fatalf("renameProjectHierarchyFolderOnDisk: %v", err)
+	}
+	if previousPath != createdPath {
+		t.Fatalf("expected previous path %s, got %s", createdPath, previousPath)
+	}
+	if renamedPath != "projects/project-primary-project/children/folder-platform-design" {
+		t.Fatalf("unexpected renamed path: %s", renamedPath)
+	}
+
+	if _, err := os.Stat(filepath.Join(rootPath, filepath.FromSlash(createdPath))); !os.IsNotExist(err) {
+		t.Fatalf("expected previous folder path to be gone, got err=%v", err)
+	}
+
+	renamedFolderPath := filepath.Join(rootPath, filepath.FromSlash(renamedPath))
+	if _, err := os.Stat(filepath.Join(renamedFolderPath, "children", filepath.Base(nestedPath))); err != nil {
+		t.Fatalf("expected nested child folder to move with renamed parent: %v", err)
+	}
+
+	folderPayload := readJSONFileForTest[map[string]any](t, filepath.Join(renamedFolderPath, "folder.json"))
+	if strings.TrimSpace(asStringForTest(folderPayload["id"])) == "" {
+		t.Fatalf("expected renamed folder to preserve stable id, got %#v", folderPayload["id"])
+	}
+	if folderPayload["name"] != "Platform Design" {
+		t.Fatalf("expected renamed folder name Platform Design, got %#v", folderPayload["name"])
+	}
+	if folderPayload["slug"] != "platform-design" {
+		t.Fatalf("expected renamed folder slug platform-design, got %#v", folderPayload["slug"])
+	}
+	if folderPayload["type"] != "folder" {
+		t.Fatalf("expected renamed folder type folder, got %#v", folderPayload["type"])
+	}
+}
+
+func TestRenameProjectTreeFolderOnDiskRenamesFolderShape(t *testing.T) {
+	rootPath := filepath.Join(t.TempDir(), "POSIX")
+	service := NewService(nil, rootPath)
+
+	err := service.ensureBootstrapPOSIXSkeleton(
+		InstallationRecord{ID: "installation-1", Name: "MangoPig", Mode: "personal", Access: "local", Protocol: "http", Host: "localhost", IsBootstrapped: true},
+		AdminSummary{ID: "admin-1", Email: "ronald@example.com", DisplayName: "Ronald"},
+		namedRecord{ID: "org-1", Name: "Primary Organization", Slug: "primary-organization"},
+		namedRecord{ID: "dept-1", Name: "Primary Department", Slug: "primary-department"},
+		namedRecord{ID: "team-1", Name: "Primary Team", Slug: "primary-team"},
+		namedRecord{ID: "project-1", Name: "Primary Project", Slug: "primary-project"},
+	)
+	if err != nil {
+		t.Fatalf("ensure bootstrap POSIX skeleton: %v", err)
+	}
+
+	createdPath, _, err := service.createProjectTreeFolderOnDisk("primary-project", "", "Docs")
+	if err != nil {
+		t.Fatalf("createProjectTreeFolderOnDisk root folder: %v", err)
+	}
+
+	previousPath, renamedPath, err := service.renameProjectTreeFolderOnDisk("primary-project", createdPath, "Specifications")
+	if err != nil {
+		t.Fatalf("renameProjectTreeFolderOnDisk: %v", err)
+	}
+	if previousPath != createdPath {
+		t.Fatalf("expected previous path %s, got %s", createdPath, previousPath)
+	}
+	if renamedPath != "projects/project-primary-project/tree/folder-specifications" {
+		t.Fatalf("unexpected renamed path: %s", renamedPath)
+	}
+
+	folderPayload := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, filepath.FromSlash(renamedPath), "folder.json"))
+	if folderPayload["name"] != "Specifications" {
+		t.Fatalf("expected renamed folder name Specifications, got %#v", folderPayload["name"])
+	}
+	if folderPayload["slug"] != "specifications" {
+		t.Fatalf("expected renamed folder slug specifications, got %#v", folderPayload["slug"])
+	}
+}
+
+func TestMoveProjectHierarchyFolderOnDiskMovesFolderToNewParent(t *testing.T) {
+	rootPath := filepath.Join(t.TempDir(), "POSIX")
+	service := NewService(nil, rootPath)
+
+	err := service.ensureBootstrapPOSIXSkeleton(
+		InstallationRecord{ID: "installation-1", Name: "MangoPig", Mode: "personal", Access: "local", Protocol: "http", Host: "localhost", IsBootstrapped: true},
+		AdminSummary{ID: "admin-1", Email: "ronald@example.com", DisplayName: "Ronald"},
+		namedRecord{ID: "org-1", Name: "Primary Organization", Slug: "primary-organization"},
+		namedRecord{ID: "dept-1", Name: "Primary Department", Slug: "primary-department"},
+		namedRecord{ID: "team-1", Name: "Primary Team", Slug: "primary-team"},
+		namedRecord{ID: "project-1", Name: "Primary Project", Slug: "primary-project"},
+	)
+	if err != nil {
+		t.Fatalf("ensure bootstrap POSIX skeleton: %v", err)
+	}
+
+	designPath, _, err := service.createProjectHierarchyFolderOnDisk("primary-project", "", "Design")
+	if err != nil {
+		t.Fatalf("create design folder: %v", err)
+	}
+	operationsPath, _, err := service.createProjectHierarchyFolderOnDisk("primary-project", "", "Operations")
+	if err != nil {
+		t.Fatalf("create operations folder: %v", err)
+	}
+	researchPath, _, err := service.createProjectHierarchyFolderOnDisk("primary-project", designPath, "Research")
+	if err != nil {
+		t.Fatalf("create research folder: %v", err)
+	}
+	nestedPath, _, err := service.createProjectHierarchyFolderOnDisk("primary-project", researchPath, "Interview Notes")
+	if err != nil {
+		t.Fatalf("create nested folder: %v", err)
+	}
+
+	previousPath, movedPath, err := service.moveProjectHierarchyFolderOnDisk("primary-project", researchPath, operationsPath)
+	if err != nil {
+		t.Fatalf("moveProjectHierarchyFolderOnDisk: %v", err)
+	}
+	if previousPath != researchPath {
+		t.Fatalf("expected previous path %s, got %s", researchPath, previousPath)
+	}
+	if movedPath != "projects/project-primary-project/children/folder-operations/children/folder-research" {
+		t.Fatalf("unexpected moved path: %s", movedPath)
+	}
+
+	if _, err := os.Stat(filepath.Join(rootPath, filepath.FromSlash(researchPath))); !os.IsNotExist(err) {
+		t.Fatalf("expected previous folder path to be gone, got err=%v", err)
+	}
+
+	movedFolderPath := filepath.Join(rootPath, filepath.FromSlash(movedPath))
+	if _, err := os.Stat(filepath.Join(movedFolderPath, "children", filepath.Base(nestedPath))); err != nil {
+		t.Fatalf("expected nested child folder to move with moved parent: %v", err)
+	}
+
+	folderPayload := readJSONFileForTest[map[string]any](t, filepath.Join(movedFolderPath, "folder.json"))
+	if strings.TrimSpace(asStringForTest(folderPayload["id"])) == "" {
+		t.Fatalf("expected moved folder to preserve stable id, got %#v", folderPayload["id"])
+	}
+	if folderPayload["name"] != "Research" {
+		t.Fatalf("expected moved folder name Research, got %#v", folderPayload["name"])
+	}
+	if folderPayload["slug"] != "research" {
+		t.Fatalf("expected moved folder slug research, got %#v", folderPayload["slug"])
+	}
+	if folderPayload["type"] != "folder" {
+		t.Fatalf("expected moved folder type folder, got %#v", folderPayload["type"])
+	}
+}
+
+func TestMoveProjectTreeFolderOnDiskMovesFolderToNewParent(t *testing.T) {
+	rootPath := filepath.Join(t.TempDir(), "POSIX")
+	service := NewService(nil, rootPath)
+
+	err := service.ensureBootstrapPOSIXSkeleton(
+		InstallationRecord{ID: "installation-1", Name: "MangoPig", Mode: "personal", Access: "local", Protocol: "http", Host: "localhost", IsBootstrapped: true},
+		AdminSummary{ID: "admin-1", Email: "ronald@example.com", DisplayName: "Ronald"},
+		namedRecord{ID: "org-1", Name: "Primary Organization", Slug: "primary-organization"},
+		namedRecord{ID: "dept-1", Name: "Primary Department", Slug: "primary-department"},
+		namedRecord{ID: "team-1", Name: "Primary Team", Slug: "primary-team"},
+		namedRecord{ID: "project-1", Name: "Primary Project", Slug: "primary-project"},
+	)
+	if err != nil {
+		t.Fatalf("ensure bootstrap POSIX skeleton: %v", err)
+	}
+
+	docsPath, _, err := service.createProjectTreeFolderOnDisk("primary-project", "", "Docs")
+	if err != nil {
+		t.Fatalf("create docs folder: %v", err)
+	}
+	archivePath, _, err := service.createProjectTreeFolderOnDisk("primary-project", "", "Archive")
+	if err != nil {
+		t.Fatalf("create archive folder: %v", err)
+	}
+
+	previousPath, movedPath, err := service.moveProjectTreeFolderOnDisk("primary-project", docsPath, archivePath)
+	if err != nil {
+		t.Fatalf("moveProjectTreeFolderOnDisk: %v", err)
+	}
+	if previousPath != docsPath {
+		t.Fatalf("expected previous path %s, got %s", docsPath, previousPath)
+	}
+	if movedPath != "projects/project-primary-project/tree/folder-archive/children/folder-docs" {
+		t.Fatalf("unexpected moved path: %s", movedPath)
+	}
+
+	folderPayload := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, filepath.FromSlash(movedPath), "folder.json"))
+	if folderPayload["name"] != "Docs" {
+		t.Fatalf("expected moved folder name Docs, got %#v", folderPayload["name"])
+	}
+	if folderPayload["slug"] != "docs" {
+		t.Fatalf("expected moved folder slug docs, got %#v", folderPayload["slug"])
+	}
+}
+
+func TestMoveProjectHierarchyFolderOnDiskRejectsDescendantTarget(t *testing.T) {
+	rootPath := filepath.Join(t.TempDir(), "POSIX")
+	service := NewService(nil, rootPath)
+
+	err := service.ensureBootstrapPOSIXSkeleton(
+		InstallationRecord{ID: "installation-1", Name: "MangoPig", Mode: "personal", Access: "local", Protocol: "http", Host: "localhost", IsBootstrapped: true},
+		AdminSummary{ID: "admin-1", Email: "ronald@example.com", DisplayName: "Ronald"},
+		namedRecord{ID: "org-1", Name: "Primary Organization", Slug: "primary-organization"},
+		namedRecord{ID: "dept-1", Name: "Primary Department", Slug: "primary-department"},
+		namedRecord{ID: "team-1", Name: "Primary Team", Slug: "primary-team"},
+		namedRecord{ID: "project-1", Name: "Primary Project", Slug: "primary-project"},
+	)
+	if err != nil {
+		t.Fatalf("ensure bootstrap POSIX skeleton: %v", err)
+	}
+
+	parentPath, _, err := service.createProjectHierarchyFolderOnDisk("primary-project", "", "Parent")
+	if err != nil {
+		t.Fatalf("create parent folder: %v", err)
+	}
+	childPath, _, err := service.createProjectHierarchyFolderOnDisk("primary-project", parentPath, "Child")
+	if err != nil {
+		t.Fatalf("create child folder: %v", err)
+	}
+
+	_, _, err = service.moveProjectHierarchyFolderOnDisk("primary-project", parentPath, childPath)
+	if !errors.Is(err, ErrInvalidProjectFolderMove) {
+		t.Fatalf("expected ErrInvalidProjectFolderMove, got %v", err)
+	}
+}
+
+func TestBuildProjectHierarchyFolderTreeBuildsNestedStructure(t *testing.T) {
+	rows := []projectHierarchyFolderRow{
+		{ID: "folder-design-id", Path: "projects/project-primary-project/children/folder-design", ParentPath: projectHierarchyRootPath("primary-project"), Label: "Design"},
+		{ID: "folder-research-id", Path: "projects/project-primary-project/children/folder-design/children/folder-research", ParentPath: "projects/project-primary-project/children/folder-design/children", Label: "Research"},
+		{ID: "folder-ops-id", Path: "projects/project-primary-project/children/folder-ops", ParentPath: projectHierarchyRootPath("primary-project"), Label: "Ops"},
+	}
+
+	folders := buildProjectHierarchyFolderTree(rows, projectHierarchyRootPath("primary-project"))
+	if len(folders) != 2 {
+		t.Fatalf("expected 2 top-level folders, got %d", len(folders))
+	}
+	if folders[0].Label != "Design" || folders[1].Label != "Ops" {
+		t.Fatalf("unexpected top-level folder labels: %#v", folders)
+	}
+	if len(folders[0].Children) != 1 || folders[0].Children[0].Label != "Research" {
+		t.Fatalf("unexpected nested folder structure: %#v", folders[0].Children)
+	}
+	if folders[0].ID != "folder-design-id" || folders[0].Path != "projects/project-primary-project/children/folder-design" {
+		t.Fatalf("expected design folder to retain stable id/path, got %#v", folders[0])
+	}
+	if folders[0].Children[0].ID != "folder-research-id" || folders[1].ID != "folder-ops-id" {
+		t.Fatalf("expected nested/top-level folder ids to be preserved, got %#v / %#v", folders[0].Children[0], folders[1])
+	}
+}
+
+func TestApplyProjectHierarchyFolderOrderingOrdersRootAndChildrenByStableID(t *testing.T) {
+	folders := []ProjectHierarchyFolderRecord{
+		{
+			ID:    "folder-design-id",
+			Path:  "projects/project-primary-project/children/folder-design",
+			Label: "Design",
+			Children: []ProjectHierarchyFolderRecord{
+				{ID: "folder-research-id", Path: "projects/project-primary-project/children/folder-design/children/folder-research", Label: "Research"},
+				{ID: "folder-assets-id", Path: "projects/project-primary-project/children/folder-design/children/folder-assets", Label: "Assets"},
+			},
+		},
+		{ID: "folder-ops-id", Path: "projects/project-primary-project/children/folder-ops", Label: "Ops"},
+		{ID: "folder-qa-id", Path: "projects/project-primary-project/children/folder-qa", Label: "QA"},
+	}
+
+	ordered := applyProjectHierarchyFolderOrdering(folders, map[string][]string{
+		projectFolderOrderRootKey: {"folder-qa-id", "folder-design-id"},
+		"folder-design-id":        {"folder-assets-id", "folder-research-id"},
+	})
+
+	if len(ordered) != 3 {
+		t.Fatalf("expected 3 ordered root folders, got %d", len(ordered))
+	}
+	if ordered[0].ID != "folder-qa-id" || ordered[1].ID != "folder-design-id" || ordered[2].ID != "folder-ops-id" {
+		t.Fatalf("unexpected ordered root ids: %#v", ordered)
+	}
+	if len(ordered[1].Children) != 2 {
+		t.Fatalf("expected design folder children to be preserved, got %#v", ordered[1].Children)
+	}
+	if ordered[1].Children[0].ID != "folder-assets-id" || ordered[1].Children[1].ID != "folder-research-id" {
+		t.Fatalf("unexpected ordered child ids: %#v", ordered[1].Children)
+	}
+}
+
+func TestInsertFolderOrderReordersWithinSameParent(t *testing.T) {
+	folderOrder := map[string][]string{
+		projectFolderOrderRootKey: {"folder-a", "folder-b", "folder-c"},
+	}
+
+	insertFolderOrder(folderOrder, "", "folder-c", 0)
+
+	got := folderOrder[projectFolderOrderRootKey]
+	if len(got) != 3 || got[0] != "folder-c" || got[1] != "folder-a" || got[2] != "folder-b" {
+		t.Fatalf("unexpected reordered root children: %#v", got)
+	}
+}
+
+func asStringForTest(value any) string {
+	text, _ := value.(string)
+	return text
+}
+
+func readJSONFileForTest[T any](t *testing.T, path string) T {
+	t.Helper()
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read %s: %v", path, err)
+	}
+
+	var payload T
+	if err := json.Unmarshal(data, &payload); err != nil {
+		t.Fatalf("unmarshal %s: %v", path, err)
+	}
+
+	return payload
+}

Backend/internal/config/config.go

@@ -15,9 +15,9 @@ type Config struct {
 	LogLevel        string
 	WebPort         string
 	APIPort         string
-	WorkerPort      string
 	PostgresURL     string
 	ValkeyURL       string
+	POSIXRoot       string
 	ShutdownTimeout time.Duration
 }
 
@@ -28,9 +28,9 @@ func Load() *Config {
 		LogLevel:        getEnv("LOG_LEVEL", "debug"),
 		WebPort:         getEnv("BACKEND_WEB_PORT", "8080"),
 		APIPort:         getEnv("BACKEND_API_PORT", "8081"),
-		WorkerPort:      getEnv("BACKEND_WORKER_PORT", "8082"),
 		PostgresURL:     getEnv("DATABASE_URL", "postgres://moku:moku_dev_password@localhost:5432/moku?sslmode=disable"),
 		ValkeyURL:       getEnv("VALKEY_URL", "redis://localhost:6379/0"),
+		POSIXRoot:       getEnv("POSIX_ROOT", "../POSIX"),
 		ShutdownTimeout: getDurationEnv("BACKEND_SHUTDOWN_TIMEOUT", 10*time.Second),
 	}
 }
@@ -43,8 +43,6 @@ func (c *Config) Address(serviceName string) string {
 		port = c.WebPort
 	case "api":
 		port = c.APIPort
-	case "worker":
-		port = c.WorkerPort
 	default:
 		port = c.WebPort
 	}

Backend/internal/httpx/api_bootstrap_routes.go

@@ -0,0 +1,396 @@
+// Path: Backend/internal/httpx/api_bootstrap_routes.go
+
+package httpx
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+
+	bootstrapservice "moku-backend/internal/bootstrap"
+)
+
+type bootstrapInstanceStepRequest struct {
+	Protocol string `json:"protocol"`
+	Access   string `json:"access"`
+	Host     string `json:"host"`
+}
+
+type bootstrapModeStepRequest struct {
+	Mode string `json:"mode"`
+	Name string `json:"name"`
+}
+
+type bootstrapAdminStepRequest struct {
+	DisplayName string `json:"displayName"`
+	Email       string `json:"email"`
+	Password    string `json:"password"`
+}
+
+type bootstrapStructureStepRequest struct {
+	OrganizationName string `json:"organizationName"`
+	DepartmentName   string `json:"departmentName"`
+	TeamName         string `json:"teamName"`
+	ProjectName      string `json:"projectName"`
+}
+
+func (routes apiRoutes) handleBootstrapOverview(w http.ResponseWriter, _ *http.Request) {
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": map[string]any{
+			"resource": "bootstrap",
+			"status":   "persisted",
+			"steps": []map[string]string{
+				{
+					"id":     "instance",
+					"method": http.MethodPost,
+					"path":   "/v1/bootstrap/steps/instance",
+				},
+				{
+					"id":     "mode",
+					"method": http.MethodPost,
+					"path":   "/v1/bootstrap/steps/mode",
+				},
+				{
+					"id":     "admin",
+					"method": http.MethodPost,
+					"path":   "/v1/bootstrap/steps/admin",
+				},
+				{
+					"id":     "structure",
+					"method": http.MethodPost,
+					"path":   "/v1/bootstrap/steps/structure",
+				},
+				{
+					"id":     "installation",
+					"method": http.MethodGet,
+					"path":   "/v1/bootstrap/installation",
+				},
+				{
+					"id":     "admin-state",
+					"method": http.MethodGet,
+					"path":   "/v1/bootstrap/admin",
+				},
+				{
+					"id":     "structure-state",
+					"method": http.MethodGet,
+					"path":   "/v1/bootstrap/structure",
+				},
+				{
+					"id":     "bootstrap-state",
+					"method": http.MethodGet,
+					"path":   "/v1/bootstrap/state",
+				},
+				{
+					"id":     "app-shell",
+					"method": http.MethodGet,
+					"path":   "/v1/app-shell",
+				},
+			},
+		},
+	})
+}
+
+func (routes apiRoutes) handleBootstrapInstallation(w http.ResponseWriter, r *http.Request) {
+	record, err := routes.bootstrapService().GetInstallation(r.Context())
+	if err != nil {
+		routes.writeBootstrapPersistenceError(w, r, err)
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": record,
+		"meta": map[string]any{
+			"resource": "bootstrap-installation",
+		},
+	})
+}
+
+func (routes apiRoutes) handleBootstrapAdmin(w http.ResponseWriter, r *http.Request) {
+	record, err := routes.bootstrapService().GetAdmin(r.Context())
+	if err != nil {
+		routes.writeBootstrapPersistenceError(w, r, err)
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": record,
+		"meta": map[string]any{
+			"resource": "bootstrap-admin",
+		},
+	})
+}
+
+func (routes apiRoutes) handleBootstrapStructure(w http.ResponseWriter, r *http.Request) {
+	record, err := routes.bootstrapService().GetStructure(r.Context())
+	if err != nil {
+		routes.writeBootstrapPersistenceError(w, r, err)
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": record,
+		"meta": map[string]any{
+			"resource": "bootstrap-structure",
+		},
+	})
+}
+
+func (routes apiRoutes) handleBootstrapState(w http.ResponseWriter, r *http.Request) {
+	record, err := routes.bootstrapService().GetState(r.Context())
+	if err != nil {
+		routes.writeBootstrapPersistenceError(w, r, err)
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": record,
+		"meta": map[string]any{
+			"resource": "bootstrap-state",
+		},
+	})
+}
+
+func (routes apiRoutes) handleAppShellState(w http.ResponseWriter, r *http.Request) {
+	record, err := routes.bootstrapService().GetAppShellState(r.Context())
+	if err != nil {
+		routes.writeBootstrapPersistenceError(w, r, err)
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": record,
+		"meta": map[string]any{
+			"resource": "app-shell",
+		},
+	})
+}
+
+func (routes apiRoutes) handleDevelopmentBootstrapReset(w http.ResponseWriter, r *http.Request) {
+	if !routes.cfg.Config.IsDevelopment() {
+		WriteError(w, http.StatusNotFound, RequestIDFromContext(r.Context()), "not_found", "The requested endpoint does not exist.")
+		return
+	}
+
+	if err := routes.bootstrapService().ResetDevelopmentState(r.Context()); err != nil {
+		routes.writeBootstrapPersistenceError(w, r, err)
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": map[string]any{
+			"reset": true,
+		},
+		"meta": map[string]any{
+			"resource":        "development-bootstrap-reset",
+			"developmentOnly": true,
+		},
+	})
+}
+
+func (routes apiRoutes) handleBootstrapInstanceStep(w http.ResponseWriter, r *http.Request) {
+	payload, ok := decodeBootstrapRequest[bootstrapInstanceStepRequest](w, r)
+	if !ok {
+		return
+	}
+	payload.Protocol = strings.ToLower(strings.TrimSpace(payload.Protocol))
+	payload.Access = strings.ToLower(strings.TrimSpace(payload.Access))
+	payload.Host = strings.TrimSpace(payload.Host)
+
+	if payload.Protocol != "http" && payload.Protocol != "https" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Protocol must be either 'http' or 'https'.")
+		return
+	}
+
+	if payload.Access != "local" && payload.Access != "remote" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Access must be either 'local' or 'remote'.")
+		return
+	}
+
+	if payload.Host == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Host is required.")
+		return
+	}
+
+	record, err := routes.bootstrapService().SaveInstance(r.Context(), bootstrapservice.SaveInstanceInput{
+		Protocol: payload.Protocol,
+		Access:   payload.Access,
+		Host:     payload.Host,
+	})
+	if err != nil {
+		routes.writeBootstrapPersistenceError(w, r, err)
+		return
+	}
+
+	routes.writeBootstrapStepResponse(w, http.StatusOK, "instance", map[string]any{
+		"request":      payload,
+		"installation": record,
+	})
+}
+
+func (routes apiRoutes) handleBootstrapModeStep(w http.ResponseWriter, r *http.Request) {
+	payload, ok := decodeBootstrapRequest[bootstrapModeStepRequest](w, r)
+	if !ok {
+		return
+	}
+	payload.Mode = strings.ToLower(strings.TrimSpace(payload.Mode))
+	payload.Name = strings.TrimSpace(payload.Name)
+
+	if payload.Mode != "personal" && payload.Mode != "organizational" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Mode must be either 'personal' or 'organizational'.")
+		return
+	}
+
+	if payload.Name == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Name is required.")
+		return
+	}
+
+	record, err := routes.bootstrapService().SaveMode(r.Context(), bootstrapservice.SaveModeInput{Mode: payload.Mode, Name: payload.Name})
+	if err != nil {
+		routes.writeBootstrapPersistenceError(w, r, err)
+		return
+	}
+
+	routes.writeBootstrapStepResponse(w, http.StatusOK, "mode", map[string]any{
+		"request":      payload,
+		"installation": record,
+	})
+}
+
+func (routes apiRoutes) handleBootstrapAdminStep(w http.ResponseWriter, r *http.Request) {
+	payload, ok := decodeBootstrapRequest[bootstrapAdminStepRequest](w, r)
+	if !ok {
+		return
+	}
+	payload.DisplayName = strings.TrimSpace(payload.DisplayName)
+	payload.Email = strings.ToLower(strings.TrimSpace(payload.Email))
+
+	if payload.DisplayName == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Display name is required.")
+		return
+	}
+
+	if payload.Email == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Email is required.")
+		return
+	}
+
+	if strings.TrimSpace(payload.Password) == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Password is required.")
+		return
+	}
+
+	record, err := routes.bootstrapService().SaveAdmin(r.Context(), bootstrapservice.SaveAdminInput{
+		DisplayName: payload.DisplayName,
+		Email:       payload.Email,
+		Password:    payload.Password,
+	})
+	if err != nil {
+		routes.writeBootstrapPersistenceError(w, r, err)
+		return
+	}
+
+	routes.writeBootstrapStepResponse(w, http.StatusOK, "admin", map[string]any{
+		"request": payload,
+		"admin":   record,
+	})
+}
+
+func (routes apiRoutes) handleBootstrapStructureStep(w http.ResponseWriter, r *http.Request) {
+	payload, ok := decodeBootstrapRequest[bootstrapStructureStepRequest](w, r)
+	if !ok {
+		return
+	}
+	payload.OrganizationName = strings.TrimSpace(payload.OrganizationName)
+	payload.DepartmentName = strings.TrimSpace(payload.DepartmentName)
+	payload.TeamName = strings.TrimSpace(payload.TeamName)
+	payload.ProjectName = strings.TrimSpace(payload.ProjectName)
+
+	if payload.DepartmentName == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Department name is required.")
+		return
+	}
+
+	if payload.TeamName == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Team name is required.")
+		return
+	}
+
+	if payload.ProjectName == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Project name is required.")
+		return
+	}
+
+	record, err := routes.bootstrapService().SaveStructure(r.Context(), bootstrapservice.SaveStructureInput{
+		OrganizationName: payload.OrganizationName,
+		DepartmentName:   payload.DepartmentName,
+		TeamName:         payload.TeamName,
+		ProjectName:      payload.ProjectName,
+	})
+	if err != nil {
+		routes.writeBootstrapPersistenceError(w, r, err)
+		return
+	}
+
+	routes.writeBootstrapStepResponse(w, http.StatusOK, "structure", map[string]any{
+		"request":   payload,
+		"structure": record,
+	})
+}
+
+func (routes apiRoutes) bootstrapService() *bootstrapservice.Service {
+	return bootstrapservice.NewService(routes.cfg.Database, routes.cfg.Config.POSIXRoot)
+}
+
+func (routes apiRoutes) writeBootstrapStepResponse(w http.ResponseWriter, status int, step string, payload any) {
+	WriteJSON(w, status, map[string]any{
+		"data": map[string]any{
+			"step":   step,
+			"result": payload,
+		},
+		"meta": map[string]any{
+			"resource":  "bootstrap-step",
+			"persisted": true,
+		},
+	})
+}
+
+func (routes apiRoutes) writeBootstrapPersistenceError(w http.ResponseWriter, r *http.Request, err error) {
+	switch {
+	case errors.Is(err, bootstrapservice.ErrInstallationNotConfigured), errors.Is(err, bootstrapservice.ErrAdminNotConfigured):
+		WriteError(w, http.StatusConflict, RequestIDFromContext(r.Context()), "bootstrap_prerequisite_missing", err.Error())
+	default:
+		routes.cfg.Logger.Error("persist bootstrap step", "error", err, "path", r.URL.Path)
+		message := "Failed to persist bootstrap data."
+		if routes.cfg.Config.IsDevelopment() {
+			message = message + " " + err.Error()
+		}
+		WriteError(w, http.StatusInternalServerError, RequestIDFromContext(r.Context()), "bootstrap_persist_failed", message)
+	}
+}
+
+func decodeBootstrapRequest[T any](w http.ResponseWriter, r *http.Request) (T, bool) {
+	var payload T
+
+	decoder := json.NewDecoder(r.Body)
+	decoder.DisallowUnknownFields()
+
+	if err := decoder.Decode(&payload); err != nil {
+		if errors.Is(err, io.EOF) {
+			WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body is required and must be valid JSON for this bootstrap step.")
+			return payload, false
+		}
+
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body must be valid JSON for this bootstrap step.")
+		return payload, false
+	}
+
+	if err := decoder.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body must contain a single JSON object.")
+		return payload, false
+	}
+
+	return payload, true
+}

Backend/internal/httpx/api_project_routes.go

@@ -0,0 +1,485 @@
+package httpx
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+
+	bootstrapservice "moku-backend/internal/bootstrap"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type createProjectFolderRequest struct {
+	Name           string `json:"name"`
+	ParentFolderID string `json:"parentFolderId"`
+}
+
+type renameProjectFolderRequest struct {
+	FolderID string `json:"folderId"`
+	Name     string `json:"name"`
+}
+
+type deleteProjectFolderRequest struct {
+	FolderID string `json:"folderId"`
+}
+
+type moveProjectFolderRequest struct {
+	FolderID       string `json:"folderId"`
+	FolderNodeID   string `json:"folderNodeId"`
+	ParentFolderID string `json:"parentFolderId"`
+	ParentNodeID   string `json:"parentNodeId"`
+	TargetIndex    int    `json:"targetIndex"`
+}
+
+func (routes apiRoutes) handleProjectFolders(w http.ResponseWriter, r *http.Request) {
+	projectID := strings.TrimSpace(chi.URLParam(r, "projectId"))
+	if projectID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Project ID is required.")
+		return
+	}
+
+	folders, err := routes.bootstrapService().GetProjectHierarchyFolders(r.Context(), projectID)
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "load")
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": map[string]any{
+			"projectId": projectID,
+			"folders":   folders,
+		},
+		"meta": map[string]any{
+			"resource": "project-folders",
+		},
+	})
+}
+
+func (routes apiRoutes) handleCreateProjectFolder(w http.ResponseWriter, r *http.Request) {
+	projectID := strings.TrimSpace(chi.URLParam(r, "projectId"))
+	if projectID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Project ID is required.")
+		return
+	}
+
+	payload, ok := decodeProjectFolderRequest(w, r)
+	if !ok {
+		return
+	}
+
+	payload.Name = strings.TrimSpace(payload.Name)
+	payload.ParentFolderID = strings.TrimSpace(payload.ParentFolderID)
+	if payload.Name == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder name is required.")
+		return
+	}
+
+	result, err := routes.bootstrapService().CreateProjectFolder(r.Context(), bootstrapservice.CreateProjectFolderInput{
+		ProjectID:      projectID,
+		ParentFolderID: payload.ParentFolderID,
+		Name:           payload.Name,
+	})
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "persist")
+		return
+	}
+
+	WriteJSON(w, http.StatusCreated, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-folder-create",
+			"persisted": true,
+		},
+	})
+}
+
+func (routes apiRoutes) handleDeleteProjectFolder(w http.ResponseWriter, r *http.Request) {
+	projectID := strings.TrimSpace(chi.URLParam(r, "projectId"))
+	if projectID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Project ID is required.")
+		return
+	}
+
+	payload := decodeDeleteProjectFolderRequest(r)
+	if strings.TrimSpace(payload.FolderID) == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
+		return
+	}
+
+	result, err := routes.bootstrapService().DeleteProjectFolder(r.Context(), bootstrapservice.DeleteProjectFolderInput{
+		ProjectID: projectID,
+		FolderID:  payload.FolderID,
+	})
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "delete")
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-folder-delete",
+			"persisted": true,
+		},
+	})
+}
+
+func (routes apiRoutes) handleRenameProjectFolder(w http.ResponseWriter, r *http.Request) {
+	projectID := strings.TrimSpace(chi.URLParam(r, "projectId"))
+	if projectID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Project ID is required.")
+		return
+	}
+
+	payload, ok := decodeRenameProjectFolderRequest(w, r)
+	if !ok {
+		return
+	}
+
+	payload.FolderID = strings.TrimSpace(payload.FolderID)
+	payload.Name = strings.TrimSpace(payload.Name)
+	if payload.FolderID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
+		return
+	}
+	if payload.Name == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder name is required.")
+		return
+	}
+
+	result, err := routes.bootstrapService().RenameProjectFolder(r.Context(), bootstrapservice.RenameProjectFolderInput{
+		ProjectID: projectID,
+		FolderID:  payload.FolderID,
+		Name:      payload.Name,
+	})
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "rename")
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-folder-rename",
+			"persisted": true,
+		},
+	})
+}
+
+func (routes apiRoutes) handleMoveProjectFolder(w http.ResponseWriter, r *http.Request) {
+	projectID := strings.TrimSpace(chi.URLParam(r, "projectId"))
+	if projectID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Project ID is required.")
+		return
+	}
+
+	payload, ok := decodeMoveProjectFolderRequest(w, r)
+	if !ok {
+		return
+	}
+
+	payload.FolderID = strings.TrimSpace(payload.FolderID)
+	payload.FolderNodeID = strings.TrimSpace(payload.FolderNodeID)
+	payload.ParentFolderID = strings.TrimSpace(payload.ParentFolderID)
+	payload.ParentNodeID = strings.TrimSpace(payload.ParentNodeID)
+	if payload.FolderID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
+		return
+	}
+
+	result, err := routes.bootstrapService().MoveProjectFolder(r.Context(), bootstrapservice.MoveProjectFolderInput{
+		ProjectID:      projectID,
+		FolderID:       payload.FolderID,
+		FolderNodeID:   payload.FolderNodeID,
+		ParentFolderID: payload.ParentFolderID,
+		ParentNodeID:   payload.ParentNodeID,
+		TargetIndex:    payload.TargetIndex,
+	})
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "move")
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-folder-move",
+			"persisted": true,
+		},
+	})
+}
+
+func (routes apiRoutes) handleProjectTreeFolders(w http.ResponseWriter, r *http.Request) {
+	projectID := strings.TrimSpace(chi.URLParam(r, "projectId"))
+	if projectID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Project ID is required.")
+		return
+	}
+
+	folders, err := routes.bootstrapService().GetProjectTreeFolders(r.Context(), projectID)
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "load")
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": map[string]any{
+			"projectId": projectID,
+			"folders":   folders,
+		},
+		"meta": map[string]any{
+			"resource": "project-tree-folders",
+		},
+	})
+}
+
+func (routes apiRoutes) handleCreateProjectTreeFolder(w http.ResponseWriter, r *http.Request) {
+	projectID := strings.TrimSpace(chi.URLParam(r, "projectId"))
+	if projectID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Project ID is required.")
+		return
+	}
+
+	payload, ok := decodeProjectFolderRequest(w, r)
+	if !ok {
+		return
+	}
+
+	payload.Name = strings.TrimSpace(payload.Name)
+	payload.ParentFolderID = strings.TrimSpace(payload.ParentFolderID)
+	if payload.Name == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder name is required.")
+		return
+	}
+
+	result, err := routes.bootstrapService().CreateProjectTreeFolder(r.Context(), bootstrapservice.CreateProjectFolderInput{
+		ProjectID:      projectID,
+		ParentFolderID: payload.ParentFolderID,
+		Name:           payload.Name,
+	})
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "persist")
+		return
+	}
+
+	WriteJSON(w, http.StatusCreated, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-tree-folder-create",
+			"persisted": true,
+		},
+	})
+}
+
+func (routes apiRoutes) handleDeleteProjectTreeFolder(w http.ResponseWriter, r *http.Request) {
+	projectID := strings.TrimSpace(chi.URLParam(r, "projectId"))
+	if projectID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Project ID is required.")
+		return
+	}
+
+	payload := decodeDeleteProjectFolderRequest(r)
+	if strings.TrimSpace(payload.FolderID) == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
+		return
+	}
+
+	result, err := routes.bootstrapService().DeleteProjectTreeFolder(r.Context(), bootstrapservice.DeleteProjectFolderInput{
+		ProjectID: projectID,
+		FolderID:  payload.FolderID,
+	})
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "delete")
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-tree-folder-delete",
+			"persisted": true,
+		},
+	})
+}
+
+func (routes apiRoutes) handleRenameProjectTreeFolder(w http.ResponseWriter, r *http.Request) {
+	projectID := strings.TrimSpace(chi.URLParam(r, "projectId"))
+	if projectID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Project ID is required.")
+		return
+	}
+
+	payload, ok := decodeRenameProjectFolderRequest(w, r)
+	if !ok {
+		return
+	}
+
+	payload.FolderID = strings.TrimSpace(payload.FolderID)
+	payload.Name = strings.TrimSpace(payload.Name)
+	if payload.FolderID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
+		return
+	}
+	if payload.Name == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder name is required.")
+		return
+	}
+
+	result, err := routes.bootstrapService().RenameProjectTreeFolder(r.Context(), bootstrapservice.RenameProjectFolderInput{
+		ProjectID: projectID,
+		FolderID:  payload.FolderID,
+		Name:      payload.Name,
+	})
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "rename")
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-tree-folder-rename",
+			"persisted": true,
+		},
+	})
+}
+
+func (routes apiRoutes) handleMoveProjectTreeFolder(w http.ResponseWriter, r *http.Request) {
+	projectID := strings.TrimSpace(chi.URLParam(r, "projectId"))
+	if projectID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Project ID is required.")
+		return
+	}
+
+	payload, ok := decodeMoveProjectFolderRequest(w, r)
+	if !ok {
+		return
+	}
+
+	payload.FolderID = strings.TrimSpace(payload.FolderID)
+	payload.FolderNodeID = strings.TrimSpace(payload.FolderNodeID)
+	payload.ParentFolderID = strings.TrimSpace(payload.ParentFolderID)
+	payload.ParentNodeID = strings.TrimSpace(payload.ParentNodeID)
+	if payload.FolderID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
+		return
+	}
+
+	result, err := routes.bootstrapService().MoveProjectTreeFolder(r.Context(), bootstrapservice.MoveProjectFolderInput{
+		ProjectID:      projectID,
+		FolderID:       payload.FolderID,
+		FolderNodeID:   payload.FolderNodeID,
+		ParentFolderID: payload.ParentFolderID,
+		ParentNodeID:   payload.ParentNodeID,
+		TargetIndex:    payload.TargetIndex,
+	})
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "move")
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-tree-folder-move",
+			"persisted": true,
+		},
+	})
+}
+
+func (routes apiRoutes) writeProjectFolderError(w http.ResponseWriter, r *http.Request, err error, operation string) {
+	switch {
+	case errors.Is(err, bootstrapservice.ErrProjectNotFound), errors.Is(err, bootstrapservice.ErrProjectFolderNotFound):
+		WriteError(w, http.StatusNotFound, RequestIDFromContext(r.Context()), "not_found", err.Error())
+	case errors.Is(err, bootstrapservice.ErrInvalidProjectFolderMove):
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", err.Error())
+	default:
+		routes.cfg.Logger.Error(operation+" project folder", "error", err, "path", r.URL.Path)
+		message := "Failed to " + operation + " project folder."
+		if routes.cfg.Config.IsDevelopment() {
+			message = message + " " + err.Error()
+		}
+		WriteError(w, http.StatusInternalServerError, RequestIDFromContext(r.Context()), "project_folder_"+operation+"_failed", message)
+	}
+}
+
+func decodeMoveProjectFolderRequest(w http.ResponseWriter, r *http.Request) (moveProjectFolderRequest, bool) {
+	var payload moveProjectFolderRequest
+
+	decoder := json.NewDecoder(r.Body)
+	decoder.DisallowUnknownFields()
+
+	if err := decoder.Decode(&payload); err != nil {
+		if errors.Is(err, io.EOF) {
+			WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body is required and must be valid JSON.")
+			return payload, false
+		}
+
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body must be valid JSON.")
+		return payload, false
+	}
+
+	if err := decoder.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body must contain a single JSON object.")
+		return payload, false
+	}
+
+	return payload, true
+}
+
+func decodeDeleteProjectFolderRequest(r *http.Request) deleteProjectFolderRequest {
+	return deleteProjectFolderRequest{
+		FolderID: strings.TrimSpace(r.URL.Query().Get("folderId")),
+	}
+}
+
+func decodeRenameProjectFolderRequest(w http.ResponseWriter, r *http.Request) (renameProjectFolderRequest, bool) {
+	var payload renameProjectFolderRequest
+
+	decoder := json.NewDecoder(r.Body)
+	decoder.DisallowUnknownFields()
+
+	if err := decoder.Decode(&payload); err != nil {
+		if errors.Is(err, io.EOF) {
+			WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body is required and must be valid JSON.")
+			return payload, false
+		}
+
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body must be valid JSON.")
+		return payload, false
+	}
+
+	if err := decoder.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body must contain a single JSON object.")
+		return payload, false
+	}
+
+	return payload, true
+}
+
+func decodeProjectFolderRequest(w http.ResponseWriter, r *http.Request) (createProjectFolderRequest, bool) {
+	var payload createProjectFolderRequest
+
+	decoder := json.NewDecoder(r.Body)
+	decoder.DisallowUnknownFields()
+
+	if err := decoder.Decode(&payload); err != nil {
+		if errors.Is(err, io.EOF) {
+			WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body is required and must be valid JSON.")
+			return payload, false
+		}
+
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body must be valid JSON.")
+		return payload, false
+	}
+
+	if err := decoder.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body must contain a single JSON object.")
+		return payload, false
+	}
+
+	return payload, true
+}

Backend/internal/httpx/api_routes.go

@@ -19,8 +19,36 @@ func newAPIRoutes(cfg RouterConfig) routeRegistrar {
 func (routes apiRoutes) Register(router chi.Router) {
 	router.Route("/v1", func(apiRouter chi.Router) {
 		apiRouter.Get("/", routes.handleIndex)
+		apiRouter.Get("/bootstrap", routes.handleBootstrapOverview)
+		apiRouter.Get("/bootstrap/installation", routes.handleBootstrapInstallation)
+		apiRouter.Get("/bootstrap/admin", routes.handleBootstrapAdmin)
+		apiRouter.Get("/bootstrap/structure", routes.handleBootstrapStructure)
+		apiRouter.Get("/bootstrap/state", routes.handleBootstrapState)
+		apiRouter.Route("/bootstrap/steps", func(bootstrapRouter chi.Router) {
+			bootstrapRouter.Post("/instance", routes.handleBootstrapInstanceStep)
+			bootstrapRouter.Post("/mode", routes.handleBootstrapModeStep)
+			bootstrapRouter.Post("/admin", routes.handleBootstrapAdminStep)
+			bootstrapRouter.Post("/structure", routes.handleBootstrapStructureStep)
+		})
+		apiRouter.Get("/app-shell", routes.handleAppShellState)
 		apiRouter.Get("/organizations", routes.handleOrganizations)
 		apiRouter.Get("/workspaces", routes.handleWorkspaces)
+		apiRouter.Route("/projects/{projectId}", func(projectRouter chi.Router) {
+			projectRouter.Get("/folders", routes.handleProjectFolders)
+			projectRouter.Post("/folders", routes.handleCreateProjectFolder)
+			projectRouter.Patch("/folders", routes.handleRenameProjectFolder)
+			projectRouter.Patch("/folders/move", routes.handleMoveProjectFolder)
+			projectRouter.Delete("/folders", routes.handleDeleteProjectFolder)
+			projectRouter.Get("/tree/folders", routes.handleProjectTreeFolders)
+			projectRouter.Post("/tree/folders", routes.handleCreateProjectTreeFolder)
+			projectRouter.Patch("/tree/folders", routes.handleRenameProjectTreeFolder)
+			projectRouter.Patch("/tree/folders/move", routes.handleMoveProjectTreeFolder)
+			projectRouter.Delete("/tree/folders", routes.handleDeleteProjectTreeFolder)
+		})
+
+		if routes.cfg.Config.IsDevelopment() {
+			apiRouter.Post("/dev/bootstrap/reset", routes.handleDevelopmentBootstrapReset)
+		}
 	})
 }
 

Backend/internal/posixproj/projector.go

@@ -0,0 +1,553 @@
+package posixproj
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"moku-backend/internal/database"
+)
+
+const rootProjectionPath = "/"
+
+type Projector struct {
+	db   *database.DB
+	root string
+}
+
+type RebuildSummary struct {
+	TotalNodes      int
+	DirectoryCount  int
+	FileCount       int
+}
+
+type NodeKind string
+
+const (
+	NodeKindDirectory NodeKind = "directory"
+	NodeKindFile      NodeKind = "file"
+)
+
+type Scope struct {
+	InstallationID  string
+	OrganizationID  string
+	OrganizationSlug string
+	DepartmentSlug  string
+	TeamSlug        string
+	ProjectSlug     string
+	PersonalSlug    string
+}
+
+type Node struct {
+	Path            string
+	ParentPath      *string
+	Name            string
+	Depth           int
+	NodeKind        NodeKind
+	LogicalType     string
+	FileRole        string
+	ResourceID      string
+	ResourceName    string
+	ResourceSlug    string
+	InstallationID  string
+	OrganizationID  string
+	OrganizationSlug string
+	DepartmentSlug  string
+	TeamSlug        string
+	ProjectSlug     string
+	PersonalSlug    string
+	ContentJSON     []byte
+	SizeBytes       int64
+	Checksum        string
+}
+
+func NewProjector(db *database.DB, root string) *Projector {
+	return &Projector{db: db, root: strings.TrimSpace(root)}
+}
+
+func (projector *Projector) Rebuild(ctx context.Context) error {
+	_, err := projector.RebuildWithSummary(ctx)
+	return err
+}
+
+func (projector *Projector) RebuildWithSummary(ctx context.Context) (RebuildSummary, error) {
+	if projector == nil || projector.db == nil || projector.db.Pool == nil {
+		return RebuildSummary{}, nil
+	}
+
+	nodes, err := ScanRoot(projector.root)
+	if err != nil {
+		return RebuildSummary{}, err
+	}
+
+	summary := summarizeNodes(nodes)
+
+	tx, err := projector.db.Pool.Begin(ctx)
+	if err != nil {
+		return RebuildSummary{}, err
+	}
+	defer func() {
+		_ = tx.Rollback(ctx)
+	}()
+
+	if _, err := tx.Exec(ctx, `DELETE FROM posix_nodes;`); err != nil {
+		return RebuildSummary{}, fmt.Errorf("clear posix_nodes: %w", err)
+	}
+
+	for _, node := range nodes {
+		if _, err := tx.Exec(ctx, `
+			INSERT INTO posix_nodes (
+				path,
+				parent_path,
+				name,
+				depth,
+				node_kind,
+				logical_type,
+				file_role,
+				resource_id,
+				resource_name,
+				resource_slug,
+				installation_id,
+				organization_id,
+				organization_slug,
+				department_slug,
+				team_slug,
+				project_slug,
+				personal_slug,
+				content_json,
+				size_bytes,
+				checksum
+			) VALUES (
+				$1, $2, $3, $4, $5::posix_node_kind, $6, $7, $8, $9, $10,
+				$11, $12, $13, $14, $15, $16, $17, $18::jsonb, $19, $20
+			);
+		`,
+			node.Path,
+			node.ParentPath,
+			node.Name,
+			node.Depth,
+			string(node.NodeKind),
+			node.LogicalType,
+			node.FileRole,
+			node.ResourceID,
+			node.ResourceName,
+			node.ResourceSlug,
+			node.InstallationID,
+			node.OrganizationID,
+			node.OrganizationSlug,
+			node.DepartmentSlug,
+			node.TeamSlug,
+			node.ProjectSlug,
+			node.PersonalSlug,
+				node.ContentJSON,
+				node.SizeBytes,
+				node.Checksum,
+		); err != nil {
+			return RebuildSummary{}, fmt.Errorf("insert posix node %s: %w", node.Path, err)
+		}
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return RebuildSummary{}, err
+	}
+
+	return summary, nil
+}
+
+func ScanRoot(root string) ([]Node, error) {
+	rootPath := strings.TrimSpace(root)
+	if rootPath == "" {
+		return nil, nil
+	}
+
+	info, err := os.Stat(rootPath)
+	if err != nil {
+		return nil, fmt.Errorf("stat POSIX root: %w", err)
+	}
+	if !info.IsDir() {
+		return nil, fmt.Errorf("POSIX root is not a directory: %s", rootPath)
+	}
+
+	rootScope, err := loadRootScope(rootPath)
+	if err != nil {
+		return nil, err
+	}
+
+	nodes := []Node{{
+		Path:             rootProjectionPath,
+		ParentPath:       nil,
+		Name:             filepath.Base(rootPath),
+		Depth:            0,
+		NodeKind:         NodeKindDirectory,
+		LogicalType:      "tenant_root",
+		InstallationID:   rootScope.InstallationID,
+		OrganizationID:   rootScope.OrganizationID,
+		OrganizationSlug: rootScope.OrganizationSlug,
+	}}
+
+	err = filepath.WalkDir(rootPath, func(path string, entry fs.DirEntry, walkErr error) error {
+		if walkErr != nil {
+			return walkErr
+		}
+		if path == rootPath {
+			return nil
+		}
+
+		relPath, err := filepath.Rel(rootPath, path)
+		if err != nil {
+			return err
+		}
+		relPath = filepath.ToSlash(relPath)
+		if relPath == "." {
+			return nil
+		}
+
+		node, err := buildNode(rootPath, relPath, entry, rootScope)
+		if err != nil {
+			return err
+		}
+
+		nodes = append(nodes, node)
+		return nil
+	})
+	if err != nil {
+		return nil, fmt.Errorf("scan POSIX root: %w", err)
+	}
+
+	return nodes, nil
+}
+
+func loadRootScope(rootPath string) (Scope, error) {
+	settingsPath := filepath.Join(rootPath, "settings.json")
+	content, err := os.ReadFile(settingsPath)
+	if err != nil {
+		if errorsIsNotExist(err) {
+			return Scope{}, nil
+		}
+		return Scope{}, fmt.Errorf("read root settings.json: %w", err)
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(content, &payload); err != nil {
+		return Scope{}, fmt.Errorf("decode root settings.json: %w", err)
+	}
+
+	installation, _ := payload["installation"].(map[string]any)
+	organization, _ := payload["organization"].(map[string]any)
+
+	return Scope{
+		InstallationID:  stringValue(installation["id"]),
+		OrganizationID:  stringValue(organization["id"]),
+		OrganizationSlug: stringValue(organization["slug"]),
+	}, nil
+}
+
+func buildNode(rootPath, relPath string, entry fs.DirEntry, rootScope Scope) (Node, error) {
+	scope := deriveScope(relPath, rootScope)
+	parentPath := projectionParentPath(relPath)
+	logicalType, fileRole := classifyPath(relPath, entry.IsDir())
+
+	node := Node{
+		Path:             relPath,
+		ParentPath:       parentPath,
+		Name:             entry.Name(),
+		Depth:            strings.Count(relPath, "/") + 1,
+		NodeKind:         NodeKindDirectory,
+		LogicalType:      logicalType,
+		FileRole:         fileRole,
+		InstallationID:   scope.InstallationID,
+		OrganizationID:   scope.OrganizationID,
+		OrganizationSlug: scope.OrganizationSlug,
+		DepartmentSlug:   scope.DepartmentSlug,
+		TeamSlug:         scope.TeamSlug,
+		ProjectSlug:      scope.ProjectSlug,
+		PersonalSlug:     scope.PersonalSlug,
+	}
+
+	if entry.IsDir() {
+		return node, nil
+	}
+
+	absPath := filepath.Join(rootPath, filepath.FromSlash(relPath))
+	content, err := os.ReadFile(absPath)
+	if err != nil {
+		return Node{}, fmt.Errorf("read POSIX file %s: %w", relPath, err)
+	}
+
+	hash := sha256.Sum256(content)
+	node.NodeKind = NodeKindFile
+	node.SizeBytes = int64(len(content))
+	node.Checksum = hex.EncodeToString(hash[:])
+
+	if strings.EqualFold(filepath.Ext(entry.Name()), ".json") {
+		var payload map[string]any
+		if err := json.Unmarshal(content, &payload); err == nil {
+			jsonContent, err := json.Marshal(payload)
+			if err != nil {
+				return Node{}, fmt.Errorf("remarshal POSIX file %s: %w", relPath, err)
+			}
+			node.ContentJSON = jsonContent
+			node.ResourceID = stringValue(payload["id"])
+			node.ResourceName = stringValue(payload["name"])
+			node.ResourceSlug = stringValue(payload["slug"])
+			if node.ResourceID == "" && fileRole == "settings" && logicalType == "tenant" {
+				installation, _ := payload["installation"].(map[string]any)
+				organization, _ := payload["organization"].(map[string]any)
+				node.ResourceID = stringValue(installation["id"])
+				node.ResourceName = stringValue(installation["name"])
+				node.InstallationID = stringValue(installation["id"])
+				node.OrganizationID = stringValue(organization["id"])
+				node.OrganizationSlug = firstNonEmpty(node.OrganizationSlug, stringValue(organization["slug"]))
+			}
+			if node.ResourceID == "" && fileRole == "users" {
+				node.ResourceName = firstNonEmpty(node.ResourceName, parentEntityName(logicalType, scope))
+			}
+		}
+	}
+
+	if node.ResourceSlug == "" {
+		node.ResourceSlug = inferredResourceSlug(logicalType, scope)
+	}
+
+	return node, nil
+}
+
+func deriveScope(relPath string, rootScope Scope) Scope {
+	scope := rootScope
+	parts := strings.Split(relPath, "/")
+	for _, part := range parts {
+		switch {
+		case strings.HasPrefix(part, "department-"):
+			scope.DepartmentSlug = strings.TrimPrefix(part, "department-")
+		case strings.HasPrefix(part, "team-"):
+			scope.TeamSlug = strings.TrimPrefix(part, "team-")
+		case strings.HasPrefix(part, "project-"):
+			scope.ProjectSlug = strings.TrimPrefix(part, "project-")
+		case strings.HasPrefix(part, "personal-"):
+			scope.PersonalSlug = strings.TrimPrefix(part, "personal-")
+		}
+	}
+	return scope
+}
+
+func classifyPath(relPath string, isDir bool) (logicalType, fileRole string) {
+	parts := strings.Split(relPath, "/")
+	name := parts[len(parts)-1]
+	if !isDir {
+		fileRole = strings.TrimSuffix(name, filepath.Ext(name))
+	}
+
+	hasChildrenAncestor := pathContainsSegment(parts, "children")
+	hasTreeAncestor := pathContainsSegment(parts, "tree")
+	parentName := ""
+	if len(parts) >= 2 {
+		parentName = parts[len(parts)-2]
+	}
+
+	switch {
+	case relPath == "settings.json":
+		return "tenant", "settings"
+	case relPath == "layout.json":
+		return "tenant", "layout"
+	case len(parts) >= 1 && parts[0] == "catalog":
+		if isDir {
+			if len(parts) == 1 {
+				return "catalog", ""
+			}
+			if len(parts) >= 2 && parts[1] == "packs" {
+				if len(parts) == 2 {
+					return "catalog_packs", ""
+				}
+				if len(parts) == 3 {
+					return "catalog_pack", ""
+				}
+				if len(parts) >= 4 && parts[3] == "entries" {
+					return "catalog_pack_entries", ""
+				}
+				return "catalog_entry", ""
+			}
+			if len(parts) >= 2 && parts[1] == "standalone" {
+				if len(parts) == 2 {
+					return "catalog_standalone", ""
+				}
+				return "catalog_entry", ""
+			}
+		}
+		return "catalog", fileRole
+	case len(parts) >= 2 && parts[0] == "departments" && strings.HasPrefix(parts[1], "department-"):
+		if isDir {
+			if len(parts) == 2 {
+				return "department", ""
+			}
+			if len(parts) == 3 && parts[2] == "teams" {
+				return "department_teams", ""
+			}
+			if len(parts) >= 4 && strings.HasPrefix(parts[3], "team-") {
+				return "team", ""
+			}
+		}
+		if len(parts) >= 4 && strings.HasPrefix(parts[3], "team-") {
+			return "team", fileRole
+		}
+		return "department", fileRole
+	case len(parts) >= 2 && parts[0] == "projects" && strings.HasPrefix(parts[1], "project-"):
+		if isDir {
+			if strings.HasPrefix(name, "project-") {
+				return "project", ""
+			}
+			if name == "children" {
+				return "project_children", ""
+			}
+			if name == "tree" {
+				return "project_tree", ""
+			}
+			if hasChildrenAncestor && strings.HasPrefix(name, "folder-") {
+				return "hierarchy_folder", ""
+			}
+			if hasTreeAncestor && strings.HasPrefix(name, "folder-") {
+				return "hierarchy_folder", ""
+			}
+			if hasTreeAncestor && strings.HasPrefix(name, "item-") {
+				return "item", ""
+			}
+		}
+		if hasChildrenAncestor && strings.HasPrefix(parentName, "folder-") {
+			return "hierarchy_folder", fileRole
+		}
+		if hasTreeAncestor {
+			if strings.HasPrefix(parentName, "item-") {
+				return "item", fileRole
+			}
+			if strings.HasPrefix(parentName, "folder-") {
+				return "hierarchy_folder", fileRole
+			}
+		}
+		return "project", fileRole
+	case len(parts) >= 1 && parts[0] == "users":
+		if isDir {
+			if len(parts) == 1 {
+				return "users", ""
+			}
+			if len(parts) == 2 && parts[1] == "personals" {
+				return "personals", ""
+			}
+			if len(parts) >= 3 && parts[1] == "personals" && strings.HasPrefix(parts[2], "personal-") {
+				return "personal", ""
+			}
+			if strings.Contains(relPath, "/tree/") || strings.HasSuffix(relPath, "/tree") {
+				if strings.HasPrefix(name, "folder-") {
+					return "folder", ""
+				}
+				if strings.HasPrefix(name, "item-") {
+					return "item", ""
+				}
+			}
+		}
+		if len(parts) >= 3 && parts[1] == "personals" && strings.HasPrefix(parts[2], "personal-") {
+			if strings.Contains(relPath, "/tree/") {
+				if strings.HasPrefix(parts[len(parts)-2], "item-") {
+					return "item", fileRole
+				}
+				if strings.HasPrefix(parts[len(parts)-2], "folder-") {
+					return "folder", fileRole
+				}
+			}
+			return "personal", fileRole
+		}
+		return "users", fileRole
+	default:
+		if isDir {
+			return "directory", ""
+		}
+		return "file", fileRole
+	}
+}
+
+func pathContainsSegment(parts []string, target string) bool {
+	for _, part := range parts {
+		if part == target {
+			return true
+		}
+	}
+	return false
+}
+
+func projectionParentPath(relPath string) *string {
+	if relPath == "" || relPath == rootProjectionPath {
+		return nil
+	}
+	parent := filepath.ToSlash(filepath.Dir(relPath))
+	if parent == "." || parent == "" {
+		root := rootProjectionPath
+		return &root
+	}
+	return &parent
+}
+
+func inferredResourceSlug(logicalType string, scope Scope) string {
+	switch logicalType {
+	case "department":
+		return scope.DepartmentSlug
+	case "team":
+		return scope.TeamSlug
+	case "project":
+		return scope.ProjectSlug
+	case "personal":
+		return scope.PersonalSlug
+	default:
+		return ""
+	}
+}
+
+func parentEntityName(logicalType string, scope Scope) string {
+	switch logicalType {
+	case "department":
+		return scope.DepartmentSlug
+	case "team":
+		return scope.TeamSlug
+	case "project":
+		return scope.ProjectSlug
+	case "personal":
+		return scope.PersonalSlug
+	default:
+		return ""
+	}
+}
+
+func stringValue(value any) string {
+	stringValue, _ := value.(string)
+	return strings.TrimSpace(stringValue)
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, value := range values {
+		trimmed := strings.TrimSpace(value)
+		if trimmed != "" {
+			return trimmed
+		}
+	}
+	return ""
+}
+
+func summarizeNodes(nodes []Node) RebuildSummary {
+	summary := RebuildSummary{TotalNodes: len(nodes)}
+	for _, node := range nodes {
+		switch node.NodeKind {
+		case NodeKindDirectory:
+			summary.DirectoryCount++
+		case NodeKindFile:
+			summary.FileCount++
+		}
+	}
+	return summary
+}
+
+func errorsIsNotExist(err error) bool {
+	return err != nil && os.IsNotExist(err)
+}

Backend/internal/posixproj/projector_test.go

@@ -0,0 +1,232 @@
+package posixproj
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestScanRootBuildsProjectedNodesFromBootstrapShape(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "POSIX")
+
+	mustMkdirAll(t, filepath.Join(root, "catalog", "packs"))
+	mustMkdirAll(t, filepath.Join(root, "catalog", "standalone"))
+	mustMkdirAll(t, filepath.Join(root, "departments", "department-primary-department", "teams", "team-primary-team"))
+	mustMkdirAll(t, filepath.Join(root, "projects", "project-primary-project", "children", "folder-design", "children", "project-web", "children"))
+	mustMkdirAll(t, filepath.Join(root, "projects", "project-primary-project", "children", "folder-design", "children", "project-web", "tree"))
+	mustMkdirAll(t, filepath.Join(root, "projects", "project-primary-project", "tree"))
+	mustMkdirAll(t, filepath.Join(root, "projects", "project-primary-project", "tree", "folder-docs", "children"))
+	mustMkdirAll(t, filepath.Join(root, "projects", "project-primary-project", "tree", "folder-docs", "item-roadmap"))
+	mustMkdirAll(t, filepath.Join(root, "users", "personals"))
+
+	mustWriteJSON(t, filepath.Join(root, "settings.json"), map[string]any{
+		"installation": map[string]any{
+			"id":             "installation-1",
+			"name":           "MangoPig",
+			"isBootstrapped": true,
+		},
+		"organization": map[string]any{
+			"id":   "org-1",
+			"name": "Primary Organization",
+			"slug": "primary-organization",
+		},
+	})
+	mustWriteJSON(t, filepath.Join(root, "layout.json"), map[string]any{
+		"type": "tenant-layout",
+		"home": map[string]any{"defaultProjectSlug": "primary-project"},
+	})
+	mustWriteJSON(t, filepath.Join(root, "departments", "department-primary-department", "settings.json"), map[string]any{
+		"id":   "dept-1",
+		"name": "Primary Department",
+		"slug": "primary-department",
+		"type": "department",
+	})
+	mustWriteJSON(t, filepath.Join(root, "departments", "department-primary-department", "users.json"), map[string]any{
+		"users": []map[string]any{{"id": "admin-1"}},
+	})
+	mustWriteJSON(t, filepath.Join(root, "departments", "department-primary-department", "teams", "team-primary-team", "settings.json"), map[string]any{
+		"id":   "team-1",
+		"name": "Primary Team",
+		"slug": "primary-team",
+		"type": "team",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "settings.json"), map[string]any{
+		"id":   "project-1",
+		"name": "Primary Project",
+		"slug": "primary-project",
+		"type": "project",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "home.json"), map[string]any{
+		"type":    "project-home",
+		"project": "primary-project",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "acl.json"), map[string]any{
+		"inherits": true,
+		"rules":    []any{},
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "children", "folder-design", "folder.json"), map[string]any{
+		"name": "Design",
+		"slug": "design",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "children", "folder-design", "acl.json"), map[string]any{
+		"inherits": true,
+		"rules":    []any{},
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "children", "folder-design", "children", "project-web", "settings.json"), map[string]any{
+		"id":   "project-2",
+		"name": "Web Project",
+		"slug": "web",
+		"type": "project",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "children", "folder-design", "children", "project-web", "home.json"), map[string]any{
+		"type":    "project-home",
+		"project": "web",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "children", "folder-design", "children", "project-web", "acl.json"), map[string]any{
+		"inherits": true,
+		"rules":    []any{},
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "tree", "folder-docs", "folder.json"), map[string]any{
+		"name": "Docs",
+		"slug": "docs",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "tree", "folder-docs", "item-roadmap", "item.json"), map[string]any{
+		"id":   "item-1",
+		"name": "Roadmap",
+		"slug": "roadmap",
+		"type": "board",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "tree", "folder-docs", "item-roadmap", "schema.json"), map[string]any{
+		"type": "object",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "tree", "folder-docs", "item-roadmap", "data.json"), map[string]any{
+		"title": "Roadmap",
+	})
+	mustWriteJSON(t, filepath.Join(root, "users", "settings.json"), map[string]any{
+		"primaryAdminId": "admin-1",
+	})
+	mustWriteJSON(t, filepath.Join(root, "users", "data.json"), map[string]any{
+		"users": []map[string]any{{"id": "admin-1", "email": "ronald@example.com"}},
+	})
+
+	nodes, err := ScanRoot(root)
+	if err != nil {
+		t.Fatalf("ScanRoot() error = %v", err)
+	}
+
+	index := make(map[string]Node, len(nodes))
+	for _, node := range nodes {
+		index[node.Path] = node
+	}
+
+	rootNode, ok := index[rootProjectionPath]
+	if !ok {
+		t.Fatalf("expected synthetic root node")
+	}
+	if rootNode.LogicalType != "tenant_root" {
+		t.Fatalf("expected root logical type tenant_root, got %q", rootNode.LogicalType)
+	}
+	if rootNode.OrganizationSlug != "primary-organization" {
+		t.Fatalf("expected root organization slug primary-organization, got %q", rootNode.OrganizationSlug)
+	}
+
+	tenantSettings := index["settings.json"]
+	if tenantSettings.LogicalType != "tenant" || tenantSettings.FileRole != "settings" {
+		t.Fatalf("unexpected tenant settings classification: %#v", tenantSettings)
+	}
+	if tenantSettings.InstallationID != "installation-1" {
+		t.Fatalf("expected installation id installation-1, got %q", tenantSettings.InstallationID)
+	}
+
+	deptSettings := index["departments/department-primary-department/settings.json"]
+	if deptSettings.DepartmentSlug != "primary-department" {
+		t.Fatalf("expected department slug primary-department, got %q", deptSettings.DepartmentSlug)
+	}
+	if deptSettings.ResourceID != "dept-1" {
+		t.Fatalf("expected department resource id dept-1, got %q", deptSettings.ResourceID)
+	}
+
+	teamSettings := index["departments/department-primary-department/teams/team-primary-team/settings.json"]
+	if teamSettings.TeamSlug != "primary-team" {
+		t.Fatalf("expected team slug primary-team, got %q", teamSettings.TeamSlug)
+	}
+
+	projectSettings := index["projects/project-primary-project/settings.json"]
+	if projectSettings.ProjectSlug != "primary-project" {
+		t.Fatalf("expected project slug primary-project, got %q", projectSettings.ProjectSlug)
+	}
+	if projectSettings.ResourceName != "Primary Project" {
+		t.Fatalf("expected project resource name Primary Project, got %q", projectSettings.ResourceName)
+	}
+
+	projectTree := index["projects/project-primary-project/tree"]
+	if projectTree.LogicalType != "project_tree" || projectTree.NodeKind != NodeKindDirectory {
+		t.Fatalf("unexpected project tree node: %#v", projectTree)
+	}
+
+	projectChildren := index["projects/project-primary-project/children"]
+	if projectChildren.LogicalType != "project_children" || projectChildren.NodeKind != NodeKindDirectory {
+		t.Fatalf("unexpected project children node: %#v", projectChildren)
+	}
+
+	hierarchyFolder := index["projects/project-primary-project/children/folder-design"]
+	if hierarchyFolder.LogicalType != "hierarchy_folder" || hierarchyFolder.ProjectSlug != "primary-project" {
+		t.Fatalf("unexpected hierarchy folder node: %#v", hierarchyFolder)
+	}
+
+	hierarchyFolderACL := index["projects/project-primary-project/children/folder-design/acl.json"]
+	if hierarchyFolderACL.LogicalType != "hierarchy_folder" || hierarchyFolderACL.FileRole != "acl" {
+		t.Fatalf("unexpected hierarchy folder acl classification: %#v", hierarchyFolderACL)
+	}
+
+	childProjectSettings := index["projects/project-primary-project/children/folder-design/children/project-web/settings.json"]
+	if childProjectSettings.LogicalType != "project" || childProjectSettings.ProjectSlug != "web" {
+		t.Fatalf("unexpected child project classification: %#v", childProjectSettings)
+	}
+
+	treeFolder := index["projects/project-primary-project/tree/folder-docs"]
+	if treeFolder.LogicalType != "hierarchy_folder" || treeFolder.ProjectSlug != "primary-project" {
+		t.Fatalf("unexpected tree folder node: %#v", treeFolder)
+	}
+
+	treeFolderACL := index["projects/project-primary-project/tree/folder-docs/folder.json"]
+	if treeFolderACL.LogicalType != "hierarchy_folder" || treeFolderACL.FileRole != "folder" {
+		t.Fatalf("unexpected tree folder file classification: %#v", treeFolderACL)
+	}
+
+	treeItem := index["projects/project-primary-project/tree/folder-docs/item-roadmap/item.json"]
+	if treeItem.LogicalType != "item" || treeItem.FileRole != "item" {
+		t.Fatalf("unexpected tree item classification: %#v", treeItem)
+	}
+	if treeItem.ResourceSlug != "roadmap" {
+		t.Fatalf("expected tree item resource slug roadmap, got %#v", treeItem.ResourceSlug)
+	}
+
+	usersData := index["users/data.json"]
+	if usersData.LogicalType != "users" || usersData.FileRole != "data" {
+		t.Fatalf("unexpected users data classification: %#v", usersData)
+	}
+	if usersData.Checksum == "" || usersData.SizeBytes == 0 {
+		t.Fatalf("expected users/data.json checksum and size to be populated: %#v", usersData)
+	}
+}
+
+func mustMkdirAll(t *testing.T, path string) {
+	t.Helper()
+	if err := os.MkdirAll(path, 0o755); err != nil {
+		t.Fatalf("MkdirAll(%q) error = %v", path, err)
+	}
+}
+
+func mustWriteJSON(t *testing.T, path string, payload any) {
+	t.Helper()
+	bytes, err := json.MarshalIndent(payload, "", "  ")
+	if err != nil {
+		t.Fatalf("MarshalIndent(%q) error = %v", path, err)
+	}
+	bytes = append(bytes, '\n')
+	if err := os.WriteFile(path, bytes, 0o644); err != nil {
+		t.Fatalf("WriteFile(%q) error = %v", path, err)
+	}
+}

Commands/Local/Dev/backend.just

@@ -9,18 +9,22 @@ migrate-up:
 migrate-down:
 	cd '{{backend_dir}}' && go run ./cmd/migrate down
 
-# Reset all embedded database migrations and reapply from scratch.
+# Reset all embedded database migrations.
 migrate-reset:
 	cd '{{backend_dir}}' && go run ./cmd/migrate reset
 
+# Reset embedded database migrations and apply them again from scratch.
+migrate-rebuild:
+	cd '{{backend_dir}}' && go run ./cmd/migrate reset && go run ./cmd/migrate up
+
 # Show the embedded database migration status.
 migrate-status:
 	cd '{{backend_dir}}' && go run ./cmd/migrate status
 
+# Rebuild the POSIX-to-DB projection from the current POSIX root.
+posix-rebuild:
+	cd '{{backend_dir}}' && go run ./cmd/posix rebuild
+
 # Format backend Go source files.
 fmt:
 	cd '{{backend_dir}}' && gofmt -w ./cmd ./db ./internal
-
-# Run backend test suite.
-test:
-	cd '{{backend_dir}}' && go test ./...

Commands/Local/prod.just

@@ -1,11 +1,15 @@
 project_root := justfile_directory()
 proxy_bake := project_root + "/Proxy/docker-bake.hcl"
+backend_bake := project_root + "/Backend/docker-bake.hcl"
 local_compose := project_root + "/Docker/docker-compose.local.prod.yaml"
 proxy_image := "moku/work-proxy:local-prod"
+backend_api_image := "moku/work-backend:local-prod-api"
+backend_worker_image := "moku/work-backend:local-prod-worker"
 
 # Build the local production proxy image locally.
 build:
 	cd '{{project_root}}' && docker buildx bake -f '{{proxy_bake}}' prod
+	cd '{{project_root}}' && docker buildx bake -f '{{backend_bake}}' prod-api prod-worker
 
 # Start the local production stack in the background using the current image.
 up:
@@ -17,6 +21,7 @@ start: build up
 # Rebuild the local production proxy image locally.
 rebuild:
 	cd '{{project_root}}' && docker buildx bake -f '{{proxy_bake}}' --set '*.no-cache=true' prod
+	cd '{{project_root}}' && docker buildx bake -f '{{backend_bake}}' --set '*.no-cache=true' prod-api prod-worker
 	docker compose -f '{{local_compose}}' up -d --remove-orphans --force-recreate
 
 # Stop and remove the local production stack.
@@ -35,3 +40,5 @@ restart:
 clean:
 	docker compose -f '{{local_compose}}' down --remove-orphans --volumes
 	docker image rm -f '{{proxy_image}}' >/dev/null 2>&1 || true
+	docker image rm -f '{{backend_api_image}}' >/dev/null 2>&1 || true
+	docker image rm -f '{{backend_worker_image}}' >/dev/null 2>&1 || true

Commands/Test/backend.just

@@ -0,0 +1,11 @@
+project_root := justfile_directory()
+backend_dir := project_root + "/Backend"
+
+# Run the full backend test suite.
+[default]
+all:
+	cd '{{backend_dir}}' && go test ./...
+
+# Run the isolated POSIX bootstrap smoke test.
+posix-bootstrap:
+	cd '{{backend_dir}}' && go test ./internal/bootstrap -run TestEnsureBootstrapPOSIXSkeletonInitializesEmptyRoot -count=1 -v

Commands/Test/mod.just

@@ -0,0 +1 @@
+mod backend

Docker/docker-compose.local.dev.yaml

@@ -6,6 +6,7 @@ x-backend-service: &backend-service
   environment:
     DATABASE_URL: postgres://moku:moku_dev_password@postgres:5432/moku?sslmode=disable
     VALKEY_URL: redis://valkey:6379/0
+    POSIX_ROOT: /posix
   depends_on:
     postgres:
       condition: service_healthy
@@ -13,6 +14,7 @@ x-backend-service: &backend-service
       condition: service_healthy
   volumes:
     - ../Backend:/app
+    - ../POSIX:/posix
     - moku_work_backend_go_pkg:/go/pkg/mod
     - moku_work_backend_go_build:/root/.cache/go-build
 

Docker/docker-compose.local.prod.yaml

@@ -1,7 +1,70 @@
+x-backend-service: &backend-service
+  restart: unless-stopped
+  env_file:
+    - ../Env/.env.local
+  environment:
+    DATABASE_URL: postgres://moku:moku_dev_password@postgres:5432/moku?sslmode=disable
+    VALKEY_URL: redis://valkey:6379/0
+    POSIX_ROOT: /posix
+  depends_on:
+    postgres:
+      condition: service_healthy
+    valkey:
+      condition: service_healthy
+  volumes:
+    - ../POSIX:/posix
+
 services:
+  postgres:
+    image: postgres:17-alpine
+    container_name: moku-work-postgres-prod
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: moku
+      POSTGRES_USER: moku
+      POSTGRES_PASSWORD: moku_dev_password
+    volumes:
+      - moku_work_postgres_prod_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U moku -d moku"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+
+  valkey:
+    image: valkey/valkey:8-alpine
+    container_name: moku-work-valkey-prod
+    restart: unless-stopped
+    volumes:
+      - moku_work_valkey_prod_data:/data
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 5s
+
+  api:
+    <<: *backend-service
+    image: moku/work-backend:local-prod-api
+    container_name: moku-work-backend-api-prod
+
+  worker:
+    <<: *backend-service
+    image: moku/work-backend:local-prod-worker
+    container_name: moku-work-backend-worker-prod
+
   proxy:
     image: moku/work-proxy:local-prod
     container_name: moku-work-proxy-local
     restart: unless-stopped
+    depends_on:
+      api:
+        condition: service_started
     ports:
       - "8080:80"
+
+volumes:
+  moku_work_postgres_prod_data:
+  moku_work_valkey_prod_data:

Documentation/POSIX-Structure.md

@@ -0,0 +1,75 @@
+# POSIX Structure
+
+[Filetree Link](https://tree.nathanfriend.com/?s=(%27optiUs!(%27fancy!Yue~fullPath!fbq~YailingSlash!Yue~rootDot!fbq)~R(%27R%27PJ%20or%20OrganizatiU%20%7Bqrver%7DM*46layout6cNlog7packs7*pack37A2*enYies75W5A_standbUe7WA6HwH30LZ2teamw5teamGL5Z6FwF30LKTC058T5C7XFG5LXKXTXC7XI7I05QG5BN2*8QG5BN6Z04_dN_pJw*pJGlayout2L*KI70%27)~vEiU!%271%27)*%20%200M52_*3-%3Cslug%3E4qttings5**69M*7%2F08VG*V259.jsUA5manifestBQ25*schema25*dCchildrenEersFprojectG305HdepartmentI*YeeJEUbKhome2L*42M%5CnNataQitemRsource!Tacl2UonVfolderW*app37X55YtrZusE_90balqsews0%01wqb_ZYXWVUTRQNMLKJIHGFECBA987654320*)
+
+``` markdown
+Personal or Organization (server)/
+├── settings.json
+├── layout.json
+├── catalog/
+│   ├── packs/
+│   │   └── pack-<slug>/
+│   │       ├── manifest.json
+│   │       └── entries/
+│   │           └── app-<slug>/
+│   │               └── manifest.json
+│   └── standalone/
+│       └── app-<slug>/
+│           └── manifest.json
+├── departments/
+│   └── department-<slug>/
+│       ├── settings.json
+│       ├── users.json
+│       └── teams/
+│           └── team-<slug>/
+│               ├── settings.json
+│               └── users.json
+├── projects/
+│   └── project-<slug>/
+│       ├── settings.json
+│       ├── home.json
+│       ├── acl.json
+│       ├── children/
+│       │   └── folder-<slug>/
+│       │       ├── folder.json
+│       │       ├── acl.json
+│       │       └── children/
+│       │           └── project-<slug>/
+│       │               ├── settings.json
+│       │               ├── home.json
+│       │               ├── acl.json
+│       │               ├── children/
+│       │               └── tree/
+│       └── tree/
+│           ├── item-<slug>/
+│           │   ├── item.json
+│           │   ├── schema.json
+│           │   └── data.json
+│           └── folder-<slug>/
+│               ├── folder.json
+│               └── item-<slug>/
+│                   ├── item.json
+│                   ├── schema.json
+│                   └── data.json
+└── users/
+    ├── settings.json
+    ├── data.json
+    └── personals/
+        └── personal-<slug>/
+            ├── layout.json
+            ├── settings.json
+            ├── home.json
+            └── tree/
+```
+
+## File Responsibilities
+
+- `settings.json` — Metadata and presentation config for the thing, such as display name, icon, description, and simple settings.
+- `layout.json` — Layout configuration for the current server or personal space.
+- `home.json` — Home surface configuration, such as widgets, sections, and how they are arranged.
+- `folder.json` — Metadata for a folder node in a tree.
+- `item.json` — Instance metadata for a created item, including what it is and how it should behave.
+- `schema.json` — The structure expected by that item's data.
+- `data.json` — The actual content or state data for that item.
+- `manifest.json` — Catalog definition metadata, including versioning, description, and capabilities for reusable apps or entries.
+- `users.json` — User membership or assignment data for departments and teams.

Documentation/TODO.md

@@ -4,87 +4,149 @@
 
 ### Version 0.1.0
 
-**Goal:** Barebone frontend with a real backend core.
+**Goal:** Finish the base application shell, auth, and platform foundations.
 
-#### Architecture
+#### Architecture and Delivery
 
-- [ ] Project-Structure
-- [ ] Stack-Decisions
-- [ ] Proxy
-  - [ ] Local-Prod-NGINX-Proxy
-  - [ ] Static-Frontend-Serving
-- [ ] First-Request-Web-Loader
-  - [ ] Bootstrap-Document
-  - [ ] Route-Intent-Handoff
-  - [ ] Tiny-First-Paint-Budget
-- [ ] Dev-and-Prod-Builds
+- [x] Project-Structure
+- [x] Stack-Decisions
+- [x] Proxy
+  - [x] Local-Dev-Vite-Proxy
+  - [x] Local-Prod-NGINX-Proxy
+- [x] First-Request-Web-Loader
+  - [x] Bootstrap-Document
+  - [x] Route-Intent-Handoff
+  - [x] Tiny-First-Paint-Budget
+- [x] Dev-and-Prod-Builds
   - [x] Local-Dev-Just-Commands
   - [x] Local-Dev-Docker-Compose
-  - [ ] Local-Prod-Just-Commands
-  - [ ] Local-Prod-Docker-Compose
-  - [ ] Frontend-Production-Dockerfile
-  - [ ] Frontend-docker-bake
+  - [x] Local-Prod-Just-Commands
+  - [x] Local-Prod-Docker-Compose
+  - [x] Frontend-Production-Dockerfile
+  - [x] Frontend-docker-bake
 
-#### Backend
+#### Backend — Done Foundations
+
+- [x] Bootstrap-Persistence
+  - [x] Installation-Step
+  - [x] Mode-Step
+  - [x] Admin-Step
+  - [x] Structure-Step
+  - [x] Bootstrap-State-Authority
+  - [x] Development-Bootstrap-Reset
+- [x] Base-Schema
+  - [x] Installations
+  - [x] Users
+  - [x] User-Homes
+  - [x] Organizations
+  - [x] Departments
+  - [x] Teams
+  - [x] Projects
+  - [x] Workspaces
+  - [x] Membership-Tables
+- [x] App-Shell-Read-API
+  - [x] App-Shell-State-Endpoint
+  - [x] Bootstrap-Read-Endpoints
+  - [x] Shell-Tree-Hydration
+- [x] Web-Route-Scaffolds
+  - [x] Session-Endpoint-Scaffold
+  - [x] Bootstrap-Endpoint-Scaffold
+  - [x] Current-User-Endpoint-Scaffold
+
+#### Backend — Remaining for 0.1.0
 
 - [ ] Auth
   - [ ] Session-Flow
   - [ ] Login-Logout-Foundation
   - [ ] Authentication
-- [ ] User
-  - [ ] Base-Model
+- [ ] Current-User-Implementation
+- [ ] POSIX-Lite-File-Persistence-Foundation
+  - [ ] Mounted-Storage-Root-Config
+  - [ ] Project-Folder-Creation-On-Backend
+  - [ ] moku.project.json
+  - [ ] Item-Folder-Creation
+  - [ ] item.json
+  - [ ] schema.json
+  - [ ] data.json
+  - [ ] DB-To-Files-Write-Flow
+- [ ] User-and-Workspace-Domain-Readiness
   - [ ] Base-Workspace
-    - [ ] Folders-and-Subfolders
   - [ ] Boards
   - [ ] Dashboard
-- [ ] Organization
-  - [ ] Base-Model
-  - [ ] Access-Rules-and-Membership
-- [ ] Workspace
-  - [ ] Folders-and-Subfolders
 - [ ] API
+  - [ ] Real-Organizations-Read-Endpoint
+  - [ ] Real-Workspaces-Read-Endpoint
+  - [ ] Tree-Mutation-Endpoints
+  - [ ] Project-Creation-Endpoint
 
-#### Frontend
+#### Frontend — Done Foundations
 
 - [x] Foundation
 - [x] Typography
 - [x] Icons
-- [ ] App Shell
+- [x] App-Shell
+  - [x] Left-Rail
+  - [x] Top-Bar
+  - [x] Server-Dock
+  - [x] Department-Selector
+  - [x] Theme-Toggle
+  - [x] Notifications-Menu
+  - [x] Profile-Menu
+- [x] Responsive-Shell
+  - [x] Collapsible-Shell
+  - [x] Mobile-Bottom-Nav
+  - [x] Mobile-Workspace-Browser
+  - [x] Mobile-Workspace-Views
+- [x] Context-Menus
+  - [x] Workspace-Context-Menu
+  - [x] Project-Context-Menu
+- [x] Bootstrap-Workspace-Home
+  - [x] Bootstrap-Wizard
+  - [x] Bootstrap-Step-Submission
+  - [x] App-Shell-Reload-After-Bootstrap
+- [x] Project-Menu
+  - [x] Folders-and-Subfolders
+  - [x] Rooted-From-Department
+  - [x] Long-Press-Drag-and-Drop
+- [x] Workspace-Tree
+  - [x] Folders-and-Subfolders
+  - [x] Long-Press-Drag-and-Drop
+- [x] App-Shell-Hydration
+
+#### Frontend — Remaining for 0.1.0
+
 - [ ] Primitives
   - [ ] Button
   - [ ] IconButton
   - [ ] Input
   - [ ] Surface
-- [ ] Nav-Bar
 - [ ] Workspace-Switching
-- [ ] Workspace-Home
+- [ ] Real-Workspace-Home
+- [ ] Real-Workspace-Tree-Hydration
+- [ ] Create-Project-Flow
+- [ ] Persist-Tree-Mutations
+- [ ] Connect-Tree-Interactions-To-Backend-Data
 
 ### Version 0.2.0
 
-**Goal:** First real work surface.
-
-- [ ] Table
-- [ ] CVA
-- [ ] Storyboard
-- [ ] Theme-System
-  - [ ] Theme-Registry
-  - [ ] Built-In-Theme-Presets
-  - [ ] Active-Theme-Persistence
-  - [ ] Theme-Switcher
-  - [ ] Theme-JSON-Upload
-  - [ ] Theme-JSON-Import-Validation
-  - [ ] Community-Theme-Readiness
+**Goal:** Build the plugin app system on top of the base platform. And core app plugins like calendar, board, docs and text channels
 
 ### Version 0.3.0
 
-**Goal:** Documents and system hardening.
-
-- [ ] Document
-- [ ] Accessibility-Rules
-- [ ] Motion-Foundation
+**Goal:** Communications and Collaboration (Email System, Reminder System, and Live Collaboration on Documents)
 
 ### Version 0.4.0
 
-- [ ] Gantt-Board
-- [ ] Calendar
-- [ ] Timeline
+**Goal:** Introduce the POSIX-based file system drive direction with OnlyOffice + S3 blob storage + Per File Versioning
+
+### Version 0.5.0
+
+**Goal:** File Sharing and Per File Permissions
+
+### Version 0.6.0
+
+**Goal:** Git as a core plugin
+
+### Version 0.7.0
+
+**Goal:** Full Automation System (Extensive)

Env/.env.example

@@ -6,8 +6,14 @@ LOG_LEVEL=debug
 
 BACKEND_WEB_PORT=8080
 BACKEND_API_PORT=8081
-BACKEND_WORKER_PORT=8082
 BACKEND_SHUTDOWN_TIMEOUT=10s
 
 DATABASE_URL=postgres://moku:moku_dev_password@localhost:5432/moku?sslmode=disable
 VALKEY_URL=redis://localhost:6379/0
+POSIX_ROOT=../POSIX
+
+VITE_API_BASE_URL=/v1
+
+# Local frontend dev uses the Vite proxy for /v1 requests.
+# Override only if the browser must call the API directly:
+# VITE_API_BASE_URL=http://localhost:8081/v1

Frontend/src/app.tsx

@@ -3,6 +3,7 @@
 import type { JSX } from "solid-js";
 import { AppShell } from "./components/shell/AppShell/AppShell";
 import "./styles/main.scss";
+import "./styles/user-overrides.scss";
 
 const App = (): JSX.Element => {
 	return <AppShell />;

Frontend/src/components/shell/AppShell/AppShell.module.scss

@@ -8,8 +8,10 @@
 }
 
 .body {
+  --shell-dock-clearance: calc(var(--space-12) + var(--space-12) + var(--space-8));
   --rail-width: 4.75rem;
   --sidebar-width: 16.75rem;
+  --mobile-bottom-nav-clearance: 0rem;
   --shell-top-left-radius: calc(var(--radius-xl) + var(--space-1));
   --shell-frame-border: color-mix(in srgb, var(--color-border-strong) 44%, transparent);
   --shell-divider-border: color-mix(in srgb, var(--color-border-strong) 34%, transparent);
@@ -23,6 +25,14 @@
   background: var(--color-surface);
 }
 
+.bodyRailCollapsed {
+  --rail-width: 0rem;
+}
+
+.bodySidebarCollapsed {
+  --sidebar-width: 0rem;
+}
+
 .railColumn {
   min-height: 0;
   display: flex;
@@ -93,11 +103,21 @@
   border-top-right-radius: 0;
 }
 
+.mobileWorkspaceView {
+  min-width: 0;
+  min-height: 0;
+  height: 100%;
+  display: grid;
+  box-sizing: border-box;
+  overflow: hidden;
+  background: var(--workspace-panel-surface);
+}
+
 .sidebarDock {
   position: absolute;
   bottom: var(--space-3);
   left: calc(var(--space-1) + (var(--rail-width) * 0.1));
-  width: calc(var(--sidebar-width) + (var(--rail-width) * 0.9) - var(--space-2));
+  width: max(12rem, calc(var(--sidebar-width) + (var(--rail-width) * 0.9) - var(--space-2)));
   right: auto;
   z-index: calc(var(--z-modal) + 1);
   pointer-events: none;
@@ -112,6 +132,14 @@
     --rail-width: 5rem;
     --sidebar-width: 17.25rem;
   }
+
+  .bodyRailCollapsed {
+    --rail-width: 0rem;
+  }
+
+  .bodySidebarCollapsed {
+    --sidebar-width: 0rem;
+  }
 }
 
 @include respond-down(tablet) {
@@ -119,21 +147,102 @@
     --rail-width: 4.5rem;
     --sidebar-width: 13.25rem;
   }
+
+  .bodyRailCollapsed {
+    --rail-width: 0rem;
+  }
+
+  .bodySidebarCollapsed {
+    --sidebar-width: 0rem;
+  }
+}
+
+.bodyRailCollapsed .railColumn {
+  overflow: hidden;
+}
+
+.bodySidebarCollapsed .railColumn {
+  --rail-dock-clearance: 0rem;
+}
+
+.bodySidebarCollapsed:not(.bodyRailCollapsed) .railColumn {
+  --rail-bottom-offset: var(--space-3);
+}
+
+.bodySidebarCollapsed .sidebarColumn {
+  --sidebar-dock-clearance: 0rem;
+  display: none;
+  overflow: hidden;
+  border-left-width: 0;
+  border-top-width: 0;
+}
+
+.bodySidebarCollapsed .workspaceRegion {
+  grid-template-columns: minmax(0, 1fr);
+}
+
+.bodySidebarCollapsed .workspaceMain {
+  border-left-color: transparent;
+}
+
+.bodySidebarCollapsed:not(.bodyRailCollapsed) .workspaceMain {
+  border-top-width: 1px;
+  border-top-color: var(--shell-frame-border);
+  border-left-color: var(--shell-frame-border);
+  border-top-left-radius: var(--shell-top-left-radius);
+  box-shadow: none;
+}
+
+.bodySidebarCollapsed:not(.bodyRailCollapsed) .workspaceRegion::before {
+  display: none;
+}
+
+.bodySidebarCollapsed .sidebarDock {
+  display: none;
 }
 
 @include respond-down(mobile) {
   .body {
-    grid-template-columns: 4.5rem minmax(0, 1fr);
-    --rail-width: 4.5rem;
+    grid-template-columns: minmax(0, 1fr);
+    --rail-width: 0rem;
+    --sidebar-width: 0rem;
+    --mobile-bottom-nav-clearance: calc(var(--space-12) + var(--space-10) + env(safe-area-inset-bottom, 0px));
   }
 
   .railColumn {
-    position: sticky;
-    top: 0;
+    display: none;
   }
 
-  .workspaceRegion,
+  .workspaceRegion {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    border-top-left-radius: 0;
+  }
+
+  .workspaceRegion::before {
+    background: var(--workspace-panel-surface);
+    border-left-width: 0;
+    border-right-width: 0;
+    border-top-left-radius: 0;
+  }
+
+  .sidebarColumn,
   .sidebarDock {
     display: none;
   }
+
+  .workspaceMain {
+    border-left-width: 0;
+    border-top-right-radius: 0;
+    border-top-left-radius: 0;
+    box-sizing: border-box;
+    padding-bottom: var(--mobile-bottom-nav-clearance);
+  }
+
+  .mobileWorkspaceView {
+    height: 100%;
+    max-height: none;
+    padding-bottom: 0;
+    background: var(--workspace-panel-surface);
+  }
 }

Frontend/src/components/shell/AppShell/AppShell.tsx

@@ -1,19 +1,54 @@
 // Path: Frontend/src/components/shell/AppShell/AppShell.tsx
 
-import { createSignal, onMount, type JSX } from "solid-js";
+import { createSignal, onCleanup, onMount, Show, type JSX } from "solid-js";
 import { getDocumentTheme, setTheme, type Theme } from "../../../theme/runtime";
 import { WorkspaceHome } from "../../workspace-home/WorkspaceHome/WorkspaceHome";
+import { AppShellDataProvider, useAppShellData } from "../data/app-shell.context";
 import { LeftRail } from "../LeftRail/LeftRail";
+import { MobileBottomNav } from "../MobileBottomNav/MobileBottomNav";
+import { MobileWorkspaceBrowser } from "../MobileWorkspaceBrowser/MobileWorkspaceBrowser";
 import { ServerDock } from "../ServerDock/ServerDock";
+import { NotificationsMenu } from "../TopBar/NotificationsMenu";
+import { ProfileMenu } from "../TopBar/ProfileMenu";
 import { TopBar } from "../TopBar/TopBar";
 import { WorkspaceSidebar } from "../WorkspaceSidebar/WorkspaceSidebar";
 import styles from "./AppShell.module.scss";
 
-export const AppShell = (): JSX.Element => {
+type MobileWorkspaceView = "notifications" | "profile" | null;
+const MOBILE_VIEWPORT_QUERY = "(max-width: 48rem)";
+
+const AppShellContent = (): JSX.Element => {
 	const [themeState, setThemeState] = createSignal<Theme>("light");
+	const [isRailCollapsed, setIsRailCollapsed] = createSignal(false);
+	const [isSidebarCollapsed, setIsSidebarCollapsed] = createSignal(false);
+	const [isMobileViewport, setIsMobileViewport] = createSignal(false);
+	const [isMobileWorkspaceBrowserOpen, setIsMobileWorkspaceBrowserOpen] = createSignal(false);
+	const [activeMobileWorkspaceView, setActiveMobileWorkspaceView] = createSignal<MobileWorkspaceView>(null);
+	const appShellData = useAppShellData();
 
 	onMount((): void => {
 		setThemeState(getDocumentTheme());
+
+		if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+			return;
+		}
+
+		const mediaQuery = window.matchMedia(MOBILE_VIEWPORT_QUERY);
+		const syncMobileViewport = (): void => {
+			setIsMobileViewport(mediaQuery.matches);
+
+			if (!mediaQuery.matches) {
+				setIsMobileWorkspaceBrowserOpen(false);
+				setActiveMobileWorkspaceView(null);
+			}
+		};
+
+		syncMobileViewport();
+		mediaQuery.addEventListener("change", syncMobileViewport);
+
+		onCleanup(() => {
+			mediaQuery.removeEventListener("change", syncMobileViewport);
+		});
 	});
 
 	const toggleTheme = (): void => {
@@ -23,32 +58,118 @@ export const AppShell = (): JSX.Element => {
 		setThemeState(next);
 	};
 
-	return (
-		<div class={styles.shell}>
-			<TopBar theme={themeState()} onToggleTheme={toggleTheme} />
+	const openMobileWorkspaceView = (view: Exclude<MobileWorkspaceView, null>): void => {
+		setIsMobileWorkspaceBrowserOpen(false);
+		setActiveMobileWorkspaceView((current) => (current === view ? null : view));
+	};
 
-			<div class={styles.body}>
+	const toggleMobileWorkspaceBrowser = (): void => {
+		setActiveMobileWorkspaceView(null);
+		setIsMobileWorkspaceBrowserOpen((open) => !open);
+	};
+
+	const toggleMobileNotifications = (): void => {
+		openMobileWorkspaceView("notifications");
+	};
+
+	const toggleMobileProfile = (): void => {
+		openMobileWorkspaceView("profile");
+	};
+
+	const closeMobileWorkspaceView = (): void => {
+		setActiveMobileWorkspaceView(null);
+	};
+
+	return (
+		<div class={styles.shell} data-ui="app-shell" data-app-shell-status={appShellData.status()}>
+			<TopBar
+				theme={themeState()}
+				onToggleTheme={toggleTheme}
+				isMobileViewport={isMobileViewport()}
+				isNotificationsOpen={activeMobileWorkspaceView() === "notifications"}
+				isProfileOpen={activeMobileWorkspaceView() === "profile"}
+				onToggleNotifications={toggleMobileNotifications}
+				onToggleProfile={toggleMobileProfile}
+			/>
+
+			<div
+				classList={{
+					[styles.body]: true,
+					[styles.bodyRailCollapsed]: isRailCollapsed(),
+					[styles.bodySidebarCollapsed]: isSidebarCollapsed(),
+				}}
+				data-slot="shell-body"
+				data-rail-collapsed={isRailCollapsed() ? "true" : "false"}
+				data-sidebar-collapsed={isSidebarCollapsed() ? "true" : "false"}
+			>
 				{/* Left server rail */}
-				<div class={styles.railColumn}>
-					<LeftRail />
+				<div class={styles.railColumn} data-slot="rail-column">
+					<LeftRail collapsed={isRailCollapsed()} />
 				</div>
 
 				{/* Sidebar + main workspace frame */}
-				<div class={styles.workspaceRegion}>
-					<div class={styles.sidebarColumn}>
-						<WorkspaceSidebar />
+				<div class={styles.workspaceRegion} data-slot="workspace-region">
+					<div class={styles.sidebarColumn} data-slot="sidebar-column">
+						<WorkspaceSidebar
+							collapsed={isSidebarCollapsed()}
+							railCollapsed={isRailCollapsed()}
+							onToggleRailCollapse={(): void => {
+								setIsRailCollapsed((collapsed) => !collapsed);
+							}}
+						/>
 					</div>
 
-					<div class={styles.workspaceMain}>
-						<WorkspaceHome />
+					<div class={styles.workspaceMain} data-slot="workspace-main">
+						{/* On mobile, top-bar menus become full workspace views instead of popovers. */}
+						<Show
+							when={isMobileViewport() && activeMobileWorkspaceView() !== null}
+							fallback={
+								<WorkspaceHome
+									sidebarCollapsed={isSidebarCollapsed()}
+									onToggleSidebarCollapse={(): void => {
+										setIsSidebarCollapsed((collapsed) => !collapsed);
+									}}
+								/>
+							}
+						>
+							<div class={styles.mobileWorkspaceView} data-slot="mobile-workspace-view" data-view={activeMobileWorkspaceView() ?? undefined}>
+								<Show when={activeMobileWorkspaceView() === "notifications"}>
+									<NotificationsMenu id="mobile-workspace-notifications" onSelect={closeMobileWorkspaceView} variant="workspace" />
+								</Show>
+								<Show when={activeMobileWorkspaceView() === "profile"}>
+									<ProfileMenu id="mobile-workspace-profile" onSelect={closeMobileWorkspaceView} variant="workspace" />
+								</Show>
+							</div>
+						</Show>
 					</div>
 				</div>
 
 				{/* Floating server dock overlay */}
-				<div class={styles.sidebarDock}>
+				<div class={styles.sidebarDock} data-slot="sidebar-dock">
 					<ServerDock />
 				</div>
 			</div>
+
+			<MobileBottomNav
+				isBrowseOpen={isMobileWorkspaceBrowserOpen()}
+				onBrowseToggle={(): void => {
+					toggleMobileWorkspaceBrowser();
+				}}
+			/>
+			<MobileWorkspaceBrowser
+				open={isMobileWorkspaceBrowserOpen()}
+				onClose={(): void => {
+					setIsMobileWorkspaceBrowserOpen(false);
+				}}
+			/>
 		</div>
 	);
 };
+
+export const AppShell = (): JSX.Element => {
+	return (
+		<AppShellDataProvider>
+			<AppShellContent />
+		</AppShellDataProvider>
+	);
+};

Frontend/src/components/shell/DepartmentSelector/DepartmentSelector.module.scss

@@ -7,7 +7,7 @@
   min-width: 0;
   padding: 0;
   display: inline-flex;
-  align-items: center;
+  align-items: flex-end;
   justify-content: flex-start;
   gap: var(--space-2);
   border: 0;
@@ -43,14 +43,25 @@
   box-shadow: 0 0 0 0.12rem color-mix(in srgb, var(--color-accent-soft) 14%, transparent);
 }
 
+.copy {
+  min-width: 0;
+  display: inline-flex;
+  align-items: baseline;
+  gap: var(--space-1);
+}
+
 .value {
   @include text-title;
   color: var(--color-text);
   font-weight: var(--font-weight-title);
+  line-height: 1;
 }
 
 .meta {
+  @include text-caption;
   color: var(--color-text-muted);
+  line-height: 1;
+  padding-left: var(--space-1);
 }
 
 .icon {
@@ -80,7 +91,7 @@
 
 .menuSection {
   display: grid;
-  gap: 0.15rem;
+  gap: calc(var(--space-1) / 2);
 }
 
 .menuSectionLabel {
@@ -171,14 +182,39 @@
 }
 
 .submenuIndicator {
-  width: 0.35rem;
-  height: 0.35rem;
+  width: calc(var(--space-1) + (var(--space-1) / 2));
+  height: calc(var(--space-1) + (var(--space-1) / 2));
   flex: 0 0 auto;
   border-radius: 999px;
   background: var(--color-accent-soft);
 }
 
 @include respond-down(mobile) {
+  .selector {
+    align-items: flex-end;
+    gap: var(--space-1);
+  }
+
+  .copy {
+    gap: var(--space-2);
+  }
+
+  .value {
+    line-height: 0.95;
+  }
+
+  .meta {
+    font-size: 0.68rem;
+    line-height: 1;
+    letter-spacing: 0.01em;
+    padding-bottom: calc(var(--space-1) / 2);
+  }
+
+  .icon {
+    align-self: flex-end;
+    margin-bottom: calc(var(--space-1) / 2);
+  }
+
   .menu {
     min-width: min(16rem, calc(100vw - (var(--space-4) * 2)));
   }

Frontend/src/components/shell/DepartmentSelector/DepartmentSelector.tsx

@@ -1,22 +1,29 @@
-import { For, createSignal, onCleanup, onMount, type JSX } from "solid-js";
+import { For, createEffect, createSignal, onCleanup, onMount, type JSX } from "solid-js";
 import { ChevronDown } from "../../../lib/icons";
-import { activeDepartment, departmentItems, type DepartmentItem } from "../data/shell.data";
+import { useAppShellData } from "../data/app-shell.context";
+import { type DepartmentItem } from "../data/shell.data";
 import styles from "./DepartmentSelector.module.scss";
 
-const defaultDepartment = departmentItems.find((item) => item.id === activeDepartment.id) ?? departmentItems[0];
-const defaultTeamName = departmentItems
-	.find((item) => item.id === activeDepartment.id)
-	?.teams.find((teamName) => teamName === activeDepartment.teamName)
-	?? defaultDepartment?.teams[0]
-	?? "";
-
 export const DepartmentSelector = (): JSX.Element => {
+	const appShellData = useAppShellData();
 	const [isOpen, setIsOpen] = createSignal(false);
-	const [selectedDepartment, setSelectedDepartment] = createSignal<DepartmentItem>(defaultDepartment);
-	const [selectedTeamName, setSelectedTeamName] = createSignal(defaultTeamName);
+	const [selectedDepartment, setSelectedDepartment] = createSignal<DepartmentItem>(appShellData.departmentItems()[0] ?? appShellData.activeDepartment());
+	const [selectedTeamName, setSelectedTeamName] = createSignal(appShellData.activeDepartment().teamName);
 
 	let rootRef: HTMLDivElement | undefined;
 
+	createEffect(() => {
+		const activeDepartment = appShellData.activeDepartment();
+		const matchingDepartment = appShellData.departmentItems().find((item) => item.id === activeDepartment.id) ?? appShellData.departmentItems()[0];
+
+		if (!matchingDepartment) {
+			return;
+		}
+
+		setSelectedDepartment(matchingDepartment);
+		setSelectedTeamName(activeDepartment.teamName || matchingDepartment.teams[0] || "");
+	});
+
 	onMount(() => {
 		const handlePointerDown = (event: PointerEvent): void => {
 			if (!isOpen()) return;
@@ -53,8 +60,10 @@ export const DepartmentSelector = (): JSX.Element => {
 				aria-expanded={isOpen()}
 				onClick={() => setIsOpen((open) => !open)}
 			>
+				<span class={styles.copy}>
 					<strong class={styles.value}>{selectedDepartment().name}</strong>
-				<span class={styles.meta}>{selectedTeamName()} team</span>
+					<span class={styles.meta}>{selectedTeamName()}</span>
+				</span>
 
 				<ChevronDown classList={{ [styles.icon]: true, [styles.iconOpen]: isOpen() }} size={16} strokeWidth={2} />
 			</button>
@@ -64,7 +73,7 @@ export const DepartmentSelector = (): JSX.Element => {
 					<div class={styles.menuSection}>
 						<span class={styles.menuSectionLabel}>Departments</span>
 
-						<For each={departmentItems}>
+						<For each={appShellData.departmentItems()}>
 							{(item): JSX.Element => (
 								<button
 									classList={{ [styles.menuItem]: true, [styles.menuItemActive]: item.id === selectedDepartment().id }}

Frontend/src/components/shell/LeftRail/LeftRail.module.scss

@@ -1,7 +1,5 @@
 .rail {
   --rail-workspace-size: var(--control-size-lg);
-  --rail-action-size: var(--control-size-md);
-  --rail-dock-clearance: 8rem;
   position: relative;
   z-index: 3;
   flex: 1;
@@ -10,12 +8,19 @@
   flex-direction: column;
   align-items: center;
   gap: var(--space-3);
-  padding: var(--space-3) var(--space-2) calc(var(--space-3) + var(--rail-dock-clearance));
+  padding: var(--space-3) var(--space-2) calc(var(--space-3) + var(--rail-dock-clearance, var(--shell-dock-clearance)));
   overflow: visible;
 }
 
-.topCluster,
-.bottomCluster {
+.railCollapsed {
+  --rail-workspace-size: calc(var(--control-size-md) + 0.1rem);
+  justify-content: flex-start;
+  gap: 0;
+  padding-top: var(--space-4);
+  padding-inline: var(--space-1);
+}
+
+.topCluster {
   width: 100%;
   display: flex;
   flex-direction: column;
@@ -23,14 +28,18 @@
   gap: var(--space-2);
 }
 
-.bottomCluster {
-  margin-top: auto;
-}
-
 .topCluster {
   gap: var(--space-3);
 }
 
+.railCollapsed .topCluster {
+  gap: var(--space-3);
+}
+
+.railCollapsed .topCluster {
+  align-items: center;
+}
+
 .items {
   width: 100%;
   min-height: 0;
@@ -173,20 +182,3 @@
   border-radius: var(--radius-md);
   box-shadow: none;
 }
-
-.addButton {
-  width: var(--rail-action-size);
-  height: var(--rail-action-size);
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  border: 1px dashed var(--color-border-strong);
-  border-radius: var(--radius-pill);
-  background: transparent;
-  color: var(--color-text-muted);
-
-  &:hover {
-    background: var(--color-surface-hover);
-    color: var(--color-text);
-  }
-}

Frontend/src/components/shell/LeftRail/LeftRail.tsx

@@ -1,8 +1,8 @@
 // Path: Frontend/src/components/shell/LeftRail/LeftRail.tsx
 
-import { For, type JSX } from "solid-js";
-import { Plus } from "../../../lib/icons";
-import { railItems, type RailItem } from "../data/shell.data";
+import { For, Show, type JSX } from "solid-js";
+import { useAppShellData } from "../data/app-shell.context";
+import { type RailItem } from "../data/shell.data";
 import styles from "./LeftRail.module.scss";
 
 type RailEntryProps = {
@@ -42,29 +42,42 @@ const RailEntry = (props: RailEntryProps): JSX.Element => {
 	);
 };
 
-export const LeftRail = (): JSX.Element => {
-	const personalItem = railItems.find((item) => item.kind === "personal");
-	const organizationItems = railItems.filter((item) => item.kind === "organization");
+type LeftRailProps = {
+	collapsed: boolean;
+};
+
+export const LeftRail = (props: LeftRailProps): JSX.Element => {
+	const appShellData = useAppShellData();
+	const personalItem = () => appShellData.railItems().find((item) => item.kind === "personal");
+	const organizationItems = () => appShellData.railItems().filter((item) => item.kind === "organization");
 
 	return (
-		<aside class={styles.rail} aria-label="Server rail">
+		<aside
+			classList={{
+				[styles.rail]: true,
+				[styles.railCollapsed]: props.collapsed,
+			}}
+			aria-label="Server rail"
+		>
 			<div class={styles.topCluster}>
-				{personalItem ? <RailEntry item={personalItem} label={personalItem.label} abbreviation="M" personal /> : null}
+				<Show when={!props.collapsed && personalItem()}>
+					{(item): JSX.Element => (
+						<RailEntry item={item()} label={item().label} abbreviation={item().abbreviation} personal />
+					)}
+				</Show>
 
+				<Show when={!props.collapsed}>
 					<div class={styles.sectionDivider} aria-hidden="true" />
+				</Show>
 			</div>
 
+			<Show when={!props.collapsed}>
 				<div class={styles.items}>
-				<For each={organizationItems}>
+					<For each={organizationItems()}>
 						{(item): JSX.Element => <RailEntry item={item} label={item.label} abbreviation={item.abbreviation} />}
 					</For>
 				</div>
-
-			<div class={styles.bottomCluster}>
-				<button type="button" class={styles.addButton} aria-label="Create server" title="Create server">
-					<Plus size={16} strokeWidth={2} />
-				</button>
-			</div>
+			</Show>
 		</aside>
 	);
 };

Frontend/src/components/shell/MobileBottomNav/MobileBottomNav.module.scss

@@ -0,0 +1,108 @@
+.mobileNav {
+  display: none;
+}
+
+@include respond-down(mobile) {
+  .mobileNav {
+    --mobile-nav-button-gap: var(--space-1);
+    --mobile-nav-button-padding-inline: var(--space-2);
+    --mobile-nav-button-padding-top: calc(var(--space-2) + (var(--space-1) / 2));
+    --mobile-nav-button-padding-bottom: var(--space-2);
+    position: fixed;
+    right: 0;
+    bottom: 0;
+    left: 0;
+    display: grid;
+    gap: var(--space-2);
+    padding: var(--space-2) var(--space-3) calc(var(--space-2) + env(safe-area-inset-bottom, 0px));
+    background:
+      linear-gradient(to top, color-mix(in srgb, var(--color-canvas) 98%, transparent), color-mix(in srgb, var(--color-canvas) 92%, transparent));
+    border-top: 1px solid color-mix(in srgb, var(--color-border-strong) 40%, transparent);
+    backdrop-filter: blur(var(--blur-overlay));
+    z-index: var(--z-sticky);
+  }
+
+  .contextBar {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--space-2);
+    min-width: 0;
+    color: var(--color-text-muted);
+  }
+
+  .contextServer,
+  .contextProject {
+    @include text-caption;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .contextServer {
+    max-width: 45vw;
+  }
+
+  .contextProject {
+    max-width: 30vw;
+  }
+
+  .contextDivider {
+    @include text-caption;
+    color: var(--color-text-subtle);
+  }
+
+	.navGrid {
+	  display: grid;
+	  grid-template-columns: repeat(3, minmax(0, 1fr));
+	  gap: var(--space-2);
+	}
+
+  .navButton {
+    min-width: 0;
+    display: grid;
+    justify-items: center;
+    gap: var(--mobile-nav-button-gap);
+    padding: var(--mobile-nav-button-padding-top) var(--mobile-nav-button-padding-inline) var(--mobile-nav-button-padding-bottom);
+    border: 1px solid transparent;
+    border-radius: var(--radius-xl);
+    background: transparent;
+    color: var(--color-text-muted);
+    transition:
+      background 160ms var(--easing-standard),
+      color 160ms var(--easing-standard),
+      border-color 160ms var(--easing-standard),
+      transform 180ms var(--easing-standard);
+  }
+
+  .navButton:hover,
+  .navButton:focus-visible {
+    color: var(--color-text);
+    background: color-mix(in srgb, var(--color-surface) 82%, transparent);
+    border-color: color-mix(in srgb, var(--color-border-strong) 28%, transparent);
+  }
+
+  .navButton:active {
+    transform: translateY(calc(var(--space-1) / 2));
+  }
+
+  .navButtonActive {
+    color: var(--color-text);
+    background: color-mix(in srgb, var(--color-surface) 90%, transparent);
+    border-color: color-mix(in srgb, var(--color-border-strong) 34%, transparent);
+    box-shadow: var(--shadow-soft);
+  }
+
+  .iconWrap {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  .label {
+    @include text-caption;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+}

Frontend/src/components/shell/MobileBottomNav/MobileBottomNav.tsx

@@ -0,0 +1,66 @@
+// Path: Frontend/src/components/shell/MobileBottomNav/MobileBottomNav.tsx
+
+import { For, type JSX } from "solid-js";
+import { useAppShellData } from "../data/app-shell.context";
+import { mobileBottomNavItems, type MobileBottomNavItem } from "../data/shell.data";
+import styles from "./MobileBottomNav.module.scss";
+
+type MobileBottomNavProps = {
+	isBrowseOpen: boolean;
+	onBrowseToggle: VoidFunction;
+};
+
+const MobileNavEntry = (props: {
+	item: MobileBottomNavItem;
+	isActive: boolean;
+	onSelect?: VoidFunction;
+}): JSX.Element => {
+	const Icon = props.item.icon;
+
+	return (
+		<button
+			type="button"
+			onClick={() => props.onSelect?.()}
+			classList={{
+				[styles.navButton]: true,
+				[styles.navButtonActive]: props.isActive,
+			}}
+			aria-current={props.isActive ? "page" : undefined}
+			aria-expanded={props.item.id === "browse" ? props.isActive : undefined}
+			aria-label={props.item.label}
+			title={props.item.label}
+		>
+			<span class={styles.iconWrap} aria-hidden="true">
+				<Icon size={18} strokeWidth={2} />
+			</span>
+
+			<span class={styles.label}>{props.item.label}</span>
+		</button>
+	);
+};
+
+export const MobileBottomNav = (props: MobileBottomNavProps): JSX.Element => {
+	const appShellData = useAppShellData();
+
+	return (
+		<nav class={styles.mobileNav} aria-label="Mobile workspace navigation">
+			<div class={styles.contextBar}>
+				<span class={styles.contextServer}>{appShellData.activeServer().name}</span>
+				<span class={styles.contextDivider}>/</span>
+				<span class={styles.contextProject}>{appShellData.activeProject().name}</span>
+			</div>
+
+			<div class={styles.navGrid}>
+				<For each={mobileBottomNavItems}>
+					{(item): JSX.Element => (
+						<MobileNavEntry
+							item={item}
+							isActive={item.id === "browse" ? props.isBrowseOpen : (item.active ?? false) && !props.isBrowseOpen}
+							onSelect={item.id === "browse" ? props.onBrowseToggle : undefined}
+						/>
+					)}
+				</For>
+			</div>
+		</nav>
+	);
+};

Frontend/src/components/shell/MobileWorkspaceBrowser/MobileWorkspaceBrowser.module.scss

@@ -0,0 +1,190 @@
+.browserLayer {
+  display: none;
+}
+
+@include respond-down(mobile) {
+  .browserLayer {
+    position: fixed;
+    inset: 0;
+    display: grid;
+    z-index: calc(var(--z-popover, 20) + 2);
+    background: color-mix(in srgb, var(--color-canvas) 96%, black 4%);
+  }
+
+	.sheet {
+    min-height: 100dvh;
+    display: grid;
+    grid-template-rows: auto minmax(0, 1fr);
+    background:
+      linear-gradient(180deg, color-mix(in srgb, var(--color-surface) 84%, transparent) 0%, transparent 8rem),
+      color-mix(in srgb, var(--color-canvas) 97%, black 3%);
+    overflow: clip;
+  }
+
+  .sheetHeader {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--space-3);
+    padding: calc(var(--space-5) + env(safe-area-inset-top, 0px)) var(--space-4) var(--space-4);
+    border-bottom: 1px solid color-mix(in srgb, var(--color-border) 84%, transparent);
+  }
+
+  .headerActions {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--space-2);
+  }
+
+  .brandBlock {
+    min-width: 0;
+    display: grid;
+    gap: var(--space-1);
+  }
+
+  .sectionLabel {
+    @include text-caption;
+    color: var(--color-text-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+  }
+
+  .brandEyebrow {
+    @include text-caption;
+    color: var(--color-text-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+  }
+
+  .brandTitle {
+    @include text-title;
+    color: var(--color-text);
+    font-weight: var(--font-weight-semibold);
+  }
+
+  .brandContext {
+    @include text-caption;
+    color: var(--color-text-subtle);
+  }
+
+  .closeButton {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--control-size-md);
+    height: var(--control-size-md);
+    padding: 0;
+    border: 1px solid color-mix(in srgb, var(--color-border) 92%, transparent);
+    border-radius: 999px;
+    background: color-mix(in srgb, var(--color-surface) 92%, transparent);
+    color: var(--color-text-subtle);
+  }
+
+  .createButton {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--space-2);
+    min-height: var(--control-size-md);
+    padding: 0 var(--space-3);
+    border: 1px solid color-mix(in srgb, var(--color-border-strong, var(--color-border)) 82%, transparent);
+    border-radius: 999px;
+    background: color-mix(in srgb, var(--color-surface) 94%, var(--color-canvas) 6%);
+    color: var(--color-text);
+    box-shadow: var(--shadow-soft);
+    font: inherit;
+    font-weight: var(--font-weight-semibold);
+  }
+
+  .sheetBody {
+    min-height: 0;
+    display: grid;
+    gap: var(--space-5);
+    padding: var(--space-5) var(--space-5) calc(var(--space-12) + var(--space-10) + env(safe-area-inset-bottom, 0px));
+    overflow: auto;
+  }
+
+  .sectionBlock {
+    display: grid;
+    gap: var(--space-2);
+  }
+
+  .treeList,
+  .treeListItem {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  .treeList {
+    display: grid;
+    gap: 0;
+    border-top: 1px solid color-mix(in srgb, var(--color-border) 92%, transparent);
+  }
+
+  .treeListNested {
+    display: grid;
+    gap: 0;
+  }
+
+  .treeRow {
+    min-width: 0;
+    width: 100%;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--space-3);
+    min-height: calc(var(--control-size-lg) + var(--space-3));
+    padding: var(--space-4) var(--space-2) var(--space-4) calc(var(--space-2) + (var(--tree-depth, 0) * var(--space-4)));
+    border: 0;
+    border-bottom: 1px solid color-mix(in srgb, var(--color-border) 92%, transparent);
+    border-radius: 0;
+    background: transparent;
+    color: var(--color-text);
+    text-align: left;
+  }
+
+  .treeRowActive {
+    color: var(--color-text);
+    background: color-mix(in srgb, var(--color-surface) 72%, transparent);
+  }
+
+  .treeRowBranch {
+    font-weight: var(--font-weight-semibold);
+  }
+
+  .treeRowLead,
+  .treeRowTrail {
+    min-width: 0;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--space-2);
+  }
+
+  .treeRowTrail {
+    flex: 0 0 auto;
+    color: var(--color-text-muted);
+  }
+
+  .treeLabel {
+    @include text-label;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .treeMeta {
+    @include text-caption;
+    min-width: 1rem;
+    text-align: right;
+  }
+
+  .treeChevron {
+    color: var(--color-text-subtle);
+  }
+
+  .treeListNested > .treeListItem > .treeRow {
+    min-height: calc(var(--control-size-lg) + var(--space-1));
+  }
+}

Frontend/src/components/shell/MobileWorkspaceBrowser/MobileWorkspaceBrowser.tsx

@@ -0,0 +1,247 @@
+import { For, Show, createSignal, type JSX } from "solid-js";
+import { ChevronRight, Plus, X } from "../../../lib/icons";
+import { useAppShellData } from "../data/app-shell.context";
+import { createLongPressGesture } from "../createLongPressGesture";
+import {
+	createWorkspaceStaticTarget,
+	createWorkspaceSurfaceTarget,
+	createWorkspaceTreeTarget,
+	getWorkspaceNodeIcon,
+	workspaceStaticItems,
+	type SidebarItem,
+	type WorkspaceContextMenuAction,
+	type WorkspaceContextMenuTarget,
+	type WorkspaceStaticItem,
+	type WorkspaceTreeNode,
+} from "../data/shell.data";
+import { WorkspaceMobileActionSheet } from "../WorkspaceMobileActionSheet/WorkspaceMobileActionSheet";
+import styles from "./MobileWorkspaceBrowser.module.scss";
+
+type MobileWorkspaceBrowserProps = {
+	open: boolean;
+	onClose: VoidFunction;
+};
+
+const TreeRow = (props: { node: WorkspaceTreeNode; depth?: number }): JSX.Element => {
+	const depth = props.depth ?? 0;
+	const Icon = getWorkspaceNodeIcon(props.node);
+	const hasChildren = (props.node.children?.length ?? 0) > 0;
+
+	return (
+		<button
+			classList={{
+				[styles.treeRow]: true,
+				[styles.treeRowActive]: props.node.active ?? false,
+				[styles.treeRowBranch]: hasChildren,
+			}}
+			type="button"
+			style={{ "--tree-depth": `${depth}` }}
+			data-slot="mobile-workspace-tree-row"
+			data-kind={props.node.kind}
+			data-item-type={props.node.kind === "item" ? props.node.itemType : undefined}
+			data-active={props.node.active ? "true" : "false"}
+		>
+			<span class={styles.treeRowLead}>
+				<Icon size={16} strokeWidth={2} />
+				<span class={styles.treeLabel}>{props.node.label}</span>
+			</span>
+
+			<span class={styles.treeRowTrail}>
+				<Show when={props.node.meta}>
+					<span class={styles.treeMeta}>{props.node.meta}</span>
+				</Show>
+				<Show when={hasChildren}>
+					<ChevronRight size={14} strokeWidth={2} class={styles.treeChevron} />
+				</Show>
+			</span>
+		</button>
+	);
+};
+
+const StaticRow = (props: { item: SidebarItem }): JSX.Element => {
+	const Icon = props.item.icon;
+
+	return (
+		<button classList={{ [styles.treeRow]: true, [styles.treeRowActive]: props.item.active ?? false }} type="button" style={{ "--tree-depth": "0" }} data-slot="mobile-workspace-static-row" data-active={props.item.active ? "true" : "false"}>
+			<span class={styles.treeRowLead}>
+				<Icon size={16} strokeWidth={2} />
+				<span class={styles.treeLabel}>{props.item.label}</span>
+			</span>
+			<span class={styles.treeRowTrail}>
+				<Show when={props.item.meta}>
+					<span class={styles.treeMeta}>{props.item.meta}</span>
+				</Show>
+				<ChevronRight size={14} strokeWidth={2} class={styles.treeChevron} />
+			</span>
+		</button>
+	);
+};
+const WorkspaceStaticRow = (props: {
+	item: WorkspaceStaticItem;
+	onOpenActionSheet: (target: WorkspaceContextMenuTarget) => void;
+}): JSX.Element => {
+	const target = createWorkspaceStaticTarget(props.item);
+	const longPress = createLongPressGesture({
+		onLongPress: () => {
+			props.onOpenActionSheet(target);
+		},
+	});
+
+	return (
+		<li
+			class={styles.treeListItem}
+			data-slot="mobile-workspace-static-item"
+			data-target-kind={target.kind}
+			onContextMenu={(event): void => {
+				event.preventDefault();
+				props.onOpenActionSheet(target);
+			}}
+			{...longPress}
+		>
+			<StaticRow item={props.item} />
+		</li>
+	);
+};
+
+const WorkspaceTreeBranch = (props: {
+	nodes: readonly WorkspaceTreeNode[];
+	depth?: number;
+	onOpenActionSheet: (target: WorkspaceContextMenuTarget) => void;
+}): JSX.Element => {
+	const depth = props.depth ?? 0;
+
+	return (
+		<For each={props.nodes}>
+			{(node): JSX.Element => {
+				const target = createWorkspaceTreeTarget(node);
+				const longPress = createLongPressGesture({
+					onLongPress: () => {
+						props.onOpenActionSheet(target);
+					},
+				});
+
+				return (
+					<li
+						class={styles.treeListItem}
+						data-slot="mobile-workspace-tree-item"
+						data-kind={node.kind}
+						data-item-type={node.kind === "item" ? node.itemType : undefined}
+						onContextMenu={(event): void => {
+							event.preventDefault();
+							props.onOpenActionSheet(target);
+						}}
+						{...longPress}
+					>
+						<TreeRow node={node} depth={depth} />
+
+						<Show when={node.children?.length}>
+							<ul class={styles.treeListNested}>
+								<WorkspaceTreeBranch nodes={node.children ?? []} depth={depth + 1} onOpenActionSheet={props.onOpenActionSheet} />
+							</ul>
+						</Show>
+					</li>
+				);
+			}}
+		</For>
+	);
+};
+
+export const MobileWorkspaceBrowser = (props: MobileWorkspaceBrowserProps): JSX.Element => {
+	const appShellData = useAppShellData();
+	const [actionSheetTarget, setActionSheetTarget] = createSignal<WorkspaceContextMenuTarget | null>(null);
+	const sectionNodes = () => appShellData.workspaceTree().filter((node) => (node.children?.length ?? 0) > 0);
+	const looseNodes = () => appShellData.workspaceTree().filter((node) => (node.children?.length ?? 0) === 0);
+	const workspaceTarget = () => createWorkspaceSurfaceTarget(appShellData.activeProject());
+	const openActionSheet = (target: WorkspaceContextMenuTarget): void => {
+		setActionSheetTarget(target);
+	};
+	const closeActionSheet = (): void => {
+		setActionSheetTarget(null);
+	};
+	const openWorkspaceActionSheet = (): void => {
+		openActionSheet(workspaceTarget());
+	};
+
+	const handleActionSelect = (_action: WorkspaceContextMenuAction, _target: WorkspaceContextMenuTarget): void => {
+		// Mobile first pass only establishes the action-sheet IA and long-press behavior.
+	};
+
+	const workspaceLongPress = createLongPressGesture({
+		onLongPress: openWorkspaceActionSheet,
+	});
+
+	return (
+		<Show when={props.open}>
+			<div class={styles.browserLayer} data-ui="mobile-workspace-browser">
+				<section class={styles.sheet} aria-label="Mobile workspace browser" data-slot="mobile-workspace-sheet">
+					<header class={styles.sheetHeader} data-slot="mobile-workspace-header">
+						<div
+							class={styles.brandBlock}
+							data-slot="mobile-workspace-brand"
+							onContextMenu={(event): void => {
+								event.preventDefault();
+								openWorkspaceActionSheet();
+							}}
+							{...workspaceLongPress}
+						>
+							{/* Long-pressing the browser header exposes workspace-level actions on mobile. */}
+							<span class={styles.brandEyebrow}>Moku Work</span>
+							<strong class={styles.brandTitle}>{appShellData.activeProject().name}</strong>
+							<span class={styles.brandContext}>{appShellData.activeServer().name}</span>
+						</div>
+
+						<div class={styles.headerActions} data-slot="mobile-workspace-header-actions">
+							<button
+								class={styles.createButton}
+								type="button"
+								aria-label="Create"
+								data-slot="mobile-workspace-create"
+								onClick={openWorkspaceActionSheet}
+							>
+								<Plus size={16} strokeWidth={2.25} />
+								<span>Create</span>
+							</button>
+
+							<button class={styles.closeButton} type="button" aria-label="Close workspace browser" data-slot="mobile-workspace-close" onClick={props.onClose}>
+								<X size={18} strokeWidth={2} />
+							</button>
+						</div>
+					</header>
+
+					<div class={styles.sheetBody} data-slot="mobile-workspace-body">
+						<section class={styles.sectionBlock} data-slot="mobile-workspace-section" data-section-id="workspace">
+							<span class={styles.sectionLabel}>Workspace</span>
+							<ul class={styles.treeList} data-slot="mobile-workspace-list" data-section-id="workspace">
+						<For each={workspaceStaticItems}>
+							{(item): JSX.Element => <WorkspaceStaticRow item={item} onOpenActionSheet={openActionSheet} />}
+						</For>
+							</ul>
+						</section>
+
+						<section class={styles.sectionBlock} data-slot="mobile-workspace-section" data-section-id="items">
+							<span class={styles.sectionLabel}>Items</span>
+							<ul class={styles.treeList} data-slot="mobile-workspace-list" data-section-id="items">
+								<WorkspaceTreeBranch nodes={sectionNodes()} onOpenActionSheet={openActionSheet} />
+							</ul>
+						</section>
+
+						<Show when={looseNodes().length > 0}>
+							<section class={styles.sectionBlock} data-slot="mobile-workspace-section" data-section-id="more">
+								<span class={styles.sectionLabel}>More</span>
+								<ul class={styles.treeList} data-slot="mobile-workspace-list" data-section-id="more">
+									<WorkspaceTreeBranch nodes={looseNodes()} onOpenActionSheet={openActionSheet} />
+								</ul>
+							</section>
+						</Show>
+					</div>
+				</section>
+
+				<WorkspaceMobileActionSheet
+					target={actionSheetTarget()}
+					onClose={closeActionSheet}
+					onSelect={handleActionSelect}
+				/>
+			</div>
+		</Show>
+	);
+};

Frontend/src/components/shell/ProjectContextMenu/ProjectContextMenu.tsx

@@ -0,0 +1,204 @@
+import { For, Show, createEffect, createMemo, createSignal, onMount, type JSX } from "solid-js";
+import { Portal } from "solid-js/web";
+import { ChevronRight, Plus } from "../../../lib/icons";
+import {
+	getProjectContextMenuEyebrow,
+	getProjectContextMenuSections,
+	type ProjectContextMenuAction,
+	type ProjectMenuTarget,
+	type WorkspaceContextMenuShortcut,
+} from "../data/shell.data";
+import styles from "../WorkspaceContextMenu/WorkspaceContextMenu.module.scss";
+
+type ShortcutPlatform = "mac" | "windows";
+
+type NavigatorWithUserAgentData = Navigator & {
+	userAgentData?: {
+		platform?: string;
+	};
+};
+
+type ProjectContextMenuPosition = {
+	x: number;
+	y: number;
+};
+
+type ProjectContextMenuProps = {
+	target: ProjectMenuTarget | null;
+	position: ProjectContextMenuPosition | null;
+	onClose: VoidFunction;
+	onSelect: (action: ProjectContextMenuAction, target: ProjectMenuTarget) => void;
+	menuRef: (element: HTMLDivElement) => void;
+};
+
+const getShortcutPlatform = (): ShortcutPlatform => {
+	if (typeof navigator === "undefined") {
+		return "mac";
+	}
+
+	const navigatorWithUserAgentData = navigator as NavigatorWithUserAgentData;
+	const platform =
+		typeof navigatorWithUserAgentData.userAgentData?.platform === "string"
+			? navigatorWithUserAgentData.userAgentData.platform
+			: navigator.platform;
+
+	return /mac|iphone|ipad|ipod/i.test(platform) ? "mac" : "windows";
+};
+
+const formatShortcut = (shortcut: WorkspaceContextMenuShortcut, platform: ShortcutPlatform): string => {
+	const keyLabel = (() => {
+		switch (shortcut.key) {
+			case "enter":
+				return platform === "mac" ? "↩" : "Enter";
+			case "delete":
+				return platform === "mac" ? "⌫" : "Del";
+			default:
+				return shortcut.key.toUpperCase();
+		}
+	})();
+
+	const modifierLabels =
+		shortcut.modifiers?.map((modifier) => {
+			switch (modifier) {
+				case "meta":
+					return platform === "mac" ? "⌘" : "Ctrl";
+				case "alt":
+					return platform === "mac" ? "⌥" : "Alt";
+				case "shift":
+					return platform === "mac" ? "⇧" : "Shift";
+			}
+		}) ?? [];
+
+	return platform === "mac" ? `${modifierLabels.join("")}${keyLabel}` : [...modifierLabels, keyLabel].join("+");
+};
+
+export const ProjectContextMenu = (props: ProjectContextMenuProps): JSX.Element => {
+	const [activeSubmenuActionId, setActiveSubmenuActionId] = createSignal<string | null>(null);
+	const [shortcutPlatform, setShortcutPlatform] = createSignal<ShortcutPlatform>("mac");
+	const sections = createMemo(() => (props.target ? getProjectContextMenuSections(props.target) : []));
+	const isCreateAction = (action: ProjectContextMenuAction): boolean => action.id.startsWith("new-");
+	const menuState = createMemo<{
+		target: ProjectMenuTarget;
+		position: ProjectContextMenuPosition;
+	} | null>(() => (props.target && props.position ? { target: props.target, position: props.position } : null));
+
+	onMount(() => {
+		setShortcutPlatform(getShortcutPlatform());
+	});
+
+	createEffect(() => {
+		void props.target;
+		setActiveSubmenuActionId(null);
+	});
+
+	return (
+		<Show when={menuState()}>
+			{(resolvedMenuState): JSX.Element => {
+				const target = resolvedMenuState().target;
+				const position = resolvedMenuState().position;
+
+				return (
+					<Portal>
+						<div
+							ref={props.menuRef}
+							class={styles.menu}
+							role="menu"
+							aria-label={`${target.label} project context menu`}
+							style={{ left: `${position.x}px`, top: `${position.y}px` }}
+						>
+							<Show when={target.kind !== "surface"}>
+								<header class={styles.header}>
+									<span class={styles.eyebrow}>{getProjectContextMenuEyebrow(target)}</span>
+									<strong class={styles.title}>{target.label}</strong>
+								</header>
+							</Show>
+
+							<div class={styles.sectionList}>
+								<For each={sections()}>
+									{(section): JSX.Element => (
+										<section class={styles.section}>
+											<Show when={section.label}>
+												<span class={styles.sectionLabel}>{section.label}</span>
+											</Show>
+											<div class={styles.actionList}>
+												<For each={section.items}>
+													{(action): JSX.Element => {
+														const isSubmenuOpen = () => activeSubmenuActionId() === action.id;
+
+														return (
+															<div class={styles.actionItem} onMouseEnter={() => setActiveSubmenuActionId(action.children ? action.id : null)}>
+												<button
+													type="button"
+													role="menuitem"
+													classList={{
+														[styles.action]: true,
+														[styles.actionCreate]: isCreateAction(action),
+														[styles.actionDanger]: action.tone === "danger",
+														[styles.actionSubmenuOpen]: isSubmenuOpen(),
+													}}
+																	onClick={() => {
+																		if (action.children) {
+																			setActiveSubmenuActionId(isSubmenuOpen() ? null : action.id);
+																			return;
+																		}
+
+														props.onSelect(action, target);
+														props.onClose();
+													}}
+												>
+													<Show when={isCreateAction(action)}>
+														<span class={styles.actionCreateIcon} aria-hidden="true">
+															<Plus size={14} strokeWidth={2.25} />
+														</span>
+													</Show>
+																	<span class={styles.actionLabel}>{action.label}</span>
+																	<div class={styles.actionMeta}>
+																		<Show when={action.shortcut}>
+																			<span class={styles.actionShortcut}>{formatShortcut(action.shortcut!, shortcutPlatform())}</span>
+																		</Show>
+																		<Show when={action.children}>
+																			<ChevronRight class={styles.actionChevron} size={16} strokeWidth={2} />
+																		</Show>
+																	</div>
+																</button>
+
+																<Show when={action.children && isSubmenuOpen()}>
+																	<div class={styles.submenu} role="menu" aria-label={`${action.label} submenu`}>
+																		<div class={styles.submenuList}>
+																			<For each={action.children ?? []}>
+																				{(childAction): JSX.Element => (
+																					<button
+																						type="button"
+																						role="menuitem"
+																						classList={{
+																							[styles.action]: true,
+																							[styles.actionDanger]: childAction.tone === "danger",
+																						}}
+																						onClick={() => {
+																							props.onSelect(childAction, target);
+																							props.onClose();
+																						}}
+																					>
+																						<span class={styles.actionLabel}>{childAction.label}</span>
+																					</button>
+																				)}
+																			</For>
+																		</div>
+																	</div>
+																</Show>
+															</div>
+														);
+													}}
+												</For>
+											</div>
+										</section>
+									)}
+								</For>
+							</div>
+						</div>
+					</Portal>
+				);
+			}}
+		</Show>
+	);
+};

Frontend/src/components/shell/ProjectContextMenu/createProjectContextMenuController.ts

@@ -0,0 +1,120 @@
+import { createEffect, createSignal, onCleanup } from "solid-js";
+import type { ProjectMenuTarget } from "../data/shell.data";
+
+type ProjectContextMenuState = {
+	target: ProjectMenuTarget;
+	x: number;
+	y: number;
+};
+
+const readRootPixelToken = (name: string, fallback: number): number => {
+	if (typeof window === "undefined") {
+		return fallback;
+	}
+
+	const value = window.getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+	const parsed = Number.parseFloat(value);
+
+	if (!Number.isFinite(parsed)) {
+		return fallback;
+	}
+
+	if (value.endsWith("px")) {
+		return parsed;
+	}
+
+	return parsed * 16;
+};
+
+const clampMenuPosition = (value: number, min: number, max: number): number => {
+	if (max <= min) {
+		return min;
+	}
+
+	return Math.min(Math.max(value, min), max);
+};
+
+export const createProjectContextMenuController = () => {
+	const [menuState, setMenuState] = createSignal<ProjectContextMenuState | null>(null);
+	let menuRef: HTMLDivElement | undefined;
+
+	const closeMenu = (): void => {
+		setMenuState(null);
+	};
+
+	const repositionMenu = (): void => {
+		if (typeof window === "undefined" || !menuRef) {
+			return;
+		}
+
+		const current = menuState();
+
+		if (!current) {
+			return;
+		}
+
+		const viewportPadding = readRootPixelToken("--space-4", 16);
+		const rect = menuRef.getBoundingClientRect();
+		const nextX = clampMenuPosition(current.x, viewportPadding, window.innerWidth - rect.width - viewportPadding);
+		const nextY = clampMenuPosition(current.y, viewportPadding, window.innerHeight - rect.height - viewportPadding);
+
+		if (nextX === current.x && nextY === current.y) {
+			return;
+		}
+
+		setMenuState({ ...current, x: nextX, y: nextY });
+	};
+
+	const openMenu = (event: MouseEvent, target: ProjectMenuTarget): void => {
+		event.preventDefault();
+		setMenuState({ target, x: event.clientX, y: event.clientY });
+	};
+
+	createEffect(() => {
+		if (!menuState() || typeof window === "undefined") {
+			return;
+		}
+
+		const frame = window.requestAnimationFrame(() => {
+			repositionMenu();
+		});
+
+		const handlePointerDown = (event: PointerEvent): void => {
+			if (!menuRef?.contains(event.target as Node)) {
+				closeMenu();
+			}
+		};
+
+		const handleKeyDown = (event: KeyboardEvent): void => {
+			if (event.key === "Escape") {
+				closeMenu();
+			}
+		};
+
+		const handleViewportChange = (): void => {
+			closeMenu();
+		};
+
+		document.addEventListener("pointerdown", handlePointerDown);
+		window.addEventListener("resize", handleViewportChange);
+		window.addEventListener("scroll", handleViewportChange, true);
+		window.addEventListener("keydown", handleKeyDown);
+
+		onCleanup(() => {
+			window.cancelAnimationFrame(frame);
+			document.removeEventListener("pointerdown", handlePointerDown);
+			window.removeEventListener("resize", handleViewportChange);
+			window.removeEventListener("scroll", handleViewportChange, true);
+			window.removeEventListener("keydown", handleKeyDown);
+		});
+	});
+
+	return {
+		menuState,
+		openMenu,
+		closeMenu,
+		setMenuRef: (element: HTMLDivElement): void => {
+			menuRef = element;
+		},
+	};
+};

Frontend/src/components/shell/ProjectSelector/ProjectSelector.module.scss

@@ -1,8 +1,23 @@
+@use "../shared/tree-nav" as treeNav;
+
 .root {
   display: grid;
   --project-drawer-gap: var(--space-3);
   --project-drawer-top: calc(var(--space-4) + var(--control-size-lg));
-  --project-drawer-bottom: calc(var(--sidebar-dock-clearance) + var(--project-drawer-gap));
+  --project-drawer-bottom: calc(var(--sidebar-dock-clearance, var(--shell-dock-clearance)) + var(--project-drawer-gap));
+}
+
+.rootCompact {
+  justify-items: center;
+}
+
+.rootDragMode {
+	user-select: none;
+	cursor: grabbing;
+}
+
+.rootDragMode .treeItem {
+	cursor: grabbing;
 }
 
 .trigger {
@@ -34,9 +49,32 @@
 }
 
 .triggerOpen {
-  border-color: color-mix(in srgb, var(--color-border-strong) 22%, transparent);
-  background: color-mix(in srgb, var(--color-surface) 92%, transparent);
-  box-shadow: var(--shadow-soft);
+  border-color: color-mix(in srgb, var(--color-accent-strong) 22%, var(--color-border-strong));
+  background: color-mix(in srgb, var(--color-accent-soft) 26%, var(--color-surface));
+  box-shadow: 0 10px 28px color-mix(in srgb, black 8%, transparent);
+}
+
+.triggerCompact {
+  width: var(--control-size-xl);
+  min-height: var(--control-size-xl);
+  grid-template-columns: auto;
+  justify-items: center;
+  gap: 0.15rem;
+  padding: var(--space-2) 0;
+  border-radius: var(--radius-xl);
+}
+
+.triggerCompact .triggerLead {
+  width: var(--control-size-md);
+  height: var(--control-size-md);
+}
+
+.triggerCompact .triggerIcon {
+  transform: rotate(0deg);
+}
+
+.triggerCompact .triggerIconOpen {
+  transform: rotate(180deg);
 }
 
 .triggerLead {
@@ -56,19 +94,14 @@
   gap: 0.12rem;
 }
 
-.eyebrow,
-.projectItemDescription {
+.eyebrow {
   @include text-caption;
   color: var(--color-text-muted);
-}
-
-.eyebrow {
   text-transform: uppercase;
   letter-spacing: 0.08em;
 }
 
-.value,
-.projectItemName {
+.value {
   @include text-label;
 }
 
@@ -99,6 +132,13 @@
   pointer-events: auto;
 }
 
+.rootCompact .scrim,
+.rootCompact .drawer {
+  left: 0;
+  right: auto;
+  width: min(18rem, calc(100vw - 6rem));
+}
+
 .drawer {
   position: absolute;
   inset: calc(var(--project-drawer-top) + var(--project-drawer-gap)) var(--space-4)
@@ -141,7 +181,7 @@
   min-height: 0;
   display: grid;
   align-content: start;
-  gap: var(--space-3);
+  gap: var(--space-2);
   padding: var(--space-4);
   overflow-y: auto;
   overscroll-behavior: contain;
@@ -152,49 +192,132 @@
 	width: 0;
 }
 
-.projectList {
-  list-style: none;
-  display: grid;
-  gap: 0.2rem;
-  padding: 0;
+.treeSectionLabel {
+	@include treeNav.section-label;
+  margin: 0;
+  padding: 0 var(--space-3);
 }
 
-.projectItem {
-  width: 100%;
-  min-width: 0;
-  min-height: calc(var(--control-size-md) + var(--space-2));
-  padding: var(--space-2) var(--space-3);
-  border: 1px solid transparent;
-  border-radius: var(--radius-sm);
-  background: transparent;
+.treeSectionHeader {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: var(--space-2);
+	margin-bottom: var(--space-2);
+	padding-right: var(--space-1);
+}
+
+.treeControls {
+	display: inline-flex;
+	align-items: center;
+	gap: var(--space-1);
+	flex-wrap: wrap;
+	justify-content: flex-end;
+}
+
+.treeControlButton {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	width: calc(var(--control-size-md) - var(--space-1));
+	height: calc(var(--control-size-md) - var(--space-1));
+	@include text-caption;
+	padding: 0;
+	border: 1px solid color-mix(in srgb, var(--color-border) 46%, transparent);
+	border-radius: var(--radius-pill);
+	background: color-mix(in srgb, var(--color-surface) 95%, transparent);
 	color: var(--color-text-muted);
 	transition:
-    background 160ms var(--easing-standard),
-    color 160ms var(--easing-standard),
 		border-color 160ms var(--easing-standard),
-    transform 180ms var(--easing-standard);
-  text-align: left;
+		background 160ms var(--easing-standard),
+		color 160ms var(--easing-standard);
 }
 
-.projectItem:hover {
-  background: color-mix(in srgb, var(--color-surface-hover) 82%, transparent);
+.treeControlButton:hover,
+.treeControlButton:focus-visible {
+	border-color: color-mix(in srgb, var(--color-border-strong) 56%, transparent);
+	background: var(--color-surface-hover);
 	color: var(--color-text);
-  border-color: color-mix(in srgb, var(--color-border) 22%, transparent);
+	outline: none;
 }
 
-.projectItemActive {
-  border-color: color-mix(in srgb, var(--color-border) 28%, transparent);
-  background: color-mix(in srgb, var(--color-surface) 82%, transparent);
-  color: var(--color-text);
-  box-shadow: none;
+.treeControlButton:disabled {
+	opacity: 0.45;
+	cursor: default;
 }
 
-.projectItemCopy {
-  min-width: 0;
-  display: grid;
-  gap: 0.05rem;
+.treeList {
+	@include treeNav.tree-list;
 }
 
-.projectItemDescription {
-  color: color-mix(in srgb, var(--color-text-muted) 84%, transparent);
+.treeEmptySlot {
+	@include treeNav.empty-slot;
+}
+
+.treeInputRow {
+	@include treeNav.input-row;
+}
+
+.treeInput {
+	@include treeNav.input;
+}
+
+.treeItem {
+	@include treeNav.item;
+}
+
+.treeItem:hover,
+.treeItem:focus-visible {
+	@include treeNav.item-hover;
+}
+
+.treeItemFolder {
+	@include treeNav.item-folder;
+}
+
+.treeItemDragging {
+	@include treeNav.item-dragging;
+}
+
+.treeItemDropBefore {
+	@include treeNav.item-drop-before;
+}
+
+.treeItemDropAfter {
+	@include treeNav.item-drop-after;
+}
+
+.treeItemDropInside {
+	@include treeNav.item-drop-inside;
+}
+
+.folderChevron {
+	@include treeNav.folder-chevron;
+}
+
+.folderChevronOpen {
+	@include treeNav.folder-chevron-open;
+}
+
+.treeItemActive {
+	@include treeNav.item-active;
+}
+
+.icon {
+	@include treeNav.icon;
+}
+
+.label {
+	@include treeNav.label;
+}
+
+.itemMeta {
+	@include treeNav.item-meta;
+}
+
+@media (max-width: 720px) {
+  .rootCompact .scrim,
+  .rootCompact .drawer {
+    width: min(18rem, calc(100vw - 5rem));
+  }
 }

Frontend/src/components/shell/ServerDock/ServerDock.tsx

@@ -1,38 +1,41 @@
 // Path: Frontend/src/components/shell/ServerDock/ServerDock.tsx
 
 import { For, Show, type JSX } from "solid-js";
-import { activeServer } from "../data/shell.data";
+import { useAppShellData } from "../data/app-shell.context";
 import styles from "./ServerDock.module.scss";
 
 export const ServerDock = (): JSX.Element => {
+	const appShellData = useAppShellData();
+	const activeServer = () => appShellData.activeServer();
+
 	return (
-		<section class={styles.panel} aria-label="Server dock">
-			<div class={styles.identity}>
+		<section class={styles.panel} aria-label="Server dock" data-ui="server-dock" data-server-kind={activeServer().kind}>
+			<div class={styles.identity} data-slot="server-dock-identity">
 				<div class={styles.glyph} aria-hidden="true">
-					{activeServer.abbreviation}
+					{activeServer().abbreviation}
 				</div>
-				<div class={styles.copy}>
-					<span class={styles.name}>{activeServer.name}</span>
+				<div class={styles.copy} data-slot="server-dock-copy">
+					<span class={styles.name}>{activeServer().name}</span>
 					<Show
-						when={activeServer.kind === "organization"}
-						fallback={<span class={styles.subtitle}>{activeServer.subtitle}</span>}
+						when={activeServer().kind === "organization"}
+						fallback={<span class={styles.subtitle}>{activeServer().subtitle}</span>}
 					>
 						<span class={styles.status}>
 							<span class={styles.statusDot} aria-hidden="true" />
-							<span>{activeServer.connectedLabel}</span>
+							<span>{activeServer().connectedLabel}</span>
 						</span>
 					</Show>
 				</div>
 			</div>
 
-			<Show when={activeServer.dockActions.length > 0}>
-				<div class={styles.actions}>
-					<For each={activeServer.dockActions}>
+			<Show when={activeServer().dockActions.length > 0}>
+				<div class={styles.actions} data-slot="server-dock-actions">
+					<For each={activeServer().dockActions}>
 						{(item): JSX.Element => {
 							const Icon = item.icon;
 
 							return (
-								<button type="button" class={styles.action} aria-label={item.label} title={item.label}>
+								<button type="button" class={styles.action} aria-label={item.label} title={item.label} data-slot="server-dock-action" data-action-id={item.id}>
 									<Icon size={16} strokeWidth={2} />
 									<span class={styles.actionLabel}>{item.label}</span>
 								</button>

Frontend/src/components/shell/TopBar/NotificationsButton.module.scss

@@ -0,0 +1,66 @@
+.button {
+	display: inline-flex;
+	justify-content: center;
+	align-items: center;
+	width: 2.75rem;
+	height: 2.75rem;
+	aspect-ratio: 1;
+	padding: 0;
+	border: 0;
+	border-radius: 999px;
+	flex-shrink: 0;
+	cursor: pointer;
+	background: transparent;
+	color: var(--color-text-muted);
+	transition:
+		background-color 220ms var(--easing-standard),
+		color 220ms var(--easing-standard),
+		transform 180ms var(--easing-standard);
+}
+
+.button:hover {
+	background: color-mix(in srgb, var(--color-text) 8%, transparent);
+	color: var(--color-text);
+}
+
+.buttonOpen {
+	background: color-mix(in srgb, var(--color-surface) 92%, transparent);
+	color: var(--color-text);
+}
+
+.button:focus-visible {
+	outline: none;
+	background: color-mix(in srgb, var(--color-accent-strong) 12%, transparent);
+	box-shadow: 0 0 0 0.12rem color-mix(in srgb, var(--color-accent-strong) 28%, transparent);
+	color: var(--color-text);
+}
+
+.iconWrap {
+	position: relative;
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	width: 1.5rem;
+	height: 1.5rem;
+}
+
+.badge {
+	@include text-caption;
+	position: absolute;
+	top: -0.45rem;
+	right: -0.7rem;
+	min-width: 1rem;
+	height: 1rem;
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	padding: 0 0.24rem;
+	border: 1px solid color-mix(in srgb, var(--color-surface) 68%, transparent);
+	border-radius: 999px;
+	background: color-mix(in srgb, var(--color-primary-3) 84%, black 16%);
+	color: white;
+	font-weight: var(--font-weight-semibold);
+	line-height: 1;
+	box-shadow: 0 6px 14px color-mix(in srgb, black 18%, transparent);
+	pointer-events: none;
+}

Frontend/src/components/shell/TopBar/NotificationsButton.tsx

@@ -0,0 +1,36 @@
+import type { JSX } from "solid-js";
+import { Bell } from "../../../lib/icons";
+import { unreadNotificationCount } from "../data/shell.data";
+import styles from "./NotificationsButton.module.scss";
+
+type NotificationsButtonProps = {
+	isOpen: boolean;
+	menuId: string;
+	onToggle: () => void;
+};
+
+export const NotificationsButton = (props: NotificationsButtonProps): JSX.Element => {
+	const hasUnread = unreadNotificationCount > 0;
+	const unreadLabel = hasUnread ? `, ${unreadNotificationCount} unread` : "";
+
+	return (
+		<button
+			classList={{
+				[styles.button]: true,
+				[styles.buttonOpen]: props.isOpen,
+			}}
+			type="button"
+			aria-label={`${props.isOpen ? "Close" : "Open"} notifications${unreadLabel}`}
+			title={`${props.isOpen ? "Close" : "Open"} notifications`}
+			aria-haspopup="menu"
+			aria-controls={props.menuId}
+			aria-expanded={props.isOpen}
+			onClick={props.onToggle}
+		>
+			<span class={styles.iconWrap} aria-hidden="true">
+				<Bell size={18} strokeWidth={2} />
+				{hasUnread ? <span class={styles.badge}>{unreadNotificationCount}</span> : null}
+			</span>
+		</button>
+	);
+};

Frontend/src/components/shell/TopBar/NotificationsMenu.module.scss

@@ -0,0 +1,271 @@
+.menu {
+	position: absolute;
+	top: calc(100% + var(--space-2));
+	right: 0;
+	width: min(24rem, calc(100vw - (var(--space-4) * 2)));
+	display: grid;
+	gap: var(--space-3);
+	padding: var(--space-3);
+	border: 1px solid var(--color-border-strong);
+	border-radius: calc(var(--radius-lg) + (var(--space-1) / 2));
+	background: color-mix(in srgb, var(--color-surface-muted) 96%, transparent);
+	box-shadow: var(--shadow-strong);
+	backdrop-filter: blur(var(--blur-overlay));
+	z-index: var(--z-dropdown);
+}
+
+.menu.menuWorkspace {
+	position: static;
+	top: auto;
+	right: auto;
+	left: auto;
+	bottom: auto;
+	width: 100%;
+	max-width: none;
+	height: 100%;
+	min-height: 0;
+	display: grid;
+	grid-template-rows: auto minmax(0, 1fr) auto;
+	gap: var(--space-4);
+	padding: var(--space-4);
+	border: 0;
+	border-radius: 0;
+	background: transparent;
+	box-shadow: none;
+	backdrop-filter: none;
+	z-index: auto;
+	overflow: hidden;
+}
+
+.header,
+.footer {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: var(--space-3);
+}
+
+.header {
+	padding-bottom: var(--space-3);
+	border-bottom: 1px solid var(--color-border);
+}
+
+.headerCopy {
+	min-width: 0;
+	display: grid;
+	gap: calc(var(--space-1) / 2);
+}
+
+.title {
+	@include text-label;
+	color: var(--color-text);
+}
+
+.subtitle,
+.sectionLabel,
+.itemMeta,
+.itemTime {
+	@include text-caption;
+	color: var(--color-text-muted);
+}
+
+.headerAction,
+.footerAction {
+	@include text-caption;
+	display: inline-flex;
+	align-items: center;
+	gap: var(--space-1);
+	padding: 0;
+	border: 0;
+	background: transparent;
+	color: var(--color-text-muted);
+	transition: color 160ms var(--easing-standard);
+}
+
+.headerAction:hover,
+.headerAction:focus-visible,
+.footerAction:hover,
+.footerAction:focus-visible {
+	outline: none;
+	color: var(--color-text);
+}
+
+.listWrap {
+	display: grid;
+	gap: var(--space-3);
+	max-height: min(24rem, 60vh);
+	overflow-y: auto;
+	padding-right: var(--space-1);
+	margin-right: calc(var(--space-1) * -1);
+}
+
+.stateCard {
+	display: grid;
+	justify-items: start;
+	gap: var(--space-2);
+	padding: var(--space-3);
+	border: 1px solid color-mix(in srgb, var(--color-border) 18%, transparent);
+	border-radius: var(--radius-md);
+	background: color-mix(in srgb, var(--color-surface) 92%, transparent);
+}
+
+.stateIcon {
+	width: 2.2rem;
+	height: 2.2rem;
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	border-radius: 999px;
+	background: color-mix(in srgb, var(--color-surface-muted) 88%, transparent);
+	color: var(--color-text);
+}
+
+.stateTitle {
+	@include text-label;
+	color: var(--color-text);
+}
+
+.stateCopy {
+	@include text-caption;
+	color: var(--color-text-muted);
+}
+
+.section {
+	display: grid;
+	gap: var(--space-2);
+}
+
+.section + .section {
+	padding-top: var(--space-3);
+	border-top: 1px solid var(--color-border);
+}
+
+.sectionLabel {
+	text-transform: uppercase;
+	letter-spacing: 0.06em;
+	color: var(--color-text-subtle);
+}
+
+.list {
+	display: grid;
+	gap: var(--space-1);
+}
+
+.item {
+	width: 100%;
+	min-width: 0;
+	display: grid;
+	grid-template-columns: auto minmax(0, 1fr) auto;
+	align-items: start;
+	gap: var(--space-2);
+	padding: var(--space-2);
+	border: 1px solid transparent;
+	border-radius: var(--radius-sm);
+	background: transparent;
+	color: var(--color-text);
+	text-align: left;
+	transition:
+		background-color 160ms var(--easing-standard),
+		border-color 160ms var(--easing-standard),
+		color 160ms var(--easing-standard);
+}
+
+.item:hover {
+	background: color-mix(in srgb, var(--color-surface) 88%, transparent);
+	border-color: color-mix(in srgb, var(--color-border) 20%, transparent);
+}
+
+.item:focus-visible {
+	outline: none;
+	background: color-mix(in srgb, var(--color-surface) 92%, transparent);
+	border-color: color-mix(in srgb, var(--color-accent-soft) 52%, transparent);
+	box-shadow: 0 0 0 0.12rem color-mix(in srgb, var(--color-accent-soft) 14%, transparent);
+}
+
+.itemUnread {
+	background: color-mix(in srgb, var(--color-surface) 90%, transparent);
+	border-color: color-mix(in srgb, var(--color-border) 16%, transparent);
+}
+
+.itemMarker,
+.itemMarkerMuted {
+	width: 0.5rem;
+	height: 0.5rem;
+	margin-top: 0.45rem;
+	border-radius: 999px;
+	flex-shrink: 0;
+	background: color-mix(in srgb, var(--color-primary-2) 78%, white 22%);
+}
+
+.itemMarkerMuted {
+	background: color-mix(in srgb, var(--color-text-subtle) 36%, transparent);
+}
+
+.itemBody {
+	min-width: 0;
+	display: grid;
+	gap: calc(var(--space-1) / 2);
+}
+
+.itemTitle {
+	@include text-label;
+	color: var(--color-text);
+}
+
+.itemTime {
+	padding-top: calc(var(--space-1) / 4);
+	white-space: nowrap;
+	color: var(--color-text-subtle);
+}
+
+.footer {
+	padding-top: var(--space-3);
+	border-top: 1px solid var(--color-border);
+	justify-content: space-between;
+	flex-wrap: wrap;
+}
+
+.menu.menuWorkspace .listWrap {
+	min-height: 0;
+	max-height: none;
+	height: 100%;
+	padding-right: 0;
+	margin-right: 0;
+}
+
+.menu.menuWorkspace .header,
+.menu.menuWorkspace .footer {
+	padding-left: 0;
+	padding-right: 0;
+}
+
+@include respond-down(mobile) {
+	.menu.menuWorkspace {
+		height: 100%;
+		min-height: 0;
+		padding: var(--space-5);
+	}
+
+	.menu.menuWorkspace .listWrap {
+		min-height: 0;
+		max-height: none;
+	}
+
+	.menu.menuWorkspace .item {
+		grid-template-columns: auto minmax(0, 1fr);
+	}
+
+	.menu.menuWorkspace .itemTime {
+		grid-column: 2;
+		padding-top: 0;
+	}
+
+	.menu.menuWorkspace .footer {
+		align-items: flex-start;
+		flex-direction: column;
+	}
+
+	.menu.menuWorkspace .footerAction {
+		padding: var(--space-1) 0;
+	}
+}

Frontend/src/components/shell/TopBar/NotificationsMenu.tsx

@@ -0,0 +1,125 @@
+import { For, Show, type JSX } from "solid-js";
+import { Bell, Settings } from "../../../lib/icons";
+import { notificationItems, unreadNotificationCount } from "../data/shell.data";
+import styles from "./NotificationsMenu.module.scss";
+
+type NotificationsMenuProps = {
+	id: string;
+	menuRef?: (element: HTMLDivElement) => void;
+	onSelect: () => void;
+	variant?: "popover" | "workspace";
+};
+
+export const NotificationsMenu = (props: NotificationsMenuProps): JSX.Element => {
+	const unreadItems = notificationItems.filter((item) => item.unread);
+	const earlierItems = notificationItems.filter((item) => !item.unread);
+	const hasNotifications = notificationItems.length > 0;
+	const isCaughtUp = unreadItems.length === 0 && hasNotifications;
+	const variant = props.variant ?? "popover";
+
+	return (
+		<div
+			id={props.id}
+			classList={{
+				[styles.menu]: true,
+				[styles.menuWorkspace]: variant === "workspace",
+			}}
+			role="menu"
+			aria-label="Notifications"
+			ref={props.menuRef}
+			data-ui="notifications-menu"
+			data-variant={variant}
+		>
+			<div class={styles.header} data-slot="notifications-header">
+				<div class={styles.headerCopy} data-slot="notifications-header-copy">
+					<strong class={styles.title}>Notifications</strong>
+					<span class={styles.subtitle}>
+						{unreadNotificationCount > 0
+							? `You have ${unreadNotificationCount} unread`
+							: "You’re all caught up"}
+					</span>
+				</div>
+
+				<Show when={unreadNotificationCount > 0}>
+					<button type="button" role="menuitem" class={styles.headerAction} onClick={props.onSelect}>
+						Mark all read
+					</button>
+				</Show>
+			</div>
+
+			<div class={styles.listWrap} data-slot="notifications-body">
+				<Show when={!hasNotifications}>
+					<div class={styles.stateCard}>
+						<span class={styles.stateIcon} aria-hidden="true">
+							<Bell size={18} strokeWidth={2} />
+						</span>
+						<strong class={styles.stateTitle}>No notifications yet</strong>
+						<span class={styles.stateCopy}>When activity starts across your workspace, it’ll show up here.</span>
+					</div>
+				</Show>
+
+				<Show when={isCaughtUp}>
+					<div class={styles.stateCard}>
+						<span class={styles.stateIcon} aria-hidden="true">
+							<Bell size={18} strokeWidth={2} />
+						</span>
+						<strong class={styles.stateTitle}>You’re all caught up</strong>
+						<span class={styles.stateCopy}>No unread notifications right now. Earlier activity is still available below.</span>
+					</div>
+				</Show>
+
+				<Show when={unreadItems.length > 0}>
+					<section class={styles.section} aria-label="Unread notifications" data-slot="notifications-section" data-section-id="unread">
+						<span class={styles.sectionLabel}>Unread</span>
+						<div class={styles.list} data-slot="notifications-list" data-section-id="unread">
+							<For each={unreadItems}>
+								{(item): JSX.Element => (
+									<button type="button" role="menuitem" classList={{ [styles.item]: true, [styles.itemUnread]: true }} data-slot="notification-item" data-state="unread" onClick={props.onSelect}>
+										<span class={styles.itemMarker} aria-hidden="true" />
+										<div class={styles.itemBody}>
+											<span class={styles.itemTitle}>{item.title}</span>
+											<span class={styles.itemMeta}>{item.contextLabel}</span>
+										</div>
+										<span class={styles.itemTime}>{item.timeLabel}</span>
+									</button>
+								)}
+							</For>
+						</div>
+					</section>
+				</Show>
+
+				<Show when={earlierItems.length > 0}>
+					<section class={styles.section} aria-label="Earlier notifications" data-slot="notifications-section" data-section-id="earlier">
+						<span class={styles.sectionLabel}>Earlier</span>
+						<div class={styles.list} data-slot="notifications-list" data-section-id="earlier">
+							<For each={earlierItems}>
+								{(item): JSX.Element => (
+									<button type="button" role="menuitem" class={styles.item} data-slot="notification-item" data-state="read" onClick={props.onSelect}>
+										<span class={styles.itemMarkerMuted} aria-hidden="true" />
+										<div class={styles.itemBody}>
+											<span class={styles.itemTitle}>{item.title}</span>
+											<span class={styles.itemMeta}>{item.contextLabel}</span>
+										</div>
+										<span class={styles.itemTime}>{item.timeLabel}</span>
+									</button>
+								)}
+							</For>
+						</div>
+					</section>
+				</Show>
+			</div>
+
+			<div class={styles.footer} data-slot="notifications-footer">
+				<button type="button" role="menuitem" class={styles.footerAction} onClick={props.onSelect}>
+					<Settings size={16} strokeWidth={2} />
+					<span>Notification settings</span>
+				</button>
+
+				<button type="button" role="menuitem" class={styles.footerAction} onClick={props.onSelect}>
+					<Bell size={16} strokeWidth={2} />
+					<span>View all notifications</span>
+				</button>
+			</div>
+		</div>
+	);
+};

Frontend/src/components/shell/TopBar/NotificationsNav.module.scss

@@ -0,0 +1,5 @@
+.root {
+	position: relative;
+	display: inline-flex;
+	align-items: center;
+}

Frontend/src/components/shell/TopBar/NotificationsNav.tsx

@@ -0,0 +1,38 @@
+import { createUniqueId, Show, type JSX } from "solid-js";
+import { NotificationsButton } from "./NotificationsButton";
+import { NotificationsMenu } from "./NotificationsMenu";
+import { createDesktopMenuController } from "./createDesktopMenuController";
+import styles from "./NotificationsNav.module.scss";
+
+type NotificationsNavProps = {
+	isMobileViewport: boolean;
+	isMobileWorkspaceOpen: boolean;
+	onToggleMobileWorkspace: VoidFunction;
+};
+
+export const NotificationsNav = (props: NotificationsNavProps): JSX.Element => {
+	const menuId = createUniqueId();
+
+	return (
+		<Show
+			when={props.isMobileViewport}
+			fallback={<DesktopNotificationsNav />}
+		>
+			<div class={styles.root}>
+				<NotificationsButton isOpen={props.isMobileWorkspaceOpen} menuId={menuId} onToggle={props.onToggleMobileWorkspace} />
+			</div>
+		</Show>
+	);
+};
+
+const DesktopNotificationsNav = (): JSX.Element => {
+	const controller = createDesktopMenuController();
+	const menuId = createUniqueId();
+
+	return (
+		<div class={styles.root} ref={controller.setRootRef}>
+			<NotificationsButton isOpen={controller.isOpen()} menuId={menuId} onToggle={controller.toggleMenu} />
+			{controller.isOpen() ? <NotificationsMenu id={menuId} menuRef={controller.setMenuRef} onSelect={controller.closeMenu} /> : null}
+		</div>
+	);
+};

Frontend/src/components/shell/TopBar/ProfileMenu.module.scss

@@ -7,11 +7,39 @@
   gap: var(--space-3);
   padding: var(--space-3);
   border: 1px solid var(--color-border-strong);
-  border-radius: calc(var(--radius-lg) + 0.1rem);
+  border-radius: calc(var(--radius-lg) + (var(--space-1) / 2));
   background: color-mix(in srgb, var(--color-surface-muted) 96%, transparent);
-  box-shadow: 0 18px 36px color-mix(in srgb, black 16%, transparent);
-  backdrop-filter: blur(18px);
-  z-index: 30;
+  box-shadow: var(--shadow-strong);
+  backdrop-filter: blur(var(--blur-overlay));
+  z-index: var(--z-dropdown);
+}
+
+.menu.menuWorkspace {
+  position: static;
+  top: auto;
+  right: auto;
+  left: auto;
+  bottom: auto;
+  width: 100%;
+  max-width: none;
+  height: 100%;
+  min-height: 0;
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr);
+  gap: var(--space-4);
+  padding: var(--space-4);
+  border: 0;
+  border-radius: 0;
+  background: transparent;
+  box-shadow: none;
+  backdrop-filter: none;
+  z-index: auto;
+  overflow: hidden;
+}
+
+.sections {
+  display: grid;
+  gap: var(--space-3);
 }
 
 .summary {
@@ -71,7 +99,7 @@
 .summaryCopy {
   min-width: 0;
   display: grid;
-  gap: 0.08rem;
+  gap: calc(var(--space-1) / 2);
 }
 
 .name,
@@ -97,7 +125,7 @@
 
 .section {
   display: grid;
-  gap: 0.2rem;
+  gap: var(--space-1);
 }
 
 .section + .section {
@@ -108,7 +136,7 @@
 .item {
   width: 100%;
   min-width: 0;
-  min-height: 2.65rem;
+  min-height: calc(var(--control-size-lg) + (var(--space-1) / 2));
   display: grid;
   grid-template-columns: auto minmax(0, 1fr);
   align-items: center;
@@ -148,8 +176,8 @@
 }
 
 .itemIcon {
-  width: 1.9rem;
-  height: 1.9rem;
+  width: calc(var(--control-size-lg) - var(--space-2));
+  height: calc(var(--control-size-lg) - var(--space-2));
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -158,8 +186,15 @@
   color: currentColor;
 }
 
-@include respond-down(mobile) {
-  .menu {
-    width: min(20rem, calc(100vw - (var(--space-3) * 2)));
+.menu.menuWorkspace .sections {
+  min-height: 0;
+  height: 100%;
+  align-content: start;
+  overflow-y: auto;
 }
+
+.menu.menuWorkspace .summary,
+.menu.menuWorkspace .sections {
+  padding-left: 0;
+  padding-right: 0;
 }

Frontend/src/components/shell/TopBar/ProfileMenu.tsx

@@ -1,18 +1,35 @@
 import { For, type JSX } from "solid-js";
 import { User } from "../../../lib/icons";
-import { activeUserProfile, profileMenuSections } from "../data/shell.data";
+import { useAppShellData } from "../data/app-shell.context";
+import { profileMenuSections } from "../data/shell.data";
 import styles from "./ProfileMenu.module.scss";
 
 type ProfileMenuProps = {
 	id: string;
-	menuRef: (element: HTMLDivElement) => void;
+	menuRef?: (element: HTMLDivElement) => void;
 	onSelect: () => void;
+	variant?: "popover" | "workspace";
 };
 
 export const ProfileMenu = (props: ProfileMenuProps): JSX.Element => {
+	const variant = props.variant ?? "popover";
+	const appShellData = useAppShellData();
+	const activeUserProfile = () => appShellData.activeUserProfile();
+
 	return (
-		<div id={props.id} class={styles.menu} role="menu" aria-label="Profile menu" ref={props.menuRef}>
-			<div class={styles.summary}>
+		<div
+			id={props.id}
+			classList={{
+				[styles.menu]: true,
+				[styles.menuWorkspace]: variant === "workspace",
+			}}
+			role="menu"
+			aria-label="Profile menu"
+			ref={props.menuRef}
+			data-ui="profile-menu"
+			data-variant={variant}
+		>
+			<div class={styles.summary} data-slot="profile-summary">
 				<div class={styles.avatar} aria-hidden="true">
 					<span class={styles.avatarRing} />
 					<span class={styles.avatarCore}>
@@ -21,16 +38,17 @@ export const ProfileMenu = (props: ProfileMenuProps): JSX.Element => {
 				</div>
 
 				<div class={styles.summaryCopy}>
-					<strong class={styles.name}>{activeUserProfile.name}</strong>
-					<span class={styles.email}>{activeUserProfile.email}</span>
-					<span class={styles.role}>{activeUserProfile.roleLabel}</span>
-					<span class={styles.context}>{activeUserProfile.contextLabel}</span>
+					<strong class={styles.name}>{activeUserProfile().name}</strong>
+					<span class={styles.email}>{activeUserProfile().email}</span>
+					<span class={styles.role}>{activeUserProfile().roleLabel}</span>
+					<span class={styles.context}>{activeUserProfile().contextLabel}</span>
 				</div>
 			</div>
 
+			<div class={styles.sections} data-slot="profile-sections">
 				<For each={profileMenuSections}>
 					{(section): JSX.Element => (
-					<div class={styles.section}>
+						<div class={styles.section} data-slot="profile-section" data-section-id={section.id}>
 							<For each={section.items}>
 								{(item): JSX.Element => {
 									const Icon = item.icon;
@@ -43,6 +61,9 @@ export const ProfileMenu = (props: ProfileMenuProps): JSX.Element => {
 											[styles.item]: true,
 											[styles.itemDanger]: item.tone === "danger",
 										}}
+										data-slot="profile-action"
+										data-action-id={item.id}
+										data-tone={item.tone ?? "default"}
 										onClick={props.onSelect}
 										>
 											<span class={styles.itemIcon} aria-hidden="true">
@@ -57,5 +78,6 @@ export const ProfileMenu = (props: ProfileMenuProps): JSX.Element => {
 					)}
 				</For>
 			</div>
+		</div>
 	);
 };

Frontend/src/components/shell/TopBar/TopBar.tsx

@@ -4,6 +4,7 @@ import { For, type JSX } from "solid-js";
 import type { Theme } from "../../../theme/runtime";
 import { topBarActions } from "../data/shell.data";
 import { DepartmentSelector } from "../DepartmentSelector/DepartmentSelector";
+import { NotificationsNav } from "./NotificationsNav";
 import { ThemeToggle } from "./ThemeToggle";
 import { UserNav } from "./UserNav";
 import styles from "./TopBar.module.scss";
@@ -11,24 +12,29 @@ import styles from "./TopBar.module.scss";
 type TopBarProps = {
 	theme: Theme;
 	onToggleTheme: VoidFunction;
+	isMobileViewport: boolean;
+	isNotificationsOpen: boolean;
+	isProfileOpen: boolean;
+	onToggleNotifications: VoidFunction;
+	onToggleProfile: VoidFunction;
 };
 
 export const TopBar = (props: TopBarProps): JSX.Element => {
 	return (
-		<header class={styles.topBar}>
-			<div class={styles.identity}>
+		<header class={styles.topBar} data-ui="top-bar">
+			<div class={styles.identity} data-slot="top-bar-identity">
 				<span class={styles.eyebrow}>Moku Work</span>
 				<DepartmentSelector />
 			</div>
 
-			<div class={styles.controls}>
-				<div class={styles.actions}>
+			<div class={styles.controls} data-slot="top-bar-controls">
+				<div class={styles.actions} data-slot="top-bar-actions">
 					<For each={topBarActions}>
 						{(item): JSX.Element => {
 							const Icon = item.icon;
 
 							return (
-								<button class={styles.actionButton} type="button" aria-label={item.label} title={item.label}>
+								<button class={styles.actionButton} type="button" aria-label={item.label} title={item.label} data-slot="top-bar-action" data-action-id={item.id}>
 									<Icon size={18} strokeWidth={2} />
 								</button>
 							);
@@ -36,8 +42,17 @@ export const TopBar = (props: TopBarProps): JSX.Element => {
 					</For>
 				</div>
 
+				<NotificationsNav
+					isMobileViewport={props.isMobileViewport}
+					isMobileWorkspaceOpen={props.isNotificationsOpen}
+					onToggleMobileWorkspace={props.onToggleNotifications}
+				/>
 				<ThemeToggle theme={props.theme} onToggle={props.onToggleTheme} />
-				<UserNav />
+				<UserNav
+					isMobileViewport={props.isMobileViewport}
+					isMobileWorkspaceOpen={props.isProfileOpen}
+					onToggleMobileWorkspace={props.onToggleProfile}
+				/>
 			</div>
 		</header>
 	);

Frontend/src/components/shell/TopBar/UserNav.tsx

@@ -1,54 +1,38 @@
-import { createEffect, createSignal, createUniqueId, onCleanup, type JSX } from "solid-js";
+import { createUniqueId, Show, type JSX } from "solid-js";
 import { ProfileMenu } from "./ProfileMenu";
 import { UserNavButton } from "./UserNavButton";
+import { createDesktopMenuController } from "./createDesktopMenuController";
 import styles from "./UserNav.module.scss";
 
-export const UserNav = (): JSX.Element => {
-	const [isOpen, setIsOpen] = createSignal(false);
+type UserNavProps = {
+	isMobileViewport: boolean;
+	isMobileWorkspaceOpen: boolean;
+	onToggleMobileWorkspace: VoidFunction;
+};
+
+export const UserNav = (props: UserNavProps): JSX.Element => {
 	const menuId = createUniqueId();
-	let rootRef: HTMLDivElement | undefined;
-	let menuRef: HTMLDivElement | undefined;
-
-	const closeMenu = (): void => {
-		setIsOpen(false);
-	};
-
-	const toggleMenu = (): void => {
-		setIsOpen((open) => !open);
-	};
-
-	createEffect(() => {
-		if (!isOpen()) return;
-
-		const handlePointerDown = (event: PointerEvent): void => {
-			if (!rootRef) return;
-
-			const target = event.target;
-			if (target instanceof Node && !rootRef.contains(target)) {
-				closeMenu();
-			}
-		};
-
-		const handleKeyDown = (event: KeyboardEvent): void => {
-			if (event.key === "Escape") {
-				closeMenu();
-			}
-		};
-
-		document.addEventListener("pointerdown", handlePointerDown);
-		document.addEventListener("keydown", handleKeyDown);
-		menuRef?.querySelector<HTMLButtonElement>("[role='menuitem']")?.focus();
-
-		onCleanup(() => {
-			document.removeEventListener("pointerdown", handlePointerDown);
-			document.removeEventListener("keydown", handleKeyDown);
-		});
-	});
 
 	return (
-		<div class={styles.root} ref={rootRef}>
-			<UserNavButton isOpen={isOpen()} menuId={menuId} onToggle={toggleMenu} />
-			{isOpen() ? <ProfileMenu id={menuId} menuRef={(element) => (menuRef = element)} onSelect={closeMenu} /> : null}
+		<Show
+			when={props.isMobileViewport}
+			fallback={<DesktopUserNav />}
+		>
+			<div class={styles.root}>
+				<UserNavButton isOpen={props.isMobileWorkspaceOpen} menuId={menuId} onToggle={props.onToggleMobileWorkspace} />
+			</div>
+		</Show>
+	);
+};
+
+const DesktopUserNav = (): JSX.Element => {
+	const controller = createDesktopMenuController();
+	const menuId = createUniqueId();
+
+	return (
+		<div class={styles.root} ref={controller.setRootRef}>
+			<UserNavButton isOpen={controller.isOpen()} menuId={menuId} onToggle={controller.toggleMenu} />
+			{controller.isOpen() ? <ProfileMenu id={menuId} menuRef={controller.setMenuRef} onSelect={controller.closeMenu} /> : null}
 		</div>
 	);
 };

Frontend/src/components/shell/TopBar/createDesktopMenuController.ts

@@ -0,0 +1,72 @@
+import { createEffect, createSignal, onCleanup } from "solid-js";
+
+type DesktopMenuController = {
+	isOpen: () => boolean;
+	rootRef: HTMLDivElement | undefined;
+	menuRef: HTMLDivElement | undefined;
+	setRootRef: (element: HTMLDivElement) => void;
+	setMenuRef: (element: HTMLDivElement) => void;
+	closeMenu: VoidFunction;
+	toggleMenu: VoidFunction;
+};
+
+// Shared desktop popover behavior for top-bar menus.
+export const createDesktopMenuController = (): DesktopMenuController => {
+	const [isOpen, setIsOpen] = createSignal(false);
+	let rootRef: HTMLDivElement | undefined;
+	let menuRef: HTMLDivElement | undefined;
+
+	const closeMenu = (): void => {
+		setIsOpen(false);
+	};
+
+	const toggleMenu = (): void => {
+		setIsOpen((open) => !open);
+	};
+
+	createEffect(() => {
+		if (!isOpen()) return;
+
+		const handlePointerDown = (event: PointerEvent): void => {
+			if (!rootRef) return;
+
+			const target = event.target;
+			if (target instanceof Node && !rootRef.contains(target)) {
+				closeMenu();
+			}
+		};
+
+		const handleKeyDown = (event: KeyboardEvent): void => {
+			if (event.key === "Escape") {
+				closeMenu();
+			}
+		};
+
+		document.addEventListener("pointerdown", handlePointerDown);
+		document.addEventListener("keydown", handleKeyDown);
+		menuRef?.querySelector<HTMLButtonElement>("[role='menuitem']")?.focus();
+
+		onCleanup(() => {
+			document.removeEventListener("pointerdown", handlePointerDown);
+			document.removeEventListener("keydown", handleKeyDown);
+		});
+	});
+
+	return {
+		isOpen,
+		get rootRef() {
+			return rootRef;
+		},
+		get menuRef() {
+			return menuRef;
+		},
+		setRootRef: (element: HTMLDivElement): void => {
+			rootRef = element;
+		},
+		setMenuRef: (element: HTMLDivElement): void => {
+			menuRef = element;
+		},
+		closeMenu,
+		toggleMenu,
+	};
+};

Frontend/src/components/shell/WorkspaceContextMenu/WorkspaceContextMenu.module.scss

@@ -0,0 +1,194 @@
+.menu {
+	--context-menu-width: 13.5rem;
+	position: fixed;
+	width: min(var(--context-menu-width), calc(100vw - (var(--space-4) * 2)));
+	display: grid;
+	gap: 0;
+	padding: var(--space-1);
+	border: 1px solid color-mix(in srgb, var(--color-border-strong) 56%, transparent);
+	border-radius: calc(var(--radius-md) + (var(--space-1) / 2));
+	background: var(--color-surface);
+	box-shadow: var(--shadow-soft);
+	z-index: 2147483647;
+	user-select: none;
+}
+
+.header {
+	display: grid;
+	gap: calc(var(--space-1) / 2);
+	padding: var(--space-2) calc(var(--space-2) + (var(--space-1) / 2));
+}
+
+.eyebrow {
+	@include text-caption;
+	color: var(--color-text-muted);
+	text-transform: uppercase;
+	letter-spacing: 0.06em;
+}
+
+.title {
+	@include text-label;
+	color: var(--color-text);
+	font-weight: var(--font-weight-title);
+}
+
+.sectionList {
+	display: grid;
+	gap: 0;
+}
+
+.sectionListCompact {
+	gap: calc(var(--space-1) / 2);
+}
+
+.section {
+	display: grid;
+	gap: 0;
+}
+
+.section:first-child {
+	padding-top: calc(var(--space-1) / 2);
+}
+
+.section + .section {
+	margin-top: calc(var(--space-1) / 2);
+	padding-top: var(--space-2);
+	border-top: 1px solid color-mix(in srgb, var(--color-border) 78%, transparent);
+}
+
+.sectionLabel {
+	@include text-caption;
+	color: var(--color-text-subtle);
+	padding: 0 var(--space-2);
+	text-transform: uppercase;
+	letter-spacing: 0.04em;
+}
+
+.actionList {
+	display: grid;
+	gap: 0;
+}
+
+.actionItem {
+	position: relative;
+}
+
+.action {
+	width: 100%;
+	min-height: calc(var(--control-size-md) - var(--space-2));
+	display: inline-flex;
+	align-items: center;
+	justify-content: flex-start;
+	gap: var(--space-2);
+	padding: var(--space-2) calc(var(--space-2) + (var(--space-1) / 2));
+	border: 1px solid transparent;
+	border-radius: var(--radius-sm);
+	background: transparent;
+	color: var(--color-text);
+	text-align: left;
+	font-size: var(--font-size-label);
+	line-height: var(--line-height-label);
+	font-weight: var(--font-weight-label);
+	transition:
+		background var(--motion-duration-fast) var(--motion-ease-standard),
+		border-color var(--motion-duration-fast) var(--motion-ease-standard),
+		color var(--motion-duration-fast) var(--motion-ease-standard);
+}
+
+.actionCreate {
+	border-color: transparent;
+	background: transparent;
+	font-weight: var(--font-weight-title);
+	box-shadow: none;
+}
+
+.actionCreate:hover,
+.actionCreate:focus-visible,
+.actionCreate.actionSubmenuOpen {
+	background: color-mix(in srgb, var(--color-surface-hover) 82%, var(--color-surface));
+	border-color: color-mix(in srgb, var(--color-border) 72%, transparent);
+}
+
+.actionCreateIcon {
+	width: calc(var(--control-size-md) - var(--space-3));
+	height: calc(var(--control-size-md) - var(--space-3));
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	border-radius: var(--radius-sm);
+	background: color-mix(in srgb, var(--color-surface-hover) 72%, var(--color-surface));
+	color: var(--color-text);
+	box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--color-border) 74%, transparent);
+}
+
+.actionLabel {
+	min-width: 0;
+}
+
+.actionMeta {
+	margin-left: auto;
+	display: inline-flex;
+	align-items: center;
+	justify-content: flex-end;
+	gap: var(--space-2);
+	padding-left: var(--space-3);
+}
+
+.actionShortcut {
+	color: var(--color-text-muted);
+	font-size: var(--font-size-caption);
+	line-height: var(--line-height-caption);
+	font-weight: var(--font-weight-caption);
+	white-space: nowrap;
+}
+
+.actionChevron {
+	color: var(--color-text-subtle);
+	flex: 0 0 auto;
+}
+
+.actionSubmenuOpen {
+	background: color-mix(in srgb, var(--color-surface-hover) 82%, var(--color-surface));
+	border-color: color-mix(in srgb, var(--color-border-strong) 72%, transparent);
+}
+
+.action:hover,
+.action:focus-visible {
+	background: color-mix(in srgb, var(--color-surface-hover) 78%, var(--color-surface));
+	border-color: color-mix(in srgb, var(--color-border) 72%, transparent);
+}
+
+.actionDanger {
+	color: var(--color-danger-text, var(--color-text));
+}
+
+.actionDanger:hover,
+.actionDanger:focus-visible {
+	background: color-mix(in srgb, var(--color-danger-soft, var(--color-surface-hover)) 72%, transparent);
+	border-color: color-mix(in srgb, var(--color-danger-border, var(--color-border)) 72%, transparent);
+	color: var(--color-danger-text, var(--color-text));
+}
+
+.submenu {
+	position: absolute;
+	top: calc(var(--space-1) * -1);
+	left: calc(100% + var(--space-2));
+	width: min(var(--context-menu-width), calc(100vw - (var(--space-4) * 2)));
+	padding: var(--space-1);
+	border: 1px solid color-mix(in srgb, var(--color-border-strong) 56%, transparent);
+	border-radius: calc(var(--radius-md) + (var(--space-1) / 2));
+	background: var(--color-surface);
+	box-shadow: var(--shadow-soft);
+	z-index: 2147483647;
+}
+
+.submenuList {
+	display: grid;
+	gap: var(--space-1);
+}
+
+@include respond-down(mobile) {
+	.menu {
+		display: none;
+	}
+}

Frontend/src/components/shell/WorkspaceContextMenu/WorkspaceContextMenu.tsx

@@ -0,0 +1,242 @@
+import { For, Show, createEffect, createMemo, createSignal, onMount, type JSX } from "solid-js";
+import { Portal } from "solid-js/web";
+import { ChevronRight, Plus } from "../../../lib/icons";
+import {
+	getWorkspaceContextMenuEyebrow,
+	getWorkspaceContextMenuSections,
+	type WorkspaceContextMenuAction,
+	type WorkspaceContextMenuShortcut,
+	type WorkspaceContextMenuTarget,
+} from "../data/shell.data";
+import styles from "./WorkspaceContextMenu.module.scss";
+
+type ShortcutPlatform = "mac" | "windows";
+
+type NavigatorWithUserAgentData = Navigator & {
+	userAgentData?: {
+		platform?: string;
+	};
+};
+
+type WorkspaceContextMenuPosition = {
+	x: number;
+	y: number;
+};
+
+type WorkspaceContextMenuProps = {
+	target: WorkspaceContextMenuTarget | null;
+	position: WorkspaceContextMenuPosition | null;
+	onClose: VoidFunction;
+	onSelect: (action: WorkspaceContextMenuAction, target: WorkspaceContextMenuTarget) => void;
+	menuRef: (element: HTMLDivElement) => void;
+};
+
+const getShortcutPlatform = (): ShortcutPlatform => {
+	if (typeof navigator === "undefined") {
+		return "mac";
+	}
+
+	const navigatorWithUserAgentData = navigator as NavigatorWithUserAgentData;
+
+	const platform =
+		typeof navigatorWithUserAgentData.userAgentData?.platform === "string"
+			? navigatorWithUserAgentData.userAgentData.platform
+			: navigator.platform;
+
+	return /mac|iphone|ipad|ipod/i.test(platform) ? "mac" : "windows";
+};
+
+const formatShortcut = (shortcut: WorkspaceContextMenuShortcut, platform: ShortcutPlatform): string => {
+	const keyLabel = (() => {
+		switch (shortcut.key) {
+			case "enter":
+				return platform === "mac" ? "↩" : "Enter";
+			case "delete":
+				return platform === "mac" ? "⌫" : "Del";
+			default:
+				return shortcut.key.toUpperCase();
+		}
+	})();
+
+	const modifierLabels =
+		shortcut.modifiers?.map((modifier) => {
+			switch (modifier) {
+				case "meta":
+					return platform === "mac" ? "⌘" : "Ctrl";
+				case "alt":
+					return platform === "mac" ? "⌥" : "Alt";
+				case "shift":
+					return platform === "mac" ? "⇧" : "Shift";
+			}
+		}) ?? [];
+
+	if (platform === "mac") {
+		return `${modifierLabels.join("")}${keyLabel}`;
+	}
+
+	return [...modifierLabels, keyLabel].join("+");
+};
+
+export const WorkspaceContextMenu = (props: WorkspaceContextMenuProps): JSX.Element => {
+	const [activeSubmenuActionId, setActiveSubmenuActionId] = createSignal<string | null>(null);
+	const [shortcutPlatform, setShortcutPlatform] = createSignal<ShortcutPlatform>("mac");
+	const sections = createMemo(() => (props.target ? getWorkspaceContextMenuSections(props.target) : []));
+	const handleActionSelect = (action: WorkspaceContextMenuAction, target: WorkspaceContextMenuTarget): void => {
+		props.onSelect(action, target);
+		props.onClose();
+	};
+	const menuState = createMemo<{
+		target: WorkspaceContextMenuTarget;
+		position: WorkspaceContextMenuPosition;
+	} | null>(() =>
+		props.target && props.position
+			? {
+				target: props.target,
+				position: props.position,
+			}
+			: null,
+	);
+	const showHeader = (): boolean => props.target?.kind !== "workspace";
+	const sectionHasLabel = createMemo(() => sections().some((section) => Boolean(section.label)));
+
+	onMount(() => {
+		setShortcutPlatform(getShortcutPlatform());
+	});
+
+	createEffect(() => {
+		void props.target;
+		setActiveSubmenuActionId(null);
+	});
+
+	return (
+		<Show when={menuState()}>
+			{(resolvedMenuState): JSX.Element => {
+				const target = resolvedMenuState().target;
+				const position = resolvedMenuState().position;
+
+				return (
+					<Portal>
+						<div
+							ref={props.menuRef}
+							class={styles.menu}
+							role="menu"
+							aria-label={`${target.label} context menu`}
+							data-ui="workspace-context-menu"
+							data-target-kind={target.kind}
+							data-item-type={target.kind === "item" ? target.itemType : undefined}
+							style={{
+								left: `${position.x}px`,
+								top: `${position.y}px`,
+							}}
+						>
+							<Show when={target.kind !== "workspace"}>
+								<header class={styles.header} data-slot="context-menu-header">
+									<span class={styles.eyebrow}>{getWorkspaceContextMenuEyebrow(target)}</span>
+									<strong class={styles.title}>{target.label}</strong>
+								</header>
+							</Show>
+
+							<div classList={{ [styles.sectionList]: true, [styles.sectionListCompact]: !sectionHasLabel() }} data-slot="context-menu-sections">
+								<For each={sections()}>
+									{(section): JSX.Element => (
+											<section class={styles.section} data-slot="context-menu-section" data-section-id={section.id}>
+												<Show when={section.label}>
+													<span class={styles.sectionLabel}>{section.label}</span>
+												</Show>
+
+												<div class={styles.actionList} data-slot="context-menu-action-list">
+													<For each={section.items}>
+														{(action): JSX.Element => {
+															const isSubmenuOpen = () => activeSubmenuActionId() === action.id;
+
+															return (
+														<div
+															class={styles.actionItem}
+															data-slot="context-menu-action-item"
+															data-action-id={action.id}
+															onMouseEnter={() => {
+																		setActiveSubmenuActionId(action.children ? action.id : null);
+																	}}
+																>
+															<button
+																type="button"
+																role="menuitem"
+																		classList={{
+																			[styles.action]: true,
+																			[styles.actionCreate]: action.id === "create",
+																	[styles.actionDanger]: action.tone === "danger",
+																	[styles.actionSubmenuOpen]: isSubmenuOpen(),
+																}}
+																data-slot="context-menu-action"
+																data-action-id={action.id}
+																data-tone={action.tone ?? "default"}
+															onClick={() => {
+																if (action.children) {
+																	setActiveSubmenuActionId(isSubmenuOpen() ? null : action.id);
+																	return;
+																}
+
+																handleActionSelect(action, target);
+															}}
+														>
+																		<Show when={action.id === "create"}>
+																			<span class={styles.actionCreateIcon} aria-hidden="true">
+																				<Plus size={14} strokeWidth={2.25} />
+																			</span>
+																		</Show>
+																		<span class={styles.actionLabel}>{action.label}</span>
+																		<div class={styles.actionMeta}>
+																			<Show when={action.shortcut}>
+																				<span class={styles.actionShortcut}>{formatShortcut(action.shortcut!, shortcutPlatform())}</span>
+																			</Show>
+																			<Show when={action.children}>
+																				<ChevronRight class={styles.actionChevron} size={16} strokeWidth={2} />
+																			</Show>
+																		</div>
+																	</button>
+
+																	<Show when={action.children && isSubmenuOpen()}>
+																<div class={styles.submenu} role="menu" aria-label={`${action.label} submenu`} data-slot="context-menu-submenu">
+																	<div class={styles.submenuList} data-slot="context-menu-submenu-list">
+																				<For each={action.children ?? []}>
+																					{(childAction): JSX.Element => (
+																			<button
+																				type="button"
+																				role="menuitem"
+																	classList={{
+																					[styles.action]: true,
+																					[styles.actionDanger]: childAction.tone === "danger",
+																				}}
+																				data-slot="context-menu-submenu-action"
+																				data-action-id={childAction.id}
+																				data-tone={childAction.tone ?? "default"}
+																				onClick={() => handleActionSelect(childAction, target)}
+																>
+																							<span class={styles.actionLabel}>{childAction.label}</span>
+																							<div class={styles.actionMeta}>
+																								<Show when={childAction.shortcut}>
+																									<span class={styles.actionShortcut}>{formatShortcut(childAction.shortcut!, shortcutPlatform())}</span>
+																								</Show>
+																							</div>
+																						</button>
+																					)}
+																				</For>
+																			</div>
+																		</div>
+																	</Show>
+																</div>
+															);
+														}}
+													</For>
+												</div>
+											</section>
+										)}
+								</For>
+							</div>
+						</div>
+					</Portal>
+				);
+			}}
+		</Show>
+	);
+};

Frontend/src/components/shell/WorkspaceContextMenu/createWorkspaceContextMenuController.ts

@@ -0,0 +1,134 @@
+import { createEffect, createSignal, onCleanup } from "solid-js";
+import type { WorkspaceContextMenuTarget } from "../data/shell.data";
+
+type WorkspaceContextMenuState = {
+	target: WorkspaceContextMenuTarget;
+	x: number;
+	y: number;
+};
+
+const readRootPixelToken = (name: string, fallback: number): number => {
+	if (typeof window === "undefined") {
+		return fallback;
+	}
+
+	const value = window.getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+	const parsed = Number.parseFloat(value);
+
+	if (!Number.isFinite(parsed)) {
+		return fallback;
+	}
+
+	if (value.endsWith("px")) {
+		return parsed;
+	}
+
+	return parsed * 16;
+};
+
+const clampMenuPosition = (value: number, min: number, max: number): number => {
+	if (max <= min) {
+		return min;
+	}
+
+	return Math.min(Math.max(value, min), max);
+};
+
+export const createWorkspaceContextMenuController = () => {
+	const [menuState, setMenuState] = createSignal<WorkspaceContextMenuState | null>(null);
+	let menuRef: HTMLDivElement | undefined;
+
+	const closeMenu = (): void => {
+		setMenuState(null);
+	};
+
+	const repositionMenu = (): void => {
+		if (typeof window === "undefined" || !menuRef) {
+			return;
+		}
+
+		const current = menuState();
+
+		if (!current) {
+			return;
+		}
+
+		const viewportPadding = readRootPixelToken("--space-4", 16);
+		const rect = menuRef.getBoundingClientRect();
+		const nextX = clampMenuPosition(current.x, viewportPadding, window.innerWidth - rect.width - viewportPadding);
+		const nextY = clampMenuPosition(current.y, viewportPadding, window.innerHeight - rect.height - viewportPadding);
+
+		if (nextX === current.x && nextY === current.y) {
+			return;
+		}
+
+		setMenuState({ ...current, x: nextX, y: nextY });
+	};
+
+	const openMenu = (event: MouseEvent, target: WorkspaceContextMenuTarget): void => {
+		event.preventDefault();
+		setMenuState({ target, x: event.clientX, y: event.clientY });
+	};
+
+	const openMenuFromElement = (element: HTMLElement, target: WorkspaceContextMenuTarget): void => {
+		const rect = element.getBoundingClientRect();
+		setMenuState({
+			target,
+			x: rect.left + rect.width / 2,
+			y: rect.top + rect.height / 2,
+		});
+	};
+
+	createEffect(() => {
+		if (!menuState()) {
+			return;
+		}
+
+		if (typeof window === "undefined") {
+			return;
+		}
+
+		const frame = window.requestAnimationFrame(() => {
+			repositionMenu();
+		});
+
+		const handlePointerDown = (event: PointerEvent): void => {
+			if (!menuRef?.contains(event.target as Node)) {
+				closeMenu();
+			}
+		};
+
+		const handleKeyDown = (event: KeyboardEvent): void => {
+			if (event.key === "Escape") {
+				closeMenu();
+			}
+		};
+
+		const handleViewportChange = (): void => {
+			closeMenu();
+		};
+
+		document.addEventListener("pointerdown", handlePointerDown);
+		window.addEventListener("resize", handleViewportChange);
+		window.addEventListener("scroll", handleViewportChange, true);
+		window.addEventListener("keydown", handleKeyDown);
+
+		onCleanup(() => {
+			window.cancelAnimationFrame(frame);
+			document.removeEventListener("pointerdown", handlePointerDown);
+			window.removeEventListener("resize", handleViewportChange);
+			window.removeEventListener("scroll", handleViewportChange, true);
+			window.removeEventListener("keydown", handleKeyDown);
+		});
+	});
+
+	return {
+		menuState,
+		openMenu,
+		openMenuFromElement,
+		closeMenu,
+		setMenuRef: (element: HTMLDivElement): void => {
+			menuRef = element;
+		},
+	};
+};

Frontend/src/components/shell/WorkspaceMobileActionSheet/WorkspaceMobileActionSheet.module.scss

@@ -0,0 +1,146 @@
+.layer {
+	display: none;
+}
+
+@include respond-down(mobile) {
+	.layer {
+		position: fixed;
+		inset: 0;
+		display: block;
+		z-index: var(--z-modal);
+	}
+
+	.backdrop {
+		position: absolute;
+		inset: 0;
+		border: 0;
+		background: color-mix(in srgb, black 52%, transparent);
+	}
+
+	.sheet {
+		position: absolute;
+		right: 0;
+		bottom: 0;
+		left: 0;
+		max-height: calc(100dvh - (var(--space-12) * 2));
+		display: grid;
+		gap: var(--space-3);
+		padding: var(--space-3) var(--space-3) calc(var(--space-4) + env(safe-area-inset-bottom, 0px));
+		border-top: 1px solid color-mix(in srgb, var(--color-border) 88%, transparent);
+		border-radius: var(--radius-xl) var(--radius-xl) 0 0;
+		background: var(--color-surface);
+		box-shadow: var(--shadow-strong);
+		overflow: auto;
+	}
+
+	.handle {
+		width: var(--space-10);
+		height: var(--space-1);
+		margin: 0 auto;
+		border-radius: var(--radius-pill);
+		background: color-mix(in srgb, var(--color-text-muted) 24%, transparent);
+	}
+
+	.header {
+		display: flex;
+		align-items: start;
+		justify-content: space-between;
+		gap: var(--space-3);
+		padding-bottom: var(--space-3);
+		border-bottom: 1px solid color-mix(in srgb, var(--color-border) 88%, transparent);
+	}
+
+	.headerCopy {
+		min-width: 0;
+		display: grid;
+		gap: calc(var(--space-1) / 2);
+	}
+
+	.eyebrow {
+		@include text-caption;
+		color: var(--color-text-muted);
+		text-transform: uppercase;
+		letter-spacing: 0.06em;
+	}
+
+	.title {
+		@include text-title;
+		color: var(--color-text);
+		font-weight: var(--font-weight-semibold);
+	}
+
+	.closeButton {
+		flex: 0 0 auto;
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		width: var(--control-size-md);
+		height: var(--control-size-md);
+		padding: 0;
+		border: 1px solid color-mix(in srgb, var(--color-border) 88%, transparent);
+		border-radius: var(--radius-pill);
+		background: color-mix(in srgb, var(--color-surface) 84%, var(--color-surface-elevated, var(--color-surface)) 16%);
+		color: var(--color-text-subtle);
+	}
+
+	.sectionList {
+		display: grid;
+		gap: var(--space-3);
+	}
+
+	.section {
+		display: grid;
+		gap: var(--space-2);
+	}
+
+	.section + .section {
+		padding-top: var(--space-3);
+		border-top: 1px solid color-mix(in srgb, var(--color-border) 92%, transparent);
+	}
+
+	.sectionLabel {
+		@include text-caption;
+		padding-inline: var(--space-1);
+		color: var(--color-text-muted);
+		text-transform: uppercase;
+		letter-spacing: 0.06em;
+	}
+
+	.actionList {
+		display: grid;
+		overflow: hidden;
+		border: 1px solid color-mix(in srgb, var(--color-border) 88%, transparent);
+		border-radius: var(--radius-lg);
+		background: color-mix(in srgb, var(--color-surface) 88%, var(--color-surface-elevated, var(--color-surface)) 12%);
+	}
+
+	.action {
+		min-width: 0;
+		width: 100%;
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		min-height: calc(var(--control-size-lg) + var(--space-2));
+		padding: 0 var(--space-3);
+		border: 0;
+		background: transparent;
+		color: var(--color-text);
+		text-align: left;
+	}
+
+	.action:active {
+		background: color-mix(in srgb, var(--color-text) 6%, transparent);
+	}
+
+	.action + .action {
+		border-top: 1px solid color-mix(in srgb, var(--color-border) 92%, transparent);
+	}
+
+	.actionLabel {
+		@include text-label;
+	}
+
+	.actionDanger {
+		color: var(--color-danger-text, var(--color-text));
+	}
+}

Frontend/src/components/shell/WorkspaceMobileActionSheet/WorkspaceMobileActionSheet.tsx

@@ -0,0 +1,134 @@
+import { For, Show, createMemo, type JSX } from "solid-js";
+import { Portal } from "solid-js/web";
+import { X } from "../../../lib/icons";
+import {
+	getWorkspaceContextMenuEyebrow,
+	getWorkspaceContextMenuSections,
+	type WorkspaceContextMenuAction,
+	type WorkspaceContextMenuSection,
+	type WorkspaceContextMenuTarget,
+} from "../data/shell.data";
+import styles from "./WorkspaceMobileActionSheet.module.scss";
+
+type WorkspaceMobileActionSheetProps = {
+	target: WorkspaceContextMenuTarget | null;
+	onClose: VoidFunction;
+	onSelect: (action: WorkspaceContextMenuAction, target: WorkspaceContextMenuTarget) => void;
+};
+
+type FlattenedActionSection = {
+	id: string;
+	label?: string;
+	items: readonly WorkspaceContextMenuAction[];
+};
+
+const flattenMobileSections = (
+	sections: readonly WorkspaceContextMenuSection[],
+): readonly FlattenedActionSection[] => {
+	// Mobile uses a flat action-sheet model, so desktop flyout groups become
+	// standalone labeled sections instead of nested menus.
+	return sections.flatMap((section) => {
+		const directActions = section.items.filter((action) => !action.children?.length);
+		const nestedSections = section.items
+			.filter((action) => action.children?.length)
+			.map((action) => ({
+				id: `${section.id}-${action.id}`,
+				label: action.label,
+				items: action.children ?? [],
+			}));
+
+		const flattenedSections: FlattenedActionSection[] = [];
+
+		if (directActions.length > 0) {
+			flattenedSections.push({
+				id: section.id,
+				label: section.label,
+				items: directActions,
+			});
+		}
+
+		return [...flattenedSections, ...nestedSections];
+	});
+};
+
+export const WorkspaceMobileActionSheet = (props: WorkspaceMobileActionSheetProps): JSX.Element => {
+	const sheetState = createMemo(() => {
+		if (!props.target) {
+			return null;
+		}
+
+		return {
+			target: props.target,
+			sections: flattenMobileSections(getWorkspaceContextMenuSections(props.target)),
+		};
+	});
+
+	const handleActionSelect = (action: WorkspaceContextMenuAction, target: WorkspaceContextMenuTarget): void => {
+		props.onSelect(action, target);
+		props.onClose();
+	};
+
+	return (
+		<Show when={sheetState()}>
+			{(sheetState): JSX.Element => {
+				const target = sheetState().target;
+				const sections = sheetState().sections;
+
+				return (
+					<Portal>
+					<div class={styles.layer} data-ui="workspace-mobile-action-sheet" data-target-kind={target.kind} data-item-type={target.kind === "item" ? target.itemType : undefined}>
+						<button class={styles.backdrop} type="button" aria-label="Close action sheet" data-slot="mobile-action-sheet-backdrop" onClick={props.onClose} />
+
+						<section class={styles.sheet} aria-label={`${target.label} actions`} data-slot="mobile-action-sheet-panel">
+							<div class={styles.handle} data-slot="mobile-action-sheet-handle" aria-hidden="true" />
+
+							<header class={styles.header} data-slot="mobile-action-sheet-header">
+								<div class={styles.headerCopy} data-slot="mobile-action-sheet-header-copy">
+										<span class={styles.eyebrow}>{getWorkspaceContextMenuEyebrow(target)}</span>
+										<strong class={styles.title}>{target.label}</strong>
+									</div>
+
+								<button class={styles.closeButton} type="button" aria-label="Close action sheet" data-slot="mobile-action-sheet-close" onClick={props.onClose}>
+										<X size={18} strokeWidth={2} />
+									</button>
+								</header>
+
+							<div class={styles.sectionList} data-slot="mobile-action-sheet-sections">
+									<For each={sections}>
+										{(section): JSX.Element => (
+											<section class={styles.section} data-slot="mobile-action-sheet-section" data-section-id={section.id}>
+												<Show when={section.label}>
+													<span class={styles.sectionLabel}>{section.label}</span>
+												</Show>
+
+												<div class={styles.actionList} data-slot="mobile-action-sheet-action-list">
+													<For each={section.items}>
+														{(action): JSX.Element => (
+															<button
+																type="button"
+																classList={{
+																	[styles.action]: true,
+																	[styles.actionDanger]: action.tone === "danger",
+																}}
+																data-slot="mobile-action-sheet-action"
+																data-action-id={action.id}
+																data-tone={action.tone ?? "default"}
+																onClick={() => handleActionSelect(action, target)}
+															>
+																<span class={styles.actionLabel}>{action.label}</span>
+															</button>
+														)}
+													</For>
+												</div>
+											</section>
+										)}
+									</For>
+								</div>
+							</section>
+						</div>
+					</Portal>
+				);
+			}}
+		</Show>
+	);
+};

Frontend/src/components/shell/WorkspaceSidebar/WorkspaceSidebar.module.scss

@@ -1,6 +1,7 @@
+@use "../shared/tree-nav" as treeNav;
+
 .sidebar {
   --sidebar-nav-item-min-height: var(--control-size-lg);
-  --sidebar-dock-clearance: 8rem;
   position: relative;
   min-width: 0;
   min-height: 0;
@@ -13,15 +14,71 @@
   isolation: isolate;
 }
 
+.sidebarDragMode {
+	user-select: none;
+	cursor: grabbing;
+}
+
+.sidebarDragMode .treeItem {
+	cursor: grabbing;
+}
+
 .header {
   display: grid;
+  gap: var(--space-3);
+}
+
+.headerActions {
+  display: grid;
+  grid-template-columns: repeat(5, minmax(0, 1fr));
   gap: var(--space-2);
+  justify-items: stretch;
+}
+
+.headerControls {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  align-items: start;
 }
 
 .headerDrawerOpen {
   z-index: 4;
 }
 
+.headerActionButton {
+  width: 100%;
+  min-height: var(--control-size-md);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid color-mix(in srgb, var(--color-border-strong) 44%, transparent);
+  border-radius: var(--radius-pill);
+  background: color-mix(in srgb, var(--color-surface) 94%, transparent);
+  color: var(--color-text-muted);
+  box-shadow: var(--shadow-soft);
+  transition:
+    background 160ms var(--easing-standard),
+    color 160ms var(--easing-standard),
+    border-color 160ms var(--easing-standard),
+    transform 180ms var(--easing-standard);
+}
+
+.headerActionButton:hover,
+.headerActionButton:focus-visible {
+  background: var(--color-surface-hover);
+  border-color: var(--color-border);
+  color: var(--color-text);
+}
+
+.headerActionButton:hover {
+  transform: translateY(-1px);
+}
+
+.headerCollapseButton {
+  background: color-mix(in srgb, var(--color-accent-soft) 58%, transparent);
+  color: var(--color-accent-strong);
+}
+
 .section {
   display: grid;
   grid-template-rows: auto minmax(0, 1fr);
@@ -45,7 +102,7 @@
   overflow-y: auto;
   overscroll-behavior: contain;
   padding-right: var(--space-1);
-  padding-bottom: calc(var(--space-4) + var(--sidebar-dock-clearance));
+	padding-bottom: calc(var(--space-4) + var(--sidebar-dock-clearance, var(--shell-dock-clearance)));
   margin-right: calc(var(--space-1) * -1);
 }
 
@@ -61,6 +118,28 @@
   padding: 0;
 }
 
+.treeSectionLabel {
+	@include treeNav.section-label;
+  margin: var(--space-3) 0 var(--space-2);
+  padding: 0 var(--space-3);
+}
+
+.treeList {
+	@include treeNav.tree-list;
+}
+
+.treeEmptySlot {
+	@include treeNav.empty-slot;
+}
+
+.treeInputRow {
+	@include treeNav.input-row;
+}
+
+.treeInput {
+	@include treeNav.input;
+}
+
 .navItem {
   width: 100%;
   min-width: 0;
@@ -75,6 +154,47 @@
   @include interactive-frame-hover(var(--color-surface-hover), transparent, var(--color-text));
 }
 
+.treeItem {
+	@include treeNav.item;
+}
+
+.treeItem:hover,
+.treeItem:focus-visible {
+	@include treeNav.item-hover;
+}
+
+.treeItemFolder {
+	@include treeNav.item-folder;
+}
+
+.treeItemDragging {
+	@include treeNav.item-dragging;
+}
+
+.treeItemDropBefore {
+	@include treeNav.item-drop-before;
+}
+
+.treeItemDropAfter {
+	@include treeNav.item-drop-after;
+}
+
+.treeItemDropInside {
+	@include treeNav.item-drop-inside;
+}
+
+.folderChevron {
+	@include treeNav.folder-chevron;
+}
+
+.folderChevronOpen {
+	@include treeNav.folder-chevron-open;
+}
+
+.treeItemActive {
+	@include treeNav.item-active;
+}
+
 .navItemActive {
   border-color: var(--color-border);
   background: var(--color-surface);
@@ -83,18 +203,61 @@
 }
 
 .icon {
-  color: inherit;
-  opacity: 0.85;
+	@include treeNav.icon;
 }
 
 .label {
-  @include text-label;
-  min-width: 0;
+	@include treeNav.label;
 }
 
 .itemMeta {
-  @include text-caption;
-  color: var(--color-text-muted);
+	@include treeNav.item-meta;
+}
+
+.sidebarCollapsed {
+  gap: var(--space-3);
+  padding: var(--space-3) var(--space-2);
+}
+
+.sidebarCollapsed .headerActions {
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+.sidebarCollapsed .headerControls {
+  justify-items: center;
+}
+
+.sidebarCollapsed .header {
+  justify-items: center;
+}
+
+.sidebarCollapsed .navScroller {
+  padding-right: 0;
+  margin-right: 0;
+}
+
+.sidebarCollapsed .navItem {
+  grid-template-columns: auto;
+  justify-content: center;
+  gap: 0;
+  min-height: calc(var(--control-size-lg) - var(--space-1));
+  padding: var(--space-2);
+  border-radius: var(--radius-md);
+}
+
+.sidebarCollapsed .label,
+.sidebarCollapsed .itemMeta,
+.sidebarCollapsed .treeSectionLabel,
+.sidebarCollapsed .treeList {
+  display: none;
+}
+
+.sidebarCollapsed .icon {
+  opacity: 1;
+}
+
+.sidebarCollapsed .section {
+  gap: var(--space-3);
 }
 
 @include respond-down(mobile) {

Frontend/src/components/shell/createLongPressGesture.ts

@@ -0,0 +1,73 @@
+import type { JSX } from "solid-js";
+
+type PointerHandler = NonNullable<JSX.DOMAttributes<Element>["onPointerDown"]>;
+
+type LongPressGestureOptions = {
+	onLongPress: () => void;
+	delay?: number;
+	movementThreshold?: number;
+};
+
+type LongPressGestureHandlers = {
+	onPointerDown: PointerHandler;
+	onPointerMove: PointerHandler;
+	onPointerUp: PointerHandler;
+	onPointerCancel: PointerHandler;
+	onPointerLeave: PointerHandler;
+};
+
+export const createLongPressGesture = (options: LongPressGestureOptions): LongPressGestureHandlers => {
+	let timeoutId: number | undefined;
+	let originX = 0;
+	let originY = 0;
+
+	const delay = options.delay ?? 420;
+	const movementThreshold = options.movementThreshold ?? 10;
+
+	const clearPendingLongPress = (): void => {
+		if (typeof timeoutId === "number") {
+			window.clearTimeout(timeoutId);
+			timeoutId = undefined;
+		}
+	};
+
+	const onPointerDown: PointerHandler = (event): void => {
+		// Mobile long-press should only respond to the primary touch/pen pointer.
+		if (event.pointerType === "mouse" || !event.isPrimary) {
+			return;
+		}
+
+		originX = event.clientX;
+		originY = event.clientY;
+		clearPendingLongPress();
+		timeoutId = window.setTimeout(() => {
+			timeoutId = undefined;
+			options.onLongPress();
+		}, delay);
+	};
+
+	const onPointerMove: PointerHandler = (event): void => {
+		if (typeof timeoutId !== "number") {
+			return;
+		}
+
+		const deltaX = Math.abs(event.clientX - originX);
+		const deltaY = Math.abs(event.clientY - originY);
+
+		if (deltaX > movementThreshold || deltaY > movementThreshold) {
+			clearPendingLongPress();
+		}
+	};
+
+	const onPointerUp: PointerHandler = (): void => {
+		clearPendingLongPress();
+	};
+
+	return {
+		onPointerDown,
+		onPointerMove,
+		onPointerUp,
+		onPointerCancel: onPointerUp,
+		onPointerLeave: onPointerUp,
+	};
+};

Frontend/src/components/shell/data/app-shell.context.tsx

@@ -0,0 +1,352 @@
+// Path: Frontend/src/components/shell/data/app-shell.context.tsx
+
+import {
+	createContext,
+	createMemo,
+	createSignal,
+	onMount,
+	useContext,
+	type Accessor,
+	type JSX,
+} from "solid-js";
+import { Folder } from "../../../lib/icons";
+import { resolveAPIBase } from "../../../lib/api";
+import {
+	activeDepartment as fallbackActiveDepartment,
+	activeProject as fallbackActiveProject,
+	activeServer as fallbackActiveServer,
+	activeUserProfile as fallbackActiveUserProfile,
+	departmentItems as fallbackDepartmentItems,
+	organizationAdminDockActions,
+	personalDockActions,
+	projectItems as fallbackProjectItems,
+	railItems as fallbackRailItems,
+	workspaceTree as fallbackWorkspaceTree,
+	type ActiveDepartment,
+	type ActiveProject,
+	type ActiveServer,
+	type ActiveUserProfile,
+	type DepartmentItem,
+	type ProjectItem,
+	type RailItem,
+	type WorkspaceTreeNode,
+} from "./shell.data";
+
+type AppShellInstallation = {
+	id: string;
+	name: string;
+	mode: "personal" | "organizational" | string;
+	access: string;
+	protocol: string;
+	host: string;
+	isBootstrapped: boolean;
+};
+
+type AppShellAdmin = {
+	id: string;
+	email: string;
+	displayName: string;
+	isInstanceAdmin: boolean;
+	homeTitle: string;
+};
+
+type AppShellOrganization = {
+	id: string;
+	name: string;
+	slug: string;
+};
+
+type AppShellDepartment = {
+	id: string;
+	organizationId: string;
+	name: string;
+	slug: string;
+};
+
+type AppShellTeam = {
+	id: string;
+	organizationId: string;
+	departmentId?: string;
+	name: string;
+	slug: string;
+};
+
+type AppShellProject = {
+	id: string;
+	organizationId: string;
+	departmentId?: string;
+	teamId?: string;
+	name: string;
+	slug: string;
+};
+
+type AppShellWorkspace = {
+	id: string;
+	organizationId: string;
+	name: string;
+	slug: string;
+	kind: "organization" | "department" | "team" | "project" | string;
+	departmentId?: string;
+	teamId?: string;
+	projectId?: string;
+};
+
+type AppShellPayload = {
+	installation?: AppShellInstallation;
+	admin?: AppShellAdmin;
+	organizations: AppShellOrganization[];
+	departments: AppShellDepartment[];
+	teams: AppShellTeam[];
+	projects: AppShellProject[];
+	workspaces: AppShellWorkspace[];
+};
+
+const normalizeAppShellPayload = (payload: AppShellPayload | null | undefined): AppShellPayload => ({
+	installation: payload?.installation,
+	admin: payload?.admin,
+	organizations: Array.isArray(payload?.organizations) ? payload.organizations : [],
+	departments: Array.isArray(payload?.departments) ? payload.departments : [],
+	teams: Array.isArray(payload?.teams) ? payload.teams : [],
+	projects: Array.isArray(payload?.projects) ? payload.projects : [],
+	workspaces: Array.isArray(payload?.workspaces) ? payload.workspaces : [],
+});
+
+type AppShellContextValue = {
+	status: Accessor<"idle" | "loading" | "success" | "error">;
+	error: Accessor<string>;
+	installation: Accessor<AppShellInstallation | undefined>;
+	railItems: Accessor<readonly RailItem[]>;
+	activeServer: Accessor<ActiveServer>;
+	activeProject: Accessor<ActiveProject>;
+	activeDepartment: Accessor<ActiveDepartment>;
+	projectItems: Accessor<readonly ProjectItem[]>;
+	departmentItems: Accessor<readonly DepartmentItem[]>;
+	workspaceTree: Accessor<readonly WorkspaceTreeNode[]>;
+	activeUserProfile: Accessor<ActiveUserProfile>;
+	reload: () => Promise<void>;
+};
+
+const AppShellContext = createContext<AppShellContextValue>();
+
+const buildAbbreviation = (name: string, fallback: string): string => {
+	const parts = name
+		.trim()
+		.split(/\s+/)
+		.filter(Boolean);
+
+	if (parts.length === 0) {
+		return fallback;
+	}
+
+	const abbreviation = parts
+		.slice(0, 2)
+		.map((part) => part[0]?.toUpperCase() ?? "")
+		.join("");
+
+	return abbreviation || fallback;
+};
+
+const buildRailItems = (payload: AppShellPayload | null): readonly RailItem[] => {
+	if (!payload?.installation || payload.organizations.length === 0) {
+		return fallbackRailItems;
+	}
+
+	const kind = payload.installation.mode === "personal" ? "personal" : "organization";
+	const serverName = payload.installation.name || payload.organizations[0]?.name || payload.installation.host;
+
+	return payload.organizations.map((organization, index) => ({
+		id: organization.id,
+		label: serverName || organization.name,
+		abbreviation: buildAbbreviation(serverName || organization.name, kind === "personal" ? "P" : "O"),
+		kind,
+		active: index === 0,
+	}));
+};
+
+const buildActiveServer = (payload: AppShellPayload | null): ActiveServer => {
+	const installation = payload?.installation;
+	const organization = payload?.organizations[0];
+
+	if (!installation || !organization) {
+		return fallbackActiveServer;
+	}
+
+	const kind = installation.mode === "personal" ? "personal" : "organization";
+	const serverName = installation.name || organization.name || installation.host;
+
+	return {
+		id: installation.id,
+		name: serverName || fallbackActiveServer.name,
+		abbreviation: buildAbbreviation(serverName, kind === "personal" ? "P" : "O"),
+		kind,
+		connectedLabel: kind === "organization" ? `${payload?.teams.length ?? 0} connected` : undefined,
+		subtitle: kind === "personal" ? installation.host || payload?.admin?.homeTitle || "Personal home" : undefined,
+		dockActions: kind === "personal" ? personalDockActions : organizationAdminDockActions,
+	};
+};
+
+const buildProjectItems = (payload: AppShellPayload | null): readonly ProjectItem[] => {
+	if (!payload?.projects.length) {
+		return fallbackProjectItems;
+	}
+
+	return payload.projects.map((project, index) => ({
+		id: project.id,
+		name: project.name,
+		description: project.slug || "Persisted project workspace",
+		groupLabel: payload.departments.find((department) => department.id === project.departmentId)?.name || "Projects",
+		parentLabel:
+			payload.teams.find((team) => team.id === project.teamId)?.name ||
+			payload.departments.find((department) => department.id === project.departmentId)?.name ||
+			"Shared project",
+		meta: (() => {
+			const workspaceCount = payload.workspaces.filter((workspace) => workspace.projectId === project.id).length;
+
+			return workspaceCount > 0 ? `${workspaceCount} workspace${workspaceCount === 1 ? "" : "s"}` : undefined;
+		})(),
+		active: index === 0,
+	}));
+};
+
+const buildActiveProject = (payload: AppShellPayload | null): ActiveProject => {
+	const firstProject = payload?.projects[0];
+
+	if (!firstProject) {
+		return fallbackActiveProject;
+	}
+
+	return {
+		id: firstProject.id,
+		name: firstProject.name,
+	};
+};
+
+const buildDepartmentItems = (payload: AppShellPayload | null): readonly DepartmentItem[] => {
+	if (!payload?.departments.length) {
+		return fallbackDepartmentItems;
+	}
+
+	return payload.departments.map((department, index) => ({
+		id: department.id,
+		name: department.name,
+		teams: payload.teams
+			.filter((team) => team.departmentId === department.id)
+			.map((team) => team.name),
+		active: index === 0,
+	}));
+};
+
+const buildActiveDepartment = (payload: AppShellPayload | null): ActiveDepartment => {
+	const firstDepartment = payload?.departments[0];
+
+	if (!firstDepartment) {
+		return fallbackActiveDepartment;
+	}
+
+	const firstTeamName = payload?.teams.find((team) => team.departmentId === firstDepartment.id)?.name ?? "";
+
+	return {
+		id: firstDepartment.id,
+		name: firstDepartment.name,
+		teamName: firstTeamName,
+	};
+};
+
+const buildWorkspaceTree = (payload: AppShellPayload | null): readonly WorkspaceTreeNode[] => {
+	if (!payload?.projects.length) {
+		return fallbackWorkspaceTree;
+	}
+
+	// The workspace tree should represent items inside the current project, not the
+	// project container itself. We do not have project-contents hydration yet, so
+	// return an empty tree rather than showing the project root as a fake item.
+	return [];
+};
+
+const buildActiveUserProfile = (payload: AppShellPayload | null): ActiveUserProfile => {
+	if (!payload?.admin) {
+		return fallbackActiveUserProfile;
+	}
+
+	const organizationName = payload.installation?.name || payload.organizations[0]?.name || fallbackActiveServer.name;
+	const departmentName = payload.departments[0]?.name;
+
+	return {
+		name: payload.admin.displayName,
+		email: payload.admin.email,
+		roleLabel: payload.admin.isInstanceAdmin ? "Instance admin" : "Member",
+		contextLabel: departmentName ? `${organizationName} • ${departmentName}` : organizationName,
+	};
+};
+
+export const AppShellDataProvider = (props: { children: JSX.Element }): JSX.Element => {
+	const [status, setStatus] = createSignal<"idle" | "loading" | "success" | "error">("idle");
+	const [error, setError] = createSignal("");
+	const [payload, setPayload] = createSignal<AppShellPayload | null>(null);
+
+	const load = async (): Promise<void> => {
+		setStatus("loading");
+		setError("");
+
+		try {
+			const response = await fetch(`${resolveAPIBase()}/app-shell`, {
+				headers: {
+					Accept: "application/json",
+				},
+			});
+
+			const body = (await response.json()) as {
+				data?: AppShellPayload;
+				error?: { message?: string } | string;
+				message?: string;
+			};
+			const errorMessage =
+				typeof body.message === "string"
+					? body.message
+					: typeof body.error === "string"
+						? body.error
+						: body.error?.message;
+
+			if (!response.ok || !body.data) {
+				throw new Error(errorMessage || "Failed to load app shell state.");
+			}
+
+			setPayload(normalizeAppShellPayload(body.data));
+			setStatus("success");
+		} catch (loadError) {
+			setStatus("error");
+			setError(loadError instanceof Error ? loadError.message : "Failed to load app shell state.");
+		}
+	};
+
+	onMount(() => {
+		void load();
+	});
+
+	const value: AppShellContextValue = {
+		status,
+		error,
+		installation: createMemo(() => payload()?.installation),
+		railItems: createMemo(() => buildRailItems(payload())),
+		activeServer: createMemo(() => buildActiveServer(payload())),
+		activeProject: createMemo(() => buildActiveProject(payload())),
+		activeDepartment: createMemo(() => buildActiveDepartment(payload())),
+		projectItems: createMemo(() => buildProjectItems(payload())),
+		departmentItems: createMemo(() => buildDepartmentItems(payload())),
+		workspaceTree: createMemo(() => buildWorkspaceTree(payload())),
+		activeUserProfile: createMemo(() => buildActiveUserProfile(payload())),
+		reload: load,
+	};
+
+	return <AppShellContext.Provider value={value}>{props.children}</AppShellContext.Provider>;
+};
+
+export const useAppShellData = (): AppShellContextValue => {
+	const context = useContext(AppShellContext);
+
+	if (!context) {
+		throw new Error("useAppShellData must be used within AppShellDataProvider");
+	}
+
+	return context;
+};

Frontend/src/components/shell/data/shell.data.ts

@@ -4,10 +4,12 @@ import type { Component } from "solid-js";
 import {
 	Bell,
 	CircleHelp,
+	FileText,
 	Folder,
 	Home,
 	Keyboard,
 	LayoutGrid,
+	ListCollapse,
 	LogOut,
 	Repeat,
 	Search,
@@ -70,9 +72,43 @@ export type ProjectItem = {
 	id: string;
 	name: string;
 	description: string;
+	groupLabel?: string;
+	parentLabel?: string;
+	meta?: string;
 	active?: boolean;
 };
 
+export type ProjectMenuTarget =
+	| {
+		id: string;
+		label: string;
+		kind: "surface";
+	  }
+	| {
+		id: string;
+		label: string;
+		kind: "folder";
+	  }
+	| {
+		id: string;
+		label: string;
+		kind: "project";
+	  };
+
+export type ProjectContextMenuAction = {
+	id: string;
+	label: string;
+	tone?: "default" | "danger";
+	shortcut?: WorkspaceContextMenuShortcut;
+	children?: readonly ProjectContextMenuAction[];
+};
+
+export type ProjectContextMenuSection = {
+	id: string;
+	label?: string;
+	items: readonly ProjectContextMenuAction[];
+};
+
 export type SidebarItem = {
 	id: string;
 	label: string;
@@ -81,12 +117,231 @@ export type SidebarItem = {
 	meta?: string;
 };
 
+export type WorkspaceStaticKind = "workspace" | "home" | "settings";
+
+// Keep this open-ended so future server-driven or plugin-provided item types do
+// not require a frontend source edit before they can be represented safely.
+export type WorkspaceItemTypeId = string;
+
+export type WorkspaceStaticItem = SidebarItem & {
+	contextKind: WorkspaceStaticKind;
+};
+
+export type WorkspaceFolderNode = {
+	id: string;
+	path?: string;
+	label: string;
+	kind: "folder";
+	icon: ShellIcon;
+	active?: boolean;
+	meta?: string;
+	children?: readonly WorkspaceTreeNode[];
+};
+
+export type WorkspaceItemNode = {
+	id: string;
+	label: string;
+	kind: "item";
+	itemType: WorkspaceItemTypeId;
+	active?: boolean;
+	meta?: string;
+	children?: undefined;
+};
+
+export type WorkspaceTreeNode = WorkspaceFolderNode | WorkspaceItemNode;
+
+export type WorkspaceItemTypeDefinition = {
+	id: WorkspaceItemTypeId;
+	label: string;
+	shortLabel: string;
+	icon: ShellIcon;
+	noun: string;
+	actionPrefix: string;
+	defaultCreateLabel: string;
+	includeInWorkspaceCreate?: boolean;
+	description?: string;
+};
+
+export type SidebarHeaderAction = {
+	id: string;
+	label: string;
+	icon: ShellIcon;
+};
+
 export type TopBarAction = {
 	id: string;
 	label: string;
 	icon: ShellIcon;
 };
 
+export type MobileBottomNavItem = {
+	id: string;
+	label: string;
+	icon: ShellIcon;
+	active?: boolean;
+};
+
+export type WorkspaceContextMenuTarget =
+	| {
+		id: string;
+		label: string;
+		kind: WorkspaceStaticKind;
+	  }
+	| {
+		id: string;
+		label: string;
+		kind: "folder";
+	  }
+	| {
+		id: string;
+		label: string;
+		kind: "item";
+		itemType: WorkspaceItemTypeId;
+	  };
+
+export type WorkspaceContextMenuAction = {
+	id: string;
+	label: string;
+	tone?: "default" | "danger";
+	shortcut?: WorkspaceContextMenuShortcut;
+	children?: readonly WorkspaceContextMenuAction[];
+};
+
+export type WorkspaceContextMenuShortcutModifier = "meta" | "alt" | "shift";
+
+export type WorkspaceContextMenuShortcutKey = "b" | "c" | "d" | "delete" | "enter" | "f" | "m" | "r";
+
+export type WorkspaceContextMenuShortcut = {
+	modifiers?: readonly WorkspaceContextMenuShortcutModifier[];
+	key: WorkspaceContextMenuShortcutKey;
+};
+
+export type WorkspaceContextMenuSection = {
+	id: string;
+	label?: string;
+	items: readonly WorkspaceContextMenuAction[];
+};
+
+export const firstPartyWorkspaceItemTypes: readonly WorkspaceItemTypeDefinition[] = [
+	{
+		id: "core.doc",
+		label: "Doc",
+		shortLabel: "Doc",
+		icon: FileText,
+		noun: "doc",
+		actionPrefix: "doc",
+		defaultCreateLabel: "New doc",
+		includeInWorkspaceCreate: true,
+		description: "Rich text documents and notes.",
+	},
+	{
+		id: "core.board.kanban",
+		label: "Kanban board",
+		shortLabel: "Board",
+		icon: LayoutGrid,
+		noun: "board",
+		actionPrefix: "board",
+		defaultCreateLabel: "New board",
+		includeInWorkspaceCreate: true,
+		description: "Default board-style workspace item.",
+	},
+	{
+		id: "core.board.list",
+		label: "List board",
+		shortLabel: "Board",
+		icon: LayoutGrid,
+		noun: "board",
+		actionPrefix: "list-board",
+		defaultCreateLabel: "New list board",
+		description: "Alternate first-party board view prepared for the future registry.",
+	},
+] as const;
+
+const workspaceItemTypeMap = new Map<WorkspaceItemTypeId, WorkspaceItemTypeDefinition>(
+	firstPartyWorkspaceItemTypes.map((definition) => [definition.id, definition]),
+);
+
+const createUnknownWorkspaceItemTypeDefinition = (
+	itemType: WorkspaceItemTypeId,
+): WorkspaceItemTypeDefinition => ({
+	id: itemType,
+	label: "Item",
+	shortLabel: "Item",
+	icon: FileText,
+	noun: "item",
+	actionPrefix: "item",
+	defaultCreateLabel: "New item",
+	description: "Fallback definition for unknown or future workspace item types.",
+});
+
+export const getWorkspaceItemTypeDefinition = (itemType: WorkspaceItemTypeId): WorkspaceItemTypeDefinition => {
+	return workspaceItemTypeMap.get(itemType) ?? createUnknownWorkspaceItemTypeDefinition(itemType);
+};
+
+export const getWorkspaceNodeIcon = (node: WorkspaceTreeNode): ShellIcon =>
+	node.kind === "folder" ? node.icon : getWorkspaceItemTypeDefinition(node.itemType).icon;
+
+const getWorkspaceCreateActions = (): readonly WorkspaceContextMenuAction[] => [
+	{ id: "new-folder", label: "New folder", shortcut: { modifiers: ["alt"], key: "f" } },
+	...firstPartyWorkspaceItemTypes
+		.filter((definition) => definition.includeInWorkspaceCreate)
+		.map((definition) => ({
+			id: `create-${definition.actionPrefix}`,
+			label: definition.defaultCreateLabel,
+			shortcut:
+				definition.id === "core.board.kanban"
+					? ({ modifiers: ["alt"], key: "b" } as const)
+					: definition.id === "core.doc"
+						? ({ modifiers: ["alt"], key: "d" } as const)
+						: undefined,
+		})),
+];
+
+export const getWorkspaceContextMenuEyebrow = (target: WorkspaceContextMenuTarget): string => {
+	switch (target.kind) {
+		case "workspace":
+		case "home":
+			return "Workspace";
+		case "settings":
+			return "Configuration";
+		case "folder":
+			return "Folder";
+		case "item":
+			return getWorkspaceItemTypeDefinition(target.itemType).shortLabel;
+	}
+};
+
+export const createWorkspaceSurfaceTarget = (workspace: ActiveProject): WorkspaceContextMenuTarget => ({
+	id: `workspace-${workspace.id}`,
+	label: workspace.name,
+	kind: "workspace",
+});
+
+export const createWorkspaceStaticTarget = (item: WorkspaceStaticItem): WorkspaceContextMenuTarget => ({
+	id: item.id,
+	label: item.label,
+	kind: item.contextKind,
+});
+
+export const createWorkspaceTreeTarget = (node: WorkspaceTreeNode): WorkspaceContextMenuTarget => ({
+	id: node.id,
+	label: node.label,
+	...(node.kind === "folder"
+		? { kind: "folder" as const }
+		: {
+			kind: "item" as const,
+			itemType: node.itemType,
+		}),
+});
+
+export type NotificationItem = {
+	id: string;
+	title: string;
+	contextLabel: string;
+	timeLabel: string;
+	unread?: boolean;
+};
+
 export type ProfileMenuAction = {
 	id: string;
 	label: string;
@@ -106,12 +361,12 @@ export type ActiveUserProfile = {
 	contextLabel: string;
 };
 
-const personalDockActions: readonly ServerDockAction[] = [
+export const personalDockActions: readonly ServerDockAction[] = [
 	{ id: "account", label: "Account", icon: User },
 	{ id: "settings", label: "Settings", icon: Settings },
 ] as const;
 
-const organizationAdminDockActions: readonly ServerDockAction[] = [
+export const organizationAdminDockActions: readonly ServerDockAction[] = [
 	{ id: "members", label: "Members", icon: User },
 	{ id: "server", label: "Server", icon: Settings },
 ] as const;
@@ -145,9 +400,31 @@ export const activeDepartment: ActiveDepartment = {
 };
 
 export const projectItems: readonly ProjectItem[] = [
-	{ id: "general", name: "General", description: "Default shared project", active: true },
-	{ id: "operations", name: "Operations", description: "Cross-team planning and delivery" },
-	{ id: "hiring", name: "Hiring", description: "Candidate pipeline and interview loops" },
+	{
+		id: "general",
+		name: "General",
+		description: "Default shared project",
+		groupLabel: "Shared space",
+		parentLabel: "Workspace home",
+		meta: "1 workspace",
+		active: true,
+	},
+	{
+		id: "operations",
+		name: "Operations",
+		description: "Cross-team planning and delivery",
+		groupLabel: "Team folders",
+		parentLabel: "Shared Services",
+		meta: "2 workspaces",
+	},
+	{
+		id: "hiring",
+		name: "Hiring",
+		description: "Candidate pipeline and interview loops",
+		groupLabel: "Team folders",
+		parentLabel: "People Ops",
+		meta: "1 workspace",
+	},
 ] as const;
 
 export const departmentItems: readonly DepartmentItem[] = [
@@ -157,18 +434,272 @@ export const departmentItems: readonly DepartmentItem[] = [
 ] as const;
 
 // Sidebar and topbar scaffold data
-export const serverSidebarItems: readonly SidebarItem[] = [
-	{ id: "home", label: "Home", icon: Home, active: true },
-	{ id: "boards", label: "Boards", icon: LayoutGrid, meta: "0" },
-	{ id: "docs", label: "Docs", icon: Folder, meta: "0" },
-	{ id: "settings", label: "Settings", icon: Settings },
+// These static entries stay pinned in both desktop and mobile workspace navigation.
+export const workspaceStaticItems: readonly WorkspaceStaticItem[] = [
+	{ id: "home", label: "Home", icon: Home, active: true, contextKind: "home" },
+	{ id: "workspace-settings", label: "Settings", icon: Settings, contextKind: "settings" },
 ] as const;
 
+// Freeform workspace tree scaffold: folders are structural, while non-folder
+// nodes already flow through the future-safe itemType registry seam.
+export const workspaceTree: readonly WorkspaceTreeNode[] = [
+	{
+		id: "product-workspace",
+		label: "Product",
+		kind: "folder",
+		icon: Folder,
+		children: [
+			{ id: "roadmap-board", label: "Roadmap", kind: "item", itemType: "core.board.kanban", active: true },
+			{ id: "launch-brief", label: "Launch Brief", kind: "item", itemType: "core.doc" },
+			{
+				id: "research-folder",
+				label: "Research",
+				kind: "folder",
+				icon: Folder,
+				children: [
+					{ id: "interviews-doc", label: "Interviews", kind: "item", itemType: "core.doc" },
+					{ id: "signals-board", label: "Signals", kind: "item", itemType: "core.board.kanban", meta: "2" },
+				],
+			},
+		],
+	},
+	{
+		id: "design-folder",
+		label: "Design",
+		kind: "folder",
+		icon: Folder,
+		children: [
+			{ id: "system-doc", label: "Design System", kind: "item", itemType: "core.doc" },
+			{ id: "review-board", label: "Review Queue", kind: "item", itemType: "core.board.kanban" },
+		],
+	},
+	{ id: "general-notes", label: "General Notes", kind: "item", itemType: "core.doc" },
+] as const;
+
+export const workspaceSidebarHeaderActions: readonly SidebarHeaderAction[] = [
+	{ id: "search-workspace", label: "Search workspace", icon: Search },
+	{ id: "toggle-workspace-folders", label: "Collapse all folders", icon: ListCollapse },
+] as const;
+
+export const mobileBottomNavItems: readonly MobileBottomNavItem[] = [
+	{ id: "home", label: "Home", icon: Home, active: true },
+	{ id: "search", label: "Search", icon: Search },
+	{ id: "browse", label: "Browse", icon: Folder },
+] as const;
+
+// Initial context-menu IA scaffold. Behavior wiring can evolve later, but the
+// target kinds and action grouping should stay shared across workspace surfaces.
+export const getWorkspaceContextMenuSections = (
+	target: WorkspaceContextMenuTarget,
+): readonly WorkspaceContextMenuSection[] => {
+	const createActions = getWorkspaceCreateActions();
+
+	const createSubmenuAction = {
+		id: "create",
+		label: "Create",
+		children: createActions,
+	} as const;
+
+	switch (target.kind) {
+		case "workspace":
+			return [
+				{
+					id: "create",
+					label: undefined,
+					items: [createSubmenuAction],
+				},
+				{
+					id: "workspace",
+					label: undefined,
+					items: [
+						{ id: "rename-workspace", label: "Rename workspace", shortcut: { key: "enter" } },
+						{ id: "copy-workspace-link", label: "Copy link", shortcut: { modifiers: ["meta"], key: "c" } },
+					],
+				},
+			] as const;
+		case "home":
+			return [
+				{
+					id: "create",
+					label: undefined,
+					items: [createSubmenuAction],
+				},
+				{
+					id: "workspace",
+					label: undefined,
+					items: [{ id: "open-home", label: "Open home", shortcut: { key: "enter" } }],
+				},
+			] as const;
+		case "settings":
+			return [
+				{
+					id: "settings",
+					label: undefined,
+					items: [
+						{ id: "open-settings", label: "Open settings", shortcut: { key: "enter" } },
+						{ id: "copy-settings-link", label: "Copy link", shortcut: { modifiers: ["meta"], key: "c" } },
+					],
+				},
+			] as const;
+		case "folder":
+			return [
+				{
+					id: "open",
+					items: [
+						{ id: "open-folder", label: "Open folder", shortcut: { key: "enter" } },
+						{ id: "rename-folder", label: "Rename", shortcut: { modifiers: ["meta"], key: "r" } },
+					],
+				},
+				{
+					id: "create",
+					label: undefined,
+					items: [createSubmenuAction],
+				},
+				{
+					id: "organize",
+					label: undefined,
+					items: [
+						{ id: "duplicate-folder", label: "Duplicate", shortcut: { modifiers: ["meta"], key: "d" } },
+						{ id: "move-folder", label: "Move", shortcut: { modifiers: ["meta"], key: "m" } },
+						{ id: "delete-folder", label: "Delete", shortcut: { modifiers: ["meta"], key: "delete" }, tone: "danger" },
+					],
+				},
+			] as const;
+		case "item": {
+			const definition = getWorkspaceItemTypeDefinition(target.itemType);
+			const actionPrefix = definition.actionPrefix;
+			const nounLabel = definition.noun;
+
+			return [
+				{
+					id: `${actionPrefix}-primary`,
+					items: [
+						{ id: `open-${actionPrefix}`, label: `Open ${nounLabel}`, shortcut: { key: "enter" } },
+						{ id: `rename-${actionPrefix}`, label: "Rename", shortcut: { modifiers: ["meta"], key: "r" } },
+					],
+				},
+				{
+					id: "organize",
+					label: undefined,
+					items: [
+						{ id: `duplicate-${actionPrefix}`, label: "Duplicate", shortcut: { modifiers: ["meta"], key: "d" } },
+						{ id: `move-${actionPrefix}`, label: "Move", shortcut: { modifiers: ["meta"], key: "m" } },
+						{ id: `delete-${actionPrefix}`, label: "Delete", shortcut: { modifiers: ["meta"], key: "delete" }, tone: "danger" },
+					],
+				},
+			] as const;
+		}
+	}
+};
+
+const getProjectCreateActions = (): readonly ProjectContextMenuAction[] =>
+	[
+		{ id: "new-project", label: "New project" },
+		{ id: "new-folder", label: "New folder" },
+	] as const;
+
+const getProjectFolderDangerActions = (): readonly ProjectContextMenuAction[] =>
+	[
+		{ id: "rename-folder", label: "Rename", shortcut: { modifiers: ["meta"], key: "r" } },
+		{ id: "delete-folder", label: "Delete", shortcut: { modifiers: ["meta"], key: "delete" }, tone: "danger" },
+	] as const;
+
+export const createProjectSurfaceTarget = (label = "Projects"): ProjectMenuTarget => ({
+	id: "project-surface",
+	label,
+	kind: "surface",
+});
+
+export const createProjectFolderTarget = (id: string, label: string): ProjectMenuTarget => ({
+	id,
+	label,
+	kind: "folder",
+});
+
+export const createProjectTarget = (project: ProjectItem): ProjectMenuTarget => ({
+	id: project.id,
+	label: project.name,
+	kind: "project",
+});
+
+export const getProjectContextMenuEyebrow = (target: ProjectMenuTarget): string => {
+	switch (target.kind) {
+		case "surface":
+			return "Projects";
+		case "folder":
+			return "Folder";
+		case "project":
+			return "Project";
+	}
+};
+
+export const getProjectContextMenuSections = (target: ProjectMenuTarget): readonly ProjectContextMenuSection[] => {
+	const createActions = getProjectCreateActions();
+
+	switch (target.kind) {
+		case "surface":
+			return [
+				{
+					id: "create",
+					items: createActions,
+				},
+			] as const;
+		case "folder":
+			return [
+				{
+					id: "create",
+					items: createActions,
+				},
+				{
+					id: "organize",
+					items: getProjectFolderDangerActions(),
+				},
+			] as const;
+		case "project":
+			return [
+				{
+					id: "create",
+					items: createActions,
+				},
+			] as const;
+	}
+};
+
 export const topBarActions: readonly TopBarAction[] = [
 	{ id: "search", label: "Search", icon: Search },
-	{ id: "inbox", label: "Inbox", icon: Bell },
 ] as const;
 
+export const notificationItems: readonly NotificationItem[] = [
+	{
+		id: "comment-design-systems",
+		title: "New comment on Design Systems",
+		contextLabel: "Product • Review thread updated",
+		timeLabel: "2m ago",
+		unread: true,
+	},
+	{
+		id: "sprint-platform",
+		title: "Sprint updated in Platform",
+		contextLabel: "Engineering • Scope changed",
+		timeLabel: "15m ago",
+		unread: true,
+	},
+	{
+		id: "member-joined",
+		title: "New member joined Operations",
+		contextLabel: "Organization Name • Access granted",
+		timeLabel: "1h ago",
+	},
+	{
+		id: "daily-summary",
+		title: "Daily summary is ready",
+		contextLabel: "General • 8 updates across boards",
+		timeLabel: "Today, 8:00 AM",
+	},
+] as const;
+
+export const unreadNotificationCount = notificationItems.filter((item) => item.unread).length;
+
 export const activeUserProfile: ActiveUserProfile = {
 	name: "Demo Account",
 	email: "demo@moku.work",

Frontend/src/components/shell/shared/_tree-nav.scss

@@ -0,0 +1,188 @@
+@use "../../../styles/tools/mixins" as *;
+
+@mixin section-label {
+	@include text-caption;
+	color: var(--color-text-subtle);
+	text-transform: uppercase;
+	letter-spacing: 0.04em;
+}
+
+@mixin tree-list {
+	list-style: none;
+	display: grid;
+	gap: var(--space-1);
+	padding: 0;
+}
+
+@mixin empty-slot {
+	min-height: calc(var(--control-size-lg) - var(--space-2));
+	padding-left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
+	border-radius: var(--radius-lg);
+	border: 1px dashed color-mix(in srgb, var(--color-border) 38%, transparent);
+	opacity: 0.35;
+}
+
+@mixin input-row {
+	width: 100%;
+	min-width: 0;
+	display: grid;
+	grid-template-columns: auto minmax(0, 1fr);
+	align-items: center;
+	gap: var(--space-2);
+	min-height: calc(var(--control-size-lg) - var(--space-2));
+	padding: var(--space-2) var(--space-3);
+	padding-left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
+	border: 1px solid color-mix(in srgb, var(--color-border) 42%, transparent);
+	border-radius: var(--radius-lg);
+	background: color-mix(in srgb, var(--color-surface) 94%, transparent);
+}
+
+@mixin input {
+	width: 100%;
+	min-width: 0;
+	border: 0;
+	background: transparent;
+	color: var(--color-text);
+	font: inherit;
+	outline: none;
+
+	&::placeholder {
+		color: var(--color-text-muted);
+	}
+}
+
+@mixin item {
+	width: 100%;
+	min-width: 0;
+	display: grid;
+	position: relative;
+	isolation: isolate;
+	grid-template-columns: auto auto minmax(0, 1fr) auto;
+	align-items: center;
+	gap: var(--space-2);
+	min-height: calc(var(--control-size-lg) - var(--space-2));
+	padding: var(--space-2) var(--space-3);
+	padding-left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
+	border: 0;
+	border-radius: 0;
+	background: transparent;
+	color: var(--color-text-muted);
+	text-align: left;
+	transition:
+		color 160ms var(--easing-standard),
+		box-shadow 160ms var(--easing-standard),
+		transform 180ms var(--easing-standard);
+
+	&::after {
+		content: "";
+		position: absolute;
+		inset: 0;
+		border: 1px solid transparent;
+		border-radius: var(--radius-lg);
+		background: transparent;
+		transition:
+			background 160ms var(--easing-standard),
+			border-color 160ms var(--easing-standard),
+			box-shadow 160ms var(--easing-standard);
+		pointer-events: none;
+		z-index: 0;
+	}
+
+	> * {
+		position: relative;
+		z-index: 1;
+	}
+}
+
+@mixin item-hover {
+	color: var(--color-text);
+
+	&::after {
+		background: color-mix(in srgb, var(--color-surface-hover) 80%, var(--color-accent-soft) 20%);
+		box-shadow: inset 0 1px 0 color-mix(in srgb, white 4%, transparent);
+	}
+}
+
+@mixin item-folder {
+	color: var(--color-text);
+}
+
+@mixin item-dragging {
+	opacity: 0.45;
+	transform: scale(0.985);
+	box-shadow: none;
+}
+
+@mixin item-drop-before {
+	&::before {
+		content: "";
+		position: absolute;
+		left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
+		right: var(--space-3);
+		top: calc((var(--space-1) * -0.5) - 1px);
+		height: 2px;
+		border-radius: 999px;
+		background: color-mix(in srgb, var(--color-accent-strong) 78%, transparent);
+		pointer-events: none;
+		z-index: 2;
+	}
+}
+
+@mixin item-drop-after {
+	&::before {
+		content: "";
+		position: absolute;
+		left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
+		right: var(--space-3);
+		bottom: calc((var(--space-1) * -0.5) - 1px);
+		height: 2px;
+		border-radius: 999px;
+		background: color-mix(in srgb, var(--color-accent-strong) 78%, transparent);
+		pointer-events: none;
+		z-index: 2;
+	}
+}
+
+@mixin item-drop-inside {
+	color: var(--color-text);
+
+	&::after {
+		border-color: color-mix(in srgb, var(--color-accent-strong) 55%, transparent);
+		background: color-mix(in srgb, var(--color-accent-soft) 36%, var(--color-surface));
+		box-shadow: inset 0 1px 0 color-mix(in srgb, white 4%, transparent);
+	}
+}
+
+@mixin folder-chevron {
+	color: var(--color-text-muted);
+	transition: transform 160ms var(--easing-standard);
+}
+
+@mixin folder-chevron-open {
+	transform: rotate(90deg);
+}
+
+@mixin item-active {
+	color: var(--color-text);
+
+	&::after {
+		border-color: var(--color-border);
+		background: var(--color-surface);
+		box-shadow: inset 0 1px 0 color-mix(in srgb, white 4%, transparent);
+	}
+}
+
+@mixin icon {
+	color: inherit;
+	opacity: 0.85;
+}
+
+@mixin label {
+	@include text-label;
+	min-width: 0;
+}
+
+@mixin item-meta {
+	@include text-caption;
+	color: var(--color-text-muted);
+}

Frontend/src/components/shell/shared/navTreeDnd.ts

@@ -0,0 +1,278 @@
+export type NavTreeDropIntent = "before" | "after" | "inside";
+
+export type NavTreeDropTarget = {
+	parentId: string | null;
+	index: number;
+	intent: NavTreeDropIntent;
+	targetNodeId?: string;
+};
+
+export type NavTreeDragState = {
+	draggedNodeId: string;
+	dropTarget: NavTreeDropTarget | null;
+};
+
+export type NavTreeLocation<TNode> = {
+	parentId: string | null;
+	index: number;
+	node: TNode;
+};
+
+export type NavTreeAdapter<TNode> = {
+	getNodeId: (node: TNode) => string;
+	isBranchNode: (node: TNode) => boolean;
+	getChildren: (node: TNode) => readonly TNode[];
+	withChildren: (node: TNode, children: readonly TNode[]) => TNode;
+};
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export const isUuidString = (value: string | null | undefined): boolean => {
+	if (typeof value !== "string") {
+		return false;
+	}
+
+	return UUID_PATTERN.test(value.trim());
+};
+
+export const collectBranchNodeIds = <TNode>(
+	nodes: readonly TNode[],
+	adapter: NavTreeAdapter<TNode>,
+): string[] => {
+	const ids: string[] = [];
+
+	for (const node of nodes) {
+		if (!adapter.isBranchNode(node)) {
+			continue;
+		}
+
+		ids.push(adapter.getNodeId(node));
+		ids.push(...collectBranchNodeIds(adapter.getChildren(node), adapter));
+	}
+
+	return ids;
+};
+
+export const findTreeNodeLocation = <TNode>(
+	nodes: readonly TNode[],
+	nodeId: string,
+	adapter: NavTreeAdapter<TNode>,
+	parentId: string | null = null,
+): NavTreeLocation<TNode> | null => {
+	for (let index = 0; index < nodes.length; index += 1) {
+		const node = nodes[index];
+
+		if (adapter.getNodeId(node) === nodeId) {
+			return { parentId, index, node };
+		}
+
+		if (!adapter.isBranchNode(node)) {
+			continue;
+		}
+
+		const nestedLocation = findTreeNodeLocation(adapter.getChildren(node), nodeId, adapter, adapter.getNodeId(node));
+		if (nestedLocation) {
+			return nestedLocation;
+		}
+	}
+
+	return null;
+};
+
+export const findTreeNodeDepth = <TNode>(
+	nodes: readonly TNode[],
+	nodeId: string,
+	adapter: NavTreeAdapter<TNode>,
+	depth = 0,
+): number | null => {
+	for (const node of nodes) {
+		if (adapter.getNodeId(node) === nodeId) {
+			return depth;
+		}
+
+		if (!adapter.isBranchNode(node)) {
+			continue;
+		}
+
+		const nestedDepth = findTreeNodeDepth(adapter.getChildren(node), nodeId, adapter, depth + 1);
+		if (nestedDepth !== null) {
+			return nestedDepth;
+		}
+	}
+
+	return null;
+};
+
+export const treeContainsNode = <TNode>(
+	nodes: readonly TNode[],
+	nodeId: string,
+	adapter: NavTreeAdapter<TNode>,
+): boolean => {
+	for (const node of nodes) {
+		if (adapter.getNodeId(node) === nodeId) {
+			return true;
+		}
+
+		if (adapter.isBranchNode(node) && treeContainsNode(adapter.getChildren(node), nodeId, adapter)) {
+			return true;
+		}
+	}
+
+	return false;
+};
+
+export const removeTreeNode = <TNode>(
+	nodes: readonly TNode[],
+	nodeId: string,
+	adapter: NavTreeAdapter<TNode>,
+): { nodes: TNode[]; removed: TNode | null } => {
+	const nextNodes: TNode[] = [];
+	let removed: TNode | null = null;
+
+	for (const node of nodes) {
+		if (adapter.getNodeId(node) === nodeId) {
+			removed = node;
+			continue;
+		}
+
+		if (adapter.isBranchNode(node)) {
+			const result = removeTreeNode(adapter.getChildren(node), nodeId, adapter);
+
+			if (result.removed) {
+				removed = result.removed;
+				nextNodes.push(adapter.withChildren(node, result.nodes));
+				continue;
+			}
+		}
+
+		nextNodes.push(node);
+	}
+
+	return { nodes: nextNodes, removed };
+};
+
+export const insertTreeNode = <TNode>(
+	nodes: readonly TNode[],
+	parentId: string | null,
+	index: number,
+	nodeToInsert: TNode,
+	adapter: NavTreeAdapter<TNode>,
+): TNode[] => {
+	if (parentId === null) {
+		const nextNodes = [...nodes];
+		nextNodes.splice(Math.max(0, Math.min(index, nextNodes.length)), 0, nodeToInsert);
+		return nextNodes;
+	}
+
+	return nodes.map((node) => {
+		if (!adapter.isBranchNode(node)) {
+			return node;
+		}
+
+		if (adapter.getNodeId(node) === parentId) {
+			const nextChildren = [...adapter.getChildren(node)];
+			nextChildren.splice(Math.max(0, Math.min(index, nextChildren.length)), 0, nodeToInsert);
+			return adapter.withChildren(node, nextChildren);
+		}
+
+		return adapter.withChildren(node, insertTreeNode(adapter.getChildren(node), parentId, index, nodeToInsert, adapter));
+	});
+};
+
+export const moveTreeNode = <TNode>(
+	nodes: readonly TNode[],
+	draggedNodeId: string,
+	dropTarget: NavTreeDropTarget,
+	adapter: NavTreeAdapter<TNode>,
+): TNode[] => {
+	const location = findTreeNodeLocation(nodes, draggedNodeId, adapter);
+
+	if (!location) {
+		return [...nodes];
+	}
+
+	if (
+		adapter.isBranchNode(location.node) &&
+		dropTarget.parentId !== null &&
+		(treeContainsNode(adapter.getChildren(location.node), dropTarget.parentId, adapter) ||
+			dropTarget.parentId === adapter.getNodeId(location.node))
+	) {
+		return [...nodes];
+	}
+
+	let normalizedIndex = dropTarget.index;
+	if (dropTarget.parentId === location.parentId && dropTarget.index > location.index) {
+		normalizedIndex -= 1;
+	}
+
+	if (dropTarget.parentId === location.parentId && normalizedIndex === location.index) {
+		return [...nodes];
+	}
+
+	const removalResult = removeTreeNode(nodes, draggedNodeId, adapter);
+	if (!removalResult.removed) {
+		return [...nodes];
+	}
+
+	return insertTreeNode(removalResult.nodes, dropTarget.parentId, normalizedIndex, removalResult.removed, adapter);
+};
+
+export const getPointerRelativeY = (event: PointerEvent): number | null => {
+	const currentTarget = event.currentTarget;
+	if (!(currentTarget instanceof HTMLElement)) {
+		return null;
+	}
+
+	const bounds = currentTarget.getBoundingClientRect();
+	return bounds.height <= 0 ? 0.5 : (event.clientY - bounds.top) / bounds.height;
+};
+
+export const resolveTreeDropTarget = <TNode>(params: {
+	parentId: string | null;
+	index: number;
+	node: TNode;
+	relativeY: number;
+	adapter: NavTreeAdapter<TNode>;
+	beforeThreshold?: number;
+	beforeThresholdFirstSibling?: number;
+	afterThreshold?: number;
+}): NavTreeDropTarget => {
+	const {
+		parentId,
+		index,
+		node,
+		relativeY,
+		adapter,
+		beforeThreshold = 0.28,
+		beforeThresholdFirstSibling = 0.42,
+		afterThreshold = 0.72,
+	} = params;
+
+	const targetNodeId = adapter.getNodeId(node);
+
+	if (adapter.isBranchNode(node)) {
+		const nextBeforeThreshold = index === 0 ? beforeThresholdFirstSibling : beforeThreshold;
+
+		if (relativeY < nextBeforeThreshold) {
+			return { parentId, index, intent: "before", targetNodeId };
+		}
+
+		if (relativeY > afterThreshold) {
+			return { parentId, index: index + 1, intent: "after", targetNodeId };
+		}
+
+		return {
+			parentId: targetNodeId,
+			index: adapter.getChildren(node).length,
+			intent: "inside",
+			targetNodeId,
+		};
+	}
+
+	return {
+		parentId,
+		index: relativeY < 0.5 ? index : index + 1,
+		intent: relativeY < 0.5 ? "before" : "after",
+		targetNodeId,
+	};
+};

Frontend/src/components/workspace-home/WorkspaceHome/WorkspaceHome.module.scss

@@ -1,6 +1,11 @@
-.viewport {
+.viewport,
+.wizardLayer {
   --workspace-content-max-width: var(--content-width-wide);
-  --workspace-card-min-height: calc(var(--space-12) * 3);
+  --bootstrap-accent: var(--color-accent-primary, var(--color-primary-2, hsl(272 80% 70%)));
+  --bootstrap-accent-contrast: var(--color-accent-primary-contrast, white);
+}
+
+.viewport {
   min-width: 0;
   min-height: 0;
   display: grid;
@@ -9,6 +14,71 @@
   padding: var(--space-5) var(--space-6);
 }
 
+.workspaceTopBar {
+  width: 100%;
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  align-items: center;
+	gap: var(--space-2);
+	min-height: calc(var(--control-size-md) - var(--space-3));
+	padding: 0;
+}
+
+.workspaceTopBarStart,
+.workspaceTopBarEnd {
+	min-width: calc(var(--control-size-md) - 0.5rem);
+  display: inline-flex;
+  align-items: center;
+}
+
+.workspaceTopBarEnd {
+  justify-content: flex-end;
+}
+
+.workspaceTopBarCenter {
+  min-width: 0;
+  display: flex;
+  justify-content: center;
+}
+
+.workspaceBreadcrumb {
+	@include text-caption;
+  min-width: 0;
+  color: var(--color-text-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.workspaceCollapseButton {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+	width: calc(var(--control-size-md) - 0.5rem);
+	height: calc(var(--control-size-md) - 0.5rem);
+  border: 1px solid color-mix(in srgb, var(--color-border-strong) 44%, transparent);
+  border-radius: var(--radius-pill);
+  background: color-mix(in srgb, var(--color-surface) 94%, transparent);
+  color: var(--color-text-muted);
+  box-shadow: var(--shadow-soft);
+  transition:
+    background 160ms var(--easing-standard),
+    color 160ms var(--easing-standard),
+    border-color 160ms var(--easing-standard),
+    transform 180ms var(--easing-standard);
+}
+
+.workspaceCollapseButton:hover,
+.workspaceCollapseButton:focus-visible {
+  background: var(--color-surface-hover);
+  border-color: var(--color-border);
+  color: var(--color-text);
+}
+
+.workspaceCollapseButton:hover {
+  transform: translateY(-1px);
+}
+
 .hero {
   display: grid;
   gap: var(--space-3);
@@ -16,10 +86,10 @@
   max-width: var(--workspace-content-max-width);
 }
 
-.eyebrow {
-  @include text-caption;
-  color: var(--color-text-muted);
-  text-transform: uppercase;
+.heroActions {
+  display: flex;
+  gap: var(--space-3);
+  flex-wrap: wrap;
 }
 
 .title {
@@ -33,18 +103,12 @@
   color: var(--color-text-muted);
 }
 
-.grid {
-  width: 100%;
-  max-width: var(--workspace-content-max-width);
-  display: grid;
-  grid-template-columns: repeat(3, minmax(0, 1fr));
-  gap: var(--space-4);
-}
-
-.card {
+.overviewCard,
+.summaryCard,
+.wizardSidebarSection,
+.wizardStepPanel {
   display: grid;
   gap: var(--space-2);
-  min-height: var(--workspace-card-min-height);
   padding: var(--space-4);
   border: 1px solid var(--color-border);
   border-radius: var(--radius-xl);
@@ -52,28 +116,456 @@
   box-shadow: var(--shadow-soft);
 }
 
-.cardTitle {
+.overviewCard {
+  width: 100%;
+  max-width: var(--workspace-content-max-width);
+  gap: var(--space-3);
+}
+
+.summaryGrid {
+  width: 100%;
+  max-width: var(--workspace-content-max-width);
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--space-4);
+}
+
+.summaryCard {
+  min-height: 0;
+}
+
+.summaryCardHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-3);
+}
+
+.summaryStepNumber,
+.wizardStepEyebrow {
+  @include text-caption;
+  color: var(--color-text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+
+.sectionHeader {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--space-3);
+}
+
+.sectionTitle,
+.cardTitle,
+.wizardTitle,
+.sidebarTitle {
   @include text-title;
 }
 
-.cardCopy {
+.sectionCopy,
+.cardCopy,
+.cardMeta {
   color: var(--color-text-muted);
 }
 
+.statusBadge {
+  @include text-caption;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: calc(var(--control-size-sm) - 0.25rem);
+  padding: 0 var(--space-2);
+  border-radius: var(--radius-pill);
+  border: 1px solid color-mix(in srgb, var(--color-border-strong) 44%, transparent);
+  background: color-mix(in srgb, var(--color-surface-secondary) 92%, transparent);
+  color: var(--color-text-muted);
+  white-space: nowrap;
+}
+
+.statusBadge[data-status="submitting"] {
+  color: var(--bootstrap-accent);
+  border-color: color-mix(in srgb, var(--bootstrap-accent) 38%, transparent);
+}
+
+.statusBadge[data-status="success"] {
+  color: var(--color-success-text, var(--color-text));
+  border-color: color-mix(in srgb, var(--color-success-border, var(--color-border)) 64%, transparent);
+  background: color-mix(in srgb, var(--color-success-surface, var(--color-surface-secondary)) 80%, transparent);
+}
+
+.statusBadge[data-status="error"] {
+  color: var(--color-danger-text, var(--color-text));
+  border-color: color-mix(in srgb, var(--color-danger-border, var(--color-border)) 68%, transparent);
+  background: color-mix(in srgb, var(--color-danger-surface, var(--color-surface-secondary)) 80%, transparent);
+}
+
+.endpointMeta {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  flex-wrap: wrap;
+}
+
+.endpointMeta span {
+  @include text-caption;
+  color: var(--color-text-muted);
+  text-transform: uppercase;
+}
+
+.endpointMeta code,
 .cardMeta {
   @include text-caption;
+}
+
+.endpointMeta code {
+  padding: 0.125rem 0.5rem;
+  border-radius: var(--radius-pill);
+  background: color-mix(in srgb, var(--color-surface-secondary) 90%, transparent);
+  color: var(--color-text);
+}
+
+.form {
+  display: grid;
+  gap: var(--space-3);
+}
+
+.field {
+  display: grid;
+  gap: var(--space-1);
+}
+
+.fieldLabel {
+  @include text-caption;
   color: var(--color-text-muted);
 }
 
+.fieldHelp {
+  @include text-caption;
+  color: var(--color-text-muted);
+}
+
+.field input,
+.field select {
+  min-height: var(--control-size-md);
+  width: 100%;
+  font: inherit;
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-lg);
+  background: var(--color-surface-elevated);
+  color: var(--color-text);
+  padding: 0 var(--space-3);
+  transition:
+    border-color 160ms var(--easing-standard),
+    box-shadow 160ms var(--easing-standard),
+    background 160ms var(--easing-standard);
+}
+
+.field input:disabled,
+.field select:disabled {
+  cursor: not-allowed;
+  color: var(--color-text-muted);
+  background: color-mix(in srgb, var(--color-surface-secondary) 92%, transparent);
+  border-color: color-mix(in srgb, var(--color-border) 72%, transparent);
+}
+
+.field input:focus-visible,
+.field select:focus-visible {
+  outline: none;
+  border-color: color-mix(in srgb, var(--bootstrap-accent) 60%, var(--color-border));
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--bootstrap-accent) 16%, transparent);
+}
+
+.wizardFormActions,
+.heroActions,
+.primaryButton,
+.secondaryButton {
+  display: flex;
+  align-items: center;
+}
+
+.wizardFormActions {
+  justify-content: space-between;
+  gap: var(--space-3);
+  flex-wrap: nowrap;
+}
+
+.wizardFormActions .primaryButton {
+  margin-left: auto;
+}
+
+.primaryButton,
+.secondaryButton,
+.wizardStepButton,
+.wizardCloseButton {
+  appearance: none;
+  justify-content: center;
+  gap: var(--space-2);
+  min-height: var(--control-size-md);
+  border-radius: var(--radius-pill);
+  font-weight: 600;
+  cursor: pointer;
+  transition:
+    transform 180ms var(--easing-standard),
+    background 160ms var(--easing-standard),
+    border-color 160ms var(--easing-standard),
+    color 160ms var(--easing-standard),
+    box-shadow 160ms var(--easing-standard);
+}
+
+.primaryButton,
+.secondaryButton,
+.wizardCloseButton {
+  padding: 0 var(--space-4);
+}
+
+.primaryButton {
+  border: 1px solid color-mix(in srgb, var(--bootstrap-accent) 72%, black 8%);
+  background: linear-gradient(
+    180deg,
+    color-mix(in srgb, var(--bootstrap-accent) 88%, white 12%),
+    color-mix(in srgb, var(--bootstrap-accent) 92%, black 8%)
+  );
+  color: var(--bootstrap-accent-contrast);
+  box-shadow:
+    inset 0 1px 0 color-mix(in srgb, white 28%, transparent),
+    0 10px 24px color-mix(in srgb, var(--bootstrap-accent) 26%, transparent);
+}
+
+.secondaryButton,
+.wizardCloseButton {
+  border: 1px solid var(--color-border);
+  background: var(--color-surface-secondary);
+  color: var(--color-text);
+}
+
+.primaryButton:hover,
+.secondaryButton:hover,
+.wizardCloseButton:hover,
+.wizardStepButton:hover {
+  transform: translateY(-1px);
+}
+
+.primaryButton:hover,
+.primaryButton:focus-visible {
+  background: linear-gradient(
+    180deg,
+    color-mix(in srgb, var(--bootstrap-accent) 84%, white 16%),
+    color-mix(in srgb, var(--bootstrap-accent) 90%, black 10%)
+  );
+  border-color: color-mix(in srgb, var(--bootstrap-accent) 78%, black 10%);
+  box-shadow:
+    inset 0 1px 0 color-mix(in srgb, white 32%, transparent),
+    0 14px 32px color-mix(in srgb, var(--bootstrap-accent) 30%, transparent);
+}
+
+.primaryButton:disabled,
+.secondaryButton:disabled {
+  opacity: 0.72;
+  cursor: not-allowed;
+  transform: none;
+  box-shadow: none;
+}
+
+.errorText {
+  @include text-caption;
+  color: var(--color-danger-text, var(--color-text));
+}
+
+.wizardLayer {
+  position: fixed;
+  inset: 0;
+  z-index: var(--z-modal);
+}
+
+.wizardBackdrop {
+  position: absolute;
+  inset: 0;
+  border: 0;
+  background: color-mix(in srgb, black 56%, transparent);
+  backdrop-filter: blur(var(--blur-overlay));
+}
+
+.wizardPanel {
+  position: relative;
+  z-index: 1;
+  width: min(calc(100vw - (var(--space-6) * 2)), 72rem);
+  max-height: calc(100dvh - (var(--space-6) * 2));
+  margin: var(--space-6) auto;
+  display: grid;
+  gap: var(--space-4);
+  padding: var(--space-4);
+  border: 1px solid color-mix(in srgb, var(--color-border) 88%, transparent);
+  border-radius: var(--radius-xl);
+  background: color-mix(in srgb, var(--color-surface) 94%, var(--color-surface-elevated, var(--color-surface)) 6%);
+  box-shadow: var(--shadow-strong);
+  overflow: auto;
+}
+
+.wizardHeader {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--space-4);
+}
+
+.wizardHeaderCopy {
+  min-width: 0;
+  display: grid;
+  gap: var(--space-1);
+}
+
+.wizardBody {
+  display: grid;
+  grid-template-columns: minmax(17rem, 20rem) minmax(0, 1fr);
+  gap: var(--space-4);
+  min-height: 0;
+}
+
+.wizardSidebar {
+  display: grid;
+  gap: var(--space-4);
+  align-content: start;
+}
+
+.wizardSidebarSection {
+  gap: var(--space-3);
+}
+
+.wizardSteps {
+  display: grid;
+  gap: var(--space-2);
+}
+
+.wizardStepButton {
+  width: 100%;
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  align-items: center;
+  text-align: left;
+  padding: var(--space-2) var(--space-3);
+  border: 1px solid color-mix(in srgb, var(--color-border) 88%, transparent);
+  background: color-mix(in srgb, var(--color-surface-secondary) 84%, transparent);
+}
+
+.wizardStepButton[data-active="true"] {
+  border-color: color-mix(in srgb, var(--bootstrap-accent) 42%, transparent);
+  background: color-mix(in srgb, var(--bootstrap-accent) 10%, var(--color-surface));
+}
+
+.wizardStepButton:disabled {
+  opacity: 0.56;
+  cursor: not-allowed;
+  transform: none;
+}
+
+.wizardStepIndex {
+  width: calc(var(--control-size-md) - var(--space-2));
+  height: calc(var(--control-size-md) - var(--space-2));
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--radius-pill);
+  background: color-mix(in srgb, var(--color-surface) 80%, transparent);
+  color: var(--color-text);
+}
+
+.wizardStepCopy {
+  min-width: 0;
+  display: grid;
+  gap: 0.125rem;
+}
+
+.wizardStepCopy strong {
+  @include text-label;
+}
+
+.wizardStepCopy small {
+  @include text-caption;
+  color: var(--color-text-muted);
+}
+
+.wizardStepPanel {
+  align-content: start;
+  gap: var(--space-3);
+}
+
 @include respond-down(tablet) {
-  .grid {
+  .summaryGrid,
+  .wizardBody {
     grid-template-columns: 1fr;
   }
+
+  .sectionHeader,
+  .wizardHeader {
+    display: grid;
+  }
 }
 
 @include respond-down(mobile) {
   .viewport {
     gap: var(--space-4);
-    padding: var(--space-4);
+    padding: var(--space-4) var(--space-4) calc(var(--space-8) + env(safe-area-inset-bottom, 0px));
+  }
+
+  .workspaceTopBar {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .workspaceTopBarStart,
+  .workspaceTopBarEnd,
+  .workspaceCollapseButton {
+    display: none;
+  }
+
+  .workspaceTopBarCenter {
+    justify-content: flex-start;
+  }
+
+  .summaryGrid {
+    grid-template-columns: 1fr;
+  }
+
+  .wizardPanel {
+    width: 100vw;
+    max-height: 100dvh;
+    margin: 0;
+    padding: var(--space-3);
+    padding-bottom: calc(var(--space-3) + env(safe-area-inset-bottom, 0px));
+    border-radius: 0;
+  }
+
+  .wizardHeader,
+  .wizardBody,
+  .wizardSidebar {
+    gap: var(--space-3);
+  }
+
+  .wizardSteps {
+    grid-auto-flow: column;
+    grid-auto-columns: minmax(10rem, 1fr);
+    overflow-x: auto;
+    padding-bottom: var(--space-1);
+    scrollbar-width: thin;
+  }
+
+  .wizardStepButton {
+    min-width: 10rem;
+  }
+
+  .wizardFormActions {
+    gap: var(--space-2);
+    flex-direction: column-reverse;
+    align-items: stretch;
+  }
+
+  .wizardFormActions .primaryButton {
+    margin-left: 0;
+  }
+
+  .wizardFormActions .primaryButton,
+  .wizardFormActions .secondaryButton,
+  .wizardCloseButton {
+    width: 100%;
   }
 }

Frontend/src/components/workspace-home/WorkspaceHome/WorkspaceHome.tsx

@@ -1,55 +1,632 @@
 // Path: Frontend/src/components/workspace-home/WorkspaceHome/WorkspaceHome.tsx
 
-import { For, type JSX } from "solid-js";
-import { activeServer } from "../../shell/data/shell.data";
+import { For, Show, createEffect, createMemo, createSignal, type JSX } from "solid-js";
+import { Portal } from "solid-js/web";
+import { createStore } from "solid-js/store";
+import { resolveAPIBase } from "../../../lib/api";
+import { ChevronLeft, ChevronRight } from "../../../lib/icons";
+import { useAppShellData } from "../../shell/data/app-shell.context";
 import styles from "./WorkspaceHome.module.scss";
 
-type ShellCheckpointCard = {
+type BootstrapStepKey = "instance" | "mode" | "admin" | "structure";
+
+type BootstrapStepDefinition = {
+	id: BootstrapStepKey;
 	title: string;
-	copy: string;
-	meta: string;
+	buttonLabel: string;
 };
 
-const shellCheckpointCards: readonly ShellCheckpointCard[] = [
+type BootstrapSubmissionState = {
+	status: "idle" | "submitting" | "success" | "error";
+	error: string;
+};
+
+type InstanceForm = {
+	protocol: "http" | "https";
+	access: "local" | "remote";
+	host: string;
+};
+
+type ModeForm = {
+	mode: "personal" | "organizational";
+	name: string;
+};
+
+type AdminForm = {
+	displayName: string;
+	email: string;
+	password: string;
+};
+
+type StructureForm = {
+	departmentName: string;
+	teamName: string;
+	projectName: string;
+};
+
+const bootstrapStepDefinitions: readonly BootstrapStepDefinition[] = [
 	{
-		title: "Server shell",
-		copy: "Top bar, server rail, sidebar, and content viewport are now split into modular components.",
-		meta: "Layout foundation",
+		id: "instance",
+		title: "Instance shape",
+		buttonLabel: "Save and continue",
 	},
 	{
-		title: "Presence foundation",
-		copy: "The dock now distinguishes personal and organization servers, leaving clear space for future presence and server-aware controls.",
-		meta: "Server foundation",
+		id: "mode",
+		title: "Server mode",
+		buttonLabel: "Save and continue",
 	},
 	{
-		title: "Next build target",
-		copy: "You can now plug in auth state, server onboarding, and live presence without redesigning the whole frame.",
-		meta: "Ready for v0.1.0 work",
+		id: "admin",
+		title: "Admin account",
+		buttonLabel: "Save and continue",
+	},
+	{
+		id: "structure",
+		title: "Initial structure",
+		buttonLabel: "Submit",
 	},
 ];
 
-export const WorkspaceHome = (): JSX.Element => {
-	return (
-		<main class={styles.viewport}>
-			<section class={styles.hero}>
-				<span class={styles.eyebrow}>Server home</span>
-				<h1 class={styles.title}>{activeServer.name} is ready for its first real shell.</h1>
-				<p class={styles.description}>
-					This is the barebone app frame for v0.1.0 — enough structure to start building a real self-hosted server experience on top of the backend core.
-				</p>
-			</section>
+const defaultInstanceForm: InstanceForm = {
+	protocol: "http",
+	access: "local",
+	host: "localhost",
+};
 
-			<section class={styles.grid} aria-label="Shell checkpoints">
-				<For each={shellCheckpointCards}>
-					{(card): JSX.Element => (
-						<article class={styles.card}>
-							<h2 class={styles.cardTitle}>{card.title}</h2>
-							<p class={styles.cardCopy}>{card.copy}</p>
-							<span class={styles.cardMeta}>{card.meta}</span>
-						</article>
-					)}
-				</For>
+const defaultModeForm: ModeForm = {
+	mode: "personal",
+	name: "",
+};
+
+const defaultAdminForm: AdminForm = {
+	displayName: "Admin",
+	email: "admin@example.com",
+	password: "",
+};
+
+const personalStructureDefaults = {
+	departmentName: "Default",
+	teamName: "Personal",
+};
+
+const organizationalStructureDefaults = {
+	departmentName: "Department",
+	teamName: "Team",
+};
+
+const defaultStructureForm: StructureForm = {
+	...personalStructureDefaults,
+	projectName: "Project",
+};
+
+const initialSubmissionState = (): BootstrapSubmissionState => ({
+	status: "idle",
+	error: "",
+});
+
+const readResponseBody = async (response: Response): Promise<unknown> => {
+	const raw = await response.text();
+
+	if (!raw.trim()) {
+		return null;
+	}
+
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+};
+
+const readResponseError = (step: BootstrapStepKey, data: unknown): string => {
+	const fallback = `Bootstrap ${step} request failed.`;
+
+	if (typeof data === "string") {
+		const message = data.trim();
+		return message || fallback;
+	}
+
+	if (!data || typeof data !== "object") {
+		return fallback;
+	}
+
+	const record = data as {
+		error?: string;
+		message?: string;
+		requestId?: string;
+	};
+	const message = typeof record.message === "string" ? record.message.trim() : "";
+	const errorCode = typeof record.error === "string" ? record.error.trim() : "";
+	const requestId = typeof record.requestId === "string" ? record.requestId.trim() : "";
+
+	if (!message && !errorCode && !requestId) {
+		return fallback;
+	}
+
+	const details: string[] = [];
+
+	if (errorCode) {
+		details.push(`code: ${errorCode}`);
+	}
+
+	if (requestId) {
+		details.push(`request: ${requestId}`);
+	}
+
+	if (message && details.length > 0) {
+		return `${message} (${details.join(", ")})`;
+	}
+
+	if (message) {
+		return message;
+	}
+
+	return `${fallback} (${details.join(", ")})`;
+};
+
+type WorkspaceHomeProps = {
+	sidebarCollapsed: boolean;
+	onToggleSidebarCollapse: () => void;
+};
+
+export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
+	const appShellData = useAppShellData();
+	const [instanceForm, setInstanceForm] = createStore<InstanceForm>({ ...defaultInstanceForm });
+	const [modeForm, setModeForm] = createStore<ModeForm>({ ...defaultModeForm });
+	const [adminForm, setAdminForm] = createStore<AdminForm>({ ...defaultAdminForm });
+	const [structureForm, setStructureForm] = createStore<StructureForm>({ ...defaultStructureForm });
+	const [stepState, setStepState] = createStore<Record<BootstrapStepKey, BootstrapSubmissionState>>({
+		instance: initialSubmissionState(),
+		mode: initialSubmissionState(),
+		admin: initialSubmissionState(),
+		structure: initialSubmissionState(),
+	});
+	const [isBootstrapStateResolved, setIsBootstrapStateResolved] = createSignal(false);
+	const [isBootstrapComplete, setIsBootstrapComplete] = createSignal(false);
+	const [isWizardOpen, setIsWizardOpen] = createSignal(false);
+	const [currentStepIndex, setCurrentStepIndex] = createSignal(0);
+
+	createEffect(() => {
+		if (modeForm.mode === "personal") {
+			setStructureForm("departmentName", personalStructureDefaults.departmentName);
+			setStructureForm("teamName", personalStructureDefaults.teamName);
+			return;
+		}
+
+		if (structureForm.departmentName === personalStructureDefaults.departmentName) {
+			setStructureForm("departmentName", organizationalStructureDefaults.departmentName);
+		}
+
+		if (structureForm.teamName === personalStructureDefaults.teamName) {
+			setStructureForm("teamName", organizationalStructureDefaults.teamName);
+		}
+	});
+
+	createEffect(() => {
+		const shellStatus = appShellData.status();
+
+		if (shellStatus === "idle" || shellStatus === "loading") {
+			return;
+		}
+
+		if (shellStatus !== "success") {
+			return;
+		}
+
+		const installationAccessor = appShellData.installation;
+		const installation = typeof installationAccessor === "function" ? installationAccessor() : undefined;
+		const isPersistedBootstrap = installation?.isBootstrapped ?? false;
+
+		if (!isPersistedBootstrap) {
+			resetWizardState();
+		}
+
+		setIsBootstrapComplete(isPersistedBootstrap);
+		setIsWizardOpen(!isPersistedBootstrap);
+		setIsBootstrapStateResolved(true);
+	});
+
+	const sidebarToggleLabel = (): string =>
+		props.sidebarCollapsed ? "Expand left workspace sidebar" : "Collapse left workspace sidebar";
+	const breadcrumb = (): string => `${appShellData.activeServer().name} / ${appShellData.activeProject().name} / Home`;
+	const apiBase = (): string => resolveAPIBase();
+	const bootstrapTargetLabel = (): string =>
+		modeForm.mode === "personal" ? "Personal server" : "Organization server";
+	const bootstrapNamePlaceholder = (): string =>
+		modeForm.mode === "personal" ? "Personal server name" : "Organization server name";
+	const currentStep = createMemo<BootstrapStepDefinition>(
+		() => bootstrapStepDefinitions[currentStepIndex()] ?? bootstrapStepDefinitions[0]!,
+	);
+	const currentStepState = createMemo<BootstrapSubmissionState>(() => stepState[currentStep().id]);
+	const isFirstStep = (): boolean => currentStepIndex() === 0;
+	const isLastStep = (): boolean => currentStepIndex() === bootstrapStepDefinitions.length - 1;
+	const canDismissWizard = (): boolean => isBootstrapComplete();
+
+	const resetWizardState = (): void => {
+		setInstanceForm({ ...defaultInstanceForm });
+		setModeForm({ ...defaultModeForm });
+		setAdminForm({ ...defaultAdminForm });
+		setStructureForm({ ...defaultStructureForm });
+		setStepState({
+			instance: initialSubmissionState(),
+			mode: initialSubmissionState(),
+			admin: initialSubmissionState(),
+			structure: initialSubmissionState(),
+		});
+		setCurrentStepIndex(0);
+	};
+
+	const submitStep = async (step: BootstrapStepKey, payload: unknown): Promise<boolean> => {
+		setStepState(step, { status: "submitting", error: "" });
+
+		try {
+			const response = await fetch(`${apiBase()}/bootstrap/steps/${step}`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					Accept: "application/json",
+				},
+				body: JSON.stringify(payload),
+			});
+			const data = await readResponseBody(response);
+
+			if (!response.ok) {
+				throw new Error(readResponseError(step, data));
+			}
+
+			setStepState(step, {
+				status: "success",
+				error: "",
+			});
+
+			return true;
+		} catch (error) {
+			setStepState(step, {
+				status: "error",
+				error: error instanceof Error ? error.message : `Bootstrap ${step} request failed.`,
+			});
+
+			return false;
+		}
+	};
+
+	const payloadForStep = (step: BootstrapStepKey): unknown => {
+		switch (step) {
+			case "instance":
+				return instanceForm;
+			case "mode":
+				return modeForm;
+			case "admin":
+				return adminForm;
+			case "structure":
+				return structureForm;
+		}
+	};
+
+	const submitCurrentStep = async (): Promise<void> => {
+		const step = currentStep().id;
+		const didSucceed = await submitStep(step, payloadForStep(step));
+
+		if (!didSucceed) {
+			return;
+		}
+
+		if (isLastStep()) {
+			await appShellData.reload();
+			const installationAccessor = appShellData.installation;
+			const installation = typeof installationAccessor === "function" ? installationAccessor() : undefined;
+			const isPersistedBootstrap = installation?.isBootstrapped ?? false;
+
+			setIsBootstrapComplete(isPersistedBootstrap);
+			setIsWizardOpen(!isPersistedBootstrap);
+			setIsBootstrapStateResolved(true);
+			return;
+		}
+
+		setCurrentStepIndex((index) => Math.min(index + 1, bootstrapStepDefinitions.length - 1));
+	};
+
+	const handleCurrentStepSubmit: JSX.EventHandler<HTMLFormElement, SubmitEvent> = (event): void => {
+		event.preventDefault();
+		void submitCurrentStep();
+	};
+
+	const statusLabel = (state: BootstrapSubmissionState): string => {
+		switch (state.status) {
+			case "submitting":
+				return "Sending";
+			case "success":
+				return "Saved";
+			case "error":
+				return "Request failed";
+			default:
+				return "Ready";
+		}
+	};
+
+	const stepStatusLabel = (step: BootstrapStepDefinition): string => {
+		const state = stepState[step.id];
+
+		if (state.status === "success") {
+			return "Done";
+		}
+
+		if (state.status === "error") {
+			return "Needs retry";
+		}
+
+		return "";
+	};
+
+	return (
+		<>
+			<main class={styles.viewport} data-ui="workspace-home">
+				<div class={styles.workspaceTopBar} data-slot="workspace-home-top-bar">
+					<div class={styles.workspaceTopBarStart} data-slot="workspace-home-top-bar-start">
+						<button
+							type="button"
+							class={styles.workspaceCollapseButton}
+							aria-label={sidebarToggleLabel()}
+							title={sidebarToggleLabel()}
+							data-slot="workspace-home-sidebar-toggle"
+							onClick={props.onToggleSidebarCollapse}
+						>
+							{props.sidebarCollapsed ? <ChevronRight size={16} strokeWidth={2} /> : <ChevronLeft size={16} strokeWidth={2} />}
+						</button>
+					</div>
+
+					<div class={styles.workspaceTopBarCenter} data-slot="workspace-home-top-bar-center">
+						<span class={styles.workspaceBreadcrumb}>{breadcrumb()}</span>
+					</div>
+
+					<div class={styles.workspaceTopBarEnd} data-slot="workspace-home-top-bar-end" aria-hidden="true" />
+				</div>
+
+				<section class={styles.hero} data-slot="workspace-home-hero">
+					<h1 class={styles.title}>{isBootstrapComplete() ? appShellData.activeServer().name : bootstrapTargetLabel()}</h1>
+					<Show when={isBootstrapStateResolved() && !isBootstrapComplete()}>
+						<div class={styles.heroActions}>
+						<button
+							type="button"
+							class={styles.primaryButton}
+							onClick={(): void => {
+								setIsWizardOpen(true);
+							}}
+						>
+								Open bootstrap wizard
+							</button>
+						</div>
+					</Show>
 				</section>
 			</main>
+
+			<Show when={isBootstrapStateResolved() && isWizardOpen()}>
+				<Portal>
+					<div class={styles.wizardLayer} data-ui="bootstrap-wizard" data-step={currentStep().id}>
+						<div class={styles.wizardBackdrop} aria-hidden="true" />
+
+						<section class={styles.wizardPanel} role="dialog" aria-modal="true" aria-labelledby="bootstrap-wizard-title" data-slot="bootstrap-wizard-panel">
+							<header class={styles.wizardHeader} data-slot="bootstrap-wizard-header">
+								<div class={styles.wizardHeaderCopy}>
+									<h2 id="bootstrap-wizard-title" class={styles.wizardTitle}>
+										Bootstrap {bootstrapTargetLabel()}
+									</h2>
+								</div>
+								<Show when={canDismissWizard()}>
+									<button
+										type="button"
+										class={styles.wizardCloseButton}
+										onClick={(): void => {
+											setIsWizardOpen(false);
+										}}
+									>
+										Close
+									</button>
+								</Show>
+							</header>
+
+							<div class={styles.wizardBody}>
+								<aside class={styles.wizardSidebar} data-slot="bootstrap-wizard-sidebar">
+									<nav class={styles.wizardSteps} aria-label="Bootstrap steps">
+										<For each={bootstrapStepDefinitions}>
+											{(step, index): JSX.Element => (
+												<button
+													type="button"
+													class={styles.wizardStepButton}
+													data-active={step.id === currentStep().id ? "true" : "false"}
+													disabled={index() > currentStepIndex()}
+													onClick={(): void => {
+														if (index() <= currentStepIndex()) {
+															setCurrentStepIndex(index());
+														}
+													}}
+												>
+													<span class={styles.wizardStepIndex}>{index() + 1}</span>
+													<span class={styles.wizardStepCopy}>
+														<strong>{step.title}</strong>
+														<Show when={stepStatusLabel(step)}>
+															<small>{stepStatusLabel(step)}</small>
+														</Show>
+													</span>
+												</button>
+											)}
+										</For>
+									</nav>
+								</aside>
+
+								<div class={styles.wizardStepPanel} data-slot="bootstrap-wizard-step-panel">
+									<div class={styles.sectionHeader}>
+										<div>
+											<span class={styles.wizardStepEyebrow}>{`Step ${currentStepIndex() + 1} of ${bootstrapStepDefinitions.length}`}</span>
+											<h3 class={styles.sectionTitle}>{currentStep().title}</h3>
+										</div>
+					<div class={styles.statusBadge} data-status={currentStepState().status}>{statusLabel(currentStepState())}</div>
+				</div>
+
+									<form class={styles.form} onSubmit={handleCurrentStepSubmit}>
+										<Show when={currentStep().id === "instance"}>
+											<>
+												<label class={styles.field}>
+													<span class={styles.fieldLabel}>Protocol</span>
+												<select
+													value={instanceForm.protocol}
+													onInput={(event): void =>
+														setInstanceForm("protocol", event.currentTarget.value as InstanceForm["protocol"])
+													}
+												>
+														<option value="http">http</option>
+														<option value="https">https</option>
+													</select>
+												</label>
+												<label class={styles.field}>
+													<span class={styles.fieldLabel}>Access</span>
+												<select
+													value={instanceForm.access}
+													onInput={(event): void =>
+														setInstanceForm("access", event.currentTarget.value as InstanceForm["access"])
+													}
+												>
+														<option value="local">local</option>
+														<option value="remote">remote</option>
+													</select>
+												</label>
+												<label class={styles.field}>
+													<span class={styles.fieldLabel}>Host</span>
+													<input
+														type="text"
+														value={instanceForm.host}
+														onInput={(event): void => setInstanceForm("host", event.currentTarget.value)}
+														placeholder="localhost or app.example.com"
+													/>
+												</label>
+											</>
+										</Show>
+
+						<Show when={currentStep().id === "mode"}>
+							<>
+								<label class={styles.field}>
+									<span class={styles.fieldLabel}>Mode</span>
+								<select
+									value={modeForm.mode}
+									onInput={(event): void => setModeForm("mode", event.currentTarget.value as ModeForm["mode"])}
+								>
+										<option value="personal">personal</option>
+										<option value="organizational">organizational</option>
+									</select>
+								</label>
+								<label class={styles.field}>
+									<span class={styles.fieldLabel}>Server name</span>
+									<input
+										type="text"
+										value={modeForm.name}
+										required
+										onInput={(event): void => setModeForm("name", event.currentTarget.value)}
+										placeholder={bootstrapNamePlaceholder()}
+									/>
+								</label>
+							</>
+						</Show>
+
+										<Show when={currentStep().id === "admin"}>
+											<>
+												<label class={styles.field}>
+													<span class={styles.fieldLabel}>Display name</span>
+											<input
+												type="text"
+												value={adminForm.displayName}
+												onInput={(event): void => setAdminForm("displayName", event.currentTarget.value)}
+												placeholder="Admin"
+											/>
+										</label>
+												<label class={styles.field}>
+													<span class={styles.fieldLabel}>Email</span>
+													<input
+														type="email"
+														value={adminForm.email}
+														onInput={(event): void => setAdminForm("email", event.currentTarget.value)}
+														placeholder="admin@example.com"
+													/>
+												</label>
+												<label class={styles.field}>
+													<span class={styles.fieldLabel}>Password</span>
+												<input
+													type="password"
+													value={adminForm.password}
+													onInput={(event): void => setAdminForm("password", event.currentTarget.value)}
+													placeholder="Create a strong password"
+												/>
+												<small class={styles.fieldHelp}>
+													Use at least 12 characters with uppercase, lowercase, numbers, and symbols.
+												</small>
+											</label>
+											</>
+										</Show>
+
+										<Show when={currentStep().id === "structure"}>
+											<>
+												<label class={styles.field}>
+													<span class={styles.fieldLabel}>Department</span>
+													<input
+														type="text"
+														value={structureForm.departmentName}
+														disabled={modeForm.mode === "personal"}
+														onInput={(event): void => setStructureForm("departmentName", event.currentTarget.value)}
+														placeholder={organizationalStructureDefaults.departmentName}
+													/>
+												</label>
+												<label class={styles.field}>
+													<span class={styles.fieldLabel}>Team</span>
+													<input
+														type="text"
+														value={structureForm.teamName}
+														disabled={modeForm.mode === "personal"}
+														onInput={(event): void => setStructureForm("teamName", event.currentTarget.value)}
+														placeholder={organizationalStructureDefaults.teamName}
+													/>
+												</label>
+												<label class={styles.field}>
+													<span class={styles.fieldLabel}>Project</span>
+													<input
+														type="text"
+														value={structureForm.projectName}
+														onInput={(event): void => setStructureForm("projectName", event.currentTarget.value)}
+														placeholder="Moku"
+													/>
+												</label>
+											</>
+										</Show>
+
+										<div class={styles.wizardFormActions}>
+											<button
+												type="button"
+												class={styles.secondaryButton}
+												disabled={isFirstStep()}
+												onClick={(): void => {
+													setCurrentStepIndex((index) => Math.max(index - 1, 0));
+												}}
+											>
+												Back
+											</button>
+											<button
+												type="submit"
+												class={styles.primaryButton}
+												disabled={currentStepState().status === "submitting"}
+											>
+												{currentStep().buttonLabel}
+											</button>
+										</div>
+									</form>
+
+					<Show when={currentStepState().error}>
+						<p class={styles.errorText}>{currentStepState().error}</p>
+					</Show>
+
+								</div>
+							</div>
+						</section>
+					</div>
+				</Portal>
+			</Show>
+		</>
 	);
 };

Frontend/src/global.d.ts

@@ -1,3 +1,11 @@
 // Path: Frontend/src/global.d.ts
 
 /// <reference types="@solidjs/start/env" />
+
+interface ImportMetaEnv {
+	readonly VITE_API_BASE_URL?: string;
+}
+
+interface ImportMeta {
+	readonly env: ImportMetaEnv;
+}

Frontend/src/lib/api.ts

@@ -0,0 +1,11 @@
+// Path: Frontend/src/lib/api.ts
+
+export const resolveAPIBase = (): string => {
+	const configuredBase = import.meta.env.VITE_API_BASE_URL?.trim();
+
+	if (!configuredBase) {
+		return "/v1";
+	}
+
+	return configuredBase.replace(/\/$/, "");
+};

Frontend/src/lib/icons/index.ts

@@ -3,17 +3,22 @@
 export { default as Bell } from "lucide-solid/icons/bell";
 export { default as CircleHelp } from "lucide-solid/icons/circle-help";
 export { default as ChevronDown } from "lucide-solid/icons/chevron-down";
+export { default as ChevronLeft } from "lucide-solid/icons/chevron-left";
+export { default as ChevronRight } from "lucide-solid/icons/chevron-right";
+export { default as FileText } from "lucide-solid/icons/file-text";
 export { default as Folder } from "lucide-solid/icons/folder";
 export { default as Home } from "lucide-solid/icons/house";
 export { default as Keyboard } from "lucide-solid/icons/keyboard";
 export { default as LayoutGrid } from "lucide-solid/icons/layout-grid";
+export { default as ListCollapse } from "lucide-solid/icons/list-collapse";
 export { default as LogOut } from "lucide-solid/icons/log-out";
 export { default as Moon } from "lucide-solid/icons/moon";
 export { default as Plus } from "lucide-solid/icons/plus";
 export { default as Repeat } from "lucide-solid/icons/repeat";
 export { default as Search } from "lucide-solid/icons/search";
-export { default as Server } from "lucide-solid/icons/server";
 export { default as Settings } from "lucide-solid/icons/settings";
 export { default as Shield } from "lucide-solid/icons/shield";
 export { default as Sun } from "lucide-solid/icons/sun";
+export { default as UnfoldVertical } from "lucide-solid/icons/unfold-vertical";
 export { default as User } from "lucide-solid/icons/user";
+export { default as X } from "lucide-solid/icons/x";

Frontend/src/styles/user-overrides.scss

@@ -0,0 +1,41 @@
+/* Path: Frontend/src/styles/user-overrides.scss */
+
+/*
+	Optional global frontend override seam.
+
+	This file is imported after the core app styles so user or deployment-specific
+	overrides can layer on top without reshaping component code first.
+
+	Examples for later:
+	- import a tenant branding bundle
+	- apply a self-hosted custom theme
+	- override shared shell spacing or color tokens
+	- target stable `data-ui`, `data-slot`, or state attributes added in the app shell
+
+	You can either place raw overrides here directly or layer another stylesheet:
+
+	@use "./my-brand" as *;
+*/
+
+/*
+	Stable override hooks are intentionally exposed with global data attributes so
+	manual overrides do not depend on CSS module hash names.
+
+	Examples:
+
+	[data-ui="top-bar"] {
+		backdrop-filter: blur(24px);
+	}
+
+	[data-ui="workspace-sidebar"] [data-slot="workspace-tree-item"][data-kind="item"] {
+		border-radius: 12px;
+	}
+
+	[data-ui="workspace-context-menu"] [data-action-id="delete"] {
+		letter-spacing: 0.01em;
+	}
+
+	[data-ui="notifications-menu"][data-variant="workspace"] {
+		max-width: none;
+	}
+*/

Frontend/vite.config.ts

@@ -9,10 +9,22 @@ const extraAllowedHosts = (process.env.ALLOWED_HOSTS ?? "")
 	.map((host) => host.trim())
 	.filter(Boolean);
 
+const backendAPIport = process.env.BACKEND_API_PORT?.trim() || "8081";
+const devAPIProxyTarget =
+	process.env.FRONTEND_API_PROXY_TARGET?.trim() ||
+	process.env.VITE_DEV_PROXY_TARGET?.trim() ||
+	`http://api:${backendAPIport}`;
+
 export default defineConfig({
 	plugins: [solidStart({ ssr: false })],
 	server: {
 		allowedHosts: ["localhost", ...extraAllowedHosts],
+		proxy: {
+			"/v1": {
+				target: devAPIProxyTarget,
+				changeOrigin: true,
+			},
+		},
 	},
 	preview: {
 		allowedHosts: ["localhost", ...extraAllowedHosts],

Justfile

@@ -1,6 +1,7 @@
 set shell := ["bash", "-cu"]
 
 mod local "Commands/Local"
+mod test "Commands/Test"
 
 [default]
 help:

Proxy/Local/default.conf

@@ -25,6 +25,15 @@ server {
     try_files $uri $uri/ $moku_bootstrap_document;
   }
 
+  location ^~ /v1/ {
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_pass http://api:8081;
+  }
+
   location /favicon.ico {
     try_files $uri =404;
     access_log off;