@ibgib/web-gib 0.0.63 → 0.0.65

package/src/witness/space/web-in-memory-workspace-projection-space/web-in-memory-workspace-projection-space-v1.respec.mts

@@ -0,0 +1,305 @@
+/**
+ * @module web-in-memory-workspace-projection-space-v1.respec
+ *
+ * Unit tests for WebInMemoryWorkspaceProjectionSpace_V1 verifying in-memory
+ * virtual tree reification, scanning, glob filtering, status observation, and deletion.
+ */
+
+import {
+    respecfully, ifWe, ifWeMight, iReckon, firstOfEach
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { getGib } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
+import { hash } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { InnerSpace_V1 } from '@ibgib/core-gib/dist/witness/space/inner-space/inner-space-v1.mjs';
+// import { getSpaceIdFromIb } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-innerspace/metaspace-innerspace-helper.mjs';
+import { DEFAULT_INNER_SPACE_DATA_V1 } from '@ibgib/core-gib/dist/witness/space/inner-space/inner-space-types.mjs';
+import { putInSpace, persistTransformResult, registerNewIbGib } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { CMD_MODIFIER_WORKSPACE_SCAN } from '@ibgib/core-gib/dist/witness/space/workspace-projection-space/workspace-projection-space-constants.mjs';
+import { getBinIb } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
+import { BinIbGib_V1 } from '@ibgib/core-gib/dist/common/bin/bin-types.mjs';
+import { createB2tFSItemIbGib } from '@ibgib/core-gib/dist/vcs/item/item-helper.mjs';
+import { B2tFSItemIbGib_V1, BINARY_REL8N_NAME } from '@ibgib/core-gib/dist/vcs/item/item-types.mjs';
+import { getRepoStatus } from '@ibgib/core-gib/dist/vcs/status/status-helper.mjs';
+import { createB2tFSIndexIbGib, updateB2tFSIndexIbGib } from '@ibgib/core-gib/dist/vcs/index/index-helper.mjs';
+import { B2tFSBranchIbGib_V1 } from '@ibgib/core-gib/dist/vcs/branch/branch-types.mjs';
+
+import { WebInMemoryWorkspaceProjectionSpace_V1 } from './web-in-memory-workspace-projection-space-v1.mjs';
+
+const lc = `[web-in-memory-workspace-projection-space-v1.respec.mts]`;
+
+async function createFileWithContent({
+    name,
+    content,
+    space,
+}: {
+    name: string;
+    content: string | Uint8Array;
+    space: any;
+}): Promise<B2tFSItemIbGib_V1> {
+    const textStr = typeof content === 'string' ? content : new TextDecoder('utf8').decode(content);
+    const dataBuffer = typeof content === 'string' ? new TextEncoder().encode(content) : content;
+    const fileHash = await hash({ s: textStr });
+
+    const fileExt = name.includes('.') ? name.split('.').pop() || 'txt' : 'txt';
+    const binIb = getBinIb({
+        binHash: fileHash,
+        binExt: fileExt,
+        binEncoding: 'utf8',
+    });
+
+    const binIbGib: BinIbGib_V1 = {
+        ib: binIb,
+        data: dataBuffer,
+    };
+    binIbGib.gib = await getGib({ ibGib: binIbGib, hasTjp: false });
+    const binAddr = getIbGibAddr({ ibGib: binIbGib });
+
+    await putInSpace({ ibGib: binIbGib, space });
+    await registerNewIbGib({ ibGib: binIbGib, space });
+
+    const itemRes = await createB2tFSItemIbGib({
+        fsType: 'file',
+        name,
+        data: {
+            fileHash,
+        },
+        rel8ns: {
+            [BINARY_REL8N_NAME]: [binAddr],
+        },
+    });
+
+    await persistTransformResult({ resTransform: itemRes, space });
+    await registerNewIbGib({ ibGib: itemRes.newIbGib, space });
+
+    return itemRes.newIbGib as B2tFSItemIbGib_V1;
+}
+
+await respecfully(lc, `WebInMemoryWorkspaceProjectionSpace_V1 Specs`, async () => {
+
+    let backingSpace: InnerSpace_V1;
+    let wsSpace: WebInMemoryWorkspaceProjectionSpace_V1;
+
+    firstOfEach(lc, async () => {
+        backingSpace = new InnerSpace_V1({
+            ...DEFAULT_INNER_SPACE_DATA_V1,
+            name: 'b2s_main',
+            uuid: 'test_backing_uuid_1',
+        });
+        await backingSpace.initialized;
+
+        wsSpace = new WebInMemoryWorkspaceProjectionSpace_V1({
+            initialData: {
+                name: 'test_in_memory_ws',
+                uuid: 'ws_uuid_1',
+                workspaceRoot: '/',
+                vcsFolderName: '.vcsgib',
+            },
+            backingSpace,
+        });
+        await wsSpace.initialized;
+    });
+
+    await respecfully(lc, `Reification into In-Memory Virtual Tree`, async () => {
+        await ifWeMight(lc, `reifies file and folder hierarchies into virtual file map`, async () => {
+            const file1 = await createFileWithContent({ name: 'main.ts', content: 'console.log("hello");', space: backingSpace });
+            const file1Addr = getIbGibAddr({ ibGib: file1 });
+
+            const file2 = await createFileWithContent({ name: 'helper.ts', content: 'export const x = 42;', space: backingSpace });
+            const file2Addr = getIbGibAddr({ ibGib: file2 });
+
+            const srcFolderRes = await createB2tFSItemIbGib({
+                fsType: 'folder',
+                name: 'src',
+                rel8ns: {
+                    b2tfs_child: [file1Addr, file2Addr],
+                },
+            });
+            await persistTransformResult({ resTransform: srcFolderRes, space: backingSpace });
+            const srcFolder = srcFolderRes.newIbGib as B2tFSItemIbGib_V1;
+            const srcFolderAddr = getIbGibAddr({ ibGib: srcFolder });
+
+            const readmeFile = await createFileWithContent({ name: 'README.md', content: '# Project Docs', space: backingSpace });
+            const readmeAddr = getIbGibAddr({ ibGib: readmeFile });
+
+            const rootFolderRes = await createB2tFSItemIbGib({
+                fsType: 'folder',
+                name: 'my-repo',
+                rel8ns: {
+                    b2tfs_child: [srcFolderAddr, readmeAddr],
+                },
+            });
+            await persistTransformResult({ resTransform: rootFolderRes, space: backingSpace });
+            const rootFolder = rootFolderRes.newIbGib as B2tFSItemIbGib_V1;
+
+            // Reify into projection space
+            await putInSpace({ ibGib: rootFolder, space: wsSpace });
+
+            // Verify virtual tree
+            const paths = wsSpace.listVirtualPaths();
+            iReckon(lc, paths).includes('src');
+            iReckon(lc, paths).includes('src/main.ts');
+            iReckon(lc, paths).includes('src/helper.ts');
+            iReckon(lc, paths).includes('README.md');
+
+            const mainText = wsSpace.getVirtualText('src/main.ts');
+            iReckon(lc, mainText).willEqual('console.log("hello");');
+
+            const readmeText = wsSpace.getVirtualText('README.md');
+            iReckon(lc, readmeText).willEqual('# Project Docs');
+        });
+    });
+
+    await respecfully(lc, `Virtual Workspace Scan & Observation`, async () => {
+        await ifWeMight(lc, `scans virtual files, computes sha256 hashes, and extracts companion comments`, async () => {
+            // Set up virtual files directly
+            wsSpace.setVirtualFile('src/index.ts', 'const a = 1;');
+            wsSpace.setVirtualFile('src/.ib.index.ts.md', '# Note on index.ts\nThis is a companion note.');
+            wsSpace.setVirtualFile('docs/guide.md', '# Guide');
+            wsSpace.setVirtualFile('node_modules/pkg/index.js', 'module.exports = {};');
+            wsSpace.setVirtualFile('debug.log', 'test log');
+            wsSpace.setVirtualFile('.ibgibignore', 'node_modules/\n*.log\n!important.log');
+            wsSpace.setVirtualFile('important.log', 'keep this log');
+
+            const resWitness = await wsSpace.witness({
+                ib: wsSpace.ib,
+                data: {
+                    cmd: 'get',
+                    cmdModifiers: [CMD_MODIFIER_WORKSPACE_SCAN],
+                },
+            });
+
+            iReckon(lc, resWitness?.data?.success).isGonnaBeTrue();
+            const scanData = resWitness?.data?.scanResult;
+            iReckon(lc, scanData).isGonnaBeTruthy();
+
+            const files = scanData!.files;
+            iReckon(lc, files.has('src/index.ts')).isGonnaBeTrue();
+            iReckon(lc, files.has('docs/guide.md')).isGonnaBeTrue();
+            iReckon(lc, files.has('important.log')).isGonnaBeTrue();
+
+            // Filtered files
+            iReckon(lc, files.has('node_modules/pkg/index.js')).isGonnaBeFalse();
+            iReckon(lc, files.has('debug.log')).isGonnaBeFalse();
+
+            // File hash verification
+            const msgBytes = new TextEncoder().encode('const a = 1;');
+            const digestBuf = await crypto.subtle.digest('SHA-256', msgBytes.buffer as ArrayBuffer);
+            const expectedHash = Array.from(new Uint8Array(digestBuf)).map(b => b.toString(16).padStart(2, '0')).join('');
+            iReckon(lc, files.get('src/index.ts')?.fileHash).willEqual(expectedHash);
+
+            // Pending comments
+            const comments = scanData!.pendingComments;
+            iReckon(lc, comments.length).willEqual(1);
+            iReckon(lc, comments[0].topicName).willEqual('index.ts');
+            iReckon(lc, comments[0].targetRelPath).willEqual('src/index.ts');
+            iReckon(lc, comments[0].content).includes('Note on index.ts');
+        });
+    });
+
+    await respecfully(lc, `Isomorphic getRepoStatus with WebInMemoryWorkspaceProjectionSpace`, async () => {
+        await ifWeMight(lc, `detects untracked, modified, and deleted files in virtual workspace`, async () => {
+            const trackedFile = await createFileWithContent({ name: 'app.ts', content: 'version 1', space: backingSpace });
+            const trackedAddr = getIbGibAddr({ ibGib: trackedFile });
+
+            const rootFolderRes = await createB2tFSItemIbGib({
+                fsType: 'folder',
+                name: 'repo',
+                rel8ns: {
+                    b2tfs_child: [trackedAddr],
+                },
+            });
+            await persistTransformResult({ resTransform: rootFolderRes, space: backingSpace });
+            const rootFolder = rootFolderRes.newIbGib as B2tFSItemIbGib_V1;
+            const rootFolderAddr = getIbGibAddr({ ibGib: rootFolder });
+
+            // Create branch ibgib in backingSpace
+            const branchIbGib: B2tFSBranchIbGib_V1 = {
+                ib: 'b2tfs_branch main',
+                data: {
+                    name: 'main',
+                    uuid: 'main_branch_uuid',
+                },
+                rel8ns: {
+                    b2tfs_item: [rootFolderAddr],
+                },
+            };
+            branchIbGib.gib = await getGib({ ibGib: branchIbGib, hasTjp: false });
+            const branchAddr = getIbGibAddr({ ibGib: branchIbGib });
+            await putInSpace({ ibGib: branchIbGib, space: backingSpace });
+            await registerNewIbGib({ ibGib: branchIbGib, space: backingSpace });
+
+            // Reify into virtual space
+            await putInSpace({ ibGib: rootFolder, space: wsSpace });
+
+            const mockMetaspace = {
+                getLocalUserSpaces: async () => [backingSpace],
+                registerNewIbGib: async ({ ibGib }: { ibGib: any }) => {
+                    await putInSpace({ ibGib, space: backingSpace });
+                },
+            } as any;
+
+            // Create index in backingSpace with unstaged working tree
+            let indexIbGib = await createB2tFSIndexIbGib({
+                // spaceId: getSpaceIdFromIb(backingSpace.ib) || 'test_backing_uuid_1',
+                activeSpaceId: backingSpace.data?.uuid || 'test_backing_uuid_1',
+                activeBranchName: 'main',
+                branchAddr,
+                space: backingSpace,
+                metaspace: mockMetaspace,
+            });
+
+            // 1. Initial status: clean
+            let status = await getRepoStatus({
+                metaspace: mockMetaspace,
+                localSpace: backingSpace,
+                workspaceSpace: wsSpace,
+                indexIbGib,
+            });
+            iReckon(lc, status.untracked.length).willEqual(0);
+            iReckon(lc, status.modified.length).willEqual(0);
+            iReckon(lc, status.deleted.length).willEqual(0);
+
+            // 2. Modify app.ts in virtual space
+            wsSpace.setVirtualFile('app.ts', 'version 2 modified');
+            // 3. Add untracked new-file.ts in virtual space
+            wsSpace.setVirtualFile('new-file.ts', 'new content');
+
+            status = await getRepoStatus({
+                metaspace: mockMetaspace,
+                localSpace: backingSpace,
+                workspaceSpace: wsSpace,
+                indexIbGib,
+            });
+
+            const modPaths = status.modified.map(m => m.path);
+            const untrackedPaths = status.untracked.map(u => u.path);
+            iReckon(lc, modPaths).includes('app.ts');
+            iReckon(lc, untrackedPaths).includes('new-file.ts');
+
+            // 4. Delete app.ts from virtual space
+            await wsSpace.witness({
+                ib: wsSpace.ib,
+                data: {
+                    cmd: 'delete',
+                },
+                ibGibs: [{
+                    ib: 'item',
+                    data: { name: 'app.ts' },
+                } as any],
+            });
+
+            status = await getRepoStatus({
+                metaspace: mockMetaspace,
+                localSpace: backingSpace,
+                workspaceSpace: wsSpace,
+                indexIbGib,
+            });
+
+            const delPaths = status.deleted.map(d => d.path);
+            iReckon(lc, delPaths).includes('app.ts');
+            iReckon(lc, status.untracked.map(u => u.path)).includes('new-file.ts');
+        });
+    });
+});

package/tools/auto-generated-agent-skills/skills/ibgib-create-app/SKILL.md

@@ -1,43 +1,69 @@
 ---
 name: ibgib-create-app
-description: The master coordinator skill for scaffolding a complete "Hello World" ibgib application. Orchestrates sub-skills for core engine, app witness, and UI shell.
+description: The Master Coordinator skill for scaffolding complete ibgib applications. Prompts for topology archetype (Full-Stack, Client-Only SPA, Browser Extension, or Server-Only) and workspace context, then orchestrates client and server sub-skills.
 ---
 
-# ibgib-create-app
-
-This is a Meta-Skill that coordinates multiple sub-skills to create a functional, buildable ibgib application from scratch (Greenfield) or to add ibgib to an existing project (Brownfield).
-
-## Goal
-To orchestrate the modular sub-skills so the final application is type-safe, buildable, and consistent.
-
-## Sub-Skills
-This coordinator uses:
-1. `ibgib-create-app-core`: FOUNDATION (Bootstrap, Global State, Types).
-2. `ibgib-create-app-witness`: LOGIC (App Witness class, commands, helpers).
-3. `ibgib-create-shell`: UI (Shell service, event handlers).
-4. `ibgib-create-component`: COMPONENT (Initial main app component - optional but recommended).
-  * _Note: You can simple create a plain-vanilla shell that is not encapsulated in an ibgib component, but you will be losing all of the plumbing associated with a backing ibgib which makes this the recommended pattern._
-
-## Parameters (Shared State)
-The agent must generate and maintain these tokens across sub-skill executions:
-- `{{APP_NAME}}`: kebab-case (e.g. `test-app`)
-- `{{APP_DIR_NAME}}`: folder name (e.g. `test-app`)
-- `{{APP_CLASSNAME_PREFIX}}`: PascalCase (e.g. `TestApp`)
-- `{{APP_CLASSNAME}}`: Full class name (e.g. `TestAppApp_V1`)
-- `{{APP_HUMAN_NAME}}`: Natural language (e.g. `Test App`)
-- `{{APP_VAR_NAME}}`: camelCase (e.g. `testApp`)
-- `{{APP_NAME_UPPER}}`: SCREAMING_SNAKE_CASE (e.g. `TEST_APP`)
-
-## Workflow for Greenfield (Fresh App)
-1. **Prepare Tokens**: Generate/confirm all tokens. Generate UUIDs for IDs in templates.
-2. **Core Engine**: Call `ibgib-create-app-core` to scaffold the 7 foundational files.
-3. **App Witness**: Call `ibgib-create-app-witness` to scaffold the witness logic.
-4. **UI Shell**: Call `ibgib-create-shell` to scaffold the shell service.
-5. **Main Component**: Call `ibgib-create-component` to create the initial app component.
-6. **Hook Up**:
-    - Update `bootstrap.mts` to use the shell service and register the component.
-    - Create `package.json` and `tsconfig.json` (if in a new directory).
-
-## Workflow for Brownfield (Existing Project)
-1. Determine the source root.
-2. Follow the Greenfield steps but skip `package.json` and `tsconfig.json` creation; instead, integrate with existing ones.
+# Skill: ibgib-create-app (Master Coordinator)
+
+## What This Skill Does
+
+This is the **Master Coordinator Skill** for scaffolding applications in the `ibgib` ecosystem. It evaluates the desired application topology and orchestrates the appropriate sub-skills to produce a buildable, type-safe, and consistent application.
+
+For complete architectural background, refer to:
+*   **The App Guide**: [`docs/CREATING_IBGIB_APPS_GUIDE.md`](../../../docs/CREATING_IBGIB_APPS_GUIDE.md)
+*   **The Client Guide**: [`docs/IBGIB_CLIENT_APPS_GUIDE.md`](../../../docs/IBGIB_CLIENT_APPS_GUIDE.md)
+*   **The Server Guide**: [`docs/IBGIB_SERVER_APPS_GUIDE.md`](../../../docs/IBGIB_SERVER_APPS_GUIDE.md)
+
+---
+
+## Topology Archetypes
+
+Before scaffolding, confirm the target topology with the developer:
+
+1.  **`fullstack`** (e.g. `space-gib` style):
+    *   SPA Client (`src/client`) + Node `serve-gib` Server (`src/server`) + Shared Types (`src/common`).
+    *   Containerized via Docker Compose & Traefik.
+    *   *Sub-skills used*: `ibgib-create-client-app` + `ibgib-create-server-app`.
+2.  **`client-only-spa`**:
+    *   Standalone in-browser SPA utilizing IndexedDB space and syncing to a remote ibgib Hub.
+    *   *Sub-skills used*: `ibgib-create-client-app`.
+3.  **`browser-extension`** (e.g. `blank-gib` style):
+    *   Manifest v3 extension with background worker and popup UI.
+    *   *Sub-skills used*: `ibgib-create-client-app`.
+4.  **`server-only`**:
+    *   Dedicated Space & Identity Hub or custom API service.
+    *   *Sub-skills used*: `ibgib-create-server-app`.
+
+---
+
+## Workspace Context
+
+Confirm the target workspace mode:
+*   **`monorepo`** (Default): App is created within the `apps/` directory of this monorepo or a downstream monorepo clone. Uses monorepo workspace links (`@ibgib/*: "*"`) and extends `../../tsconfig.base.json`.
+*   **`standalone`**: App is an independent single-package repository consuming published npm packages.
+
+---
+
+## Coordinated Sub-Skills
+
+*   **`ibgib-create-client-app`**: Coordinates client core bootstrap, app witness, UI shell, components, and Keystone identity wiring.
+    *   $\hookrightarrow$ `ibgib-create-client-app-core`
+    *   $\hookrightarrow$ `ibgib-create-client-app-witness`
+    *   $\hookrightarrow$ `ibgib-create-client-shell`
+    *   $\hookrightarrow$ `ibgib-create-client-identity`
+    *   $\hookrightarrow$ `ibgib-create-component`
+*   **`ibgib-create-server-app`**: Scaffolds the Node `serve-gib` backend runner, `tsconfig.server.json`, `Dockerfile`, and `docker-compose.yml`.
+
+---
+
+## Master Scaffolding Workflow
+
+1.  **Gather Tokens**: Confirm application names, paths, ports, and generate UUIDs using:
+    ```bash
+    node .agents/skills/ibgib-create-client-app-core/generate-id.js
+    ```
+2.  **Scaffold Client**: If archetype is `fullstack`, `client-only-spa`, or `browser-extension`, invoke **`ibgib-create-client-app`**.
+3.  **Scaffold Server**: If archetype is `fullstack` or `server-only`, invoke **`ibgib-create-server-app`**.
+4.  **Wire Build Pipeline**:
+    *   For monorepo apps: Add `build-[app-name].mts` in `build/src/concrete-build/` and add npm scripts to root `package.json`.
+    *   For standalone apps: Verify local `package.json` build and watch scripts.

package/tools/auto-generated-agent-skills/skills/ibgib-create-client-app/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ibgib-create-client-app
+description: Coordinator skill for scaffolding an ibgib client application (SPA, browser extension, or client frontend of a fullstack project).
+---
+
+# Skill: ibgib-create-client-app
+
+## What This Skill Does
+
+Coordinates the modular sub-skills required to scaffold a fully functional, type-safe, and buildable `ibgib` client application.
+
+For architectural foundations, refer to [`docs/IBGIB_CLIENT_APPS_GUIDE.md`](../../../docs/IBGIB_CLIENT_APPS_GUIDE.md).
+
+---
+
+## Coordinated Sub-Skills
+
+1. **`ibgib-create-client-app-core`**: Foundation (Three-tier Bootstrap, Metaspace, Local IndexedDB Storage, Types).
+2. **`ibgib-create-client-app-witness`**: Domain Logic (App Witness class, commands, helpers).
+3. **`ibgib-create-client-shell`**: UI Shell (Shell service, window event listeners).
+4. **`ibgib-create-component`**: Main Application Web Component.
+5. **`ibgib-create-client-identity`**: Keystone Identity Components & Remote Hub Sync wiring.
+
+---
+
+## Parameters (Shared Tokens)
+
+Confirm or generate these tokens:
+- `{{APP_NAME}}`: kebab-case (e.g. `my-app`)
+- `{{APP_DIR_NAME}}`: folder name (e.g. `my-app`)
+- `{{APP_CLASSNAME_PREFIX}}`: PascalCase (e.g. `MyApp`)
+- `{{APP_CLASSNAME}}`: Full class name (e.g. `MyAppApp_V1`)
+- `{{APP_HUMAN_NAME}}`: Natural language (e.g. `My App`)
+- `{{APP_VAR_NAME}}`: camelCase (e.g. `myApp`)
+- `{{APP_NAME_UPPER}}`: SCREAMING_SNAKE_CASE (e.g. `MY_APP`)
+- `{{DB_NAME}}`: IndexedDB name (e.g. `my_app_db`)
+- `{{APP_UUID}}`: Generated fresh via `node .agents/skills/ibgib-create-client-app-core/generate-id.js`
+
+---
+
+## Workflow for Greenfield (Fresh Client App)
+
+1. **Prepare Tokens**: Generate fresh `{{APP_UUID}}` and confirm tokens.
+2. **Core Engine**: Call `ibgib-create-client-app-core` to scaffold foundational bootstrap files.
+3. **App Witness**: Call `ibgib-create-client-app-witness` to scaffold domain logic.
+4. **UI Shell**: Call `ibgib-create-client-shell` to scaffold the shell service.
+5. **Main Component**: Call `ibgib-create-component` to create the initial app view.
+6. **Identity Wiring**: Call `ibgib-create-client-identity` to register Keystone identity components.
+7. **Hook Up**:
+   - Verify `bootstrap.mts` invokes shell `onEngineReady()` and registers identity components.
+   - Configure build script (`build-[app].mts` in monorepo, or local build script if standalone).

package/tools/auto-generated-agent-skills/skills/{ibgib-create-app-core → ibgib-create-client-app-core}/SKILL.md

@@ -1,34 +1,38 @@
 ---
-name: ibgib-create-app-core
+name: ibgib-create-client-app-core
 description: >
-  Scaffolds the foundational ibgib bootstrap flow and global state management.
+  Scaffolds the foundational ibgib client bootstrap flow and global state management.
   Generates the 8 foundational files (index.html, index.mts, script.mts,
   bootstrap.mts, constants.mts, types.mts, helpers.web.mts, and style.css)
-  required for an ibgib app to boot. Supports both greenfield and brownfield projects.
+  required for an ibgib client app to boot. Supports both greenfield and brownfield projects.
 ---
 
-# Skill: ibgib-create-app-core
+# Skill: ibgib-create-client-app-core
 
 ## What This Skill Does
 
-Generates the engineering foundation for an ibgib app. This includes:
+Generates the engineering foundation for an `ibgib` client application (SPA, browser extension, or client frontend of a full-stack project). This includes:
 - **Global State**: Wiring `globalThis.ibgib` with the appropriate app-specific sub-objects.
-- **Bootstrap flow**: Handling `DOMContentLoaded` and asynchronously loading the heavy ibgib engine.
+- **Three-Tier Bootstrap Flow**:
+  1. `Metaspace`: Initializes the runtime environment and event bus.
+  2. `Local Space`: Boots the persistent `IndexedDB` local user storage.
+  3. `App Witness`: Prepares the engine for loading the domain logic witness.
 - **Storage**: Initializing IndexedDB spaces.
 - **Types & Helpers**: Providing the basic framework for identity and witness coordination.
 
-This skill is often the first step in creating a new app, or used to "ibgib-ify" an existing project. It does this by bootstrapping the environment/storage so that global state, the "metaspace" and the default concrete local user space (backed by IndexedDB). It does NOT generate the App Witness (the business logic) or the UI Shell; use `ibgib-create-app-witness` and `ibgib-create-shell` for those.
+For the complete architectural guide, refer to [`docs/IBGIB_CLIENT_APPS_GUIDE.md`](../../../docs/IBGIB_CLIENT_APPS_GUIDE.md).
+
+> [!NOTE]
+> This skill does NOT generate the App Witness (the business logic), UI Shell, or Identity wiring; use `ibgib-create-client-app-witness`, `ibgib-create-client-shell`, and `ibgib-create-client-identity` for those.
 
 ---
 
 ## Pre-Requisites (check before running)
 
 1. Confirm the target directory exists or ask where to create files.
-2. Verify that `@ibgib/ts-gib`, `@ibgib/helper-gib`, `@ibgib/core-gib`, and
-   `@ibgib/web-gib` are available in the workspace.
-3. Confirm the project has an `AUTO-GENERATED-version.mts` file, or note that
-   one is needed. Create the `generate-version-file.js` if needed and incorporate in the prebuild script.
-   * the source for this that you can copy is at `.agents/skills/ibgib-create-app-core/generate-version-file.js`
+2. Verify that `@ibgib/ts-gib`, `@ibgib/helper-gib`, `@ibgib/core-gib`, and `@ibgib/web-gib` are available in the workspace.
+3. Confirm the project has an `AUTO-GENERATED-version.mts` file, or note that one is needed. Create the `generate-version-file.js` if needed and incorporate in the prebuild script.
+   * the source for this that you can copy is at `.agents/skills/ibgib-create-client-app-core/generate-version-file.js`
 
 ---
 
@@ -53,23 +57,23 @@ This skill is often the first step in creating a new app, or used to "ibgib-ify"
 Derive tokens from the developer's answers. Generate a fresh `{{APP_UUID}}` using:
 
 ```bash
-node .agents/skills/ibgib-create-app-core/generate-id.js
+node .agents/skills/ibgib-create-client-app-core/generate-id.js
 ```
 
 ### 2. Generate all files
 
-Apply token substitutions to templates in `templates/` and write to the target directory (`src/` by default).
+Apply token substitutions to templates in `templates/` and write to the target directory (`src/` or `src/client/`).
 
 | Template file | Output file |
 |---|---|
-| templates/index.html.template | `index.html` |
-| templates/index.mts.template | `index.mts` |
-| templates/script.mts.template | `script.mts` |
-| templates/bootstrap.mts.template | `bootstrap.mts` |
-| templates/constants.mts.template | `constants.mts` |
-| templates/types.mts.template | `types.mts` |
-| templates/helpers.web.mts.template | `helpers.web.mts` |
-| templates/style.css.template | `style.css` (if missing) |
+| `templates/index.html.template` | `index.html` |
+| `templates/index.mts.template` | `index.mts` |
+| `templates/script.mts.template` | `script.mts` |
+| `templates/bootstrap.mts.template` | `bootstrap.mts` |
+| `templates/constants.mts.template` | `constants.mts` |
+| `templates/types.mts.template` | `types.mts` |
+| `templates/helpers.web.mts.template` | `helpers.web.mts` |
+| `templates/style.css.template` | `style.css` (if missing) |
 
 ### 3. Replace `genuuid` placeholders
 

package/tools/auto-generated-agent-skills/skills/{ibgib-create-app-core → ibgib-create-client-app-core}/generate-id.js

@@ -1,4 +1,4 @@
-const crypto = require('crypto');
+import crypto from 'node:crypto';
 
 const yearStr = new Date().getFullYear().toString().slice(-2);
 

package/tools/auto-generated-agent-skills/skills/{ibgib-create-app-witness → ibgib-create-client-app-witness}/SKILL.md

@@ -1,24 +1,28 @@
 ---
-name: ibgib-create-app-witness
+name: ibgib-create-client-app-witness
 description: >
-  Scaffolds the App Witness (engine) logic for an ibgib application.
+  Scaffolds the App Witness (domain logic engine) for an ibgib client application.
   Generates the core business logic files including the App class,
   constants, helpers, and types.
 ---
 
-# Skill: ibgib-create-app-witness
+# Skill: ibgib-create-client-app-witness
 
 ## What This Skill Does
 
-An ibgib alone is a data description. A "witness" is a class that provides behavior that wraps this ibgib data shape via a single function with the following basic shape: `witness(arg: IbGib_V1): Promise<IbGib_V1>`. So a witness provides a single binding point that takes in an ibgib and returns one. This skill generates the "Brain" of an ibgib app that implements this interface. Concretely, the generated app witness class is one that adds plumbing for parsing incoming comments (commands) sent by the user or-other agents. A web app defaults to a single configuration/comment (`--interactive`), but this can be extended to have features enabled/disabled per context.
+An ibgib alone is a data description. A "witness" is a class that provides behavior that wraps this ibgib data shape via a single function with the following basic shape: `witness(arg: IbGib_V1): Promise<IbGib_V1>`. So a witness provides a single binding point that takes in an ibgib and returns one.
+
+This skill generates the domain "Brain" (App Witness) of an `ibgib` client app that implements this interface. Concretely, the generated app witness class adds plumbing for parsing incoming comments (commands) sent by the user or other agents. A web app defaults to a single configuration/comment (`--interactive`), but this can be extended to have features enabled/disabled per context.
 
 This skill scaffolds:
 - **App Class**: Inherits from `AppBase_V1` and handles the initial `--interactive` request to boot the app.
 - **App Constants**: Defines `PARAM_INFOS` and the app's internal command set.
-- **App Helpers**: boilerplate for creating request comments and validating parameters.
+- **App Helpers**: Boilerplate for creating request comments and validating parameters.
 - **App Types**: Data and Relationship structures unique to this app.
 - **API Registration**: Plumbing to register core app functions with the ibgib runtime.
 
+For complete architectural context, refer to [`docs/IBGIB_CLIENT_APPS_GUIDE.md`](../../../docs/IBGIB_CLIENT_APPS_GUIDE.md).
+
 ---
 
 ## Token Reference
@@ -36,10 +40,10 @@ This skill scaffolds:
 ## Generation Steps
 
 ### 1. Confirm Tokens
-Ensure you have the same tokens used in `ibgib-create-app-core`.
+Ensure you have the same tokens used in `ibgib-create-client-app-core`.
 
 ### 2. Generate Files
-Apply substitutions to templates and write to the target directory (usually `src/`).
+Apply substitutions to templates and write to the target directory (usually `src/` or `src/client/`).
 
 | Template file | Output file |
 |---|---|