@ibgib/web-gib 0.0.23 → 0.0.25

package/tools/auto-generated-agent-skills/skills/ibgib-create-component/templates/components/component-name/component.mts.template

@@ -0,0 +1,131 @@
+import thisCss from "./{{COMPONENT_NAME}}.css";
+import thisHtml from "./{{COMPONENT_NAME}}.html";
+
+import { extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
+import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
+
+import { getComponentCtorArg } from "../../helpers.web.mjs";
+import {
+    IbGibDynamicComponentMetaBase, IbGibDynamicComponentInstanceBase,
+} from "@ibgib/web-gib/dist/ui/component/ibgib-dynamic-component-bases.mjs";
+import {
+    ElementsBase, IbGibDynamicComponentInstance,
+    IbGibDynamicComponentInstanceInitOpts,
+} from "@ibgib/web-gib/dist/ui/component/component-types.mjs";
+
+export const {{COMPONENT_NAME_UPPER}}_COMPONENT_NAME = '{{COMPONENT_TAG_NAME}}';
+
+/**
+ * Metadata for the {{COMPONENT_CLASS_PREFIX}} component.
+ * Handles custom element registration and instance creation.
+ */
+export class {{COMPONENT_CLASS_PREFIX}}ComponentMeta extends IbGibDynamicComponentMetaBase {
+    protected lc: string = `[{{COMPONENT_CLASS_PREFIX}}ComponentMeta]`;
+
+    routeRegExp?: RegExp = new RegExp(`^${ {{COMPONENT_NAME_UPPER}}_COMPONENT_NAME }$`);
+    componentName = {{COMPONENT_NAME_UPPER}}_COMPONENT_NAME;
+
+    constructor() {
+        super(getComponentCtorArg());
+        customElements.define(this.componentName, {{COMPONENT_CLASS_PREFIX}}ComponentInstance);
+    }
+
+    async createInstance({
+        path,
+        ibGibAddr
+    }: {
+        path: string;
+        ibGibAddr: IbGibAddr;
+    }): Promise<IbGibDynamicComponentInstance> {
+        const lc = `${this.lc}[${this.createInstance.name}]`;
+        const component = document.createElement(this.componentName) as {{COMPONENT_CLASS_PREFIX}}ComponentInstance;
+        await component.initialize({
+            ibGibAddr,
+            meta: this,
+            html: thisHtml,
+            css: [thisCss],
+        });
+        return component;
+    }
+}
+
+/**
+ * References to DOM elements within the component's shadow root.
+ */
+interface {{COMPONENT_CLASS_PREFIX}}Elements extends ElementsBase {
+    containerEl: HTMLDivElement;
+    titleEl: HTMLHeadingElement;
+}
+
+/**
+ * Concrete implementation of the {{COMPONENT_CLASS_PREFIX}} component.
+ * Manages its own internal state and reacts to ibGib timeline updates.
+ */
+export class {{COMPONENT_CLASS_PREFIX}}ComponentInstance
+    extends IbGibDynamicComponentInstanceBase<IbGib_V1, {{COMPONENT_CLASS_PREFIX}}Elements>
+    implements IbGibDynamicComponentInstance<IbGib_V1, {{COMPONENT_CLASS_PREFIX}}Elements> {
+
+    protected lc: string = `[{{COMPONENT_CLASS_PREFIX}}ComponentInstance]`;
+
+    constructor() {
+        super();
+    }
+
+    override async initialize(opts: IbGibDynamicComponentInstanceInitOpts): Promise<void> {
+        await super.initialize(opts);
+    }
+
+    override async disconnected(): Promise<void> {
+        // Called when the element is removed from the DOM.
+    }
+
+    /**
+     * Called when the element is added to the DOM.
+     * Use this to query elements and attach event listeners.
+     */
+    override async created(): Promise<void> {
+        this.elements = {} as {{COMPONENT_CLASS_PREFIX}}Elements;
+        if (!this.elements) { throw new Error(`(UNEXPECTED) this.elements falsy? (E: genuuid)`); }
+
+        // Map shadow root elements
+        this.elements.containerEl = this.shadowRoot!.getElementById('container') as HTMLDivElement;
+        this.elements.titleEl = this.shadowRoot!.getElementById('title') as HTMLHeadingElement;
+
+        this.initHandlers();
+
+        if (this.ibGibAddr && !this.ibGib) {
+            await this.loadIbGib();
+        }
+        await this.renderUI();
+    }
+
+    private initHandlers() {
+        if (!this.elements) { throw new Error(`(UNEXPECTED) this.elements falsy? (E: genuuid)`); }
+        // Attach listeners here
+    }
+
+    /**
+     * Updates the UI based on the current state of this.ibGib.
+     */
+    protected override async renderUI(): Promise<void> {
+        const lc = `${this.lc}[${this.renderUI.name}]`;
+        if (!this.ibGib || !this.elements) return;
+
+        try {
+            this.elements.titleEl.textContent = `IbGib Component: ${this.ibGib.ib}`;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+        }
+    }
+
+    /**
+     * Automatically called by the framework when the ibGib timeline updates.
+     */
+    override async handleContextUpdated(): Promise<void> {
+        const lc = `${this.lc}[${this.handleContextUpdated.name}]`;
+        if (logalot) { console.log(`${lc} timeline updated.`); }
+        await this.renderUI();
+    }
+}

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

@@ -0,0 +1,34 @@
+---
+name: ibgib-create-shell
+description: Scaffolds the foundational UI Shell for an ibgib app. Generates the shell service, constants, and types required for UI management and component registration.
+---
+
+# ibgib-create-shell
+
+This skill scaffolds the UI Shell architecture for an ibgib application. The Shell Service acts as a singleton on `globalThis` that manages DOM interactions, handles shell-specific events, and registers UI components with the `ibgib-component-service`.
+
+## Goal
+To provide a clean, decoupled foundation for application-level UI management, including the `onEngineReady` lifecycle hook called by the bootstrap process.
+
+## Parameters
+Wait for the user to provide or confirm these tokens:
+- `{{APP_NAME}}`: e.g. `test-app`
+- `{{APP_DIR_NAME}}`: e.g. `test-app`
+- `{{APP_CLASSNAME_PREFIX}}`: e.g. `TestApp`
+- `{{APP_CLASSNAME}}`: e.g. `TestAppApp_V1`
+- `{{APP_HUMAN_NAME}}`: e.g. `Test App`
+- `{{APP_VAR_NAME}}`: e.g. `testApp` (used for singleton naming)
+
+## Output Files
+The skill will generate:
+1. `src/ui/shell/{{APP_DIR_NAME}}-shell-service.mts`
+2. `src/ui/shell/{{APP_DIR_NAME}}-shell-constants.mts`
+3. `src/ui/shell/{{APP_DIR_NAME}}-shell-types.mts`
+
+## Usage Instructions
+1. Ensure the `src/ui/shell` directory exists or the tool will create it.
+2. Generate the three files from templates.
+3. Update `src/bootstrap.mts` to import and call `get{{APP_CLASSNAME_PREFIX}}ShellSvc().onEngineReady()` in the `execFromArgs` function.
+
+## Integration Note
+The shell service provides an `onEngineReady()` hook. This is where you should put logic to "activate" the UI once the ibgib metaspace and app witness are fully initialized.

package/tools/auto-generated-agent-skills/skills/ibgib-create-shell/templates/ui/shell/shell-constants.mts.template

@@ -0,0 +1,10 @@
+/**
+ * DOM Element IDs for the shell.
+ */
+export const ID_SHELL_CONTAINER = 'ibgib-shell-container';
+export const ID_APP_ROOT = 'app-root';
+
+/**
+ * Custom event names for shell-level communication.
+ */
+export const EVENT_SHELL_READY = 'ibgib-shell-ready';

package/tools/auto-generated-agent-skills/skills/ibgib-create-shell/templates/ui/shell/shell-service.mts.template

@@ -0,0 +1,139 @@
+import { extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { getComponentSvc } from "@ibgib/web-gib/dist/ui/component/ibgib-component-service.mjs";
+import { IbGibDynamicComponentMeta } from "@ibgib/web-gib/dist/ui/component/component-types.mjs";
+import { getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
+
+import { APP_CONFIG } from "../../constants.mjs";
+import { getIbGibGlobalThis_{{APP_CLASSNAME_PREFIX}} } from "../../helpers.web.mjs";
+import {
+    ID_SHELL_CONTAINER,
+    EVENT_SHELL_READY,
+} from "./{{APP_DIR_NAME}}-shell-constants.mjs";
+
+/**
+ * Singleton service for managing the {{APP_HUMAN_NAME}} UI shell.
+ * Coordinates component registration and high-level DOM interactions.
+ */
+export class {{APP_CLASSNAME_PREFIX}}ShellService {
+    private lc: string = `[{{APP_CLASSNAME_PREFIX}}ShellService]`;
+
+    // Elements
+    private shellContainer: HTMLElement | null = null;
+
+    /**
+     * Promise that resolves when the shell service has completed its 
+     * asynchronous initialization (e.g. component registration).
+     */
+    public initialized: Promise<void>;
+
+    constructor() {
+        this.initialized = this.initialize();
+    }
+
+    /**
+     * Orchestrates the synchronous and asynchronous initialization of the shell.
+     */
+    private async initialize(): Promise<void> {
+        this.initElements();
+        this.initEventHandlers();
+        await this.registerComponents();
+    }
+
+    /**
+     * Registers application-specific components with the global component service.
+     */
+    private async registerComponents(): Promise<void> {
+        const lc = `${this.lc}[${this.registerComponents.name}]`;
+        try {
+            const componentsMeta: IbGibDynamicComponentMeta[] = [
+                // Add your component metas here, e.g.:
+                // new MyAwesomeComponentMeta(),
+            ];
+            const componentSvc = await getComponentSvc();
+            for (let componentMeta of componentsMeta) {
+                componentSvc.registerComponentMeta(componentMeta);
+            }
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+
+    private initElements(): void {
+        const lc = `${this.lc}[${this.initElements.name}]`;
+        try {
+            // Placeholder: this.shellContainer = document.getElementById(ID_SHELL_CONTAINER);
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+        }
+    }
+
+    private initEventHandlers(): void {
+        const lc = `${this.lc}[${this.initEventHandlers.name}]`;
+        try {
+            // Register global or shell-level event listeners here.
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+        }
+    }
+
+    /**
+     * Called by `bootstrap.mts` when the ibGib engine and metaspace are ready.
+     * Use this to reveal or activate interactive UI elements.
+     */
+    public async onEngineReady(): Promise<void> {
+        const lc = `${this.lc}[${this.onEngineReady.name}]`;
+        try {
+            await this.initialized;
+            console.log(`${lc} {{APP_HUMAN_NAME}} Shell Service is ready.`);
+
+            // 1. Get the app context from global state
+            const ibGibGlobalThis = getIbGibGlobalThis_{{APP_CLASSNAME_PREFIX}}(APP_CONFIG);
+            const appIbGib = ibGibGlobalThis.initialCommentIbGib;
+            if (!appIbGib) {
+                throw new Error(`initialCommentIbGib not found on globalThis.`);
+            }
+
+            // 2. Get the main component instance
+            const componentSvc = await getComponentSvc();
+            const component = await componentSvc.getComponentInstance({
+                path: '{{APP_DIR_NAME}}-main',
+                ibGibAddr: getIbGibAddr({ ibGib: appIbGib }),
+                useRegExpPrefilter: true,
+            });
+
+            if (!component) {
+                throw new Error(`Failed to get component instance for app.`);
+            }
+
+            // 3. Inject into the DOM
+            const appRoot = document.getElementById(ID_APP_ROOT);
+            if (appRoot) {
+                appRoot.innerHTML = ''; // Clear loading message
+                appRoot.appendChild(component as any);
+            } else {
+                console.warn(`${lc} #${ID_APP_ROOT} not found in DOM.`);
+            }
+
+            window.dispatchEvent(new CustomEvent(EVENT_SHELL_READY));
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+        }
+    }
+}
+
+/**
+ * Returns the singleton instance of the Shell Service, initializing it on 
+ * globalThis if necessary.
+ */
+export function get{{APP_CLASSNAME_PREFIX}}ShellSvc(): {{APP_CLASSNAME_PREFIX}}ShellService {
+    const lc = `[get{{APP_CLASSNAME_PREFIX}}ShellSvc]`;
+    const ibGibGlobalThis = getIbGibGlobalThis_{{APP_CLASSNAME_PREFIX}}(APP_CONFIG);
+    if (!ibGibGlobalThis.{{APP_VAR_NAME}}ShellSvc) {
+        if (typeof (console) !== 'undefined') {
+            console.log(`${lc} initializing {{APP_CLASSNAME_PREFIX}}ShellService singleton on globalThis... (I: genuuid)`);
+        }
+        ibGibGlobalThis.{{APP_VAR_NAME}}ShellSvc = new {{APP_CLASSNAME_PREFIX}}ShellService();
+    }
+    return ibGibGlobalThis.{{APP_VAR_NAME}}ShellSvc;
+}

package/tools/auto-generated-agent-skills/skills/ibgib-create-shell/templates/ui/shell/shell-types.mts.template

@@ -0,0 +1,6 @@
+/**
+ * Event detail shapes for shell events.
+ */
+export interface ShellReadyDetail {
+    timestamp: number;
+}

package/tools/auto-generated-agent-skills/skills/ibgib-enum-pattern/SKILL.md

@@ -0,0 +1,153 @@
+---
+description: TypeScript enum pattern used in this codebase
+---
+
+# Ibgib Enum Pattern Skill
+
+This codebase **never** uses TypeScript's built-in `enum` keyword (it has
+problematic runtime semantics and poor tree-shaking). Instead, use the
+following pattern for every enum-like type.
+
+## When to use
+
+- Three or more related string (or occasionally number) constants.
+- The values are part of a discriminated union or are validated at runtime.
+- A simple `'a' | 'b' | 'c'` union is fine for small, stable sets; promote
+  to the full pattern once the set starts to branch out or needs a guard/validator.
+
+## Full pattern
+
+```typescript
+// #region MyEnum enum
+
+// 1. One exported const per value.
+//    - Name: SCREAMING_SNAKE_CASE  PREFIX_MEMBER
+//    - Value: kebab-case string literal
+//    - Hyphens in values → underscores in const names.
+export const MY_ENUM_FOO_BAR = 'foo-bar';
+export const MY_ENUM_BAZ     = 'baz';
+
+// 2. Union type — use typeof references so renaming a const propagates.
+/**
+ * JSDoc describing the enum's purpose.
+ */
+export type MyEnum =
+    | typeof MY_ENUM_FOO_BAR
+    | typeof MY_ENUM_BAZ
+    ;
+
+// 3. Const enum object — keys are camelCase/underscore versions of the values
+//    (replace hyphens with underscores in the key).
+//    Satisfies the union type so TypeScript catches typos at declaration time.
+export const MyEnum = {
+    /** Doc for foo-bar member. */
+    foo_bar: MY_ENUM_FOO_BAR,
+    /** Doc for baz member. */
+    baz: MY_ENUM_BAZ,
+} satisfies { readonly [key: string]: MyEnum };
+
+// 4. Valid-values array (derived from the object — stays in sync automatically).
+export const MY_ENUM_VALID_VALUES: MyEnum[] = Object.values(MyEnum);
+
+// 5. Type guard.
+export function isMyEnum(value: any): value is MyEnum {
+    return MY_ENUM_VALID_VALUES.includes(value);
+}
+
+// #endregion MyEnum enum
+```
+
+## Consuming the enum
+
+Callers should reference values via the **const object**, not the individual string constants:
+
+```typescript
+// ✅ preferred — readable, refactor-safe
+switch (strategy) {
+    case ParseMechanicalStrategy.markdown_heading:   return splitByHeadings(text);
+    case ParseMechanicalStrategy.markdown_paragraph: return splitByParagraph(text);
+    case ParseMechanicalStrategy.custom_regexp:      return splitByRegexp(text, opts.regexp);
+    default: throw new Error(`(UNEXPECTED) unhandled strategy: '${strategy}'`);
+}
+
+// ⚠️  acceptable when the constant itself is needed (e.g. error messages, assertions)
+if (strategy === PARSE_MECHANICAL_STRATEGY_CUSTOM_REGEXP && !opts.regexp) {
+    throw new Error(`strategy is '${PARSE_MECHANICAL_STRATEGY_CUSTOM_REGEXP}' but regexp is falsy`);
+}
+
+// ❌ avoid — brittle string literals scattered through call sites
+if (strategy === 'markdown-heading') { ... }
+```
+
+## Rules
+
+| Rule | Detail |
+|---|---|
+| **No `enum` keyword** | Use the pattern above. `enum` has footguns (reverse mapping, ambient vs const, isolatedModules). |
+| **Kebab-case values** | String values use kebab-case (`'foo-bar'`). |
+| **Const names** | `PREFIX_MEMBER` in SCREAMING_SNAKE_CASE; hyphens in value → underscores in name. |
+| **Object keys** | Match the value with hyphens replaced by underscores (`foo_bar`). |
+| **`satisfies`** | Always use `satisfies { readonly [key: string]: MyEnum }` on the const object. |
+| **Start simple** | A plain string-literal union (`'foo-bar' | 'baz'`) is fine until the set grows or needs a guard. Promote to the full pattern at that point. |
+| **`_VALID_VALUES`** | Always derive from `Object.values(MyEnum)`, never hardcode. |
+| **Type guard** | Implement `isMyEnum` via `VALID_VALUES.includes(value)`. |
+
+## Region comments
+
+Wrap the entire block in:
+```typescript
+// #region MyEnum enum
+// ...
+// #endregion MyEnum enum
+```
+
+## Example from codebase
+
+```typescript
+// #region ChromeAIAvailability enum
+export const CHROME_AI_AVAILABILITY_UNAVAILABLE = 'unavailable';
+export const CHROME_AI_AVAILABILITY_DOWNLOADABLE = 'downloadable';
+export const CHROME_AI_AVAILABILITY_DOWNLOADING = 'downloading';
+export const CHROME_AI_AVAILABILITY_AVAILABLE = 'available';
+
+export type ChromeAIAvailability =
+    | typeof CHROME_AI_AVAILABILITY_UNAVAILABLE
+    | typeof CHROME_AI_AVAILABILITY_DOWNLOADABLE
+    | typeof CHROME_AI_AVAILABILITY_DOWNLOADING
+    | typeof CHROME_AI_AVAILABILITY_AVAILABLE
+    ;
+
+/**
+ * The availability of a Chrome AI API.
+ *
+ * @see https://developer.chrome.com/docs/ai/built-in
+ */
+export const ChromeAIAvailability = {
+    /**
+     * The user's device or requested session options are not supported.
+     * The device may have insufficient power or disk space.
+     */
+    unavailable: CHROME_AI_AVAILABILITY_UNAVAILABLE,
+    /**
+     * Additional downloads are needed to create a session, which may include
+     * an expert model, a language model, or fine-tuning. User activation may
+     * be required to call create().
+     */
+    downloadable: CHROME_AI_AVAILABILITY_DOWNLOADABLE,
+    /**
+     * Downloads are ongoing and must complete before you can use a a session.
+     */
+    downloading: CHROME_AI_AVAILABILITY_DOWNLOADING,
+    /**
+     * You can create a session immediately.
+     */
+    available: CHROME_AI_AVAILABILITY_AVAILABLE,
+} satisfies { readonly [key: string]: ChromeAIAvailability; };
+
+export const CHROME_AI_AVAILABILITY_VALID_VALUES: ChromeAIAvailability[] = Object.values(ChromeAIAvailability);
+
+export function isChromeAIAvailability(value: any): value is ChromeAIAvailability {
+    return CHROME_AI_AVAILABILITY_VALID_VALUES.includes(value);
+}
+// #endregion ChromeAIAvailability enum
+```

package/tools/auto-generated-agent-skills/skills/ibgib-get-pattern/SKILL.md

@@ -0,0 +1,92 @@
+---
+description: Patterns for robustly getting IbGibs from spaces
+---
+
+# IbGib Get Pattern Skill
+
+This skill documents the standard pattern for retrieving IbGib objects from a space. Use this pattern to ensure robust error handling, consistent logging, and correct space interaction.
+
+## When to Use
+
+- Whenever you need to `get` one or more IbGibs by their address(es).
+
+## Core Pattern: try..catch..finally
+
+Always wrap retrieval logic in a `try..catch..finally` block to ensure errors are logged and execution state is finalized correctly.
+
+```typescript
+const lc = `[${myFunctionName.name}]`;
+try {
+    if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+    
+    // ... retrieval logic ...
+
+} catch (error) {
+    console.error(`${lc} ${extractErrorMsg(error)}`);
+    throw error;
+} finally {
+    if (logalot) { console.log(`${lc} complete.`); }
+}
+```
+
+## Space Retrieval Helpers
+
+### Option A: Using `metaspace.get` (Preferred)
+
+Use this when you have access to a `MetaspaceService` (It is often appropriate to provide a fallback to the default local user space, which is what the metaspace provides.)
+
+```typescript
+// Ensure space is provided or fallback to local user space
+space ??= await metaspace.getLocalUserSpace({ lock: false });
+if (!space) { 
+    throw new Error(`(UNEXPECTED) space falsy and we couldn't get default local user space from metaspace? (E: genuuid)`); 
+}
+
+const resGet = await metaspace.get({ addrs, space });
+
+// Validate result
+if (resGet.success && resGet.ibGibs && resGet.ibGibs.length === addrs.length) {
+    return resGet.ibGibs;
+} else {
+    // Robust error handling using rawResultIbGib
+    const resIbGib = resGet.rawResultIbGib as IbGibSpaceResultIbGib<IbGib_V1, IbGibSpaceResultData, IbGibSpaceResultRel8ns>;
+    const addrsNotFound = resIbGib?.data?.addrsNotFound ?? 'unknown';
+    throw new Error(`couldn't find all addrs. addrsNotFound: ${addrsNotFound}? resGet.errorMsg: ${resGet.errorMsg} (E: genuuid)`);
+}
+```
+
+### Option B: Using `getFromSpace` (Lower Level)
+
+Use this when `metaspace` is not available, or when working in low-level helpers.
+
+```typescript
+import { getFromSpace } from "@ibgib/core-gib/dist/witness/space/space-helper.mjs";
+
+// ... inside try block ...
+const resGet = await getFromSpace({ space, addrs });
+
+if (resGet.success && resGet.ibGibs?.length === addrs.length) {
+    return resGet.ibGibs!;
+} else {
+    // Examine rawResultIbGib for more context
+    const resIbGib = resGet.rawResultIbGib as IbGibSpaceResultIbGib<IbGib_V1, IbGibSpaceResultData, IbGibSpaceResultRel8ns>;
+    if (!resIbGib?.data) { 
+        throw new Error(`(UNEXPECTED) resGet.rawResultIbGib.data falsy? (E: genuuid)`); 
+    }
+    throw new Error(`(UNEXPECTED) couldn't find addrs? addrsNotFound: ${resIbGib.data.addrsNotFound}? space.ib: ${space.ib} (E: genuuid)`);
+}
+```
+
+## Key Requirements
+
+| Requirement | Detail |
+|---|---|
+| **Logging** | Define `const lc = \`[\${fn.name}]\`;\` at the start. Log starting/finishing if `logalot` is true. |
+| **Error Handling** | Use `extractErrorMsg(error)` in the catch block. Re-throw after logging. |
+| **Result Validation** | Always check `resGet.success` AND that the returned `ibGibs` array matches the expected length. |
+| **Debugging Context** | When a fetch fails, cast `resGet.rawResultIbGib` to `IbGibSpaceResultIbGib` and include `addrsNotFound` in the error message. |
+| **Space Fallback** | When using `metaspace`, consider falling back to `metaspace.getLocalUserSpace({ lock: false })` if no space is provided. |
+
+## Real-World Example
+
+See `apps/learning/src/common/parse/parse-helper.mts` -> `fetchLayer` for the reference implementation of this pattern.

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

@@ -0,0 +1,42 @@
+---
+name: ibgib-scaffold-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.
+---
+
+# ibgib-scaffold-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-add-core-engine`: 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).
+
+## 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-add-core-engine` 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.