Fix: harden bootstrap worker flow

.gitignore

@@ -27,3 +27,5 @@ tmp/
 bin/
 
 .cgcignore
+
+POSIX/

Backend/cmd/posix/main.go

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

Backend/cmd/worker/main.go

@@ -1,10 +1,16 @@
 package main
 
 import (
+	"context"
+	"encoding/json"
 	"log"
+	"os/signal"
+	"syscall"
+	"time"
 
 	"moku-backend/internal/bootstrap"
-	"moku-backend/internal/process"
+	"moku-backend/internal/jobs"
+	"moku-backend/internal/worker"
 )
 
 func main() {
@@ -18,9 +24,25 @@ func main() {
 		}
 	}()
 
-	app.Logger.Info("worker ready", "service", app.ServiceName, "environment", app.Config.Environment)
+	jobStore := jobs.NewStore(app.Database)
+	runner := worker.NewRunner(jobStore, app.Logger, time.Second)
+	runner.Register(jobs.KindBootstrapStructureMaterialize, func(ctx context.Context, job jobs.Job) error {
+		var payload jobs.BootstrapStructureMaterializePayload
+		if len(job.Payload) > 0 {
+			if err := json.Unmarshal(job.Payload, &payload); err != nil {
+				return err
+			}
+		}
 
-	if err := process.WaitForShutdown(app.ServiceName, app.Logger); err != nil {
+		return bootstrap.NewService(app.Database, app.Config.POSIXRoot).ProcessBootstrapStructureMaterialization(ctx, payload.InstallationID)
+	})
+
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	app.Logger.Info("worker ready", "service", app.ServiceName, "environment", app.Config.Environment, "pollInterval", time.Second)
+
+	if err := runner.Run(ctx); err != nil {
 		app.Logger.Error("worker stopped", "error", err)
 		log.Fatal(err)
 	}

Backend/db/migrations/000003_installation_name.sql

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

Backend/db/migrations/000004_posix_nodes.sql

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

Backend/db/migrations/000005_background_jobs.sql

@@ -0,0 +1,64 @@
+-- +goose Up
+
+CREATE TYPE bootstrap_materialization_status AS ENUM ('not_started', 'pending', 'running', 'succeeded', 'failed');
+CREATE TYPE background_job_status AS ENUM ('pending', 'running', 'succeeded', 'failed');
+
+ALTER TABLE installations
+  ADD COLUMN IF NOT EXISTS materialization_status bootstrap_materialization_status NOT NULL DEFAULT 'not_started',
+  ADD COLUMN IF NOT EXISTS materialization_error TEXT,
+  ADD COLUMN IF NOT EXISTS materialization_requested_at TIMESTAMPTZ,
+  ADD COLUMN IF NOT EXISTS materialization_started_at TIMESTAMPTZ,
+  ADD COLUMN IF NOT EXISTS materialization_finished_at TIMESTAMPTZ;
+
+UPDATE installations
+SET
+  materialization_status = CASE
+    WHEN is_bootstrapped THEN 'succeeded'::bootstrap_materialization_status
+    ELSE 'not_started'::bootstrap_materialization_status
+  END,
+  materialization_error = NULL,
+  materialization_requested_at = CASE
+    WHEN is_bootstrapped THEN COALESCE(bootstrapped_at, created_at, NOW())
+    ELSE NULL
+  END,
+  materialization_started_at = CASE
+    WHEN is_bootstrapped THEN COALESCE(bootstrapped_at, created_at, NOW())
+    ELSE NULL
+  END,
+  materialization_finished_at = CASE
+    WHEN is_bootstrapped THEN COALESCE(bootstrapped_at, created_at, NOW())
+    ELSE NULL
+  END
+WHERE materialization_status = 'not_started'::bootstrap_materialization_status;
+
+CREATE TABLE IF NOT EXISTS background_jobs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  kind TEXT NOT NULL,
+  status background_job_status NOT NULL DEFAULT 'pending',
+  payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  max_attempts INTEGER NOT NULL DEFAULT 1,
+  available_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  started_at TIMESTAMPTZ,
+  finished_at TIMESTAMPTZ,
+  last_error TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_background_jobs_claim ON background_jobs (status, available_at, created_at);
+
+-- +goose Down
+
+DROP INDEX IF EXISTS idx_background_jobs_claim;
+DROP TABLE IF EXISTS background_jobs;
+
+ALTER TABLE installations
+  DROP COLUMN IF EXISTS materialization_finished_at,
+  DROP COLUMN IF EXISTS materialization_started_at,
+  DROP COLUMN IF EXISTS materialization_requested_at,
+  DROP COLUMN IF EXISTS materialization_error,
+  DROP COLUMN IF EXISTS materialization_status;
+
+DROP TYPE IF EXISTS background_job_status;
+DROP TYPE IF EXISTS bootstrap_materialization_status;

Backend/internal/bootstrap/bootstrap_installation.go

@@ -0,0 +1,159 @@
+package bootstrap
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"github.com/jackc/pgx/v5"
+)
+
+const (
+	materializationNotStarted = "not_started"
+	materializationPending    = "pending"
+	materializationRunning    = "running"
+	materializationSucceeded  = "succeeded"
+	materializationFailed     = "failed"
+)
+
+type bootstrapStructurePrerequisites struct {
+	installation InstallationRecord
+	admin        AdminSummary
+}
+
+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,
+			materialization_status::text,
+			materialization_error
+		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 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,
+			materialization_status::text,
+			materialization_error
+		FROM installations
+		WHERE singleton = TRUE
+		LIMIT 1;
+	`))
+}
+
+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()),
+			materialization_status = 'pending'::bootstrap_materialization_status,
+			materialization_error = NULL,
+			materialization_requested_at = NOW(),
+			materialization_started_at = NULL,
+			materialization_finished_at = NULL,
+			updated_at = NOW()
+		WHERE singleton = TRUE
+		RETURNING
+			id::text,
+			name,
+			mode::text,
+			access::text,
+			protocol::text,
+			host,
+			is_bootstrapped,
+			materialization_status::text,
+			materialization_error;
+	`))
+}
+
+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,
+		&record.MaterializationStatus,
+		&record.MaterializationError,
+	); err != nil {
+		return InstallationRecord{}, err
+	}
+
+	if strings.TrimSpace(record.MaterializationStatus) == "" {
+		record.MaterializationStatus = materializationNotStarted
+	}
+
+	return record, nil
+}
+
+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 (service *Service) loadBootstrapStructurePrerequisites(
+	ctx context.Context,
+	tx pgx.Tx,
+) (bootstrapStructurePrerequisites, error) {
+	installation, err := loadInstallation(ctx, tx)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return bootstrapStructurePrerequisites{}, ErrInstallationNotConfigured
+		}
+
+		return bootstrapStructurePrerequisites{}, err
+	}
+
+	admin, err := loadPrimaryAdmin(ctx, tx)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return bootstrapStructurePrerequisites{}, ErrAdminNotConfigured
+		}
+
+		return bootstrapStructurePrerequisites{}, err
+	}
+
+	return bootstrapStructurePrerequisites{
+		installation: installation,
+		admin:        admin,
+	}, nil
+}

Backend/internal/bootstrap/bootstrap_materialization.go

@@ -0,0 +1,180 @@
+package bootstrap
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"moku-backend/internal/jobs"
+	"moku-backend/internal/posixproj"
+)
+
+func (service *Service) enqueueBootstrapStructureMaterialization(
+	ctx context.Context,
+	installation *InstallationRecord,
+) error {
+	if installation == nil {
+		return nil
+	}
+
+	jobStore := jobs.NewStore(service.db)
+	if _, err := jobStore.Enqueue(ctx, jobs.EnqueueInput{
+		Kind: jobs.KindBootstrapStructureMaterialize,
+		Payload: jobs.BootstrapStructureMaterializePayload{
+			InstallationID: installation.ID,
+		},
+	}); err != nil {
+		failure := fmt.Sprintf("enqueue bootstrap materialization job: %v", err)
+		if markErr := service.markBootstrapMaterializationFailed(ctx, installation.ID, failure); markErr != nil {
+			return errors.Join(err, markErr)
+		}
+
+		// The relational bootstrap write already committed successfully, so keep the
+		// response successful and surface the enqueue problem via materialization state.
+		installation.MaterializationStatus = materializationFailed
+		installation.MaterializationError = &failure
+	}
+
+	return nil
+}
+
+func (service *Service) ProcessBootstrapStructureMaterialization(ctx context.Context, installationID string) error {
+	trimmedInstallationID := strings.TrimSpace(installationID)
+	if trimmedInstallationID == "" {
+		return ErrInstallationNotConfigured
+	}
+
+	installation, err := service.GetInstallation(ctx)
+	if err != nil {
+		return err
+	}
+	if installation == nil || installation.ID != trimmedInstallationID {
+		return ErrInstallationNotConfigured
+	}
+
+	if err := service.markBootstrapMaterializationRunning(ctx, trimmedInstallationID); err != nil {
+		return err
+	}
+
+	if err := service.materializeBootstrapStructure(ctx, *installation); err != nil {
+		failure := strings.TrimSpace(err.Error())
+		if failure == "" {
+			failure = "bootstrap materialization failed"
+		}
+
+		if markErr := service.markBootstrapMaterializationFailed(ctx, trimmedInstallationID, failure); markErr != nil {
+			return errors.Join(err, markErr)
+		}
+
+		return err
+	}
+
+	return service.markBootstrapMaterializationSucceeded(ctx, trimmedInstallationID)
+}
+
+func (service *Service) materializeBootstrapStructure(ctx context.Context, installation InstallationRecord) error {
+	admin, err := service.GetAdmin(ctx)
+	if err != nil {
+		return err
+	}
+	if admin == nil {
+		return ErrAdminNotConfigured
+	}
+
+	organization, err := service.loadPrimaryOrganization(ctx)
+	if err != nil {
+		return err
+	}
+	if organization == nil {
+		return ErrBootstrapStructureMissing
+	}
+
+	department, err := service.loadPrimaryDepartment(ctx)
+	if err != nil {
+		return err
+	}
+	if department == nil {
+		return ErrBootstrapStructureMissing
+	}
+
+	team, err := service.loadPrimaryTeam(ctx)
+	if err != nil {
+		return err
+	}
+	if team == nil {
+		return ErrBootstrapStructureMissing
+	}
+
+	project, err := service.loadPrimaryProject(ctx)
+	if err != nil {
+		return err
+	}
+	if project == nil {
+		return ErrBootstrapStructureMissing
+	}
+
+	if err := service.ensureBootstrapPOSIXSkeleton(
+		installation,
+		AdminSummary{ID: admin.ID, Email: admin.Email, DisplayName: admin.DisplayName},
+		namedRecord{ID: organization.ID, Name: organization.Name, Slug: organization.Slug},
+		namedRecord{ID: department.ID, Name: department.Name, Slug: department.Slug},
+		namedRecord{ID: team.ID, Name: team.Name, Slug: team.Slug},
+		namedRecord{ID: project.ID, Name: project.Name, Slug: project.Slug},
+	); err != nil {
+		return err
+	}
+
+	return service.rebuildProjection(ctx)
+}
+
+func (service *Service) rebuildProjection(ctx context.Context) error {
+	if err := posixproj.NewProjector(service.db, service.posixRoot).Rebuild(ctx); err != nil {
+		return fmt.Errorf("rebuild POSIX projection: %w", err)
+	}
+
+	return nil
+}
+
+func (service *Service) markBootstrapMaterializationRunning(ctx context.Context, installationID string) error {
+	_, err := service.db.Pool.Exec(ctx, `
+		UPDATE installations
+		SET
+			materialization_status = 'running'::bootstrap_materialization_status,
+			materialization_error = NULL,
+			materialization_started_at = NOW(),
+			materialization_finished_at = NULL,
+			updated_at = NOW()
+		WHERE id = $1::uuid;
+	`, strings.TrimSpace(installationID))
+
+	return err
+}
+
+func (service *Service) markBootstrapMaterializationSucceeded(ctx context.Context, installationID string) error {
+	_, err := service.db.Pool.Exec(ctx, `
+		UPDATE installations
+		SET
+			materialization_status = 'succeeded'::bootstrap_materialization_status,
+			materialization_error = NULL,
+			materialization_finished_at = NOW(),
+			updated_at = NOW()
+		WHERE id = $1::uuid;
+	`, strings.TrimSpace(installationID))
+
+	return err
+}
+
+func (service *Service) markBootstrapMaterializationFailed(ctx context.Context, installationID, failure string) error {
+	_, err := service.db.Pool.Exec(ctx, `
+		UPDATE installations
+		SET
+			materialization_status = 'failed'::bootstrap_materialization_status,
+			materialization_error = $2,
+			materialization_finished_at = NOW(),
+			updated_at = NOW()
+		WHERE id = $1::uuid;
+	`, strings.TrimSpace(installationID), strings.TrimSpace(failure))
+
+	return err
+}

Backend/internal/bootstrap/bootstrap_state.go

@@ -0,0 +1,73 @@
+package bootstrap
+
+import "context"
+
+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
+}

Backend/internal/bootstrap/service_test.go

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

Backend/internal/config/config.go

@@ -17,6 +17,7 @@ type Config struct {
 	APIPort         string
 	PostgresURL     string
 	ValkeyURL       string
+	POSIXRoot       string
 	ShutdownTimeout time.Duration
 }
 
@@ -29,6 +30,7 @@ func Load() *Config {
 		APIPort:         getEnv("BACKEND_API_PORT", "8081"),
 		PostgresURL:     getEnv("DATABASE_URL", "postgres://moku:moku_dev_password@localhost:5432/moku?sslmode=disable"),
 		ValkeyURL:       getEnv("VALKEY_URL", "redis://localhost:6379/0"),
+		POSIXRoot:       getEnv("POSIX_ROOT", "../POSIX"),
 		ShutdownTimeout: getDurationEnv("BACKEND_SHUTDOWN_TIMEOUT", 10*time.Second),
 	}
 }

Backend/internal/httpx/api_bootstrap_routes.go

@@ -20,6 +20,7 @@ type bootstrapInstanceStepRequest struct {
 
 type bootstrapModeStepRequest struct {
 	Mode string `json:"mode"`
+	Name string `json:"name"`
 }
 
 type bootstrapAdminStepRequest struct {
@@ -234,13 +235,19 @@ func (routes apiRoutes) handleBootstrapModeStep(w http.ResponseWriter, r *http.R
 		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
 	}
 
-	record, err := routes.bootstrapService().SaveMode(r.Context(), bootstrapservice.SaveModeInput{Mode: payload.Mode})
+	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
@@ -334,7 +341,7 @@ func (routes apiRoutes) handleBootstrapStructureStep(w http.ResponseWriter, r *h
 }
 
 func (routes apiRoutes) bootstrapService() *bootstrapservice.Service {
-	return bootstrapservice.NewService(routes.cfg.Database)
+	return bootstrapservice.NewService(routes.cfg.Database, routes.cfg.Config.POSIXRoot)
 }
 
 func (routes apiRoutes) writeBootstrapStepResponse(w http.ResponseWriter, status int, step string, payload any) {
@@ -356,7 +363,11 @@ func (routes apiRoutes) writeBootstrapPersistenceError(w http.ResponseWriter, r
 		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)
-		WriteError(w, http.StatusInternalServerError, RequestIDFromContext(r.Context()), "bootstrap_persist_failed", "Failed to persist bootstrap data.")
+		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)
 	}
 }
 

Backend/internal/httpx/api_project_routes.go

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

Backend/internal/httpx/api_routes.go

@@ -33,6 +33,18 @@ func (routes apiRoutes) Register(router chi.Router) {
 		apiRouter.Get("/app-shell", routes.handleAppShellState)
 		apiRouter.Get("/organizations", routes.handleOrganizations)
 		apiRouter.Get("/workspaces", routes.handleWorkspaces)
+		apiRouter.Route("/projects/{projectId}", func(projectRouter chi.Router) {
+			projectRouter.Get("/folders", routes.handleProjectFolders)
+			projectRouter.Post("/folders", routes.handleCreateProjectFolder)
+			projectRouter.Patch("/folders", routes.handleRenameProjectFolder)
+			projectRouter.Patch("/folders/move", routes.handleMoveProjectFolder)
+			projectRouter.Delete("/folders", routes.handleDeleteProjectFolder)
+			projectRouter.Get("/tree/folders", routes.handleProjectTreeFolders)
+			projectRouter.Post("/tree/folders", routes.handleCreateProjectTreeFolder)
+			projectRouter.Patch("/tree/folders", routes.handleRenameProjectTreeFolder)
+			projectRouter.Patch("/tree/folders/move", routes.handleMoveProjectTreeFolder)
+			projectRouter.Delete("/tree/folders", routes.handleDeleteProjectTreeFolder)
+		})
 
 		if routes.cfg.Config.IsDevelopment() {
 			apiRouter.Post("/dev/bootstrap/reset", routes.handleDevelopmentBootstrapReset)

Backend/internal/jobs/store.go

@@ -0,0 +1,196 @@
+package jobs
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+
+	"moku-backend/internal/database"
+)
+
+const (
+	KindBootstrapStructureMaterialize = "bootstrap.structure.materialize"
+)
+
+type Status string
+
+const (
+	StatusPending   Status = "pending"
+	StatusRunning   Status = "running"
+	StatusSucceeded Status = "succeeded"
+	StatusFailed    Status = "failed"
+)
+
+type BootstrapStructureMaterializePayload struct {
+	InstallationID string `json:"installationId"`
+}
+
+type Job struct {
+	ID          string
+	Kind        string
+	Status      Status
+	Payload     json.RawMessage
+	Attempts    int
+	MaxAttempts int
+	AvailableAt time.Time
+	StartedAt   *time.Time
+	FinishedAt  *time.Time
+	LastError   *string
+	CreatedAt   time.Time
+	UpdatedAt   time.Time
+}
+
+type EnqueueInput struct {
+	Kind        string
+	Payload     any
+	AvailableAt time.Time
+	MaxAttempts int
+}
+
+type Store struct {
+	db *database.DB
+}
+
+func NewStore(db *database.DB) *Store {
+	return &Store{db: db}
+}
+
+func (store *Store) Enqueue(ctx context.Context, input EnqueueInput) (Job, error) {
+	payload := json.RawMessage([]byte(`{}`))
+	if input.Payload != nil {
+		encoded, err := json.Marshal(input.Payload)
+		if err != nil {
+			return Job{}, err
+		}
+		payload = encoded
+	}
+
+	availableAt := input.AvailableAt
+	if availableAt.IsZero() {
+		availableAt = time.Now().UTC()
+	}
+
+	maxAttempts := input.MaxAttempts
+	if maxAttempts < 1 {
+		maxAttempts = 1
+	}
+
+	return scanJob(store.db.Pool.QueryRow(ctx, `
+		INSERT INTO background_jobs (kind, status, payload, attempts, max_attempts, available_at)
+		VALUES ($1, 'pending'::background_job_status, $2::jsonb, 0, $3, $4)
+		RETURNING
+			id::text,
+			kind,
+			status::text,
+			payload,
+			attempts,
+			max_attempts,
+			available_at,
+			started_at,
+			finished_at,
+			last_error,
+			created_at,
+			updated_at;
+	`, strings.TrimSpace(input.Kind), payload, maxAttempts, availableAt))
+}
+
+func (store *Store) ClaimNext(ctx context.Context) (*Job, error) {
+	job, err := scanJob(store.db.Pool.QueryRow(ctx, `
+		WITH next_job AS (
+			SELECT id
+			FROM background_jobs
+			WHERE status = 'pending'::background_job_status
+				AND available_at <= NOW()
+			ORDER BY created_at ASC
+			LIMIT 1
+			FOR UPDATE SKIP LOCKED
+		)
+		UPDATE background_jobs AS jobs
+		SET
+			status = 'running'::background_job_status,
+			attempts = jobs.attempts + 1,
+			started_at = NOW(),
+			finished_at = NULL,
+			last_error = NULL,
+			updated_at = NOW()
+		FROM next_job
+		WHERE jobs.id = next_job.id
+		RETURNING
+			jobs.id::text,
+			jobs.kind,
+			jobs.status::text,
+			jobs.payload,
+			jobs.attempts,
+			jobs.max_attempts,
+			jobs.available_at,
+			jobs.started_at,
+			jobs.finished_at,
+			jobs.last_error,
+			jobs.created_at,
+			jobs.updated_at;
+	`))
+	if err != nil {
+		if err == pgx.ErrNoRows {
+			return nil, nil
+		}
+
+		return nil, err
+	}
+
+	return &job, nil
+}
+
+func (store *Store) MarkSucceeded(ctx context.Context, jobID string) error {
+	_, err := store.db.Pool.Exec(ctx, `
+		UPDATE background_jobs
+		SET
+			status = 'succeeded'::background_job_status,
+			finished_at = NOW(),
+			last_error = NULL,
+			updated_at = NOW()
+		WHERE id = $1::uuid;
+	`, strings.TrimSpace(jobID))
+
+	return err
+}
+
+func (store *Store) MarkFailed(ctx context.Context, jobID, failure string) error {
+	_, err := store.db.Pool.Exec(ctx, `
+		UPDATE background_jobs
+		SET
+			status = 'failed'::background_job_status,
+			finished_at = NOW(),
+			last_error = $2,
+			updated_at = NOW()
+		WHERE id = $1::uuid;
+	`, strings.TrimSpace(jobID), strings.TrimSpace(failure))
+
+	return err
+}
+
+func scanJob(row pgx.Row) (Job, error) {
+	var job Job
+	var status string
+	if err := row.Scan(
+		&job.ID,
+		&job.Kind,
+		&status,
+		&job.Payload,
+		&job.Attempts,
+		&job.MaxAttempts,
+		&job.AvailableAt,
+		&job.StartedAt,
+		&job.FinishedAt,
+		&job.LastError,
+		&job.CreatedAt,
+		&job.UpdatedAt,
+	); err != nil {
+		return Job{}, err
+	}
+
+	job.Status = Status(status)
+	return job, nil
+}

Backend/internal/posixproj/projector.go

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

Backend/internal/posixproj/projector_test.go

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

Backend/internal/worker/runner.go

@@ -0,0 +1,124 @@
+package worker
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"strings"
+	"time"
+
+	"moku-backend/internal/jobs"
+)
+
+type JobStore interface {
+	ClaimNext(ctx context.Context) (*jobs.Job, error)
+	MarkSucceeded(ctx context.Context, jobID string) error
+	MarkFailed(ctx context.Context, jobID, failure string) error
+}
+
+type Handler func(ctx context.Context, job jobs.Job) error
+
+type Runner struct {
+	store        JobStore
+	logger       *slog.Logger
+	pollInterval time.Duration
+	handlers     map[string]Handler
+}
+
+func NewRunner(store JobStore, logger *slog.Logger, pollInterval time.Duration) *Runner {
+	interval := pollInterval
+	if interval <= 0 {
+		interval = time.Second
+	}
+
+	return &Runner{
+		store:        store,
+		logger:       logger,
+		pollInterval: interval,
+		handlers:     make(map[string]Handler),
+	}
+}
+
+func (runner *Runner) Register(kind string, handler Handler) {
+	runner.handlers[strings.TrimSpace(kind)] = handler
+}
+
+func (runner *Runner) Run(ctx context.Context) error {
+	for {
+		select {
+		case <-ctx.Done():
+			return nil
+		default:
+		}
+
+		job, err := runner.store.ClaimNext(ctx)
+		if err != nil {
+			if ctx.Err() != nil {
+				return nil
+			}
+
+			runner.logger.Error("worker claim failed", "error", err)
+
+			if err := waitForNextPoll(ctx, runner.pollInterval); err != nil {
+				return nil
+			}
+
+			continue
+		}
+
+		if job == nil {
+			if err := waitForNextPoll(ctx, runner.pollInterval); err != nil {
+				return nil
+			}
+
+			continue
+		}
+
+		handler, ok := runner.handlers[job.Kind]
+		if !ok {
+			failure := fmt.Sprintf("no handler registered for job kind %q", job.Kind)
+			if err := runner.store.MarkFailed(ctx, job.ID, failure); err != nil {
+				return err
+			}
+
+			runner.logger.Error("worker job failed", "jobID", job.ID, "kind", job.Kind, "error", failure)
+			continue
+		}
+
+		if err := handler(ctx, *job); err != nil {
+			if ctx.Err() != nil {
+				return nil
+			}
+
+			failure := strings.TrimSpace(err.Error())
+			if failure == "" {
+				failure = "job handler returned an empty error"
+			}
+
+			if markErr := runner.store.MarkFailed(ctx, job.ID, failure); markErr != nil {
+				return markErr
+			}
+
+			runner.logger.Error("worker job failed", "jobID", job.ID, "kind", job.Kind, "error", failure)
+			continue
+		}
+
+		if err := runner.store.MarkSucceeded(ctx, job.ID); err != nil {
+			return err
+		}
+
+		runner.logger.Info("worker job succeeded", "jobID", job.ID, "kind", job.Kind)
+	}
+}
+
+func waitForNextPoll(ctx context.Context, interval time.Duration) error {
+	timer := time.NewTimer(interval)
+	defer timer.Stop()
+
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}

Backend/internal/worker/runner_test.go

@@ -0,0 +1,209 @@
+package worker
+
+import (
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"moku-backend/internal/jobs"
+)
+
+func TestRunnerProcessesRegisteredJob(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	store := &fakeJobStore{
+		job: &jobs.Job{
+			ID:      "job-1",
+			Kind:    jobs.KindBootstrapStructureMaterialize,
+			Payload: []byte(`{"installationId":"installation-1"}`),
+		},
+		cancel: cancel,
+	}
+	runner := NewRunner(store, slog.New(slog.NewTextHandler(io.Discard, nil)), 0)
+
+	handlerCalled := false
+	runner.Register(jobs.KindBootstrapStructureMaterialize, func(ctx context.Context, job jobs.Job) error {
+		handlerCalled = true
+		if job.ID != "job-1" {
+			t.Fatalf("expected job id job-1, got %s", job.ID)
+		}
+		return nil
+	})
+
+	if err := runner.Run(ctx); err != nil {
+		t.Fatalf("runner returned error: %v", err)
+	}
+
+	if !handlerCalled {
+		t.Fatal("expected handler to be called")
+	}
+	if len(store.succeeded) != 1 || store.succeeded[0] != "job-1" {
+		t.Fatalf("expected job to be marked succeeded once, got %#v", store.succeeded)
+	}
+	if len(store.failed) != 0 {
+		t.Fatalf("expected no failed jobs, got %#v", store.failed)
+	}
+}
+
+func TestRunnerMarksFailedWhenHandlerErrors(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	store := &fakeJobStore{
+		job: &jobs.Job{
+			ID:   "job-2",
+			Kind: jobs.KindBootstrapStructureMaterialize,
+		},
+		cancel: cancel,
+	}
+	runner := NewRunner(store, slog.New(slog.NewTextHandler(io.Discard, nil)), 0)
+	runner.Register(jobs.KindBootstrapStructureMaterialize, func(ctx context.Context, job jobs.Job) error {
+		return errors.New("boom")
+	})
+
+	if err := runner.Run(ctx); err != nil {
+		t.Fatalf("runner returned error: %v", err)
+	}
+
+	if len(store.succeeded) != 0 {
+		t.Fatalf("expected no succeeded jobs, got %#v", store.succeeded)
+	}
+	if len(store.failed) != 1 {
+		t.Fatalf("expected one failed job, got %#v", store.failed)
+	}
+	if store.failed[0].jobID != "job-2" {
+		t.Fatalf("expected failed job id job-2, got %#v", store.failed[0])
+	}
+	if !strings.Contains(store.failed[0].failure, "boom") {
+		t.Fatalf("expected failure to mention handler error, got %#v", store.failed[0])
+	}
+}
+
+func TestRunnerMarksFailedWhenHandlerMissing(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	store := &fakeJobStore{
+		job: &jobs.Job{
+			ID:   "job-3",
+			Kind: "unknown.kind",
+		},
+		cancel: cancel,
+	}
+	runner := NewRunner(store, slog.New(slog.NewTextHandler(io.Discard, nil)), 0)
+
+	if err := runner.Run(ctx); err != nil {
+		t.Fatalf("runner returned error: %v", err)
+	}
+
+	if len(store.failed) != 1 {
+		t.Fatalf("expected one failed job, got %#v", store.failed)
+	}
+	if !strings.Contains(store.failed[0].failure, "no handler registered") {
+		t.Fatalf("expected missing handler failure, got %#v", store.failed[0])
+	}
+}
+
+func TestRunnerRetriesClaimErrors(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	store := &fakeJobStore{
+		claimErrors: []error{errors.New("relation \"background_jobs\" does not exist")},
+		job: &jobs.Job{
+			ID:   "job-4",
+			Kind: jobs.KindBootstrapStructureMaterialize,
+		},
+		cancel: cancel,
+	}
+	runner := NewRunner(store, slog.New(slog.NewTextHandler(io.Discard, nil)), time.Millisecond)
+
+	handlerCalled := false
+	runner.Register(jobs.KindBootstrapStructureMaterialize, func(ctx context.Context, job jobs.Job) error {
+		handlerCalled = true
+		return nil
+	})
+
+	if err := runner.Run(ctx); err != nil {
+		t.Fatalf("runner returned error: %v", err)
+	}
+
+	if !handlerCalled {
+		t.Fatal("expected handler to be called after claim retry")
+	}
+	if store.claimAttempts < 2 {
+		t.Fatalf("expected at least two claim attempts, got %d", store.claimAttempts)
+	}
+	if len(store.succeeded) != 1 || store.succeeded[0] != "job-4" {
+		t.Fatalf("expected job to be marked succeeded once, got %#v", store.succeeded)
+	}
+	if len(store.failed) != 0 {
+		t.Fatalf("expected no failed jobs, got %#v", store.failed)
+	}
+}
+
+type fakeJobStore struct {
+	mu            sync.Mutex
+	job           *jobs.Job
+	claimed       bool
+	claimErrors   []error
+	claimAttempts int
+	succeeded     []string
+	failed        []fakeFailure
+	cancel        context.CancelFunc
+}
+
+type fakeFailure struct {
+	jobID   string
+	failure string
+}
+
+func (store *fakeJobStore) ClaimNext(ctx context.Context) (*jobs.Job, error) {
+	store.mu.Lock()
+	defer store.mu.Unlock()
+	store.claimAttempts++
+
+	if len(store.claimErrors) > 0 {
+		err := store.claimErrors[0]
+		store.claimErrors = store.claimErrors[1:]
+		return nil, err
+	}
+
+	if store.claimed || store.job == nil {
+		return nil, nil
+	}
+
+	store.claimed = true
+	job := *store.job
+	return &job, nil
+}
+
+func (store *fakeJobStore) MarkSucceeded(ctx context.Context, jobID string) error {
+	store.mu.Lock()
+	store.succeeded = append(store.succeeded, jobID)
+	store.mu.Unlock()
+
+	if store.cancel != nil {
+		store.cancel()
+	}
+
+	return nil
+}
+
+func (store *fakeJobStore) MarkFailed(ctx context.Context, jobID, failure string) error {
+	store.mu.Lock()
+	store.failed = append(store.failed, fakeFailure{jobID: jobID, failure: failure})
+	store.mu.Unlock()
+
+	if store.cancel != nil {
+		store.cancel()
+	}
+
+	return nil
+}

Commands/Local/Dev/backend.just

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

Commands/Test/backend.just

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

Commands/Test/mod.just

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

Docker/docker-compose.local.dev.yaml

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

Docker/docker-compose.local.prod.yaml

@@ -5,11 +5,14 @@ x-backend-service: &backend-service
   environment:
     DATABASE_URL: postgres://moku:moku_dev_password@postgres:5432/moku?sslmode=disable
     VALKEY_URL: redis://valkey:6379/0
+    POSIX_ROOT: /posix
   depends_on:
     postgres:
       condition: service_healthy
     valkey:
       condition: service_healthy
+  volumes:
+    - ../POSIX:/posix
 
 services:
   postgres:

Documentation/POSIX-Structure.md

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

Documentation/TODO.md

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

Env/.env.example

@@ -10,6 +10,7 @@ BACKEND_SHUTDOWN_TIMEOUT=10s
 
 DATABASE_URL=postgres://moku:moku_dev_password@localhost:5432/moku?sslmode=disable
 VALKEY_URL=redis://localhost:6379/0
+POSIX_ROOT=../POSIX
 
 VITE_API_BASE_URL=/v1
 

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

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

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

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

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

@@ -1,3 +1,5 @@
+@use "../shared/tree-nav" as treeNav;
+
 .root {
   display: grid;
   --project-drawer-gap: var(--space-3);
@@ -9,6 +11,15 @@
   justify-items: center;
 }
 
+.rootDragMode {
+	user-select: none;
+	cursor: grabbing;
+}
+
+.rootDragMode .treeItem {
+	cursor: grabbing;
+}
+
 .trigger {
   width: 100%;
   min-width: 0;
@@ -38,9 +49,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 +94,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 +181,7 @@
   min-height: 0;
   display: grid;
   align-content: start;
-  gap: var(--space-3);
+  gap: var(--space-2);
   padding: var(--space-4);
   overflow-y: auto;
   overscroll-behavior: contain;
@@ -186,49 +192,132 @@
 	width: 0;
 }
 
-.projectList {
+.treeSectionLabel {
-  list-style: none;
+	@include treeNav.section-label;
-  display: grid;
+  margin: 0;
-  gap: 0.2rem;
+  padding: 0 var(--space-3);
-  padding: 0;
 }
 
-.projectItem {
+.treeSectionHeader {
-  width: 100%;
+	display: flex;
-  min-width: 0;
+	align-items: center;
-  min-height: calc(var(--control-size-md) + var(--space-2));
+	justify-content: space-between;
-  padding: var(--space-2) var(--space-3);
+	gap: var(--space-2);
-  border: 1px solid transparent;
+	margin-bottom: var(--space-2);
-  border-radius: var(--radius-sm);
+	padding-right: var(--space-1);
-  background: transparent;
+}
+
+.treeControls {
+	display: inline-flex;
+	align-items: center;
+	gap: var(--space-1);
+	flex-wrap: wrap;
+	justify-content: flex-end;
+}
+
+.treeControlButton {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	width: calc(var(--control-size-md) - var(--space-1));
+	height: calc(var(--control-size-md) - var(--space-1));
+	@include text-caption;
+	padding: 0;
+	border: 1px solid color-mix(in srgb, var(--color-border) 46%, transparent);
+	border-radius: var(--radius-pill);
+	background: color-mix(in srgb, var(--color-surface) 95%, transparent);
 	color: var(--color-text-muted);
 	transition:
-    background 160ms var(--easing-standard),
-    color 160ms var(--easing-standard),
 		border-color 160ms var(--easing-standard),
-    transform 180ms var(--easing-standard);
+		background 160ms var(--easing-standard),
-  text-align: left;
+		color 160ms var(--easing-standard);
 }
 
-.projectItem:hover {
+.treeControlButton:hover,
-  background: color-mix(in srgb, var(--color-surface-hover) 82%, transparent);
+.treeControlButton:focus-visible {
+	border-color: color-mix(in srgb, var(--color-border-strong) 56%, transparent);
+	background: var(--color-surface-hover);
 	color: var(--color-text);
-  border-color: color-mix(in srgb, var(--color-border) 22%, transparent);
+	outline: none;
 }
 
-.projectItemActive {
+.treeControlButton:disabled {
-  border-color: color-mix(in srgb, var(--color-border) 28%, transparent);
+	opacity: 0.45;
-  background: color-mix(in srgb, var(--color-surface) 82%, transparent);
+	cursor: default;
-  color: var(--color-text);
-  box-shadow: none;
 }
 
-.projectItemCopy {
+.treeList {
-  min-width: 0;
+	@include treeNav.tree-list;
-  display: grid;
-  gap: 0.05rem;
 }
 
-.projectItemDescription {
+.treeEmptySlot {
-  color: color-mix(in srgb, var(--color-text-muted) 84%, transparent);
+	@include treeNav.empty-slot;
+}
+
+.treeInputRow {
+	@include treeNav.input-row;
+}
+
+.treeInput {
+	@include treeNav.input;
+}
+
+.treeItem {
+	@include treeNav.item;
+}
+
+.treeItem:hover,
+.treeItem:focus-visible {
+	@include treeNav.item-hover;
+}
+
+.treeItemFolder {
+	@include treeNav.item-folder;
+}
+
+.treeItemDragging {
+	@include treeNav.item-dragging;
+}
+
+.treeItemDropBefore {
+	@include treeNav.item-drop-before;
+}
+
+.treeItemDropAfter {
+	@include treeNav.item-drop-after;
+}
+
+.treeItemDropInside {
+	@include treeNav.item-drop-inside;
+}
+
+.folderChevron {
+	@include treeNav.folder-chevron;
+}
+
+.folderChevronOpen {
+	@include treeNav.folder-chevron-open;
+}
+
+.treeItemActive {
+	@include treeNav.item-active;
+}
+
+.icon {
+	@include treeNav.icon;
+}
+
+.label {
+	@include treeNav.label;
+}
+
+.itemMeta {
+	@include treeNav.item-meta;
+}
+
+@media (max-width: 720px) {
+  .rootCompact .scrim,
+  .rootCompact .drawer {
+    width: min(18rem, calc(100vw - 5rem));
+  }
 }

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

@@ -1,3 +1,5 @@
+@use "../shared/tree-nav" as treeNav;
+
 .sidebar {
   --sidebar-nav-item-min-height: var(--control-size-lg);
   position: relative;
@@ -12,6 +14,15 @@
   isolation: isolate;
 }
 
+.sidebarDragMode {
+	user-select: none;
+	cursor: grabbing;
+}
+
+.sidebarDragMode .treeItem {
+	cursor: grabbing;
+}
+
 .header {
   display: grid;
   gap: var(--space-3);
@@ -108,19 +119,25 @@
 }
 
 .treeSectionLabel {
-  @include text-caption;
+	@include treeNav.section-label;
   margin: var(--space-3) 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;
+	@include treeNav.tree-list;
-  display: grid;
+}
-  gap: var(--space-1);
+
-  padding: 0;
+.treeEmptySlot {
+	@include treeNav.empty-slot;
+}
+
+.treeInputRow {
+	@include treeNav.input-row;
+}
+
+.treeInput {
+	@include treeNav.input;
 }
 
 .navItem {
@@ -138,42 +155,44 @@
 }
 
 .treeItem {
-  width: 100%;
+	@include treeNav.item;
-  min-width: 0;
-  display: grid;
-  grid-template-columns: 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-lg);
-  background: transparent;
-  color: var(--color-text-muted);
-  text-align: left;
-  transition:
-    background 160ms var(--easing-standard),
-    color 160ms var(--easing-standard),
-    border-color 160ms var(--easing-standard),
-    transform 180ms var(--easing-standard);
 }
 
 .treeItem:hover,
 .treeItem:focus-visible {
-  background: var(--color-surface-hover);
+	@include treeNav.item-hover;
-  color: var(--color-text);
 }
 
 .treeItemFolder {
-  color: var(--color-text);
+	@include treeNav.item-folder;
+}
+
+.treeItemDragging {
+	@include treeNav.item-dragging;
+}
+
+.treeItemDropBefore {
+	@include treeNav.item-drop-before;
+}
+
+.treeItemDropAfter {
+	@include treeNav.item-drop-after;
+}
+
+.treeItemDropInside {
+	@include treeNav.item-drop-inside;
+}
+
+.folderChevron {
+	@include treeNav.folder-chevron;
+}
+
+.folderChevronOpen {
+	@include treeNav.folder-chevron-open;
 }
 
 .treeItemActive {
-  border-color: var(--color-border);
+	@include treeNav.item-active;
-  background: var(--color-surface);
-  color: var(--color-text);
-  box-shadow: inset 0 1px 0 color-mix(in srgb, white 4%, transparent);
 }
 
 .navItemActive {
@@ -184,18 +203,15 @@
 }
 
 .icon {
-  color: inherit;
+	@include treeNav.icon;
-  opacity: 0.85;
 }
 
 .label {
-  @include text-label;
+	@include treeNav.label;
-  min-width: 0;
 }
 
 .itemMeta {
-  @include text-caption;
+	@include treeNav.item-meta;
-  color: var(--color-text-muted);
 }
 
 .sidebarCollapsed {

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

@@ -1,9 +1,21 @@
 // Path: Frontend/src/components/shell/WorkspaceSidebar/WorkspaceSidebar.tsx
 
-import { For, Show, createMemo, createSignal, type JSX } from "solid-js";
+import { For, Show, createEffect, createSignal, onCleanup, onMount, type JSX } from "solid-js";
-import { ChevronLeft, ChevronRight } from "../../../lib/icons";
+import { resolveAPIBase } from "../../../lib/api";
+import { ChevronLeft, ChevronRight, Folder, ListCollapse, UnfoldVertical } from "../../../lib/icons";
 import { useAppShellData } from "../data/app-shell.context";
 import { ProjectSelector } from "../ProjectSelector/ProjectSelector";
+import {
+	collectBranchNodeIds,
+	findTreeNodeDepth,
+	findTreeNodeLocation,
+	getPointerRelativeY,
+	isUuidString,
+	moveTreeNode,
+	resolveTreeDropTarget,
+	type NavTreeAdapter,
+	type NavTreeDropTarget,
+} from "../shared/navTreeDnd";
 import {
 	createWorkspaceStaticTarget,
 	createWorkspaceSurfaceTarget,
@@ -26,6 +38,121 @@ type WorkspaceSidebarProps = {
 	onToggleRailCollapse: () => void;
 };
 
+type PendingWorkspaceFolderDraft = {
+	parentId: string | null;
+	depth: number;
+};
+
+type WorkspaceDragTarget = NavTreeDropTarget;
+
+type WorkspaceDragState = {
+	draggedNodeId: string;
+	dropTarget: WorkspaceDragTarget | null;
+};
+
+type PersistedWorkspaceFolderRecord = {
+	id: string;
+	path: string;
+	label: string;
+	children?: PersistedWorkspaceFolderRecord[];
+};
+
+type WorkspaceFoldersResponse = {
+	data?: {
+		folders?: PersistedWorkspaceFolderRecord[];
+		renamedFolder?: PersistedWorkspaceFolderRecord;
+		movedFolder?: PersistedWorkspaceFolderRecord;
+		previousFolderId?: string;
+		previousFolderPath?: string;
+	};
+	error?: string;
+	message?: string;
+};
+
+type PendingWorkspaceFolderRename = {
+	folderId: string;
+	depth: number;
+};
+
+const LONG_PRESS_MS = 320;
+
+const getWorkspaceTreeNodeId = (node: WorkspaceTreeNode): string => node.id;
+
+const buildPersistedWorkspaceFolderNodes = (
+	folders: readonly PersistedWorkspaceFolderRecord[],
+): WorkspaceTreeNode[] =>
+	folders.map((folder) => ({
+		id: folder.id,
+		path: folder.path,
+		label: folder.label,
+		kind: "folder",
+		icon: Folder,
+		children: buildPersistedWorkspaceFolderNodes(folder.children ?? []),
+	}));
+
+const readPersistedWorkspaceFolders = (body: WorkspaceFoldersResponse): PersistedWorkspaceFolderRecord[] =>
+	Array.isArray(body.data?.folders) ? body.data.folders : [];
+
+const countWorkspaceFolderSiblingsBeforeIndex = (
+	siblings: readonly WorkspaceTreeNode[],
+	index: number,
+): number => siblings.slice(0, index).filter((node) => node.kind === "folder").length;
+
+const workspaceTreeAdapter: NavTreeAdapter<WorkspaceTreeNode> = {
+	getNodeId: getWorkspaceTreeNodeId,
+	isBranchNode: (node) => node.kind === "folder",
+	getChildren: (node) => (node.kind === "folder" ? (node.children ?? []) : []),
+	withChildren: (node, children) =>
+		node.kind === "folder"
+			? {
+				...node,
+				children: [...children],
+			}
+			: node,
+};
+
+const FolderDraftRow = (props: {
+	depth: number;
+	value: string;
+	onInput: (value: string) => void;
+	onSubmit: () => void;
+	onCancel: () => void;
+}): JSX.Element => {
+	let inputRef: HTMLInputElement | undefined;
+
+	queueMicrotask(() => inputRef?.focus());
+
+	return (
+		<li>
+			<div class={styles.treeInputRow} style={{ "--tree-depth": String(props.depth) }}>
+				<Folder class={styles.icon} size={18} strokeWidth={2} />
+				<input
+					ref={inputRef}
+					type="text"
+					class={styles.treeInput}
+					value={props.value}
+					placeholder="Folder name"
+					onInput={(event): void => props.onInput(event.currentTarget.value)}
+					onBlur={props.onSubmit}
+					onKeyDown={(event): void => {
+						if (event.key === "Enter") {
+							event.preventDefault();
+							event.currentTarget.blur();
+							return;
+						}
+
+						if (event.key === "Escape") {
+							event.preventDefault();
+							props.onCancel();
+							event.currentTarget.blur();
+						}
+					}}
+				/>
+			</div>
+		</li>
+	);
+};
+
 const isContextMenuKeyboardTrigger = (event: KeyboardEvent): boolean => event.key === "ContextMenu" || (event.shiftKey && event.key === "F10");
 
 const WorkspaceHomeEntry = (props: {
@@ -75,29 +202,70 @@ const WorkspaceHomeEntry = (props: {
 
 const WorkspaceTreeBranch = (props: {
 	nodes: readonly WorkspaceTreeNode[];
+	parentId?: string | null;
 	depth?: number;
+	isFolderCollapsed: (folderId: string) => boolean;
+	onToggleFolder: (folderId: string) => void;
+	pendingFolderDraft: PendingWorkspaceFolderDraft | null;
+	pendingFolderName: string;
+	onPendingFolderNameChange: (value: string) => void;
+	onSubmitPendingFolder: () => void;
+	onCancelPendingFolder: () => void;
+	pendingFolderRename: PendingWorkspaceFolderRename | null;
+	pendingFolderRenameName: string;
+	onPendingFolderRenameChange: (value: string) => void;
+	onSubmitPendingFolderRename: () => void;
+	onCancelPendingFolderRename: () => void;
 	onOpenContextMenu: (event: MouseEvent, target: WorkspaceContextMenuTarget) => void;
 	onOpenContextMenuFromKeyboard: (element: HTMLElement, target: WorkspaceContextMenuTarget) => void;
+	onNodePointerDown: (event: PointerEvent, nodeId: string) => void;
+	onNodePointerMove: (event: PointerEvent, parentId: string | null, index: number, node: WorkspaceTreeNode) => void;
+	dragState: WorkspaceDragState | null;
+	isTreeClickSuppressed: () => boolean;
 }): JSX.Element => {
 	const depth = () => props.depth ?? 0;
+	const parentId = () => props.parentId ?? null;
 
 	return (
 		<ul class={styles.treeList} role="list">
+			<Show when={props.nodes.length === 0 && props.pendingFolderDraft?.parentId !== parentId()}>
+				<li>
+					<div class={styles.treeEmptySlot} style={{ "--tree-depth": String(depth()) }} />
+				</li>
+			</Show>
 			<For each={props.nodes}>
-				{(node): JSX.Element => {
+				{(node, indexAccessor): JSX.Element => {
 					const Icon = getWorkspaceNodeIcon(node);
 					const target = createWorkspaceTreeTarget(node);
+					const isCollapsed = (): boolean => (node.kind === "folder" ? props.isFolderCollapsed(node.id) : false);
+					const isRenaming = (): boolean => props.pendingFolderRename?.folderId === node.id;
+					const isDraggedNode = (): boolean => props.dragState?.draggedNodeId === node.id;
+					const dropIntent = (): WorkspaceDragTarget["intent"] | null => {
+						if (props.dragState?.dropTarget?.targetNodeId !== node.id) {
+							return null;
+						}
+
+						return props.dragState.dropTarget.intent;
+					};
 
 					return (
 						<li>
+							<Show
+								when={node.kind === "folder" && isRenaming()}
+								fallback={
 									<button
 										type="button"
 										classList={{
 											[styles.treeItem]: true,
 											[styles.treeItemActive]: !!node.active,
 											[styles.treeItemFolder]: node.kind === "folder",
+											[styles.treeItemDragging]: isDraggedNode(),
+											[styles.treeItemDropBefore]: dropIntent() === "before",
+											[styles.treeItemDropAfter]: dropIntent() === "after",
+											[styles.treeItemDropInside]: dropIntent() === "inside",
 										}}
 										style={{ "--tree-depth": String(depth()) }}
+										aria-expanded={node.kind === "folder" ? !isCollapsed() : undefined}
 										aria-current={node.active ? "page" : undefined}
 										aria-label={node.label}
 										title={node.label}
@@ -105,10 +273,28 @@ const WorkspaceTreeBranch = (props: {
 										data-kind={node.kind}
 										data-item-type={node.kind === "item" ? node.itemType : undefined}
 										data-active={node.active ? "true" : "false"}
+										onClick={(): void => {
+											if (props.dragState || props.isTreeClickSuppressed()) {
+												return;
+											}
+
+											if (node.kind !== "folder") {
+												return;
+											}
+
+											props.onToggleFolder(node.id);
+										}}
 										onContextMenu={(event): void => {
 											event.stopPropagation();
 											props.onOpenContextMenu(event, target);
 										}}
+										onPointerDown={(event): void => props.onNodePointerDown(event, node.id)}
+										onPointerMove={(event): void =>
+											props.onNodePointerMove(event, parentId(), indexAccessor(), node)
+										}
+										onPointerEnter={(event): void =>
+											props.onNodePointerMove(event, parentId(), indexAccessor(), node)
+										}
 										onKeyDown={(event): void => {
 											if (!isContextMenuKeyboardTrigger(event)) {
 												return;
@@ -118,49 +304,605 @@ const WorkspaceTreeBranch = (props: {
 											props.onOpenContextMenuFromKeyboard(event.currentTarget, target);
 										}}
 									>
+										<Show when={node.kind === "folder"}>
+											<ChevronRight
+												classList={{
+													[styles.folderChevron]: true,
+													[styles.folderChevronOpen]: !isCollapsed(),
+												}}
+												size={16}
+												strokeWidth={2}
+											/>
+										</Show>
 										<Icon class={styles.icon} size={18} strokeWidth={2} />
 										<span class={styles.label}>{node.label}</span>
 										<Show when={node.meta}>
 											<span class={styles.itemMeta}>{node.meta}</span>
 										</Show>
 									</button>
+								}
+							>
+								<FolderDraftRow
+									depth={props.pendingFolderRename?.depth ?? depth()}
+									value={props.pendingFolderRenameName}
+									onInput={props.onPendingFolderRenameChange}
+									onSubmit={props.onSubmitPendingFolderRename}
+									onCancel={props.onCancelPendingFolderRename}
+								/>
+							</Show>
 
-							<Show when={node.children?.length}>
+							<Show when={node.kind === "folder" && !isCollapsed() && (((node.children?.length ?? 0) > 0) || props.pendingFolderDraft?.parentId === node.id)}>
 								<WorkspaceTreeBranch
 									nodes={node.children ?? []}
+									parentId={node.id}
 									depth={depth() + 1}
+									isFolderCollapsed={props.isFolderCollapsed}
+									onToggleFolder={props.onToggleFolder}
+									pendingFolderDraft={props.pendingFolderDraft}
+									pendingFolderName={props.pendingFolderName}
+									onPendingFolderNameChange={props.onPendingFolderNameChange}
+									onSubmitPendingFolder={props.onSubmitPendingFolder}
+									onCancelPendingFolder={props.onCancelPendingFolder}
+									pendingFolderRename={props.pendingFolderRename}
+									pendingFolderRenameName={props.pendingFolderRenameName}
+									onPendingFolderRenameChange={props.onPendingFolderRenameChange}
+									onSubmitPendingFolderRename={props.onSubmitPendingFolderRename}
+									onCancelPendingFolderRename={props.onCancelPendingFolderRename}
 									onOpenContextMenu={props.onOpenContextMenu}
 									onOpenContextMenuFromKeyboard={props.onOpenContextMenuFromKeyboard}
+									onNodePointerDown={props.onNodePointerDown}
+									onNodePointerMove={props.onNodePointerMove}
+									dragState={props.dragState}
+									isTreeClickSuppressed={props.isTreeClickSuppressed}
 								/>
 							</Show>
 						</li>
 					);
 				}}
 			</For>
+
+			<Show when={props.pendingFolderDraft && props.pendingFolderDraft.parentId === parentId()}>
+				<FolderDraftRow
+					depth={props.pendingFolderDraft?.depth ?? depth()}
+					value={props.pendingFolderName}
+					onInput={props.onPendingFolderNameChange}
+					onSubmit={props.onSubmitPendingFolder}
+					onCancel={props.onCancelPendingFolder}
+				/>
+			</Show>
 		</ul>
 	);
 };
 
 export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 	const appShellData = useAppShellData();
+	const activeProject = () => appShellData.activeProject();
 	const [isProjectDrawerOpen, setIsProjectDrawerOpen] = createSignal(false);
+	const [workspaceTreeNodes, setWorkspaceTreeNodes] = createSignal<readonly WorkspaceTreeNode[]>(appShellData.workspaceTree());
+	const [persistedFolders, setPersistedFolders] = createSignal<readonly PersistedWorkspaceFolderRecord[]>([]);
+	const [collapsedFolderIds, setCollapsedFolderIds] = createSignal<readonly string[]>([]);
+	const [pendingFolderDraft, setPendingFolderDraft] = createSignal<PendingWorkspaceFolderDraft | null>(null);
+	const [pendingFolderName, setPendingFolderName] = createSignal("");
+	const [pendingFolderRename, setPendingFolderRename] = createSignal<PendingWorkspaceFolderRename | null>(null);
+	const [pendingFolderRenameName, setPendingFolderRenameName] = createSignal("");
+	const [dragState, setDragState] = createSignal<WorkspaceDragState | null>(null);
+	const [suppressNextTreeClick, setSuppressNextTreeClick] = createSignal(false);
+	let lastSelectedProjectId: string | null = null;
+	let latestPersistedFoldersRequest = 0;
 	const contextMenu = createWorkspaceContextMenuController();
+	let longPressTimer: number | undefined;
+	let suppressClickTimer: number | undefined;
 	const railToggleLabel = (): string => (props.railCollapsed ? "Expand server rail" : "Collapse server rail");
-	const sidebarContextMenuTarget = createMemo(() => createWorkspaceSurfaceTarget(appShellData.activeProject()));
+	const sidebarContextMenuTarget = createWorkspaceSurfaceTarget(appShellData.activeProject());
-	const contextMenuTarget = createMemo(() => contextMenu.menuState()?.target ?? null);
+	const isFolderCollapsed = (folderId: string): boolean => collapsedFolderIds().includes(folderId);
-	const contextMenuPosition = createMemo(() => {
+	const folderIds = (): string[] => collectBranchNodeIds(workspaceTreeNodes(), workspaceTreeAdapter);
-		const state = contextMenu.menuState();
+	const totalFolderCount = (): number => folderIds().length;
-
+	const areAllFoldersCollapsed = (): boolean => {
-		return state
+		const count = totalFolderCount();
-			? {
+		return count > 0 && collapsedFolderIds().length >= count;
-				x: state.x,
+	};
-				y: state.y,
+	const workspaceFolderToggleLabel = (): string =>
+		areAllFoldersCollapsed() ? "Expand all folders" : "Collapse all folders";
+	const toggleFolder = (folderId: string): void => {
+		setCollapsedFolderIds((current) =>
+			current.includes(folderId) ? current.filter((id) => id !== folderId) : [...current, folderId],
+		);
+	};
+	const expandAllFolders = (): void => {
+		setCollapsedFolderIds([]);
+	};
+	const collapseAllFolders = (): void => {
+		setCollapsedFolderIds(folderIds());
+	};
+	const toggleAllFolders = (): void => {
+		if (areAllFoldersCollapsed()) {
+			expandAllFolders();
+			return;
 		}
-			: null;
+
+		collapseAllFolders();
+	};
+	const resetWorkspaceTreeInteractionState = (): void => {
+		setCollapsedFolderIds([]);
+		setPendingFolderDraft(null);
+		setPendingFolderName("");
+		setPendingFolderRename(null);
+		setPendingFolderRenameName("");
+		setDragState(null);
+	};
+	const syncWorkspaceTree = (): void => {
+		const nextTree = activeProject()?.id
+			? buildPersistedWorkspaceFolderNodes(persistedFolders())
+			: appShellData.workspaceTree();
+		const availableFolderIds = new Set(collectBranchNodeIds(nextTree, workspaceTreeAdapter));
+
+		setWorkspaceTreeNodes(nextTree);
+		setCollapsedFolderIds((current) => current.filter((id) => availableFolderIds.has(id)));
+	};
+	const loadPersistedFolders = async (projectId: string): Promise<void> => {
+		const requestId = latestPersistedFoldersRequest + 1;
+		latestPersistedFoldersRequest = requestId;
+
+		if (!projectId) {
+			setPersistedFolders([]);
+			return;
+		}
+
+		if (!isUuidString(projectId)) {
+			setPersistedFolders([]);
+			return;
+		}
+
+		try {
+			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/tree/folders`, {
+				headers: {
+					Accept: "application/json",
+				},
+			});
+			const body = (await response.json()) as WorkspaceFoldersResponse;
+
+			if (requestId !== latestPersistedFoldersRequest) {
+				return;
+			}
+
+			if (!response.ok) {
+				throw new Error(body.message || "Failed to load project tree folders.");
+			}
+
+			setPersistedFolders(readPersistedWorkspaceFolders(body));
+		} catch (error) {
+			if (requestId !== latestPersistedFoldersRequest) {
+				return;
+			}
+
+			console.error(error);
+			setPersistedFolders([]);
+		}
+	};
+	const clearLongPressTimer = (): void => {
+		if (longPressTimer !== undefined) {
+			window.clearTimeout(longPressTimer);
+			longPressTimer = undefined;
+		}
+	};
+	const suppressTreeClickTemporarily = (): void => {
+		setSuppressNextTreeClick(true);
+
+		if (suppressClickTimer !== undefined) {
+			window.clearTimeout(suppressClickTimer);
+		}
+
+		suppressClickTimer = window.setTimeout(() => {
+			setSuppressNextTreeClick(false);
+			suppressClickTimer = undefined;
+		}, 80);
+	};
+
+	createEffect(() => {
+		syncWorkspaceTree();
 	});
 
-	const handleContextActionSelect = (_action: WorkspaceContextMenuAction, _target: WorkspaceContextMenuTarget): void => {
+	createEffect(() => {
-		// Initial implementation only establishes the menu IA and placement.
+		const projectId = activeProject()?.id ?? null;
+
+		if (lastSelectedProjectId === null) {
+			lastSelectedProjectId = projectId;
+			return;
+		}
+
+		if (projectId === lastSelectedProjectId) {
+			return;
+		}
+
+		lastSelectedProjectId = projectId;
+		resetWorkspaceTreeInteractionState();
+	});
+
+	createEffect(() => {
+		void loadPersistedFolders(activeProject()?.id ?? "");
+	});
+
+	onMount(() => {
+		const handlePointerUp = (): void => {
+			clearLongPressTimer();
+
+			const nextDragState = dragState();
+
+			if (!nextDragState?.dropTarget) {
+				if (nextDragState) {
+					suppressTreeClickTemporarily();
+				}
+				setDragState(null);
+				return;
+			}
+
+			suppressTreeClickTemporarily();
+
+			const currentNodes = workspaceTreeNodes();
+			const draggedLocation = findTreeNodeLocation(currentNodes, nextDragState.draggedNodeId, workspaceTreeAdapter);
+			const canPersistMove = isUuidString(activeProject()?.id ?? "");
+			const draggedFolderPath = draggedLocation?.node.kind === "folder" ? draggedLocation.node.path ?? null : null;
+			const previewNodes = moveTreeNode(currentNodes, nextDragState.draggedNodeId, nextDragState.dropTarget as WorkspaceDragTarget, workspaceTreeAdapter);
+			const previewLocation = findTreeNodeLocation(previewNodes, nextDragState.draggedNodeId, workspaceTreeAdapter);
+			const persistedParentLocation = previewLocation?.parentId
+				? findTreeNodeLocation(previewNodes, previewLocation.parentId, workspaceTreeAdapter)
+				: null;
+			const persistedParentFolderPath = persistedParentLocation?.node.kind === "folder" ? persistedParentLocation.node.path ?? null : null;
+			const previewSiblings = previewLocation?.parentId
+				? persistedParentLocation?.node.kind === "folder"
+					? persistedParentLocation.node.children ?? []
+					: []
+				: previewNodes;
+			// The tree preview can include static/workspace items, but persisted ordering
+			// only applies to folder siblings. Convert the preview position into a folder-
+			// only index before sending it to the backend move endpoint.
+			const targetIndex = previewLocation
+				? countWorkspaceFolderSiblingsBeforeIndex(previewSiblings, previewLocation.index)
+				: 0;
+
+			if (
+				canPersistMove &&
+				draggedLocation?.node.kind === "folder" &&
+				draggedFolderPath &&
+				(!previewLocation?.parentId || persistedParentLocation?.node.kind === "folder")
+			) {
+				void movePersistedFolder(
+					draggedFolderPath,
+					persistedParentFolderPath,
+					draggedLocation.node.id,
+					persistedParentLocation?.node.kind === "folder" ? persistedParentLocation.node.id : null,
+					targetIndex,
+				);
+			} else {
+				setWorkspaceTreeNodes((current) =>
+					moveTreeNode(current, nextDragState.draggedNodeId, nextDragState.dropTarget as WorkspaceDragTarget, workspaceTreeAdapter),
+				);
+			}
+
+			setDragState(null);
+		};
+
+		const handleEscape = (event: KeyboardEvent): void => {
+			if (event.key !== "Escape") {
+				return;
+			}
+
+			clearLongPressTimer();
+
+			if (dragState()) {
+				setDragState(null);
+			}
+		};
+
+		window.addEventListener("pointerup", handlePointerUp);
+		window.addEventListener("pointercancel", handlePointerUp);
+		window.addEventListener("keydown", handleEscape);
+
+		onCleanup(() => {
+			clearLongPressTimer();
+			if (suppressClickTimer !== undefined) {
+				window.clearTimeout(suppressClickTimer);
+			}
+			window.removeEventListener("pointerup", handlePointerUp);
+			window.removeEventListener("pointercancel", handlePointerUp);
+			window.removeEventListener("keydown", handleEscape);
+		});
+	});
+
+	const beginFolderDraft = (parentId: string | null, depth: number): void => {
+		if (parentId) {
+			setCollapsedFolderIds((current) => current.filter((id) => id !== parentId));
+		}
+
+		setPendingFolderRename(null);
+		setPendingFolderRenameName("");
+		setPendingFolderName("");
+		setPendingFolderDraft({ parentId, depth });
+	};
+
+	const beginFolderRename = (folderId: string, label: string, depth: number): void => {
+		setPendingFolderDraft(null);
+		setPendingFolderName("");
+		setPendingFolderRename({ folderId, depth });
+		setPendingFolderRenameName(label);
+	};
+
+	const resolveFolderPath = (folderId: string): string | null => {
+		const location = findTreeNodeLocation(workspaceTreeNodes(), folderId, workspaceTreeAdapter);
+		return location?.node.kind === "folder" ? location.node.path ?? null : null;
+	};
+
+	const submitPendingFolder = async (): Promise<void> => {
+		const name = pendingFolderName().trim();
+		const draft = pendingFolderDraft();
+		const projectId = activeProject()?.id ?? "";
+
+		if (!draft) {
+			return;
+		}
+
+		if (!name) {
+			setPendingFolderDraft(null);
+			setPendingFolderName("");
+			return;
+		}
+
+		if (!projectId || !isUuidString(projectId)) {
+			cancelPendingFolder();
+			return;
+		}
+
+		const parentFolderPath = draft.parentId ? resolveFolderPath(draft.parentId) : null;
+		if (draft.parentId && !parentFolderPath) {
+			cancelPendingFolder();
+			return;
+		}
+
+		try {
+			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/tree/folders`, {
+				method: "POST",
+				headers: {
+					Accept: "application/json",
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({
+					name,
+					parentFolderId: parentFolderPath,
+				}),
+			});
+
+			const body = (await response.json()) as WorkspaceFoldersResponse;
+
+			if (!response.ok) {
+				throw new Error(body.message || "Failed to create project tree folder.");
+			}
+
+			setPersistedFolders(readPersistedWorkspaceFolders(body));
+			setPendingFolderDraft(null);
+			setPendingFolderName("");
+		} catch (error) {
+			console.error(error);
+		}
+	};
+
+	const deletePersistedFolder = async (folderId: string): Promise<void> => {
+		const projectId = activeProject()?.id ?? "";
+		const folderPath = resolveFolderPath(folderId);
+		if (!folderId || !projectId || !isUuidString(projectId)) {
+			return;
+		}
+		if (!folderPath) {
+			return;
+		}
+
+		try {
+			const response = await fetch(
+				`${resolveAPIBase()}/projects/${projectId}/tree/folders?folderId=${encodeURIComponent(folderPath)}`,
+				{
+					method: "DELETE",
+					headers: {
+						Accept: "application/json",
+					},
+				},
+			);
+
+			const body = (await response.json()) as WorkspaceFoldersResponse;
+
+			if (!response.ok) {
+				throw new Error(body.message || "Failed to delete project tree folder.");
+			}
+
+			setPersistedFolders(readPersistedWorkspaceFolders(body));
+			setCollapsedFolderIds((current) => current.filter((id) => id !== folderId));
+		} catch (error) {
+			console.error(error);
+		}
+	};
+
+	const movePersistedFolder = async (
+		folderPath: string,
+		parentFolderPath: string | null,
+		folderStableId: string,
+		parentStableId: string | null,
+		targetIndex: number,
+	): Promise<void> => {
+		const projectId = activeProject()?.id ?? "";
+		if (!folderPath || !folderStableId || !projectId || !isUuidString(projectId)) {
+			return;
+		}
+
+		try {
+			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/tree/folders/move`, {
+				method: "PATCH",
+				headers: {
+					Accept: "application/json",
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({
+					folderId: folderPath,
+					folderNodeId: folderStableId,
+					parentFolderId: parentFolderPath,
+					parentNodeId: parentStableId,
+					targetIndex,
+				}),
+			});
+
+			const body = (await response.json()) as WorkspaceFoldersResponse;
+
+			if (!response.ok) {
+				throw new Error(body.message || "Failed to move project tree folder.");
+			}
+
+			setPersistedFolders(readPersistedWorkspaceFolders(body));
+		} catch (error) {
+			console.error(error);
+		}
+	};
+
+	const submitPendingFolderRename = async (): Promise<void> => {
+		const draft = pendingFolderRename();
+		const name = pendingFolderRenameName().trim();
+		const projectId = activeProject()?.id ?? "";
+
+		if (!draft) {
+			return;
+		}
+
+		if (!name) {
+			setPendingFolderRename(null);
+			setPendingFolderRenameName("");
+			return;
+		}
+
+		if (!projectId || !isUuidString(projectId)) {
+			cancelPendingFolderRename();
+			return;
+		}
+
+		const folderPath = resolveFolderPath(draft.folderId);
+		if (!folderPath) {
+			cancelPendingFolderRename();
+			return;
+		}
+
+		try {
+			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/tree/folders`, {
+				method: "PATCH",
+				headers: {
+					Accept: "application/json",
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({
+					folderId: folderPath,
+					name,
+				}),
+			});
+
+			const body = (await response.json()) as WorkspaceFoldersResponse;
+
+			if (!response.ok) {
+				throw new Error(body.message || "Failed to rename project tree folder.");
+			}
+
+			setPersistedFolders(readPersistedWorkspaceFolders(body));
+			setPendingFolderRename(null);
+			setPendingFolderRenameName("");
+		} catch (error) {
+			console.error(error);
+		}
+	};
+
+	const cancelPendingFolder = (): void => {
+		setPendingFolderDraft(null);
+		setPendingFolderName("");
+	};
+
+	const cancelPendingFolderRename = (): void => {
+		setPendingFolderRename(null);
+		setPendingFolderRenameName("");
+	};
+
+	const handleHeaderActionClick = (actionId: string): void => {
+		switch (actionId) {
+			case "toggle-workspace-folders":
+				toggleAllFolders();
+				return;
+			case "search-workspace":
+			default:
+				return;
+		}
+	};
+
+	const handleNodePointerDown = (event: PointerEvent, nodeId: string): void => {
+		if (event.button !== 0 || pendingFolderDraft()) {
+			return;
+		}
+
+		clearLongPressTimer();
+		longPressTimer = window.setTimeout(() => {
+			suppressTreeClickTemporarily();
+			setDragState({ draggedNodeId: nodeId, dropTarget: null });
+		}, LONG_PRESS_MS);
+	};
+
+	const handleNodePointerMove = (
+		event: PointerEvent,
+		parentId: string | null,
+		index: number,
+		node: WorkspaceTreeNode,
+	): void => {
+		const nextDragState = dragState();
+
+		if (!nextDragState || nextDragState.draggedNodeId === getWorkspaceTreeNodeId(node)) {
+			return;
+		}
+
+		const relativeY = getPointerRelativeY(event);
+		if (relativeY === null) {
+			return;
+		}
+
+		setDragState({
+			...nextDragState,
+			dropTarget: resolveTreeDropTarget({
+				parentId,
+				index,
+				node,
+				relativeY,
+				adapter: workspaceTreeAdapter,
+			}),
+		});
+	};
+
+	const handleContextActionSelect = (action: WorkspaceContextMenuAction, target: WorkspaceContextMenuTarget): void => {
+		switch (action.id) {
+			case "new-folder":
+				switch (target.kind) {
+					case "workspace":
+					case "home":
+						beginFolderDraft(null, 0);
+						return;
+					case "folder":
+						beginFolderDraft(target.id, (findTreeNodeDepth(workspaceTreeNodes(), target.id, workspaceTreeAdapter) ?? 0) + 1);
+						return;
+					case "settings":
+					case "item":
+						return;
+				}
+				return;
+			case "delete-folder":
+				if (target.kind === "folder") {
+					void deletePersistedFolder(target.id);
+				}
+				return;
+			case "rename-folder":
+				if (target.kind === "folder") {
+					beginFolderRename(target.id, target.label, findTreeNodeDepth(workspaceTreeNodes(), target.id, workspaceTreeAdapter) ?? 0);
+				}
+				return;
+			default:
+				return;
+		}
 	};
 
 	return (
@@ -169,12 +911,13 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 				classList={{
 					[styles.sidebar]: true,
 					[styles.sidebarCollapsed]: props.collapsed,
+					[styles.sidebarDragMode]: !!dragState(),
 				}}
 				aria-label="Left workspace sidebar"
 				data-ui="workspace-sidebar"
 				data-collapsed={props.collapsed ? "true" : "false"}
 				onContextMenu={(event): void => {
-					contextMenu.openMenu(event, sidebarContextMenuTarget());
+					contextMenu.openMenu(event, sidebarContextMenuTarget);
 				}}
 			>
 				<div
@@ -202,10 +945,28 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 
 					<For each={workspaceSidebarHeaderActions}>
 						{(action): JSX.Element => {
-								const Icon = action.icon;
+							const label =
+								action.id === "toggle-workspace-folders"
+										? workspaceFolderToggleLabel()
+										: action.label;
+							const Icon =
+								action.id === "toggle-workspace-folders"
+										? areAllFoldersCollapsed()
+											? UnfoldVertical
+											: ListCollapse
+										: action.icon;
 
 							return (
-									<button type="button" class={styles.headerActionButton} aria-label={action.label} title={action.label} data-slot="workspace-sidebar-header-action" data-action-id={action.id}>
+								<button
+									type="button"
+									class={styles.headerActionButton}
+									aria-label={label}
+									title={label}
+									data-slot="workspace-sidebar-header-action"
+									data-action-id={action.id}
+									disabled={action.id === "toggle-workspace-folders" && totalFolderCount() === 0}
+									onClick={(): void => handleHeaderActionClick(action.id)}
+									>
 										<Icon size={16} strokeWidth={2} />
 									</button>
 								);
@@ -256,9 +1017,26 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 
 						<div data-slot="workspace-tree-root">
 							<WorkspaceTreeBranch
-							nodes={appShellData.workspaceTree()}
+								nodes={workspaceTreeNodes()}
+								parentId={null}
+								isFolderCollapsed={isFolderCollapsed}
+								onToggleFolder={toggleFolder}
+								pendingFolderDraft={pendingFolderDraft()}
+								pendingFolderName={pendingFolderName()}
+								onPendingFolderNameChange={setPendingFolderName}
+								onSubmitPendingFolder={submitPendingFolder}
+								onCancelPendingFolder={cancelPendingFolder}
+								pendingFolderRename={pendingFolderRename()}
+								pendingFolderRenameName={pendingFolderRenameName()}
+								onPendingFolderRenameChange={setPendingFolderRenameName}
+								onSubmitPendingFolderRename={submitPendingFolderRename}
+								onCancelPendingFolderRename={cancelPendingFolderRename}
 								onOpenContextMenu={contextMenu.openMenu}
 								onOpenContextMenuFromKeyboard={contextMenu.openMenuFromElement}
+								onNodePointerDown={handleNodePointerDown}
+								onNodePointerMove={handleNodePointerMove}
+								dragState={dragState()}
+								isTreeClickSuppressed={suppressNextTreeClick}
 							/>
 						</div>
 					</div>
@@ -266,8 +1044,16 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 			</aside>
 
 			<WorkspaceContextMenu
-				target={contextMenuTarget()}
+				target={contextMenu.menuState()?.target ?? null}
-				position={contextMenuPosition()}
+				position={(() => {
+					const state = contextMenu.menuState();
+					return state
+						? {
+							x: state.x,
+							y: state.y,
+						}
+						: null;
+				})()}
 				menuRef={contextMenu.setMenuRef}
 				onClose={contextMenu.closeMenu}
 				onSelect={handleContextActionSelect}

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

@@ -34,11 +34,14 @@ import {
 
 type AppShellInstallation = {
 	id: string;
+	name: string;
 	mode: "personal" | "organizational" | string;
 	access: string;
 	protocol: string;
 	host: string;
 	isBootstrapped: boolean;
+	materializationStatus: "not_started" | "pending" | "running" | "succeeded" | "failed" | string;
+	materializationError?: string;
 };
 
 type AppShellAdmin = {
@@ -100,8 +103,29 @@ type AppShellPayload = {
 	workspaces: AppShellWorkspace[];
 };
 
+const normalizeInstallation = (
+	installation: AppShellInstallation | null | undefined,
+): AppShellInstallation | undefined => {
+	if (!installation) {
+		return undefined;
+	}
+
+	const materializationStatus = installation.materializationStatus?.trim()
+		? installation.materializationStatus
+		: installation.isBootstrapped
+			? "succeeded"
+			: "not_started";
+	const materializationError = installation.materializationError?.trim() || undefined;
+
+	return {
+		...installation,
+		materializationStatus,
+		materializationError,
+	};
+};
+
 const normalizeAppShellPayload = (payload: AppShellPayload | null | undefined): AppShellPayload => ({
-	installation: payload?.installation,
+	installation: normalizeInstallation(payload?.installation),
 	admin: payload?.admin,
 	organizations: Array.isArray(payload?.organizations) ? payload.organizations : [],
 	departments: Array.isArray(payload?.departments) ? payload.departments : [],
@@ -151,11 +175,12 @@ const buildRailItems = (payload: AppShellPayload | null): readonly RailItem[] =>
 	}
 
 	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: organization.name,
+		label: serverName || organization.name,
-		abbreviation: buildAbbreviation(organization.name, kind === "personal" ? "P" : "O"),
+		abbreviation: buildAbbreviation(serverName || organization.name, kind === "personal" ? "P" : "O"),
 		kind,
 		active: index === 0,
 	}));
@@ -170,11 +195,12 @@ const buildActiveServer = (payload: AppShellPayload | null): ActiveServer => {
 	}
 
 	const kind = installation.mode === "personal" ? "personal" : "organization";
+	const serverName = installation.name || organization.name || installation.host;
 
 	return {
 		id: installation.id,
-		name: organization.name || installation.host || fallbackActiveServer.name,
+		name: serverName || fallbackActiveServer.name,
-		abbreviation: buildAbbreviation(organization.name || installation.host, kind === "personal" ? "P" : "O"),
+		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,
@@ -191,6 +217,16 @@ const buildProjectItems = (payload: AppShellPayload | null): readonly ProjectIte
 		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,
 	}));
 };
@@ -255,7 +291,7 @@ const buildActiveUserProfile = (payload: AppShellPayload | null): ActiveUserProf
 		return fallbackActiveUserProfile;
 	}
 
-	const organizationName = payload.organizations[0]?.name ?? fallbackActiveServer.name;
+	const organizationName = payload.installation?.name || payload.organizations[0]?.name || fallbackActiveServer.name;
 	const departmentName = payload.departments[0]?.name;
 
 	return {
@@ -282,10 +318,20 @@ export const AppShellDataProvider = (props: { children: JSX.Element }): JSX.Elem
 				},
 			});
 
-			const body = (await response.json()) as { data?: AppShellPayload; error?: { message?: string } };
+			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(body.error?.message || "Failed to load app shell state.");
+				throw new Error(errorMessage || "Failed to load app shell state.");
 			}
 
 			setPayload(normalizeAppShellPayload(body.data));

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

@@ -9,6 +9,7 @@ import {
 	Home,
 	Keyboard,
 	LayoutGrid,
+	ListCollapse,
 	LogOut,
 	Repeat,
 	Search,
@@ -71,9 +72,43 @@ export type ProjectItem = {
 	id: string;
 	name: string;
 	description: string;
+	groupLabel?: string;
+	parentLabel?: string;
+	meta?: string;
 	active?: boolean;
 };
 
+export type ProjectMenuTarget =
+	| {
+		id: string;
+		label: string;
+		kind: "surface";
+	  }
+	| {
+		id: string;
+		label: string;
+		kind: "folder";
+	  }
+	| {
+		id: string;
+		label: string;
+		kind: "project";
+	  };
+
+export type ProjectContextMenuAction = {
+	id: string;
+	label: string;
+	tone?: "default" | "danger";
+	shortcut?: WorkspaceContextMenuShortcut;
+	children?: readonly ProjectContextMenuAction[];
+};
+
+export type ProjectContextMenuSection = {
+	id: string;
+	label?: string;
+	items: readonly ProjectContextMenuAction[];
+};
+
 export type SidebarItem = {
 	id: string;
 	label: string;
@@ -94,6 +129,7 @@ export type WorkspaceStaticItem = SidebarItem & {
 
 export type WorkspaceFolderNode = {
 	id: string;
+	path?: string;
 	label: string;
 	kind: "folder";
 	icon: ShellIcon;
@@ -364,9 +400,31 @@ export const activeDepartment: ActiveDepartment = {
 };
 
 export const projectItems: readonly ProjectItem[] = [
-	{ id: "general", name: "General", description: "Default shared project", active: true },
+	{
-	{ id: "operations", name: "Operations", description: "Cross-team planning and delivery" },
+		id: "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[] = [
@@ -420,6 +478,7 @@ export const workspaceTree: readonly WorkspaceTreeNode[] = [
 
 export const workspaceSidebarHeaderActions: readonly SidebarHeaderAction[] = [
 	{ id: "search-workspace", label: "Search workspace", icon: Search },
+	{ id: "toggle-workspace-folders", label: "Collapse all folders", icon: ListCollapse },
 ] as const;
 
 export const mobileBottomNavItems: readonly MobileBottomNavItem[] = [
@@ -533,6 +592,79 @@ export const getWorkspaceContextMenuSections = (
 	}
 };
 
+const getProjectCreateActions = (): readonly ProjectContextMenuAction[] =>
+	[
+		{ id: "new-project", label: "New project" },
+		{ id: "new-folder", label: "New folder" },
+	] as const;
+
+const getProjectFolderDangerActions = (): readonly ProjectContextMenuAction[] =>
+	[
+		{ id: "rename-folder", label: "Rename", shortcut: { modifiers: ["meta"], key: "r" } },
+		{ id: "delete-folder", label: "Delete", shortcut: { modifiers: ["meta"], key: "delete" }, tone: "danger" },
+	] as const;
+
+export const createProjectSurfaceTarget = (label = "Projects"): ProjectMenuTarget => ({
+	id: "project-surface",
+	label,
+	kind: "surface",
+});
+
+export const createProjectFolderTarget = (id: string, label: string): ProjectMenuTarget => ({
+	id,
+	label,
+	kind: "folder",
+});
+
+export const createProjectTarget = (project: ProjectItem): ProjectMenuTarget => ({
+	id: project.id,
+	label: project.name,
+	kind: "project",
+});
+
+export const getProjectContextMenuEyebrow = (target: ProjectMenuTarget): string => {
+	switch (target.kind) {
+		case "surface":
+			return "Projects";
+		case "folder":
+			return "Folder";
+		case "project":
+			return "Project";
+	}
+};
+
+export const getProjectContextMenuSections = (target: ProjectMenuTarget): readonly ProjectContextMenuSection[] => {
+	const createActions = getProjectCreateActions();
+
+	switch (target.kind) {
+		case "surface":
+			return [
+				{
+					id: "create",
+					items: createActions,
+				},
+			] as const;
+		case "folder":
+			return [
+				{
+					id: "create",
+					items: createActions,
+				},
+				{
+					id: "organize",
+					items: getProjectFolderDangerActions(),
+				},
+			] as const;
+		case "project":
+			return [
+				{
+					id: "create",
+					items: createActions,
+				},
+			] as const;
+	}
+};
+
 export const topBarActions: readonly TopBarAction[] = [
 	{ id: "search", label: "Search", icon: Search },
 ] as const;

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

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

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

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

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

@@ -92,10 +92,19 @@
   flex-wrap: wrap;
 }
 
-.eyebrow {
+.heroStatus {
-  @include text-caption;
+	display: grid;
+	gap: var(--space-2);
+	justify-items: start;
+}
+
+.heroStatusMessage {
+	max-width: 64ch;
 	color: var(--color-text-muted);
-  text-transform: uppercase;
+}
+
+.heroStatusMessage[data-status="failed"] {
+	color: var(--color-danger-text, var(--color-text));
 }
 
 .title {
@@ -200,6 +209,19 @@
   background: color-mix(in srgb, var(--color-success-surface, var(--color-surface-secondary)) 80%, transparent);
 }
 
+.statusBadge[data-status="pending"],
+.statusBadge[data-status="running"] {
+	color: var(--bootstrap-accent);
+	border-color: color-mix(in srgb, var(--bootstrap-accent) 38%, transparent);
+	background: color-mix(in srgb, var(--bootstrap-accent) 10%, var(--color-surface-secondary));
+}
+
+.statusBadge[data-status="failed"] {
+	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);
+}
+
 .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);
@@ -246,10 +268,16 @@
   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);
@@ -490,6 +518,111 @@
   gap: var(--space-3);
 }
 
+.wizardFinishPanel {
+	display: grid;
+	gap: var(--space-4);
+	justify-items: stretch;
+	padding: var(--space-2) 0 0;
+	min-height: min(14rem, 32dvh);
+	align-content: center;
+}
+
+.wizardFinishShell {
+	display: grid;
+	gap: var(--space-4);
+	width: min(100%, 40rem);
+	padding: 0;
+	border: 0;
+	border-radius: 0;
+	background: transparent;
+	box-shadow: none;
+}
+
+.wizardFinishStatusRow {
+	display: grid;
+	grid-template-columns: auto minmax(0, 1fr);
+	gap: var(--space-3);
+	align-items: start;
+}
+
+.wizardFinishIndicator {
+	width: 2.5rem;
+	height: 2.5rem;
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	border-radius: 999px;
+	border: 1px solid color-mix(in srgb, var(--bootstrap-accent) 18%, transparent);
+	background: color-mix(in srgb, var(--bootstrap-accent) 8%, transparent);
+}
+
+.wizardFinishIndicator[data-status="failed"] {
+	border-color: color-mix(in srgb, var(--color-danger-border, var(--color-border)) 44%, transparent);
+	background: color-mix(in srgb, var(--color-danger-surface, var(--color-surface-secondary)) 36%, transparent);
+}
+
+.wizardFinishSpinner {
+	width: 1.25rem;
+	height: 1.25rem;
+	border-radius: 999px;
+	border: 2px solid color-mix(in srgb, var(--bootstrap-accent) 18%, transparent);
+	border-top-color: var(--bootstrap-accent);
+	animation: wizardFinishSpin 900ms linear infinite;
+}
+
+.wizardFinishIndicator[data-status="failed"] .wizardFinishSpinner {
+	border: 2px solid color-mix(in srgb, var(--color-danger-border, var(--color-border)) 22%, transparent);
+	border-top-color: var(--color-danger-text, var(--color-text));
+	animation: none;
+	transform: rotate(45deg);
+	border-radius: var(--radius-sm);
+	width: 1rem;
+	height: 1rem;
+}
+
+.wizardFinishCopy {
+	display: grid;
+	gap: var(--space-1);
+	min-width: 0;
+}
+
+.wizardFinishTitle {
+	@include text-title;
+	margin: 0;
+}
+
+.wizardFinishDescription,
+.wizardFinishMessage,
+.wizardFinishHint {
+	margin: 0;
+	color: var(--color-text-muted);
+}
+
+.wizardFinishMessage[data-status="failed"] {
+	color: var(--color-danger-text, var(--color-text));
+}
+
+.wizardFinishHint {
+	@include text-caption;
+}
+
+.wizardFinishActions {
+	display: flex;
+	gap: var(--space-3);
+	flex-wrap: wrap;
+	padding-top: var(--space-1);
+}
+
+@keyframes wizardFinishSpin {
+	from {
+		transform: rotate(0deg);
+	}
+
+	to {
+		transform: rotate(360deg);
+	}
+}
+
 @include respond-down(tablet) {
   .summaryGrid,
   .wizardBody {
@@ -527,13 +660,45 @@
   }
 
   .wizardPanel {
-    width: calc(100vw - (var(--space-4) * 2));
+    width: 100vw;
-    max-height: calc(100dvh - (var(--space-4) * 2));
+    max-height: 100dvh;
-    margin: var(--space-4) auto;
+    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,6 +1,6 @@
 // Path: Frontend/src/components/workspace-home/WorkspaceHome/WorkspaceHome.tsx
 
-import { For, Show, createEffect, createMemo, createSignal, type JSX } from "solid-js";
+import { For, Show, createEffect, createMemo, createSignal, onCleanup, type JSX } from "solid-js";
 import { Portal } from "solid-js/web";
 import { createStore } from "solid-js/store";
 import { resolveAPIBase } from "../../../lib/api";
@@ -21,6 +21,31 @@ type BootstrapSubmissionState = {
 	error: string;
 };
 
+type InstanceForm = {
+	protocol: "http" | "https";
+	access: "local" | "remote";
+	host: string;
+};
+
+type ModeForm = {
+	mode: "personal" | "organizational";
+	name: string;
+};
+
+type AdminForm = {
+	displayName: string;
+	email: string;
+	password: string;
+};
+
+type StructureForm = {
+	departmentName: string;
+	teamName: string;
+	projectName: string;
+};
+
+type MaterializationState = "not_started" | "pending" | "running" | "succeeded" | "failed";
+
 const bootstrapStepDefinitions: readonly BootstrapStepDefinition[] = [
 	{
 		id: "instance",
@@ -44,42 +69,45 @@ const bootstrapStepDefinitions: readonly BootstrapStepDefinition[] = [
 	},
 ];
 
-const defaultInstanceForm = {
+const defaultInstanceForm: InstanceForm = {
 	protocol: "http",
 	access: "local",
 	host: "localhost",
-} as const;
+};
 
-const defaultModeForm = {
+const defaultModeForm: ModeForm = {
 	mode: "personal",
-} as const;
+	name: "",
+};
 
-const defaultAdminForm = {
+const defaultAdminForm: AdminForm = {
 	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 = {
+const defaultStructureForm: StructureForm = {
 	...personalStructureDefaults,
 	projectName: "Project",
-} as const;
+};
 
 const initialSubmissionState = (): BootstrapSubmissionState => ({
 	status: "idle",
 	error: "",
 });
 
+const materializationPollIntervalMs = 2000;
+
 const readResponseBody = async (response: Response): Promise<unknown> => {
 	const raw = await response.text();
 
@@ -94,6 +122,52 @@ const readResponseBody = async (response: Response): Promise<unknown> => {
 	}
 };
 
+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;
@@ -101,10 +175,10 @@ type WorkspaceHomeProps = {
 
 export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 	const appShellData = useAppShellData();
-	const [instanceForm, setInstanceForm] = createStore({ ...defaultInstanceForm });
+	const [instanceForm, setInstanceForm] = createStore<InstanceForm>({ ...defaultInstanceForm });
-	const [modeForm, setModeForm] = createStore({ ...defaultModeForm });
+	const [modeForm, setModeForm] = createStore<ModeForm>({ ...defaultModeForm });
-	const [adminForm, setAdminForm] = createStore({ ...defaultAdminForm });
+	const [adminForm, setAdminForm] = createStore<AdminForm>({ ...defaultAdminForm });
-	const [structureForm, setStructureForm] = createStore({ ...defaultStructureForm });
+	const [structureForm, setStructureForm] = createStore<StructureForm>({ ...defaultStructureForm });
 	const [stepState, setStepState] = createStore<Record<BootstrapStepKey, BootstrapSubmissionState>>({
 		instance: initialSubmissionState(),
 		mode: initialSubmissionState(),
@@ -114,7 +188,56 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 	const [isBootstrapStateResolved, setIsBootstrapStateResolved] = createSignal(false);
 	const [isBootstrapComplete, setIsBootstrapComplete] = createSignal(false);
 	const [isWizardOpen, setIsWizardOpen] = createSignal(false);
+	const [isFinishingBootstrapFlow, setIsFinishingBootstrapFlow] = createSignal(false);
 	const [currentStepIndex, setCurrentStepIndex] = createSignal(0);
+	const installation = createMemo(() => appShellData.installation());
+	const materializationState = createMemo<MaterializationState>(() => {
+		const status = installation()?.materializationStatus;
+
+		switch (status) {
+			case "pending":
+			case "running":
+			case "failed":
+			case "succeeded":
+			case "not_started":
+				return status;
+			default:
+				return installation()?.isBootstrapped ? "succeeded" : "not_started";
+		}
+	});
+	const isBootstrapPersisted = createMemo(() => installation()?.isBootstrapped ?? false);
+	const isMaterializationInFlight = createMemo(
+		() => materializationState() === "pending" || materializationState() === "running",
+	);
+	const hasMaterializationFailed = createMemo(() => materializationState() === "failed");
+	const showBootstrapFinishingState = createMemo(
+		() => isFinishingBootstrapFlow() && (isMaterializationInFlight() || hasMaterializationFailed()),
+	);
+	const materializationStatusLabel = createMemo(() => {
+		switch (materializationState()) {
+			case "pending":
+				return "Materialization queued";
+			case "running":
+				return "Materialization running";
+			case "failed":
+				return "Materialization failed";
+			case "succeeded":
+				return "Ready";
+			default:
+				return "Not started";
+		}
+	});
+	const materializationMessage = createMemo(() => {
+		if (isMaterializationInFlight()) {
+			return "Your bootstrap is saved. The worker is still creating the POSIX skeleton and rebuilding the app shell index.";
+		}
+
+		if (hasMaterializationFailed()) {
+			return installation()?.materializationError || "Bootstrap saved, but background materialization did not finish cleanly.";
+		}
+
+		return "";
+	});
 
 	createEffect(() => {
 		if (modeForm.mode === "personal") {
@@ -143,18 +266,63 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 			return;
 		}
 
-		const installationAccessor = appShellData.installation;
+		if (!isBootstrapPersisted()) {
-		const installation = typeof installationAccessor === "function" ? installationAccessor() : undefined;
+			setIsFinishingBootstrapFlow(false);
-		const isPersistedBootstrap = installation?.isBootstrapped ?? false;
-		const wasComplete = isBootstrapComplete();
-
-		setIsBootstrapComplete(isPersistedBootstrap);
-		setIsWizardOpen(!isPersistedBootstrap);
-		setIsBootstrapStateResolved(true);
-
-		if (!isPersistedBootstrap && wasComplete) {
 			resetWizardState();
 		}
+
+		setIsBootstrapComplete(isBootstrapPersisted() && !isMaterializationInFlight());
+		setIsWizardOpen(!isBootstrapPersisted() || showBootstrapFinishingState());
+		setIsBootstrapStateResolved(true);
+	});
+
+	createEffect(() => {
+		if (!isFinishingBootstrapFlow()) {
+			return;
+		}
+
+		if (isMaterializationInFlight() || hasMaterializationFailed()) {
+			return;
+		}
+
+		setIsFinishingBootstrapFlow(false);
+		setIsWizardOpen(false);
+	});
+
+	createEffect(() => {
+		if (!isBootstrapPersisted() || !isMaterializationInFlight()) {
+			return;
+		}
+
+		let cancelled = false;
+		let timeoutId: number | undefined;
+
+		const scheduleReload = (): void => {
+			timeoutId = window.setTimeout(async () => {
+				if (cancelled) {
+					return;
+				}
+
+				// The final bootstrap step only persists relational state. Poll while the
+				// worker is materializing the POSIX skeleton so the page can transition from
+				// queued/running to ready/failed without a manual refresh.
+				await appShellData.reload();
+
+				if (!cancelled && isBootstrapPersisted() && isMaterializationInFlight()) {
+					scheduleReload();
+				}
+			}, materializationPollIntervalMs);
+		};
+
+		scheduleReload();
+
+		onCleanup(() => {
+			cancelled = true;
+
+			if (timeoutId !== undefined) {
+				window.clearTimeout(timeoutId);
+			}
+		});
 	});
 
 	const sidebarToggleLabel = (): string =>
@@ -163,13 +331,15 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 	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 canDismissWizard = (): boolean => isBootstrapPersisted() && !isMaterializationInFlight();
 
 	const resetWizardState = (): void => {
 		setInstanceForm({ ...defaultInstanceForm });
@@ -183,6 +353,7 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 			structure: initialSubmissionState(),
 		});
 		setCurrentStepIndex(0);
+		setIsFinishingBootstrapFlow(false);
 	};
 
 	const submitStep = async (step: BootstrapStepKey, payload: unknown): Promise<boolean> => {
@@ -200,11 +371,7 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 			const data = await readResponseBody(response);
 
 			if (!response.ok) {
-				throw new Error(
+				throw new Error(readResponseError(step, data));
-					typeof data?.error?.message === "string"
-						? data.error.message
-						: `Bootstrap ${step} request failed.`,
-				);
 			}
 
 			setStepState(step, {
@@ -246,12 +413,11 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 
 		if (isLastStep()) {
 			await appShellData.reload();
-			const installationAccessor = appShellData.installation;
-			const installation = typeof installationAccessor === "function" ? installationAccessor() : undefined;
-			const isPersistedBootstrap = installation?.isBootstrapped ?? false;
 
-			setIsBootstrapComplete(isPersistedBootstrap);
+			const shouldShowFinishingState = isBootstrapPersisted() && (isMaterializationInFlight() || hasMaterializationFailed());
-			setIsWizardOpen(!isPersistedBootstrap);
+			setIsFinishingBootstrapFlow(shouldShowFinishingState);
+			setIsBootstrapComplete(isBootstrapPersisted() && !isMaterializationInFlight());
+			setIsWizardOpen(!isBootstrapPersisted() || shouldShowFinishingState);
 			setIsBootstrapStateResolved(true);
 			return;
 		}
@@ -316,11 +482,16 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 				</div>
 
 				<section class={styles.hero} data-slot="workspace-home-hero">
-					<span class={styles.eyebrow}>Bootstrap</span>
+					<h1 class={styles.title}>{isBootstrapPersisted() ? appShellData.activeServer().name : bootstrapTargetLabel()}</h1>
-					<h1 class={styles.title}>{isBootstrapComplete() ? appShellData.activeServer().name : bootstrapTargetLabel()}</h1>
+				<Show when={isBootstrapStateResolved() && !isBootstrapPersisted()}>
-					<Show when={isBootstrapStateResolved() && !isBootstrapComplete()}>
 					<div class={styles.heroActions}>
-							<button type="button" class={styles.primaryButton} onClick={(): void => setIsWizardOpen(true)}>
+						<button
+							type="button"
+							class={styles.primaryButton}
+							onClick={(): void => {
+								setIsWizardOpen(true);
+							}}
+						>
 							Open bootstrap wizard
 						</button>
 					</div>
@@ -341,12 +512,64 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 									</h2>
 								</div>
 								<Show when={canDismissWizard()}>
-									<button type="button" class={styles.wizardCloseButton} onClick={(): void => setIsWizardOpen(false)}>
+									<button
+										type="button"
+										class={styles.wizardCloseButton}
+										onClick={(): void => {
+											setIsWizardOpen(false);
+										}}
+									>
 										Close
 									</button>
 								</Show>
 							</header>
 
+							<Show
+								when={!showBootstrapFinishingState()}
+								fallback={
+									<div class={styles.wizardFinishPanel} data-slot="bootstrap-wizard-finishing-state">
+										<div class={styles.wizardFinishShell}>
+											<div class={styles.wizardFinishStatusRow}>
+												<div class={styles.wizardFinishIndicator} data-status={materializationState()} aria-hidden="true">
+													<div class={styles.wizardFinishSpinner} />
+												</div>
+												<div class={styles.wizardFinishCopy}>
+													<span class={styles.wizardStepEyebrow}>Bootstrap status</span>
+													<h3 class={styles.wizardFinishTitle}>Finishing setup</h3>
+													<p class={styles.wizardFinishDescription}>
+														We saved your initial bootstrap. The server is finishing the last background setup steps now.
+													</p>
+												</div>
+											</div>
+											<div class={styles.statusBadge} data-status={materializationState()}>
+												{materializationStatusLabel()}
+											</div>
+											<Show when={materializationMessage()}>
+												<p class={styles.wizardFinishMessage} data-status={materializationState()}>
+													{materializationMessage()}
+												</p>
+											</Show>
+											<Show when={isMaterializationInFlight()}>
+												<p class={styles.wizardFinishHint}>This window will close automatically when setup is complete.</p>
+											</Show>
+										</div>
+										<Show when={hasMaterializationFailed()}>
+											<div class={styles.wizardFinishActions}>
+												<button
+													type="button"
+													class={styles.secondaryButton}
+													onClick={(): void => {
+														setIsFinishingBootstrapFlow(false);
+														setIsWizardOpen(false);
+													}}
+												>
+													Close
+												</button>
+											</div>
+										</Show>
+									</div>
+								}
+							>
 								<div class={styles.wizardBody}>
 									<aside class={styles.wizardSidebar} data-slot="bootstrap-wizard-sidebar">
 									<nav class={styles.wizardSteps} aria-label="Bootstrap steps">
@@ -382,7 +605,9 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 									<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 class={styles.statusBadge} data-status={currentStepState().status}>
+									{statusLabel(currentStepState())}
+								</div>
 							</div>
 
 									<form class={styles.form} onSubmit={handleCurrentStepSubmit}>
@@ -390,14 +615,24 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 											<>
 												<label class={styles.field}>
 													<span class={styles.fieldLabel}>Protocol</span>
-													<select value={instanceForm.protocol} onInput={(event): void => setInstanceForm("protocol", event.currentTarget.value)}>
+												<select
+													value={instanceForm.protocol}
+													onInput={(event): void =>
+														setInstanceForm("protocol", event.currentTarget.value as InstanceForm["protocol"])
+													}
+												>
 														<option value="http">http</option>
 														<option value="https">https</option>
 													</select>
 												</label>
 												<label class={styles.field}>
 													<span class={styles.fieldLabel}>Access</span>
-													<select value={instanceForm.access} onInput={(event): void => setInstanceForm("access", event.currentTarget.value)}>
+												<select
+													value={instanceForm.access}
+													onInput={(event): void =>
+														setInstanceForm("access", event.currentTarget.value as InstanceForm["access"])
+													}
+												>
 														<option value="local">local</option>
 														<option value="remote">remote</option>
 													</select>
@@ -415,13 +650,28 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 										</Show>
 
 						<Show when={currentStep().id === "mode"}>
+							<>
 								<label class={styles.field}>
 									<span class={styles.fieldLabel}>Mode</span>
-												<select value={modeForm.mode} onInput={(event): void => setModeForm("mode", event.currentTarget.value)}>
+								<select
+									value={modeForm.mode}
+									onInput={(event): void => setModeForm("mode", event.currentTarget.value as ModeForm["mode"])}
+								>
 										<option value="personal">personal</option>
 										<option value="organizational">organizational</option>
 									</select>
 								</label>
+								<label class={styles.field}>
+									<span class={styles.fieldLabel}>Server name</span>
+									<input
+										type="text"
+										value={modeForm.name}
+										required
+										onInput={(event): void => setModeForm("name", event.currentTarget.value)}
+										placeholder={bootstrapNamePlaceholder()}
+									/>
+								</label>
+							</>
 						</Show>
 
 										<Show when={currentStep().id === "admin"}>
@@ -450,8 +700,11 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 													type="password"
 													value={adminForm.password}
 													onInput={(event): void => setAdminForm("password", event.currentTarget.value)}
-														placeholder="Temporary for echo testing"
+													placeholder="Create a strong password"
 												/>
+												<small class={styles.fieldHelp}>
+													Use at least 12 characters with uppercase, lowercase, numbers, and symbols.
+												</small>
 											</label>
 											</>
 										</Show>
@@ -495,7 +748,9 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 												type="button"
 												class={styles.secondaryButton}
 												disabled={isFirstStep()}
-												onClick={(): void => setCurrentStepIndex((index) => Math.max(index - 1, 0))}
+												onClick={(): void => {
+													setCurrentStepIndex((index) => Math.max(index - 1, 0));
+												}}
 											>
 												Back
 											</button>
@@ -515,6 +770,7 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 
 									</div>
 								</div>
+							</Show>
 						</section>
 					</div>
 				</Portal>

Frontend/src/lib/icons/index.ts

@@ -10,6 +10,7 @@ export { default as Folder } from "lucide-solid/icons/folder";
 export { default as Home } from "lucide-solid/icons/house";
 export { default as Keyboard } from "lucide-solid/icons/keyboard";
 export { default as LayoutGrid } from "lucide-solid/icons/layout-grid";
+export { default as ListCollapse } from "lucide-solid/icons/list-collapse";
 export { default as LogOut } from "lucide-solid/icons/log-out";
 export { default as Moon } from "lucide-solid/icons/moon";
 export { default as Plus } from "lucide-solid/icons/plus";
@@ -18,5 +19,6 @@ export { default as Search } from "lucide-solid/icons/search";
 export { default as Settings } from "lucide-solid/icons/settings";
 export { default as Shield } from "lucide-solid/icons/shield";
 export { default as Sun } from "lucide-solid/icons/sun";
+export { default as UnfoldVertical } from "lucide-solid/icons/unfold-vertical";
 export { default as User } from "lucide-solid/icons/user";
 export { default as X } from "lucide-solid/icons/x";

Justfile

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