---
name: ibgib-create-client-workspace
description: >
  Scaffolds or integrates the unified CosmologyWorkspaceService (and WebCosmologyWorkspaceService)
  for initializing Cosmoses, managing member Galaxies, committing data, and syncing across peers.
---

# Skill: ibgib-create-client-workspace

## What This Skill Does

This skill wires the **`CosmologyWorkspaceService`** (from `@ibgib/core-gib`) and **`WebCosmologyWorkspaceService`** (from `@ibgib/web-gib`) into an `ibgib` client or fullstack application.

It replaces older, lower-level manual transforms (`createCosmosIbGib`, `addGalaxyToCosmos`, manual `getOrCreateBranchSpace`) with the unified, fail-fast Cosmology Workspace API:
1. **Cosmos Lifecycle**: Strict fail-fast `initCosmos` (throws if already exists) vs `ensureCosmos` (throws if not found).
2. **Galaxy Lifecycle**: Strict fail-fast `initGalaxy` (creates member galaxy + branchSpace + root folder item + default `main` branch + genesis snapshot) vs `ensureGalaxy`.
3. **Programmatic Data Mutation (`commitItems`)**: Commits file items and comments directly into galaxy branch spaces in pure `InnerSpace` or persistent storage without requiring a filesystem worktree.
4. **Two-Phase Peer Sync (`push` / `pull` / `sync`)**: Encapsulates WebSocket sync to remote space-gib hubs via device sync delegates.

For full architectural foundations, refer to [`docs/IBGIB_CLIENT_APPS_GUIDE.md`](../../../docs/IBGIB_CLIENT_APPS_GUIDE.md) and [`docs/impl/43_COSMOLOGY_WORKSPACE_SERVICE_IMPLEMENTATION.md`](../../../docs/impl/43_COSMOLOGY_WORKSPACE_SERVICE_IMPLEMENTATION.md).

---

## Code Pattern: Client Workspace Service Initialization

In client applications using `@ibgib/web-gib`:

```typescript
import { WebCosmologyWorkspaceService } from '@ibgib/web-gib/dist/cosmology/web-cosmology-workspace-service.mjs';
import { GalaxyPresetType } from '@ibgib/core-gib/dist/cosmology/galaxy/galaxy-configs.mjs';

// Automatically binds to the active client Metaspace and local storage space:
const workspace = new WebCosmologyWorkspaceService();

// 1. Initialize a new Cosmos (fails fast if already initialized)
const cosmos = await workspace.initCosmos({
    cosmosName: 'my-project',
    description: 'My project workspace',
});

// 2. Initialize a member Galaxy (creates branchSpace, main branch, and root folder)
const galaxyRes = await workspace.initGalaxy({
    cosmosName: 'my-project',
    galaxyName: 'code-1',
    discriminator: GalaxyPresetType.code,
    branchName: 'main',
    rootFolderName: 'root',
});

// 3. Programmatically commit files directly into the branch
await workspace.commitItems({
    cosmosName: 'my-project',
    galaxyName: 'code-1',
    branchName: 'main',
    items: [
        {
            action: 'create',
            path: 'src/index.ts',
            content: 'console.log("Hello from sovereign ibgib!");',
        },
    ],
    message: 'Initial commit via CosmologyWorkspaceService',
});

// 4. Two-Phase sync to remote Hub
await workspace.push({
    cosmosName: 'my-project',
    galaxyName: 'code-1',
    branchName: 'main',
    remoteUrl: 'https://space-gib.localhost',
});
```