---
name: ibgib-create-client-app-core
description: >
  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 client app to boot. Supports both greenfield and brownfield projects.
---

# Skill: ibgib-create-client-app-core

## What This Skill Does

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.
- **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.

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-client-app-core/generate-version-file.js`

---

## Token Reference

| Token | Example value | How it's computed |
|---|---|---|
| `{{APP_HUMAN_NAME}}` | `My App` | Asked of developer |
| `{{APP_NAME_UPPER}}` | `MY_APP` | Uppercase + underscores of app name |
| `{{APP_CLASSNAME_PREFIX}}` | `MyApp` | PascalCase, no suffix |
| `{{APP_DIR_NAME}}` | `my-app` | kebab-case |
| `{{DB_NAME}}` | `my_app_db` | Asked of developer |
| `{{STORE_NAME}}` | `my_app_store` | Asked of developer |
| `{{APP_UUID}}` | `3a95fe65cbda2833b59cadff4e279826` | **Generated fresh** with `generate-id.js`. |

---

## Generation Steps

### 1. Confirm token values

Derive tokens from the developer's answers. Generate a fresh `{{APP_UUID}}` using:

```bash
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/` 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) |

### 3. Replace `genuuid` placeholders

Replace every `(I: genuuid)`, `(W: genuuid)`, etc., with unique IDs from `generate-id.js`.

---

## Reference Implementations

- **Standalone Pattern**: These templates are designed to be self-contained. They import from shared `@ibgib/*` packages and use standard relative paths for app-internal files.
- **Library Integration (Optional)**: If the project uses a shared framework layer (like a `common` library), manually update imports in the generated files to point to that layer after scaffolding.