Merge branch 'Fix/Frontend/Projects-Menu-Polish'

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/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.go

@@ -0,0 +1,903 @@
+// Path: Backend/internal/bootstrap/service.go
+
+package bootstrap
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/jackc/pgx/v5"
+
+	"moku-backend/internal/database"
+)
+
+const (
+	primaryOrganizationSlug       = "primary-organization"
+	primaryDepartmentSlug         = "primary-department"
+	primaryTeamSlug               = "primary-team"
+	primaryProjectSlug            = "primary-project"
+	organizationWorkspaceSlug     = "organization-home"
+	departmentWorkspaceSlug       = "department-home"
+	teamWorkspaceSlug             = "team-home"
+	projectWorkspaceSlug          = "project-home"
+	defaultInstallationHost       = "localhost"
+	defaultInstallationMode       = "personal"
+	defaultInstallationAccess     = "local"
+	defaultInstallationProtocol   = "http"
+	defaultOrganizationName       = "Moku"
+	defaultPersonalServerSuffix   = "Personal"
+	defaultPersonalDisplayName    = "Personal"
+	bootstrapWorkspaceKindOrg     = "organization"
+	bootstrapWorkspaceKindDept    = "department"
+	bootstrapWorkspaceKindTeam    = "team"
+	bootstrapWorkspaceKindProject = "project"
+)
+
+var (
+	ErrInstallationNotConfigured = errors.New("bootstrap installation step has not been completed")
+	ErrAdminNotConfigured        = errors.New("bootstrap admin step has not been completed")
+)
+
+type Service struct {
+	db *database.DB
+}
+
+type SaveInstanceInput struct {
+	Protocol string
+	Access   string
+	Host     string
+}
+
+type SaveModeInput struct {
+	Mode string
+	Name string
+}
+
+type SaveAdminInput struct {
+	DisplayName string
+	Email       string
+	Password    string
+}
+
+type SaveStructureInput struct {
+	OrganizationName string
+	DepartmentName   string
+	TeamName         string
+	ProjectName      string
+}
+
+type InstallationRecord struct {
+	ID             string `json:"id"`
+	Name           string `json:"name"`
+	Mode           string `json:"mode"`
+	Access         string `json:"access"`
+	Protocol       string `json:"protocol"`
+	Host           string `json:"host"`
+	IsBootstrapped bool   `json:"isBootstrapped"`
+}
+
+type AdminRecord struct {
+	ID              string `json:"id"`
+	Email           string `json:"email"`
+	DisplayName     string `json:"displayName"`
+	IsInstanceAdmin bool   `json:"isInstanceAdmin"`
+	HomeTitle       string `json:"homeTitle"`
+}
+
+type OrganizationRecord struct {
+	ID   string `json:"id"`
+	Name string `json:"name"`
+	Slug string `json:"slug"`
+}
+
+type DepartmentRecord struct {
+	ID             string `json:"id"`
+	OrganizationID string `json:"organizationId"`
+	Name           string `json:"name"`
+	Slug           string `json:"slug"`
+}
+
+type TeamRecord struct {
+	ID             string  `json:"id"`
+	OrganizationID string  `json:"organizationId"`
+	DepartmentID   *string `json:"departmentId,omitempty"`
+	Name           string  `json:"name"`
+	Slug           string  `json:"slug"`
+}
+
+type ProjectRecord struct {
+	ID             string  `json:"id"`
+	OrganizationID string  `json:"organizationId"`
+	DepartmentID   *string `json:"departmentId,omitempty"`
+	TeamID         *string `json:"teamId,omitempty"`
+	Name           string  `json:"name"`
+	Slug           string  `json:"slug"`
+}
+
+type WorkspaceRecord struct {
+	ID             string  `json:"id"`
+	OrganizationID string  `json:"organizationId"`
+	Name           string  `json:"name"`
+	Slug           string  `json:"slug"`
+	Kind           string  `json:"kind"`
+	DepartmentID   *string `json:"departmentId,omitempty"`
+	TeamID         *string `json:"teamId,omitempty"`
+	ProjectID      *string `json:"projectId,omitempty"`
+}
+
+type StructureRecord struct {
+	Installation InstallationRecord `json:"installation"`
+	Organization namedRecord        `json:"organization"`
+	Department   namedRecord        `json:"department"`
+	Team         namedRecord        `json:"team"`
+	Project      namedRecord        `json:"project"`
+	Admin        AdminSummary       `json:"admin"`
+}
+
+type AdminSummary struct {
+	ID          string `json:"id"`
+	Email       string `json:"email"`
+	DisplayName string `json:"displayName"`
+}
+
+type BootstrapStructureState struct {
+	Organization *OrganizationRecord `json:"organization,omitempty"`
+	Department   *DepartmentRecord   `json:"department,omitempty"`
+	Team         *TeamRecord         `json:"team,omitempty"`
+	Project      *ProjectRecord      `json:"project,omitempty"`
+	Workspaces   []WorkspaceRecord   `json:"workspaces"`
+}
+
+type BootstrapState struct {
+	Installation *InstallationRecord     `json:"installation,omitempty"`
+	Admin        *AdminRecord            `json:"admin,omitempty"`
+	Structure    BootstrapStructureState `json:"structure"`
+}
+
+type AppShellState struct {
+	Installation  *InstallationRecord  `json:"installation,omitempty"`
+	Admin         *AdminRecord         `json:"admin,omitempty"`
+	Organizations []OrganizationRecord `json:"organizations"`
+	Departments   []DepartmentRecord   `json:"departments"`
+	Teams         []TeamRecord         `json:"teams"`
+	Projects      []ProjectRecord      `json:"projects"`
+	Workspaces    []WorkspaceRecord    `json:"workspaces"`
+}
+
+type namedRecord struct {
+	ID   string `json:"id"`
+	Name string `json:"name"`
+	Slug string `json:"slug"`
+}
+
+func NewService(db *database.DB) *Service {
+	return &Service{db: db}
+}
+
+func (service *Service) SaveInstance(ctx context.Context, input SaveInstanceInput) (InstallationRecord, error) {
+	row := service.db.Pool.QueryRow(ctx, `
+		INSERT INTO installations (singleton, name, mode, access, protocol, host)
+		VALUES (
+			TRUE,
+			COALESCE((SELECT name FROM installations WHERE singleton = TRUE LIMIT 1), ''),
+			COALESCE((SELECT mode FROM installations WHERE singleton = TRUE LIMIT 1), 'personal'::instance_mode),
+			$1::instance_access,
+			$2::instance_protocol,
+			$3
+		)
+		ON CONFLICT (singleton) DO UPDATE
+		SET
+			access = EXCLUDED.access,
+			protocol = EXCLUDED.protocol,
+			host = EXCLUDED.host,
+			updated_at = NOW()
+		RETURNING id::text, name, mode::text, access::text, protocol::text, host, is_bootstrapped;
+	`, input.Access, input.Protocol, input.Host)
+
+	return scanInstallationRecord(row)
+}
+
+func (service *Service) SaveMode(ctx context.Context, input SaveModeInput) (InstallationRecord, error) {
+	row := service.db.Pool.QueryRow(ctx, `
+		INSERT INTO installations (singleton, name, mode, access, protocol, host)
+		VALUES (
+			TRUE,
+			$2,
+			$1::instance_mode,
+			COALESCE((SELECT access FROM installations WHERE singleton = TRUE LIMIT 1), 'local'::instance_access),
+			COALESCE((SELECT protocol FROM installations WHERE singleton = TRUE LIMIT 1), 'http'::instance_protocol),
+			COALESCE((SELECT host FROM installations WHERE singleton = TRUE LIMIT 1), $3)
+		)
+		ON CONFLICT (singleton) DO UPDATE
+		SET
+			name = EXCLUDED.name,
+			mode = EXCLUDED.mode,
+			updated_at = NOW()
+		RETURNING id::text, name, mode::text, access::text, protocol::text, host, is_bootstrapped;
+	`, input.Mode, input.Name, defaultInstallationHost)
+
+	return scanInstallationRecord(row)
+}
+
+func (service *Service) SaveAdmin(ctx context.Context, input SaveAdminInput) (AdminRecord, error) {
+	tx, err := service.db.Pool.BeginTx(ctx, pgx.TxOptions{})
+	if err != nil {
+		return AdminRecord{}, err
+	}
+	defer func() {
+		_ = tx.Rollback(ctx)
+	}()
+
+	if _, err := tx.Exec(ctx, `
+		UPDATE users
+		SET is_instance_admin = FALSE, updated_at = NOW()
+		WHERE is_instance_admin = TRUE;
+	`); err != nil {
+		return AdminRecord{}, err
+	}
+
+	var record AdminRecord
+	if err := tx.QueryRow(ctx, `
+		INSERT INTO users (email, display_name, password_hash, is_instance_admin)
+		VALUES ($1, $2, crypt($3, gen_salt('bf')), TRUE)
+		ON CONFLICT ((LOWER(email))) DO UPDATE
+		SET
+			email = EXCLUDED.email,
+			display_name = EXCLUDED.display_name,
+			password_hash = crypt($3, gen_salt('bf')),
+			is_instance_admin = TRUE,
+			updated_at = NOW()
+		RETURNING id::text, email, display_name, is_instance_admin;
+	`, input.Email, input.DisplayName, input.Password).Scan(
+		&record.ID,
+		&record.Email,
+		&record.DisplayName,
+		&record.IsInstanceAdmin,
+	); err != nil {
+		return AdminRecord{}, err
+	}
+
+	record.HomeTitle = personalHomeTitle(record.DisplayName)
+	if err := tx.QueryRow(ctx, `
+		INSERT INTO user_homes (user_id, title)
+		VALUES ($1::uuid, $2)
+		ON CONFLICT (user_id) DO UPDATE
+		SET title = EXCLUDED.title, updated_at = NOW()
+		RETURNING title;
+	`, record.ID, record.HomeTitle).Scan(&record.HomeTitle); err != nil {
+		return AdminRecord{}, err
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return AdminRecord{}, err
+	}
+
+	return record, nil
+}
+
+func (service *Service) SaveStructure(ctx context.Context, input SaveStructureInput) (StructureRecord, error) {
+	tx, err := service.db.Pool.BeginTx(ctx, pgx.TxOptions{})
+	if err != nil {
+		return StructureRecord{}, err
+	}
+	defer func() {
+		_ = tx.Rollback(ctx)
+	}()
+
+	installation, err := loadInstallation(ctx, tx)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return StructureRecord{}, ErrInstallationNotConfigured
+		}
+
+		return StructureRecord{}, err
+	}
+
+	admin, err := loadPrimaryAdmin(ctx, tx)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return StructureRecord{}, ErrAdminNotConfigured
+		}
+
+		return StructureRecord{}, err
+	}
+
+	organizationName := strings.TrimSpace(input.OrganizationName)
+	if organizationName == "" {
+		organizationName = defaultRootOrganizationName(installation.Name, installation.Mode, installation.Host, admin.DisplayName)
+	}
+
+	organization, err := upsertNamedRecord(ctx, tx, `
+		INSERT INTO organizations (name, slug, created_by_user_id)
+		VALUES ($1, $2, $3::uuid)
+		ON CONFLICT (slug) DO UPDATE
+		SET name = EXCLUDED.name, created_by_user_id = EXCLUDED.created_by_user_id, updated_at = NOW()
+		RETURNING id::text, name, slug;
+	`, organizationName, primaryOrganizationSlug, admin.ID)
+	if err != nil {
+		return StructureRecord{}, err
+	}
+
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO organization_memberships (organization_id, user_id, role)
+		VALUES ($1::uuid, $2::uuid, 'owner'::membership_role)
+		ON CONFLICT (organization_id, user_id) DO UPDATE
+		SET role = EXCLUDED.role;
+	`, organization.ID, admin.ID); err != nil {
+		return StructureRecord{}, err
+	}
+
+	department, err := upsertNamedRecord(ctx, tx, `
+		INSERT INTO departments (organization_id, name, slug, created_by_user_id)
+		VALUES ($1::uuid, $2, $3, $4::uuid)
+		ON CONFLICT (organization_id, slug) DO UPDATE
+		SET name = EXCLUDED.name, created_by_user_id = EXCLUDED.created_by_user_id, updated_at = NOW()
+		RETURNING id::text, name, slug;
+	`, organization.ID, input.DepartmentName, primaryDepartmentSlug, admin.ID)
+	if err != nil {
+		return StructureRecord{}, err
+	}
+
+	team, err := upsertNamedRecord(ctx, tx, `
+		INSERT INTO teams (organization_id, department_id, name, slug, created_by_user_id)
+		VALUES ($1::uuid, $2::uuid, $3, $4, $5::uuid)
+		ON CONFLICT (organization_id, slug) DO UPDATE
+		SET department_id = EXCLUDED.department_id, name = EXCLUDED.name, created_by_user_id = EXCLUDED.created_by_user_id, updated_at = NOW()
+		RETURNING id::text, name, slug;
+	`, organization.ID, department.ID, input.TeamName, primaryTeamSlug, admin.ID)
+	if err != nil {
+		return StructureRecord{}, err
+	}
+
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO team_memberships (team_id, user_id, role)
+		VALUES ($1::uuid, $2::uuid, 'owner'::membership_role)
+		ON CONFLICT (team_id, user_id) DO UPDATE
+		SET role = EXCLUDED.role;
+	`, team.ID, admin.ID); err != nil {
+		return StructureRecord{}, err
+	}
+
+	project, err := upsertNamedRecord(ctx, tx, `
+		INSERT INTO projects (organization_id, department_id, team_id, name, slug, created_by_user_id)
+		VALUES ($1::uuid, $2::uuid, $3::uuid, $4, $5, $6::uuid)
+		ON CONFLICT (organization_id, slug) DO UPDATE
+		SET department_id = EXCLUDED.department_id, team_id = EXCLUDED.team_id, name = EXCLUDED.name, created_by_user_id = EXCLUDED.created_by_user_id, updated_at = NOW()
+		RETURNING id::text, name, slug;
+	`, organization.ID, department.ID, team.ID, input.ProjectName, primaryProjectSlug, admin.ID)
+	if err != nil {
+		return StructureRecord{}, err
+	}
+
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO project_memberships (project_id, user_id, role)
+		VALUES ($1::uuid, $2::uuid, 'owner'::membership_role)
+		ON CONFLICT (project_id, user_id) DO UPDATE
+		SET role = EXCLUDED.role;
+	`, project.ID, admin.ID); err != nil {
+		return StructureRecord{}, err
+	}
+
+	if err := upsertWorkspace(ctx, tx, organization.ID, organization.Name, organizationWorkspaceSlug, bootstrapWorkspaceKindOrg, admin.ID, nil, nil, nil); err != nil {
+		return StructureRecord{}, err
+	}
+
+	if err := upsertWorkspace(ctx, tx, organization.ID, department.Name, departmentWorkspaceSlug, bootstrapWorkspaceKindDept, admin.ID, &department.ID, nil, nil); err != nil {
+		return StructureRecord{}, err
+	}
+
+	if err := upsertWorkspace(ctx, tx, organization.ID, team.Name, teamWorkspaceSlug, bootstrapWorkspaceKindTeam, admin.ID, &department.ID, &team.ID, nil); err != nil {
+		return StructureRecord{}, err
+	}
+
+	if err := upsertWorkspace(ctx, tx, organization.ID, project.Name, projectWorkspaceSlug, bootstrapWorkspaceKindProject, admin.ID, &department.ID, &team.ID, &project.ID); err != nil {
+		return StructureRecord{}, err
+	}
+
+	installation, err = updateBootstrappedInstallation(ctx, tx)
+	if err != nil {
+		return StructureRecord{}, err
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return StructureRecord{}, err
+	}
+
+	return StructureRecord{
+		Installation: installation,
+		Organization: organization,
+		Department:   department,
+		Team:         team,
+		Project:      project,
+		Admin:        admin,
+	}, nil
+}
+
+func (service *Service) ResetDevelopmentState(ctx context.Context) error {
+	tx, err := service.db.Pool.BeginTx(ctx, pgx.TxOptions{})
+	if err != nil {
+		return err
+	}
+	defer func() {
+		_ = tx.Rollback(ctx)
+	}()
+
+	if _, err := tx.Exec(ctx, `
+		TRUNCATE TABLE
+			project_memberships,
+			team_memberships,
+			organization_memberships,
+			workspaces,
+			projects,
+			teams,
+			departments,
+			user_homes,
+			users,
+			organizations,
+			installations
+		RESTART IDENTITY;
+	`); err != nil {
+		return err
+	}
+
+	return tx.Commit(ctx)
+}
+
+func (service *Service) GetInstallation(ctx context.Context) (*InstallationRecord, error) {
+	record, err := scanInstallationRecord(service.db.Pool.QueryRow(ctx, `
+		SELECT id::text, name, mode::text, access::text, protocol::text, host, is_bootstrapped
+		FROM installations
+		WHERE singleton = TRUE
+		LIMIT 1;
+	`))
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+
+		return nil, err
+	}
+
+	return &record, nil
+}
+
+func (service *Service) GetAdmin(ctx context.Context) (*AdminRecord, error) {
+	var record AdminRecord
+	err := service.db.Pool.QueryRow(ctx, `
+		SELECT
+			u.id::text,
+			u.email,
+			u.display_name,
+			u.is_instance_admin,
+			COALESCE(uh.title, '')
+		FROM users u
+		LEFT JOIN user_homes uh ON uh.user_id = u.id
+		WHERE u.is_instance_admin = TRUE
+		ORDER BY u.created_at ASC
+		LIMIT 1;
+	`).Scan(
+		&record.ID,
+		&record.Email,
+		&record.DisplayName,
+		&record.IsInstanceAdmin,
+		&record.HomeTitle,
+	)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+
+		return nil, err
+	}
+
+	return &record, nil
+}
+
+func (service *Service) GetStructure(ctx context.Context) (BootstrapStructureState, error) {
+	workspaces, err := service.listWorkspaces(ctx)
+	if err != nil {
+		return BootstrapStructureState{}, err
+	}
+
+	organization, err := service.loadPrimaryOrganization(ctx)
+	if err != nil {
+		return BootstrapStructureState{}, err
+	}
+
+	department, err := service.loadPrimaryDepartment(ctx)
+	if err != nil {
+		return BootstrapStructureState{}, err
+	}
+
+	team, err := service.loadPrimaryTeam(ctx)
+	if err != nil {
+		return BootstrapStructureState{}, err
+	}
+
+	project, err := service.loadPrimaryProject(ctx)
+	if err != nil {
+		return BootstrapStructureState{}, err
+	}
+
+	return BootstrapStructureState{
+		Organization: organization,
+		Department:   department,
+		Team:         team,
+		Project:      project,
+		Workspaces:   workspaces,
+	}, nil
+}
+
+func (service *Service) GetState(ctx context.Context) (BootstrapState, error) {
+	installation, err := service.GetInstallation(ctx)
+	if err != nil {
+		return BootstrapState{}, err
+	}
+
+	admin, err := service.GetAdmin(ctx)
+	if err != nil {
+		return BootstrapState{}, err
+	}
+
+	structure, err := service.GetStructure(ctx)
+	if err != nil {
+		return BootstrapState{}, err
+	}
+
+	return BootstrapState{
+		Installation: installation,
+		Admin:        admin,
+		Structure:    structure,
+	}, nil
+}
+
+func (service *Service) GetAppShellState(ctx context.Context) (AppShellState, error) {
+	installation, err := service.GetInstallation(ctx)
+	if err != nil {
+		return AppShellState{}, err
+	}
+
+	admin, err := service.GetAdmin(ctx)
+	if err != nil {
+		return AppShellState{}, err
+	}
+
+	organizations, err := service.listOrganizations(ctx)
+	if err != nil {
+		return AppShellState{}, err
+	}
+
+	departments, err := service.listDepartments(ctx)
+	if err != nil {
+		return AppShellState{}, err
+	}
+
+	teams, err := service.listTeams(ctx)
+	if err != nil {
+		return AppShellState{}, err
+	}
+
+	projects, err := service.listProjects(ctx)
+	if err != nil {
+		return AppShellState{}, err
+	}
+
+	workspaces, err := service.listWorkspaces(ctx)
+	if err != nil {
+		return AppShellState{}, err
+	}
+
+	return AppShellState{
+		Installation:  installation,
+		Admin:         admin,
+		Organizations: organizations,
+		Departments:   departments,
+		Teams:         teams,
+		Projects:      projects,
+		Workspaces:    workspaces,
+	}, nil
+}
+
+func scanInstallationRecord(row pgx.Row) (InstallationRecord, error) {
+	var record InstallationRecord
+	if err := row.Scan(&record.ID, &record.Name, &record.Mode, &record.Access, &record.Protocol, &record.Host, &record.IsBootstrapped); err != nil {
+		return InstallationRecord{}, err
+	}
+
+	return record, nil
+}
+
+func (service *Service) loadPrimaryOrganization(ctx context.Context) (*OrganizationRecord, error) {
+	var record OrganizationRecord
+	err := service.db.Pool.QueryRow(ctx, `
+		SELECT id::text, name, slug
+		FROM organizations
+		ORDER BY CASE WHEN slug = $1 THEN 0 ELSE 1 END, created_at ASC
+		LIMIT 1;
+	`, primaryOrganizationSlug).Scan(&record.ID, &record.Name, &record.Slug)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+
+		return nil, err
+	}
+
+	return &record, nil
+}
+
+func (service *Service) loadPrimaryDepartment(ctx context.Context) (*DepartmentRecord, error) {
+	var record DepartmentRecord
+	err := service.db.Pool.QueryRow(ctx, `
+		SELECT id::text, organization_id::text, name, slug
+		FROM departments
+		ORDER BY CASE WHEN slug = $1 THEN 0 ELSE 1 END, created_at ASC
+		LIMIT 1;
+	`, primaryDepartmentSlug).Scan(&record.ID, &record.OrganizationID, &record.Name, &record.Slug)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+
+		return nil, err
+	}
+
+	return &record, nil
+}
+
+func (service *Service) loadPrimaryTeam(ctx context.Context) (*TeamRecord, error) {
+	var record TeamRecord
+	err := service.db.Pool.QueryRow(ctx, `
+		SELECT id::text, organization_id::text, department_id::text, name, slug
+		FROM teams
+		ORDER BY CASE WHEN slug = $1 THEN 0 ELSE 1 END, created_at ASC
+		LIMIT 1;
+	`, primaryTeamSlug).Scan(&record.ID, &record.OrganizationID, &record.DepartmentID, &record.Name, &record.Slug)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+
+		return nil, err
+	}
+
+	return &record, nil
+}
+
+func (service *Service) loadPrimaryProject(ctx context.Context) (*ProjectRecord, error) {
+	var record ProjectRecord
+	err := service.db.Pool.QueryRow(ctx, `
+		SELECT id::text, organization_id::text, department_id::text, team_id::text, name, slug
+		FROM projects
+		ORDER BY CASE WHEN slug = $1 THEN 0 ELSE 1 END, created_at ASC
+		LIMIT 1;
+	`, primaryProjectSlug).Scan(&record.ID, &record.OrganizationID, &record.DepartmentID, &record.TeamID, &record.Name, &record.Slug)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+
+		return nil, err
+	}
+
+	return &record, nil
+}
+
+func (service *Service) listOrganizations(ctx context.Context) ([]OrganizationRecord, error) {
+	rows, err := service.db.Pool.Query(ctx, `
+		SELECT id::text, name, slug
+		FROM organizations
+		ORDER BY created_at ASC;
+	`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var records []OrganizationRecord
+	for rows.Next() {
+		var record OrganizationRecord
+		if err := rows.Scan(&record.ID, &record.Name, &record.Slug); err != nil {
+			return nil, err
+		}
+
+		records = append(records, record)
+	}
+
+	return records, rows.Err()
+}
+
+func (service *Service) listDepartments(ctx context.Context) ([]DepartmentRecord, error) {
+	rows, err := service.db.Pool.Query(ctx, `
+		SELECT id::text, organization_id::text, name, slug
+		FROM departments
+		ORDER BY created_at ASC;
+	`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var records []DepartmentRecord
+	for rows.Next() {
+		var record DepartmentRecord
+		if err := rows.Scan(&record.ID, &record.OrganizationID, &record.Name, &record.Slug); err != nil {
+			return nil, err
+		}
+
+		records = append(records, record)
+	}
+
+	return records, rows.Err()
+}
+
+func (service *Service) listTeams(ctx context.Context) ([]TeamRecord, error) {
+	rows, err := service.db.Pool.Query(ctx, `
+		SELECT id::text, organization_id::text, department_id::text, name, slug
+		FROM teams
+		ORDER BY created_at ASC;
+	`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var records []TeamRecord
+	for rows.Next() {
+		var record TeamRecord
+		if err := rows.Scan(&record.ID, &record.OrganizationID, &record.DepartmentID, &record.Name, &record.Slug); err != nil {
+			return nil, err
+		}
+
+		records = append(records, record)
+	}
+
+	return records, rows.Err()
+}
+
+func (service *Service) listProjects(ctx context.Context) ([]ProjectRecord, error) {
+	rows, err := service.db.Pool.Query(ctx, `
+		SELECT id::text, organization_id::text, department_id::text, team_id::text, name, slug
+		FROM projects
+		ORDER BY created_at ASC;
+	`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var records []ProjectRecord
+	for rows.Next() {
+		var record ProjectRecord
+		if err := rows.Scan(&record.ID, &record.OrganizationID, &record.DepartmentID, &record.TeamID, &record.Name, &record.Slug); err != nil {
+			return nil, err
+		}
+
+		records = append(records, record)
+	}
+
+	return records, rows.Err()
+}
+
+func (service *Service) listWorkspaces(ctx context.Context) ([]WorkspaceRecord, error) {
+	rows, err := service.db.Pool.Query(ctx, `
+		SELECT id::text, organization_id::text, name, slug, kind::text, department_id::text, team_id::text, project_id::text
+		FROM workspaces
+		ORDER BY created_at ASC;
+	`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var records []WorkspaceRecord
+	for rows.Next() {
+		var record WorkspaceRecord
+		if err := rows.Scan(&record.ID, &record.OrganizationID, &record.Name, &record.Slug, &record.Kind, &record.DepartmentID, &record.TeamID, &record.ProjectID); err != nil {
+			return nil, err
+		}
+
+		records = append(records, record)
+	}
+
+	return records, rows.Err()
+}
+
+func loadInstallation(ctx context.Context, tx pgx.Tx) (InstallationRecord, error) {
+	return scanInstallationRecord(tx.QueryRow(ctx, `
+		SELECT id::text, name, mode::text, access::text, protocol::text, host, is_bootstrapped
+		FROM installations
+		WHERE singleton = TRUE
+		LIMIT 1;
+	`))
+}
+
+func loadPrimaryAdmin(ctx context.Context, tx pgx.Tx) (AdminSummary, error) {
+	var admin AdminSummary
+	if err := tx.QueryRow(ctx, `
+		SELECT id::text, email, display_name
+		FROM users
+		WHERE is_instance_admin = TRUE
+		ORDER BY created_at ASC
+		LIMIT 1;
+	`).Scan(&admin.ID, &admin.Email, &admin.DisplayName); err != nil {
+		return AdminSummary{}, err
+	}
+
+	return admin, nil
+}
+
+func updateBootstrappedInstallation(ctx context.Context, tx pgx.Tx) (InstallationRecord, error) {
+	return scanInstallationRecord(tx.QueryRow(ctx, `
+		UPDATE installations
+		SET is_bootstrapped = TRUE, bootstrapped_at = COALESCE(bootstrapped_at, NOW()), updated_at = NOW()
+		WHERE singleton = TRUE
+		RETURNING id::text, name, mode::text, access::text, protocol::text, host, is_bootstrapped;
+	`))
+}
+
+func upsertNamedRecord(ctx context.Context, tx pgx.Tx, query string, args ...any) (namedRecord, error) {
+	var record namedRecord
+	if err := tx.QueryRow(ctx, query, args...).Scan(&record.ID, &record.Name, &record.Slug); err != nil {
+		return namedRecord{}, err
+	}
+
+	return record, nil
+}
+
+func upsertWorkspace(ctx context.Context, tx pgx.Tx, organizationID, name, slug, kind, createdByUserID string, departmentID, teamID, projectID *string) error {
+	_, err := tx.Exec(ctx, `
+		INSERT INTO workspaces (organization_id, name, slug, kind, created_by_user_id, department_id, team_id, project_id)
+		VALUES ($1::uuid, $2, $3, $4::workspace_kind, $5::uuid, $6::uuid, $7::uuid, $8::uuid)
+		ON CONFLICT (organization_id, slug) DO UPDATE
+		SET
+			name = EXCLUDED.name,
+			kind = EXCLUDED.kind,
+			created_by_user_id = EXCLUDED.created_by_user_id,
+			department_id = EXCLUDED.department_id,
+			team_id = EXCLUDED.team_id,
+			project_id = EXCLUDED.project_id,
+			updated_at = NOW();
+	`, organizationID, name, slug, kind, createdByUserID, departmentID, teamID, projectID)
+
+	return err
+}
+
+func defaultRootOrganizationName(installationName, mode, host, adminDisplayName string) string {
+	trimmedInstallationName := strings.TrimSpace(installationName)
+	trimmedHost := strings.TrimSpace(host)
+	trimmedAdminDisplayName := strings.TrimSpace(adminDisplayName)
+
+	if trimmedInstallationName != "" {
+		return trimmedInstallationName
+	}
+
+	if strings.EqualFold(mode, defaultInstallationMode) {
+		if trimmedAdminDisplayName != "" {
+			return fmt.Sprintf("%s %s", trimmedAdminDisplayName, defaultPersonalServerSuffix)
+		}
+
+		return defaultPersonalDisplayName
+	}
+
+	if trimmedHost != "" {
+		return trimmedHost
+	}
+
+	return defaultOrganizationName
+}
+
+func personalHomeTitle(displayName string) string {
+	trimmedDisplayName := strings.TrimSpace(displayName)
+	if trimmedDisplayName == "" {
+		return "Home"
+	}
+
+	if strings.HasSuffix(strings.ToLower(trimmedDisplayName), "s") {
+		return fmt.Sprintf("%s' Home", trimmedDisplayName)
+	}
+
+	return fmt.Sprintf("%s's Home", trimmedDisplayName)
+}

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)
+}
+
+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_routes.go

@@ -19,8 +19,24 @@ 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)
+
+		if routes.cfg.Config.IsDevelopment() {
+			apiRouter.Post("/dev/bootstrap/reset", routes.handleDevelopmentBootstrapReset)
+		}
 	})
 }
 

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

Docker/docker-compose.local.prod.yaml

@@ -1,7 +1,67 @@
+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
+  depends_on:
+    postgres:
+      condition: service_healthy
+    valkey:
+      condition: service_healthy
+
 services:
-    proxy:
+  postgres:
-        image: moku/work-proxy:local-prod
+    image: postgres:17-alpine
-        container_name: moku-work-proxy-local
+    container_name: moku-work-postgres-prod
-        restart: unless-stopped
+    restart: unless-stopped
-        ports:
+    environment:
-            - "8080:80"
+      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:

Env/.env.example

@@ -10,3 +10,9 @@ BACKEND_SHUTDOWN_TIMEOUT=10s
 
 DATABASE_URL=postgres://moku:moku_dev_password@localhost:5432/moku?sslmode=disable
 VALKEY_URL=redis://localhost:6379/0
+
+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/components/shell/AppShell/AppShell.tsx

@@ -3,6 +3,7 @@
 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";
@@ -16,13 +17,14 @@ import styles from "./AppShell.module.scss";
 type MobileWorkspaceView = "notifications" | "profile" | null;
 const MOBILE_VIEWPORT_QUERY = "(max-width: 48rem)";
 
-export const AppShell = (): JSX.Element => {
+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());
@@ -79,7 +81,7 @@ export const AppShell = (): JSX.Element => {
 	};
 
 	return (
-		<div class={styles.shell} data-ui="app-shell">
+		<div class={styles.shell} data-ui="app-shell" data-app-shell-status={appShellData.status()}>
 			<TopBar
 				theme={themeState()}
 				onToggleTheme={toggleTheme}
@@ -163,3 +165,11 @@ export const AppShell = (): JSX.Element => {
 		</div>
 	);
 };
+
+export const AppShell = (): JSX.Element => {
+	return (
+		<AppShellDataProvider>
+			<AppShellContent />
+		</AppShellDataProvider>
+	);
+};

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 [selectedDepartment, setSelectedDepartment] = createSignal<DepartmentItem>(appShellData.departmentItems()[0] ?? appShellData.activeDepartment());
-	const [selectedTeamName, setSelectedTeamName] = createSignal(defaultTeamName);
+	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;
@@ -66,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.tsx

@@ -1,7 +1,8 @@
 // Path: Frontend/src/components/shell/LeftRail/LeftRail.tsx
 
 import { For, Show, type JSX } from "solid-js";
-import { railItems, type RailItem } from "../data/shell.data";
+import { useAppShellData } from "../data/app-shell.context";
+import { type RailItem } from "../data/shell.data";
 import styles from "./LeftRail.module.scss";
 
 type RailEntryProps = {
@@ -46,8 +47,9 @@ type LeftRailProps = {
 };
 
 export const LeftRail = (props: LeftRailProps): JSX.Element => {
-	const personalItem = railItems.find((item) => item.kind === "personal");
+	const appShellData = useAppShellData();
-	const organizationItems = railItems.filter((item) => item.kind === "organization");
+	const personalItem = () => appShellData.railItems().find((item) => item.kind === "personal");
+	const organizationItems = () => appShellData.railItems().filter((item) => item.kind === "organization");
 
 	return (
 		<aside
@@ -58,7 +60,7 @@ export const LeftRail = (props: LeftRailProps): JSX.Element => {
 			aria-label="Server rail"
 		>
 			<div class={styles.topCluster}>
-				<Show when={!props.collapsed && personalItem}>
+				<Show when={!props.collapsed && personalItem()}>
 					{(item): JSX.Element => (
 						<RailEntry item={item()} label={item().label} abbreviation={item().abbreviation} personal />
 					)}
@@ -71,7 +73,7 @@ export const LeftRail = (props: LeftRailProps): JSX.Element => {
 
 			<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>

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

@@ -1,7 +1,8 @@
 // Path: Frontend/src/components/shell/MobileBottomNav/MobileBottomNav.tsx
 
 import { For, type JSX } from "solid-js";
-import { activeProject, activeServer, mobileBottomNavItems, type MobileBottomNavItem } from "../data/shell.data";
+import { useAppShellData } from "../data/app-shell.context";
+import { mobileBottomNavItems, type MobileBottomNavItem } from "../data/shell.data";
 import styles from "./MobileBottomNav.module.scss";
 
 type MobileBottomNavProps = {
@@ -39,12 +40,14 @@ const MobileNavEntry = (props: {
 };
 
 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}>{activeServer.name}</span>
+				<span class={styles.contextServer}>{appShellData.activeServer().name}</span>
 				<span class={styles.contextDivider}>/</span>
-				<span class={styles.contextProject}>{activeProject.name}</span>
+				<span class={styles.contextProject}>{appShellData.activeProject().name}</span>
 			</div>
 
 			<div class={styles.navGrid}>

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

@@ -1,15 +1,13 @@
 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 {
-	activeProject,
-	activeServer,
 	createWorkspaceStaticTarget,
 	createWorkspaceSurfaceTarget,
 	createWorkspaceTreeTarget,
 	getWorkspaceNodeIcon,
 	workspaceStaticItems,
-	workspaceTree,
 	type SidebarItem,
 	type WorkspaceContextMenuAction,
 	type WorkspaceContextMenuTarget,
@@ -149,10 +147,11 @@ const WorkspaceTreeBranch = (props: {
 };
 
 export const MobileWorkspaceBrowser = (props: MobileWorkspaceBrowserProps): JSX.Element => {
+	const appShellData = useAppShellData();
 	const [actionSheetTarget, setActionSheetTarget] = createSignal<WorkspaceContextMenuTarget | null>(null);
-	const sectionNodes = workspaceTree.filter((node) => (node.children?.length ?? 0) > 0);
+	const sectionNodes = () => appShellData.workspaceTree().filter((node) => (node.children?.length ?? 0) > 0);
-	const looseNodes = workspaceTree.filter((node) => (node.children?.length ?? 0) === 0);
+	const looseNodes = () => appShellData.workspaceTree().filter((node) => (node.children?.length ?? 0) === 0);
-	const workspaceTarget = createWorkspaceSurfaceTarget(activeProject);
+	const workspaceTarget = () => createWorkspaceSurfaceTarget(appShellData.activeProject());
 	const openActionSheet = (target: WorkspaceContextMenuTarget): void => {
 		setActionSheetTarget(target);
 	};
@@ -160,7 +159,7 @@ export const MobileWorkspaceBrowser = (props: MobileWorkspaceBrowserProps): JSX.
 		setActionSheetTarget(null);
 	};
 	const openWorkspaceActionSheet = (): void => {
-		openActionSheet(workspaceTarget);
+		openActionSheet(workspaceTarget());
 	};
 
 	const handleActionSelect = (_action: WorkspaceContextMenuAction, _target: WorkspaceContextMenuTarget): void => {
@@ -187,8 +186,8 @@ export const MobileWorkspaceBrowser = (props: MobileWorkspaceBrowserProps): JSX.
 						>
 							{/* Long-pressing the browser header exposes workspace-level actions on mobile. */}
 							<span class={styles.brandEyebrow}>Moku Work</span>
-							<strong class={styles.brandTitle}>{activeProject.name}</strong>
+							<strong class={styles.brandTitle}>{appShellData.activeProject().name}</strong>
-							<span class={styles.brandContext}>{activeServer.name}</span>
+							<span class={styles.brandContext}>{appShellData.activeServer().name}</span>
 						</div>
 
 						<div class={styles.headerActions} data-slot="mobile-workspace-header-actions">
@@ -222,15 +221,15 @@ export const MobileWorkspaceBrowser = (props: MobileWorkspaceBrowserProps): JSX.
 						<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} />
+								<WorkspaceTreeBranch nodes={sectionNodes()} onOpenActionSheet={openActionSheet} />
 							</ul>
 						</section>
 
-						<Show when={looseNodes.length > 0}>
+						<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} />
+									<WorkspaceTreeBranch nodes={looseNodes()} onOpenActionSheet={openActionSheet} />
 								</ul>
 							</section>
 						</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

@@ -38,9 +38,9 @@
 }
 
 .triggerOpen {
-  border-color: color-mix(in srgb, var(--color-border-strong) 22%, transparent);
+  border-color: color-mix(in srgb, var(--color-accent-strong) 22%, var(--color-border-strong));
-  background: color-mix(in srgb, var(--color-surface) 92%, transparent);
+  background: color-mix(in srgb, var(--color-accent-soft) 26%, var(--color-surface));
-  box-shadow: var(--shadow-soft);
+  box-shadow: 0 10px 28px color-mix(in srgb, black 8%, transparent);
 }
 
 .triggerCompact {
@@ -83,19 +83,14 @@
   gap: 0.12rem;
 }
 
-.eyebrow,
+.eyebrow {
-.projectItemDescription {
   @include text-caption;
   color: var(--color-text-muted);
-}
-
-.eyebrow {
   text-transform: uppercase;
   letter-spacing: 0.08em;
 }
 
-.value,
+.value {
-.projectItemName {
   @include text-label;
 }
 
@@ -175,7 +170,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;
@@ -186,20 +181,34 @@
 	width: 0;
 }
 
-.projectList {
+.treeSectionLabel {
+  @include text-caption;
+  margin: 0 0 var(--space-2);
+  padding: 0 var(--space-3);
+  color: var(--color-text-subtle);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.treeList {
   list-style: none;
   display: grid;
-  gap: 0.2rem;
+  gap: var(--space-1);
   padding: 0;
 }
 
-.projectItem {
+.treeItem {
   width: 100%;
   min-width: 0;
-  min-height: calc(var(--control-size-md) + var(--space-2));
+  display: grid;
+  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: 1px solid transparent;
-  border-radius: var(--radius-sm);
+  border-radius: var(--radius-lg);
   background: transparent;
   color: var(--color-text-muted);
   transition:
@@ -210,25 +219,50 @@
   text-align: left;
 }
 
-.projectItem:hover {
+.treeItem:hover,
-  background: color-mix(in srgb, var(--color-surface-hover) 82%, transparent);
+.treeItem:focus-visible {
+  background: var(--color-surface-hover);
   color: var(--color-text);
-  border-color: color-mix(in srgb, var(--color-border) 22%, transparent);
 }
 
-.projectItemActive {
+.treeItemFolder {
-  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;
 }
 
-.projectItemCopy {
+.folderChevron {
+  color: var(--color-text-muted);
+  transition: transform 160ms var(--easing-standard);
+}
+
+.folderChevronOpen {
+  transform: rotate(90deg);
+}
+
+.treeItemActive {
+  border-color: var(--color-border);
+  background: var(--color-surface);
+  color: var(--color-text);
+  box-shadow: inset 0 1px 0 color-mix(in srgb, white 4%, transparent);
+}
+
+.icon {
+  color: inherit;
+  opacity: 0.85;
+}
+
+.label {
+  @include text-label;
   min-width: 0;
-  display: grid;
-  gap: 0.05rem;
 }
 
-.projectItemDescription {
+.itemMeta {
-  color: color-mix(in srgb, var(--color-text-muted) 84%, transparent);
+  @include text-caption;
+  color: var(--color-text-muted);
+}
+
+@media (max-width: 720px) {
+  .rootCompact .scrim,
+  .rootCompact .drawer {
+    width: min(18rem, calc(100vw - 5rem));
+  }
 }

Frontend/src/components/shell/ProjectSelector/ProjectSelector.tsx

@@ -1,8 +1,17 @@
 // Path: Frontend/src/components/shell/ProjectSelector/ProjectSelector.tsx
 
-import { For, createSignal, onCleanup, onMount, type JSX } from "solid-js";
+import { For, Show, createEffect, createMemo, createSignal, onCleanup, onMount, type JSX } from "solid-js";
-import { ChevronDown, Folder } from "../../../lib/icons";
+import { ChevronDown, ChevronRight, Folder, LayoutGrid } from "../../../lib/icons";
-import { activeProject, projectItems } from "../data/shell.data";
+import { ProjectContextMenu } from "../ProjectContextMenu/ProjectContextMenu";
+import { useAppShellData } from "../data/app-shell.context";
+import {
+	createProjectFolderTarget,
+	createProjectSurfaceTarget,
+	createProjectTarget,
+	type ProjectItem,
+	type ProjectMenuTarget,
+} from "../data/shell.data";
+import { createProjectContextMenuController } from "../ProjectContextMenu/createProjectContextMenuController";
 import styles from "./ProjectSelector.module.scss";
 
 type ProjectSelectorProps = {
@@ -12,38 +21,109 @@ type ProjectSelectorProps = {
 	onClose: () => void;
 };
 
-const defaultProject = projectItems.find((item) => item.id === activeProject.id) ?? projectItems[0];
-
 export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
-	const [selectedProject, setSelectedProject] = createSignal({ id: defaultProject.id, name: defaultProject.name });
+	const appShellData = useAppShellData();
+	const [selectedProject, setSelectedProject] = createSignal(appShellData.activeProject());
 	const [drawerTop, setDrawerTop] = createSignal<number>(0);
+	const [collapsedFolderIds, setCollapsedFolderIds] = createSignal<readonly string[]>([]);
+	let rootRef: HTMLDivElement | undefined;
 	let triggerRef: HTMLButtonElement | undefined;
+	let contextMenuRef: HTMLDivElement | undefined;
+	const contextMenu = createProjectContextMenuController();
 
-	onMount(() => {
+	const projectFolders = createMemo(() => {
-		if (!triggerRef) {
+		const sections = new Map<string, ProjectItem[]>();
-			return;
+
+		for (const item of appShellData.projectItems()) {
+			const key = item.parentLabel || item.groupLabel || "Projects";
+			const existing = sections.get(key);
+
+			if (existing) {
+				existing.push(item);
+				continue;
+			}
+
+			sections.set(key, [item]);
 		}
 
-		const updateDrawerTop = (): void => {
+		return Array.from(sections.entries()).map(([label, items]) => ({
-			if (!triggerRef) {
+			id: label.toLowerCase().replace(/\s+/g, "-"),
+			label,
+			meta: items[0]?.groupLabel && items[0].groupLabel !== label ? items[0].groupLabel : undefined,
+			items,
+		}));
+	});
+
+	const isFolderCollapsed = (folderId: string): boolean => collapsedFolderIds().includes(folderId);
+
+	const toggleFolder = (folderId: string): void => {
+		setCollapsedFolderIds((current) =>
+			current.includes(folderId) ? current.filter((id) => id !== folderId) : [...current, folderId],
+		);
+	};
+
+	createEffect(() => {
+		setSelectedProject(appShellData.activeProject());
+	});
+
+	onMount(() => {
+		if (triggerRef) {
+			const updateDrawerTop = (): void => {
+				if (!triggerRef) {
+					return;
+				}
+
+				setDrawerTop(triggerRef.offsetTop + triggerRef.offsetHeight + 8);
+			};
+
+			updateDrawerTop();
+
+			const observer = new ResizeObserver(() => {
+				updateDrawerTop();
+			});
+
+			observer.observe(triggerRef);
+			window.addEventListener("resize", updateDrawerTop);
+
+			onCleanup(() => {
+				observer.disconnect();
+				window.removeEventListener("resize", updateDrawerTop);
+			});
+		}
+
+		const handlePointerDown = (event: PointerEvent): void => {
+			if (!props.isOpen || !rootRef) {
 				return;
 			}
 
-			setDrawerTop(triggerRef.offsetTop + triggerRef.offsetHeight);
+			const target = event.target;
+
+			if (target instanceof Node && rootRef.contains(target)) {
+				return;
+			}
+
+			if (target instanceof Node && contextMenuRef?.contains(target)) {
+				return;
+			}
+
+			props.onClose();
 		};
 
-		updateDrawerTop();
+		const handleEscape = (event: KeyboardEvent): void => {
+			if (event.key !== "Escape" || !props.isOpen) {
+				return;
+			}
 
-		const observer = new ResizeObserver(() => {
+			props.onClose();
-			updateDrawerTop();
+			triggerRef?.focus();
-		});
+		};
 
-		observer.observe(triggerRef);
+		document.addEventListener("pointerdown", handlePointerDown);
-		window.addEventListener("resize", updateDrawerTop);
+		window.addEventListener("keydown", handleEscape);
 
 		onCleanup(() => {
-			observer.disconnect();
+			document.removeEventListener("pointerdown", handlePointerDown);
-			window.removeEventListener("resize", updateDrawerTop);
+			window.removeEventListener("keydown", handleEscape);
 		});
 	});
 
@@ -57,7 +137,7 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 	};
 
 	const selectProject = (projectId: string): void => {
-		const nextProject = projectItems.find((item): boolean => item.id === projectId);
+		const nextProject = appShellData.projectItems().find((item): boolean => item.id === projectId);
 
 		if (!nextProject) {
 			return;
@@ -67,8 +147,18 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 		props.onClose();
 	};
 
+	const handleContextActionSelect = (_action: { id: string; label: string }, _target: ProjectMenuTarget): void => {
+		// Initial implementation keeps the project menu aligned with workspace-menu IA.
+	};
+
+	const handleSurfaceContextMenu = (event: MouseEvent): void => {
+		event.stopPropagation();
+		contextMenu.openMenu(event, createProjectSurfaceTarget("Projects"));
+	};
+
 	return (
 		<div
+			ref={rootRef}
 			classList={{
 				[styles.root]: true,
 				[styles.rootCompact]: !!props.compact,
@@ -77,7 +167,6 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 				"--project-drawer-top": `${drawerTop()}px`,
 			}}
 		>
-			{/* Project trigger */}
 			<button
 				type="button"
 				ref={triggerRef}
@@ -86,8 +175,9 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 					[styles.triggerCompact]: !!props.compact,
 					[styles.triggerOpen]: props.isOpen,
 				}}
-				aria-label={`Open left workspace sidebar menu for ${selectedProject().name}`}
+				aria-label={`Open project menu for ${selectedProject().name}`}
 				aria-expanded={props.isOpen}
+				aria-haspopup="menu"
 				title={selectedProject().name}
 				onClick={toggleOpen}
 			>
@@ -110,54 +200,123 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 				/>
 			</button>
 
-			{/* Outside-click scrim */}
+			<Show when={props.isOpen}>
-			<button
+				<>
-				type="button"
+					<button
-				classList={{
+						type="button"
-					[styles.scrim]: true,
+						classList={{
-					[styles.scrimOpen]: props.isOpen,
+							[styles.scrim]: true,
+							[styles.scrimOpen]: props.isOpen,
+						}}
+						aria-hidden={!props.isOpen}
+						tabIndex={props.isOpen ? 0 : -1}
+						onClick={props.onClose}
+					/>
+
+					<div
+						classList={{
+							[styles.drawer]: true,
+							[styles.drawerOpen]: props.isOpen,
+						}}
+						aria-hidden={!props.isOpen}
+						onContextMenu={handleSurfaceContextMenu}
+					>
+						<div class={styles.drawerBody}>
+							<Show when={!props.compact}>
+								<div class={styles.treeSectionLabel}>Projects</div>
+							</Show>
+
+							<ul class={styles.treeList} role="list">
+								<For each={projectFolders()}>
+									{(folder): JSX.Element => {
+										const isCollapsed = (): boolean => isFolderCollapsed(folder.id);
+
+										return (
+										<li>
+											<button
+												type="button"
+												classList={{
+													[styles.treeItem]: true,
+													[styles.treeItemFolder]: true,
+												}}
+												aria-expanded={!isCollapsed()}
+												onClick={() => toggleFolder(folder.id)}
+												onContextMenu={(event): void => {
+													event.stopPropagation();
+													contextMenu.openMenu(event, createProjectFolderTarget(folder.id, folder.label));
+												}}
+											>
+												<ChevronRight
+													classList={{
+														[styles.folderChevron]: true,
+														[styles.folderChevronOpen]: !isCollapsed(),
+													}}
+													size={16}
+													strokeWidth={2}
+												/>
+												<Folder class={styles.icon} size={18} strokeWidth={2} />
+												<span class={styles.label}>{folder.label}</span>
+												<Show when={folder.meta}>
+													<span class={styles.itemMeta}>{folder.meta}</span>
+												</Show>
+											</button>
+
+											<Show when={!isCollapsed()}>
+												<ul class={styles.treeList} role="list">
+													<For each={folder.items}>
+														{(item): JSX.Element => {
+															const isSelected = (): boolean => selectedProject().id === item.id;
+
+															return (
+																<li>
+																	<button
+																		type="button"
+																		classList={{
+																			[styles.treeItem]: true,
+																			[styles.treeItemActive]: isSelected(),
+																		}}
+																		style={{ "--tree-depth": "1" }}
+																		onClick={(): void => selectProject(item.id)}
+																		onContextMenu={(event): void => {
+																			event.stopPropagation();
+																			contextMenu.openMenu(event, createProjectTarget(item));
+																		}}
+																	>
+																		<LayoutGrid class={styles.icon} size={18} strokeWidth={2} />
+																		<span class={styles.label}>{item.name}</span>
+																		<Show when={item.meta}>
+																			<span class={styles.itemMeta}>{item.meta}</span>
+																		</Show>
+																	</button>
+																</li>
+															);
+														}}
+													</For>
+												</ul>
+											</Show>
+										</li>
+										);
+									}}
+								</For>
+							</ul>
+						</div>
+					</div>
+				</>
+			</Show>
+
+			<ProjectContextMenu
+				target={contextMenu.menuState()?.target ?? null}
+				position={(() => {
+					const state = contextMenu.menuState();
+					return state ? { x: state.x, y: state.y } : null;
+				})()}
+				menuRef={(element) => {
+					contextMenuRef = element;
+					contextMenu.setMenuRef(element);
 				}}
-				aria-hidden={!props.isOpen}
+				onClose={contextMenu.closeMenu}
-				tabIndex={props.isOpen ? 0 : -1}
+				onSelect={handleContextActionSelect}
-				onClick={props.onClose}
 			/>
-
-			{/* Slide-out project list */}
-			<div
-				classList={{
-					[styles.drawer]: true,
-					[styles.drawerOpen]: props.isOpen,
-				}}
-				aria-hidden={!props.isOpen}
-			>
-				<div class={styles.drawerBody}>
-					<ul class={styles.projectList} role="list">
-						<For each={projectItems}>
-							{(item): JSX.Element => {
-								const isSelected = (): boolean => selectedProject().id === item.id;
-
-								return (
-									<li>
-										<button
-											type="button"
-											classList={{
-												[styles.projectItem]: true,
-												[styles.projectItemActive]: isSelected(),
-											}}
-											onClick={(): void => selectProject(item.id)}
-										>
-											<span class={styles.projectItemCopy}>
-												<span class={styles.projectItemName}>{item.name}</span>
-												<span class={styles.projectItemDescription}>{item.description}</span>
-											</span>
-										</button>
-									</li>
-								);
-							}}
-						</For>
-					</ul>
-				</div>
-			</div>
 		</div>
 	);
 };

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

@@ -1,33 +1,36 @@
 // 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" data-ui="server-dock" data-server-kind={activeServer.kind}>
+		<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} data-slot="server-dock-copy">
-					<span class={styles.name}>{activeServer.name}</span>
+					<span class={styles.name}>{activeServer().name}</span>
 					<Show
-						when={activeServer.kind === "organization"}
+						when={activeServer().kind === "organization"}
-						fallback={<span class={styles.subtitle}>{activeServer.subtitle}</span>}
+						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}>
+			<Show when={activeServer().dockActions.length > 0}>
 				<div class={styles.actions} data-slot="server-dock-actions">
-					<For each={activeServer.dockActions}>
+					<For each={activeServer().dockActions}>
 						{(item): JSX.Element => {
 							const Icon = item.icon;
 

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

@@ -1,6 +1,7 @@
 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 = {
@@ -12,6 +13,8 @@ type ProfileMenuProps = {
 
 export const ProfileMenu = (props: ProfileMenuProps): JSX.Element => {
 	const variant = props.variant ?? "popover";
+	const appShellData = useAppShellData();
+	const activeUserProfile = () => appShellData.activeUserProfile();
 
 	return (
 		<div
@@ -35,10 +38,10 @@ export const ProfileMenu = (props: ProfileMenuProps): JSX.Element => {
 				</div>
 
 				<div class={styles.summaryCopy}>
-					<strong class={styles.name}>{activeUserProfile.name}</strong>
+					<strong class={styles.name}>{activeUserProfile().name}</strong>
-					<span class={styles.email}>{activeUserProfile.email}</span>
+					<span class={styles.email}>{activeUserProfile().email}</span>
-					<span class={styles.role}>{activeUserProfile.roleLabel}</span>
+					<span class={styles.role}>{activeUserProfile().roleLabel}</span>
-					<span class={styles.context}>{activeUserProfile.contextLabel}</span>
+					<span class={styles.context}>{activeUserProfile().contextLabel}</span>
 				</div>
 			</div>
 

Frontend/src/components/shell/WorkspaceSidebar/WorkspaceSidebar.tsx

@@ -2,16 +2,15 @@
 
 import { For, Show, createMemo, createSignal, type JSX } from "solid-js";
 import { ChevronLeft, ChevronRight } from "../../../lib/icons";
+import { useAppShellData } from "../data/app-shell.context";
 import { ProjectSelector } from "../ProjectSelector/ProjectSelector";
 import {
-	activeProject,
 	createWorkspaceStaticTarget,
 	createWorkspaceSurfaceTarget,
 	createWorkspaceTreeTarget,
 	getWorkspaceNodeIcon,
 	workspaceSidebarHeaderActions,
 	workspaceStaticItems,
-	workspaceTree,
 	type WorkspaceContextMenuAction,
 	type WorkspaceContextMenuTarget,
 	type WorkspaceStaticItem,
@@ -142,11 +141,12 @@ const WorkspaceTreeBranch = (props: {
 	);
 };
 
-	export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
+export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
+	const appShellData = useAppShellData();
 	const [isProjectDrawerOpen, setIsProjectDrawerOpen] = createSignal(false);
 	const contextMenu = createWorkspaceContextMenuController();
 	const railToggleLabel = (): string => (props.railCollapsed ? "Expand server rail" : "Collapse server rail");
-	const sidebarContextMenuTarget = createWorkspaceSurfaceTarget(activeProject);
+	const sidebarContextMenuTarget = createMemo(() => createWorkspaceSurfaceTarget(appShellData.activeProject()));
 	const contextMenuTarget = createMemo(() => contextMenu.menuState()?.target ?? null);
 	const contextMenuPosition = createMemo(() => {
 		const state = contextMenu.menuState();
@@ -174,7 +174,7 @@ const WorkspaceTreeBranch = (props: {
 				data-ui="workspace-sidebar"
 				data-collapsed={props.collapsed ? "true" : "false"}
 				onContextMenu={(event): void => {
-					contextMenu.openMenu(event, sidebarContextMenuTarget);
+					contextMenu.openMenu(event, sidebarContextMenuTarget());
 				}}
 			>
 				<div
@@ -256,7 +256,7 @@ const WorkspaceTreeBranch = (props: {
 
 						<div data-slot="workspace-tree-root">
 						<WorkspaceTreeBranch
-							nodes={workspaceTree}
+							nodes={appShellData.workspaceTree()}
 							onOpenContextMenu={contextMenu.openMenu}
 							onOpenContextMenuFromKeyboard={contextMenu.openMenuFromElement}
 						/>

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

@@ -71,9 +71,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;
@@ -325,12 +359,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;
@@ -364,9 +398,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: "general",
-	{ id: "hiring", name: "Hiring", description: "Candidate pipeline and interview loops" },
+		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[] = [
@@ -533,6 +589,69 @@ export const getWorkspaceContextMenuSections = (
 	}
 };
 
+const getProjectCreateActions = (): readonly ProjectContextMenuAction[] =>
+	[
+		{ id: "new-project", label: "New project" },
+		{ id: "new-folder", label: "New folder" },
+	] 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,
+				},
+			] as const;
+		case "project":
+			return [
+				{
+					id: "create",
+					items: createActions,
+				},
+			] as const;
+	}
+};
+
 export const topBarActions: readonly TopBarAction[] = [
 	{ id: "search", label: "Search", icon: Search },
 ] as const;

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;
@@ -81,10 +86,10 @@
   max-width: var(--workspace-content-max-width);
 }
 
-.eyebrow {
+.heroActions {
-  @include text-caption;
+  display: flex;
-  color: var(--color-text-muted);
+  gap: var(--space-3);
-  text-transform: uppercase;
+  flex-wrap: wrap;
 }
 
 .title {
@@ -98,18 +103,12 @@
   color: var(--color-text-muted);
 }
 
-.grid {
+.overviewCard,
-  width: 100%;
+.summaryCard,
-  max-width: var(--workspace-content-max-width);
+.wizardSidebarSection,
-  display: grid;
+.wizardStepPanel {
-  grid-template-columns: repeat(3, minmax(0, 1fr));
-  gap: var(--space-4);
-}
-
-.card {
   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);
@@ -117,23 +116,390 @@
   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) {
@@ -155,4 +521,51 @@
   .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,85 +1,582 @@
 // Path: Frontend/src/components/workspace-home/WorkspaceHome/WorkspaceHome.tsx
 
-import { For, type JSX } from "solid-js";
+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 { activeProject, activeServer } from "../../shell/data/shell.data";
+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;
+	buttonLabel: string;
-	meta: string;
 };
 
-const shellCheckpointCards: readonly ShellCheckpointCard[] = [
+type BootstrapSubmissionState = {
+	status: "idle" | "submitting" | "success" | "error";
+	error: string;
+};
+
+const bootstrapStepDefinitions: readonly BootstrapStepDefinition[] = [
 	{
-		title: "Server shell",
+		id: "instance",
-		copy: "Top bar, server rail, sidebar, and content viewport are now split into modular components.",
+		title: "Instance shape",
-		meta: "Layout foundation",
+		buttonLabel: "Save and continue",
 	},
 	{
-		title: "Presence foundation",
+		id: "mode",
-		copy: "The dock now distinguishes personal and organization servers, leaving clear space for future presence and server-aware controls.",
+		title: "Server mode",
-		meta: "Server foundation",
+		buttonLabel: "Save and continue",
 	},
 	{
-		title: "Next build target",
+		id: "admin",
-		copy: "You can now plug in auth state, server onboarding, and live presence without redesigning the whole frame.",
+		title: "Admin account",
-		meta: "Ready for v0.1.0 work",
+		buttonLabel: "Save and continue",
+	},
+	{
+		id: "structure",
+		title: "Initial structure",
+		buttonLabel: "Submit",
 	},
 ];
 
+const defaultInstanceForm = {
+	protocol: "http",
+	access: "local",
+	host: "localhost",
+} as const;
+
+const defaultModeForm = {
+	mode: "personal",
+	name: "",
+} as const;
+
+const defaultAdminForm = {
+	displayName: "Admin",
+	email: "admin@example.com",
+	password: "",
+} as const;
+
+const personalStructureDefaults = {
+	departmentName: "Default",
+	teamName: "Personal",
+} as const;
+
+const organizationalStructureDefaults = {
+	departmentName: "Department",
+	teamName: "Team",
+} as const;
+
+const defaultStructureForm = {
+	...personalStructureDefaults,
+	projectName: "Project",
+} as const;
+
+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 sidebarToggleLabel = (): string => (props.sidebarCollapsed ? "Expand left workspace sidebar" : "Collapse left workspace sidebar");
+	const appShellData = useAppShellData();
-	const breadcrumb = (): string => `${activeServer.name} / ${activeProject.name} / Home`;
+	const [instanceForm, setInstanceForm] = createStore({ ...defaultInstanceForm });
+	const [modeForm, setModeForm] = createStore({ ...defaultModeForm });
+	const [adminForm, setAdminForm] = createStore({ ...defaultAdminForm });
+	const [structureForm, setStructureForm] = createStore({ ...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">
+			<main class={styles.viewport} data-ui="workspace-home">
-				<div class={styles.workspaceTopBarStart} data-slot="workspace-home-top-bar-start">
+				<div class={styles.workspaceTopBar} data-slot="workspace-home-top-bar">
-					<button
+					<div class={styles.workspaceTopBarStart} data-slot="workspace-home-top-bar-start">
-						type="button"
+						<button
-						class={styles.workspaceCollapseButton}
+							type="button"
-						aria-label={sidebarToggleLabel()}
+							class={styles.workspaceCollapseButton}
-						title={sidebarToggleLabel()}
+							aria-label={sidebarToggleLabel()}
-						data-slot="workspace-home-sidebar-toggle"
+							title={sidebarToggleLabel()}
-						onClick={props.onToggleSidebarCollapse}
+							data-slot="workspace-home-sidebar-toggle"
-					>
+							onClick={props.onToggleSidebarCollapse}
-						{props.sidebarCollapsed ? <ChevronRight size={16} strokeWidth={2} /> : <ChevronLeft size={16} strokeWidth={2} />}
+						>
-					</button>
+							{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>
 
-				<div class={styles.workspaceTopBarCenter} data-slot="workspace-home-top-bar-center">
+				<section class={styles.hero} data-slot="workspace-home-hero">
-					<span class={styles.workspaceBreadcrumb}>{breadcrumb()}</span>
+					<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>
 
-				<div class={styles.workspaceTopBarEnd} data-slot="workspace-home-top-bar-end" aria-hidden="true" />
+									<form class={styles.form} onSubmit={handleCurrentStepSubmit}>
-			</div>
+										<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)}>
+														<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)}>
+														<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>
 
-			<section class={styles.hero} data-slot="workspace-home-hero">
+						<Show when={currentStep().id === "mode"}>
-				<span class={styles.eyebrow}>Server home</span>
+							<>
-				<h1 class={styles.title}>{activeServer.name} is ready for its first real shell.</h1>
+								<label class={styles.field}>
-				<p class={styles.description}>
+									<span class={styles.fieldLabel}>Mode</span>
-					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.
+									<select value={modeForm.mode} onInput={(event): void => setModeForm("mode", event.currentTarget.value)}>
-				</p>
+										<option value="personal">personal</option>
-			</section>
+										<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>
 
-			<section class={styles.grid} aria-label="Shell checkpoints" data-slot="workspace-home-grid">
+										<Show when={currentStep().id === "admin"}>
-				<For each={shellCheckpointCards}>
+											<>
-					{(card): JSX.Element => (
+												<label class={styles.field}>
-						<article class={styles.card} data-slot="workspace-home-card">
+													<span class={styles.fieldLabel}>Display name</span>
-							<h2 class={styles.cardTitle}>{card.title}</h2>
+											<input
-							<p class={styles.cardCopy}>{card.copy}</p>
+												type="text"
-							<span class={styles.cardMeta}>{card.meta}</span>
+												value={adminForm.displayName}
-						</article>
+												onInput={(event): void => setAdminForm("displayName", event.currentTarget.value)}
-					)}
+												placeholder="Admin"
-				</For>
+											/>
-			</section>
+										</label>
-		</main>
+												<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/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],

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;