@ibgib/web-gib 0.0.52 → 0.0.55

package/src/ui/component/identity/remove-device/remove-device.mts

@@ -0,0 +1,247 @@
+import thisCss from "./remove-device.css";
+import thisHtml from "./remove-device.html";
+import commonComponentStylesCss from "../../common-component-styles.css";
+
+import { delay, 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 { KeystoneService_V1 } from "@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs";
+import { KeystoneIbGib_V1 } from "@ibgib/core-gib/dist/keystone/keystone-types.mjs";
+
+import { getGlobalMetaspace_waitIfNeeded } from "../../../../helpers.mjs";
+import {
+    IbGibDynamicComponentMetaBase, IbGibFormInstanceBase,
+} from "../../ibgib-dynamic-component-bases.mjs";
+import {
+    ElementsBase, IbGibDynamicComponentInstance,
+    IbGibDynamicComponentInstanceInitOpts,
+} from "../../component-types.mjs";
+import { getComponentCtorArg } from "../../../../app-bootstrap/init-orchestration.mjs";
+
+export const REMOVE_DEVICE_COMPONENT_NAME = 'ibgib-remove-device';
+
+/**
+ * Metadata for the Remove Device / Revocation component.
+ */
+export class RemoveDeviceComponentMeta extends IbGibDynamicComponentMetaBase {
+    protected lc: string = `[RemoveDeviceComponentMeta]`;
+
+    routeRegExp?: RegExp = new RegExp(`^${REMOVE_DEVICE_COMPONENT_NAME}$`);
+    componentName = REMOVE_DEVICE_COMPONENT_NAME;
+
+    constructor() {
+        super(getComponentCtorArg());
+        if (!customElements.get(this.componentName)) {
+            customElements.define(this.componentName, RemoveDeviceComponentInstance);
+        }
+    }
+
+    async createInstance({
+        path,
+        ibGibAddr
+    }: {
+        path: string;
+        ibGibAddr: IbGibAddr;
+    }): Promise<IbGibDynamicComponentInstance> {
+        const component = document.createElement(this.componentName) as RemoveDeviceComponentInstance;
+        await component.initialize({
+            ibGibAddr,
+            meta: this,
+            html: thisHtml,
+            css: [commonComponentStylesCss, thisCss],
+        });
+        return component;
+    }
+}
+
+interface RemoveDeviceElements extends ElementsBase {
+    containerEl: HTMLDivElement;
+    titleEl: HTMLHeadingElement;
+    selectDelegateEl: HTMLSelectElement;
+    inputPassphrase: HTMLInputElement;
+    btnRemoveDeviceEl: HTMLButtonElement;
+    statusArea: HTMLDivElement;
+    statusText: HTMLParagraphElement;
+    resultAreaEl: HTMLDivElement;
+}
+
+/**
+ * Concrete implementation of the Remove Device / Revocation component.
+ */
+export class RemoveDeviceComponentInstance
+    extends IbGibFormInstanceBase<IbGib_V1, RemoveDeviceElements>
+    implements IbGibDynamicComponentInstance<IbGib_V1, RemoveDeviceElements> {
+
+    protected lc: string = `[RemoveDeviceComponentInstance]`;
+    private activePrimaryKeystone: KeystoneIbGib_V1 | undefined;
+
+    constructor() {
+        super();
+    }
+
+    override async initialize(opts: IbGibDynamicComponentInstanceInitOpts): Promise<void> {
+        await super.initialize(opts);
+    }
+
+    override async created(): Promise<void> {
+        this.elements = {} as RemoveDeviceElements;
+
+        this.elements.containerEl = this.shadowRoot!.getElementById('container') as HTMLDivElement;
+        this.elements.titleEl = this.shadowRoot!.getElementById('title') as HTMLHeadingElement;
+        this.elements.selectDelegateEl = this.shadowRoot!.getElementById('select-delegate') as HTMLSelectElement;
+        this.elements.inputPassphrase = this.shadowRoot!.getElementById('input-passphrase') as HTMLInputElement;
+        this.elements.btnRemoveDeviceEl = this.shadowRoot!.getElementById('btn-remove-device') as HTMLButtonElement;
+        this.elements.statusArea = this.shadowRoot!.getElementById('status-area') as HTMLDivElement;
+        this.elements.statusText = this.shadowRoot!.getElementById('status-text') as HTMLParagraphElement;
+        this.elements.resultAreaEl = this.shadowRoot!.getElementById('result-area') as HTMLDivElement;
+
+        this.elements.contentEl = this.elements.containerEl;
+
+        this.initHandlers();
+        await this.loadRegisteredDelegates();
+        await this.renderUI();
+    }
+
+    override async disconnected(): Promise<void> {
+        // cleanup if needed
+    }
+
+    private initHandlers() {
+        this.elements!.btnRemoveDeviceEl.addEventListener('click', () => this.handleRemoveDevice());
+        this.elements!.inputPassphrase.addEventListener('input', () => {
+            this.elements!.inputPassphrase.classList.remove('invalid');
+        });
+    }
+
+    /**
+     * Loads registered delegate devices from the active primary identity keystone into the dropdown select.
+     */
+    protected async loadRegisteredDelegates() {
+        const lc = `${this.lc}[${this.loadRegisteredDelegates.name}]`;
+        try {
+            const metaspace = await getGlobalMetaspace_waitIfNeeded();
+            const space = await metaspace.getLocalUserSpace({});
+            if (!space) { return; }
+
+            const keystonesIndex = await metaspace.getSpecialIbGib({
+                type: "keystones",
+                space,
+                initialize: true,
+            });
+            const registeredAddrs: string[] = keystonesIndex?.rel8ns?.keystone ?? [];
+
+            // Find primary identity (n === 0 and has delegates map or is primary domain keystone)
+            for (const addr of registeredAddrs) {
+                const res = await metaspace.get({ addrs: [addr], space });
+                const keystone = res?.ibGibs?.[0] as KeystoneIbGib_V1 | undefined;
+                if (keystone && keystone.data && !keystone.data.isDelegate) {
+                    this.activePrimaryKeystone = keystone;
+                    break;
+                }
+            }
+
+            const selectEl = this.elements!.selectDelegateEl;
+            selectEl.innerHTML = '';
+
+            const delegatesMap = this.activePrimaryKeystone?.data?.delegates ?? {};
+            const delegateTjpAddrs = Object.keys(delegatesMap);
+
+            if (delegateTjpAddrs.length === 0) {
+                const opt = document.createElement('option');
+                opt.value = '';
+                opt.text = 'No registered delegate devices found';
+                selectEl.appendChild(opt);
+                this.elements!.btnRemoveDeviceEl.disabled = true;
+                return;
+            }
+
+            const defaultOpt = document.createElement('option');
+            defaultOpt.value = '';
+            defaultOpt.text = '-- Select a device to unlink --';
+            selectEl.appendChild(defaultOpt);
+
+            for (const tjpAddr of delegateTjpAddrs) {
+                const info = delegatesMap[tjpAddr];
+                const opt = document.createElement('option');
+                opt.value = tjpAddr;
+                opt.text = `${info.delegateAddr.split('^')[0]} (TJP: ${tjpAddr.substring(0, 20)}...)`;
+                selectEl.appendChild(opt);
+            }
+            this.elements!.btnRemoveDeviceEl.disabled = false;
+
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+        }
+    }
+
+    /**
+     * Executes the Phase 1 Remove-Device revocation orchestration flow.
+     */
+    protected async handleRemoveDevice() {
+        const lc = `${this.lc}[${this.handleRemoveDevice.name}]`;
+        try {
+            const humanEyeDelay = 500;
+            const delegateTjpAddr = this.elements!.selectDelegateEl.value;
+            if (!delegateTjpAddr) {
+                this.setStatus("Please select a device delegate to unlink.", "error");
+                return;
+            }
+
+            const masterSecret = this.elements!.inputPassphrase.value.trim();
+            this.elements!.inputPassphrase.value = masterSecret;
+            if (!masterSecret) {
+                this.elements!.inputPassphrase.classList.add('invalid');
+                this.setStatus("Please enter your master passphrase.", "error");
+                return;
+            }
+
+            if (!this.activePrimaryKeystone) {
+                this.setStatus("No active primary identity keystone found.", "error");
+                return;
+            }
+
+            this.showBusy({
+                isBusy: true,
+                title: 'Revoking Device...',
+                msg: 'Evolving primary identity to revoke delegate device...',
+                animationEmoji: '🔒',
+                submitBtnSelector: '#btn-remove-device',
+                loadingText: 'Unlinking...'
+            });
+
+            const metaspace = await getGlobalMetaspace_waitIfNeeded();
+            const space = await metaspace.getLocalUserSpace({});
+            if (!space) { throw new Error("No default space found in metaspace."); }
+
+            const keystoneService = new KeystoneService_V1();
+
+            // Evolve primary identity keystone unregistering delegate
+            const evolvedParent = await keystoneService.unregisterDelegate({
+                parentKeystone: this.activePrimaryKeystone,
+                delegateTjpAddr,
+                masterSecret,
+                metaspace,
+                space
+            });
+
+            // Persist evolved parent to space
+            await metaspace.put({ ibGibs: [evolvedParent], space });
+            await metaspace.registerNewIbGib({ ibGib: evolvedParent, space });
+
+            this.activePrimaryKeystone = evolvedParent;
+            await delay(humanEyeDelay);
+
+            this.showBusy({ isBusy: false });
+            this.elements!.resultAreaEl.classList.remove('collapsed');
+            this.setStatus("Device successfully unlinked and revoked!", "success");
+
+            // Refresh list
+            await this.loadRegisteredDelegates();
+
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            this.setStatus(`Revocation failed: ${extractErrorMsg(error)}`, "error");
+            this.showBusy({ isBusy: false });
+        }
+    }
+}

package/src/ui/ui-constants.mts

@@ -106,6 +106,7 @@ export const EVENT_IBGIB_UI_BUSY = 'ibgib-ui-busy';
 export const EVENT_IBGIB_UI_MESSAGE = 'ibgib-ui-message';
 export const EVENT_IBGIB_IDENTITY_REQUEST_CHANGE = 'ibgib-identity-request-change';
 export const EVENT_IBGIB_IDENTITY_CHANGED = 'ibgib-identity-changed';
+export const EVENT_IBGIB_IDENTITY_UPDATE_AVAILABLE = 'ibgib-identity-update-available';
 // #endregion Custom Events
 
 

package/src/ui/ui-types.mts

@@ -9,3 +9,11 @@ export interface UIThemeInfo {
      */
     cssVariableOverrides: { [key: string]: string; }
 }
+
+export interface EventIbGibIdentityUpdateAvailableDetail {
+    activePrimaryAddr: string;
+    hasUpdate: boolean;
+    serverN: number;
+    localN: number;
+    serverLatestAddr: string;
+}

package/src/witness/space/metaspace/metaspace-webspace/metaspace-webspace.mts

@@ -18,7 +18,7 @@ import { fnCreateNewLocalSpace, fnDtoToSpace_webFilesystem } from './metaspace-w
 import { WebFilesystemSpace_V1 } from '../../web-filesystem-space/web-filesystem-space-v1.mjs';
 // import { storageCreateStoreIfNotExist, initializeStorage, storageDBExists, } from '../../../../helpers.web.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
-import { storageCreateStoreIfNotExist } from '../../../../storage/storage-helpers.web.mjs';
+import { storageCreateStoreIfNotExist, storageRmRF } from '../../../../storage/storage-helpers.web.mjs';
 import { SpaceId } from '@ibgib/core-gib/dist/witness/space/space-types.mjs';
 import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
 import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
@@ -404,4 +404,45 @@ export class Metaspace_Webspace extends MetaspaceBase {
         }
     }
 
+    override async deleteLocalUserSpace({
+        spaceId,
+        deletePhysicalStorage = true,
+    }: {
+        spaceId: SpaceId;
+        deletePhysicalStorage?: boolean;
+    }): Promise<void> {
+        const lc = `${this.lc}[${this.deleteLocalUserSpace.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... spaceId: ${spaceId} (I: c81a5120a14941a590b512a8e0915623)`); }
+            if (!spaceId) { throw new Error(`spaceId required. (E: f3a210410a124b819e917f9db0972b23)`); }
+
+            // 1. Get space instance to evict from cache
+            const space = await this.getLocalUserSpace({ localSpaceId: spaceId });
+            if (space) {
+                const spaceAddr = getIbGibAddr({ ibGib: space });
+                NAIVE_SPACE_CACHE.delete(spaceAddr);
+            }
+            STORES_CONFIRMED.delete(spaceId);
+
+            // 2. Deregister space from bootstrap^gib and delete space record from zeroSpace via super
+            await super.deleteLocalUserSpace({ spaceId, deletePhysicalStorage });
+
+            // 3. Delete physical IndexedDB storage if requested
+            if (deletePhysicalStorage) {
+                const dbName = getGlobalDbName();
+                if (logalot) { console.log(`${lc} purging IndexedDB store/subpath for spaceId (${spaceId}) in db (${dbName})... (I: d9410a5170d14b4fb2478d102e3b2e23)`); }
+                await storageRmRF({
+                    dbName,
+                    storeName: spaceId,
+                    pathToRm: '/',
+                });
+            }
+
+            if (logalot) { console.log(`${lc} complete.`); }
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+
 }

package/tools/auto-generated-agent-skills/skills/ibgib-dependency-graph/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: ibgib-dependency-graph
+description: Detailed guide and patterns for using getDependencyGraph from core-gib to extract dependency graphs, live timelines, and graph nodes across spaces
+---
+
+# IbGib Dependency Graph Skill Guide
+
+This skill provides patterns, architecture guidelines, and multi-file operational code samples for extracting and traversing dependency graphs in the `ibgib` codebase using `getDependencyGraph` and related functions in `@ibgib/core-gib`.
+
+---
+
+## 1. Overview & Core Architecture
+
+In the `ibgib` content-addressable DAG system, an `ibgib` references other `ibgibs` through relationship links (`rel8ns`), timelines (`tjp` / time-jump-point), and past history (`past`/`ancestor`).
+
+The authoritative implementation of graph extraction resides in:
+📁 `libs/core-gib/src/common/other/graph-helper.mts`
+
+Primary exports:
+```typescript
+import {
+    getDependencyGraph,
+    getDeltaDependencyGraph,
+    toFlatGraph,
+    graphsAreEquivalent,
+    GetDependencyGraphOptions,
+    GetGraphResult,
+} from '@ibgib/core-gib/dist/common/other/graph-helper.mjs';
+```
+
+### Return Type: `FlatIbGibGraph`
+All graph extraction functions return a flat map (`FlatIbGibGraph` / `GetGraphResult`) structured as:
+```typescript
+export type FlatIbGibGraph = { [addr: IbGibAddr]: IbGib_V1 };
+```
+- **Keys**: `IbGibAddr` string (computed via `getIbGibAddr({ ibGib })`).
+- **Values**: Complete `IbGib_V1` data structure.
+- **Primitives**: Primitive ibgibs (e.g. `gib === GIB` or primitive ibs) are automatically filtered out and excluded from the graph.
+
+---
+
+## 2. Function Signatures & Options
+
+```typescript
+export interface GetGraphOptions {
+    /** Single source ibGib object */
+    ibGib?: IbGib_V1;
+    /** Multiple source ibGib objects */
+    ibGibs?: IbGib_V1[];
+    /** Single source ibGib address string */
+    ibGibAddr?: IbGibAddr;
+    /** Multiple source ibGib address strings */
+    ibGibAddrs?: IbGibAddr[];
+
+    /** Space within which to resolve & fetch missing ibgibs. */
+    space: IbGibSpaceAny | null;
+
+    /** 
+     * If true, queries space for latest timeline tips and includes newly added rel8d nodes.
+     * If false, performs backward-only DAG traversal through past rel8ns.
+     */
+    live?: boolean;
+
+    /** List of ibGib addresses to skip fetching. */
+    skipAddrs?: IbGibAddr[];
+
+    /** Blacklist of relationship names to skip during traversal (e.g. ['dna']). */
+    skipRel8nNames?: string[];
+
+    /** Whitelist of relationship names to traverse (e.g. ['comment', 'pic']). */
+    onlyRel8nNames?: string[];
+
+    /** Maximum retries when getting addresses from space if not immediately found. */
+    maxRetries?: number;
+
+    /** Delay in milliseconds between space fetch retries. */
+    msBetweenRetries?: number;
+}
+```
+
+---
+
+## 3. Real Code Patterns Sampled Across `libs/core-gib/src/sync/`
+
+Below are real usage patterns extracted across 15 distinct files in `libs/core-gib/src/sync/`:
+
+### Pattern 1: Single `ibGib` Object + Dedicated Space
+*Sampled from:* `sync-saga-coordinator.mts` (Line 1984), `sync-innerspace-deep-updates.respec.mts` (Line 116), `sync-withid.pingpong.respec.mts` (Line 170)
+
+```typescript
+// Fetch full graph for a single starting node within a space
+const depGraph = await getDependencyGraph({
+    ibGib: rootItemIbGib,
+    space: sourceSpace,
+});
+// Result: depGraph contains { [addr]: ibGib } for rootItemIbGib and all its child dependencies
+```
+
+---
+
+### Pattern 2: Array of `ibGibs` Objects
+*Sampled from:* `sync-innerspace-dest-ahead.respec.mts` (Line 99), `sync-innerspace-dest-ahead.withid.respec.mts` (Line 127)
+
+```typescript
+// Fetch graph for multiple starting objects in a single pass
+const initialDepGraph = await getDependencyGraph({
+    ibGibs: [version0IbGib, version1IbGib],
+    space: sourceSpace,
+});
+```
+
+---
+
+### Pattern 3: Single `ibGibAddr` String
+*Sampled from:* `sync-innerspace-dest-ahead.withid.respec.mts` (Line 207 & 208)
+
+```typescript
+// Fetch graph starting from a known address string (automatically fetched from space)
+const sourceV2Graph = await getDependencyGraph({
+    ibGibAddr: r1_alpha_v2_dest_newer_addr,
+    space: sourceSpace,
+});
+
+const destV2Graph = await getDependencyGraph({
+    ibGibAddr: r1_alpha_v2_dest_newer_addr,
+    space: destSpace,
+});
+```
+
+---
+
+### Pattern 4: Multiple `ibGibAddrs` Strings in `sync-saga-coordinator`
+*Sampled from:* `sync-saga-coordinator.mts` (Line 864 & Line 1717)
+
+```typescript
+// Used during SyncSaga domain analysis to fetch transitive closures for multiple target addresses
+const fullGraph = await getDependencyGraph({
+    ibGibAddrs: targetDomainAddrs,
+    space: localSpace,
+    live: false,
+});
+```
+
+---
+
+### Pattern 5: Live Timeline Query (`live: true` vs `live: false`)
+*Sampled from:* `sync-conflict-text-merge.respec.mts` (Lines 194, 199, 343, 348), `sync-saga-coordinator.mts` (Line 2706)
+
+```typescript
+// live: true queries the space's metastones for the latest timeline tips
+const liveSourceGraph = await getDependencyGraph({
+    ibGib: rootFolderItem,
+    space: sourceSpace,
+    live: true,
+});
+
+// live: false performs historical DAG walk backwards only (no space metastone queries)
+const historicalGraph = await getDependencyGraph({
+    ibGib: rootFolderItem,
+    space: sourceSpace,
+    live: false,
+});
+```
+
+---
+
+### Pattern 6: Comparing Two Graphs (`graphsAreEquivalent`)
+*Sampled from:* `sync-conflict-text-merge.respec.mts`, `sync-innerspace-deep-updates.withid.respec.mts`
+
+```typescript
+import { graphsAreEquivalent } from '@ibgib/core-gib/dist/common/other/graph-helper.mjs';
+
+const graphsMatch = graphsAreEquivalent({
+    graphA: sourceDepGraph,
+    graphB: destDepGraph,
+});
+
+if (graphsMatch) {
+    console.log('Both spaces contain identical dependency graphs.');
+}
+```
+
+---
+
+### Pattern 7: Computing Delta Graphs (`getDeltaDependencyGraph`)
+*Sampled from:* `sync-saga-coordinator.mts` (Line 2706), `graph-helper.mts`
+
+```typescript
+import { getDeltaDependencyGraph } from '@ibgib/core-gib/dist/common/other/graph-helper.mjs';
+
+// Finds nodes present in sourceGraph that are NOT present in destGraph
+const deltaGraph = await getDeltaDependencyGraph({
+    sourceGraph: sourceBranchDepGraph,
+    destGraph: targetBranchDepGraph,
+});
+// deltaGraph contains only the new/differing ibGib nodes
+```
+
+---
+
+## 4. Key Operational Nuances & Edge Cases
+
+1. **Space Resolution & Fallback**:
+   - `space` is required to resolve missing `ibGib` addresses. If an address in `rel8ns` is not already in memory (`ibGibs` or `gotten`), `getDependencyGraph` calls `space.get({ arg: addr })`.
+2. **Primitive IbGib Auto-Filtering**:
+   - Primitive ibgibs (where `gib === GIB` or primitive ibs) are automatically ignored and NOT included in `FlatIbGibGraph`.
+3. **Timeline Frames vs. Historical Walk**:
+   - When branching to a new branch sub-space (`b2s_<newBranch>`), `getDependencyGraph` extracts the flat graph map of all folder, file, and binary nodes.
+   - To register timelines in the new branch space: iterate through the graph values, sort by timeline history (`past` / `ancestor`), and call `registerNewIbGib` (or `putInSpace` + `persistTransformResult`) in order so indexing metastones track timeline tips cleanly.

package/tools/auto-generated-agent-skills/skills/ibgib-implementation-plan/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: ibgib-implementation-plan
+description: Guidelines and template for structuring, creating, and updating persistent [what]_IMPLEMENTATION.md files in the ibgib codebase.
+---
+
+# ibgib Implementation Plan (`[what]_IMPLEMENTATION.md`)
+
+This skill defines the structure, conventions, and workflow for creating and maintaining persistent `[what]_IMPLEMENTATION.md` files across the `ibgib` monorepo.
+
+## Purpose
+
+In complex `ibgib` architectural initiatives, single-session AI artifacts (like transient implementation plans or scratch notes) can be lost across chat sessions. A `[what]_IMPLEMENTATION.md` file serves as a **living, persistent design document, execution tracker, and technical decision log** for a specific sub-project or feature milestone (e.g. `VCS_PLANNING_IMPLEMENTATION.md`, `SSO_IMPLEMENTATION.md`, `TS7_IMPLEMENTATION.md`).
+
+## Standard File Location
+
+Implementation plan files should be placed either in:
+* `docs/[what]_IMPLEMENTATION.md` (for monorepo-wide or domain initiatives, e.g. `docs/vcs/VCS_PLANNING_IMPLEMENTATION.md` or `docs/VCS_IMPLEMENTATION.md`)
+* `docs/[feature]/[what]_IMPLEMENTATION.md` (for targeted domain areas, e.g. `docs/identity/SSO_IMPLEMENTATION.md`)
+
+---
+
+## Standard Structural Schema
+
+Every `[what]_IMPLEMENTATION.md` file MUST follow this high-level structure, adapting or adding sub-sections as relevant:
+
+```markdown
+# [Feature / Subsystem Name] Implementation Plan ([WHAT_CODE_NAME])
+
+## 📌 Executive Summary & Architectural Model
+
+*   **Goal & Overview**: Concise summary of what this implementation achieves.
+*   **Architectural Principles**: Core domain models, DAG dynamics, trade-offs, security model, and identity integration.
+*   **Schemas & Naming Conventions**: Strict naming formats (e.g., kebab-case delimiters, flatcase inner tokens, pool IDs, rel8n labels).
+
+---
+
+## 🛠️ Build Chain & Environment Setup
+
+*   **Workspace Build Chain**: Required build commands and dependency propagation steps (e.g., `npm run build:core-gib` vs `npm run chain:build:web-gib`).
+*   **Environment Configuration**: Required `.env` variables, port settings, or hardware/OS constraints.
+
+---
+
+## ⏱️ Baseline & Decision Log / Journal
+
+### Baseline Metrics (if performance/refactoring focused)
+*   Table of initial timings, size measurements, or code line counts.
+
+### Architectural Decision Log (Journal Entries)
+*   **Entry N ([Date])**: Context, root cause analysis, evaluation of alternatives, and finalized resolution.
+
+---
+
+## 📋 Step-by-Step Implementation Checklist
+
+Break the work into small, incremental, independently verifiable steps:
+
+### Step 1: [Component / Sub-system Name]
+- [ ] **1.1 [Sub-task Title]**: Description of changes.
+  - Linked files: [`basename.mts`](file:///absolute/path/to/file.mts#L10-L30)
+- [ ] **1.2 [Sub-task Title]**: Description of changes.
+
+### Step 2: [Next Phase / Integration]
+- [ ] **2.1 [Sub-task Title]**: Description of changes.
+
+---
+
+## 🧪 Testing & Verification Strategy
+
+*   **Unit & Integration Tests**: `respec-gib` test commands (`npm run test:core-gib`) and specific `ifWeMight` focus instructions.
+*   **Manual & E2E Checks**: Step-by-step verification steps in browser or CLI environment.
+
+---
+
+## 🔌 Upstream Upgrades & Lower-Lib PR Requests (Optional)
+
+_note: these are not PRs proper, because we're not using git. This is just to convey what to do if/when an agent wants to modify a lower lib, which they absolutely should NOT do. If this workaround doesn't work, the agent should stop and explain the blocker, just like any developer working on a complex task._
+
+*   **Application-Level Shims**: List of local shims created in `src/shims/[lib_name]/...` to avoid unvetted modifications to lower-level libraries (anything found in `/libs`, e.g., `libs/helper-gib`, `libs/ts-gib`, etc.).
+*   **Proposed Upstream Upgrades**: Descriptions of missing lower-level features or helpers identified during implementation that should be refactored upstream in future iterations.
+
+---
+
+## 💡 Addendum & Backlog
+
+*   **Deferred Scope**: Features explicitly postponed to future iterations.
+*   **Technical Debt / Security Alerts**: Notes on future refactoring or alert mechanisms needed.
+```
+
+---
+
+## Best Practices & Guidelines
+
+1. **Explicit File Links**: Always use clickable file links using absolute file paths (e.g. `[filename.mts](file:///path/to/file.mts)` or `[filename.mts#L10-L20](file:///path/to/file.mts#L10-L20)`).
+2. **Incremental Updates**: Update task checkboxes (`- [ ]` $\to$ `- [x]`) and add journal entries in real-time as tasks progress.
+3. **Strict Casing & Naming**: Maintain consistency with `ibgib` conventions (flatcase inner tokens, kebab-case component IDs, explicit transform names like `fork`, `mut8`, `rel8`).
+4. **Preserve Context**: When starting a new conversation prompt for a sub-task, reference the corresponding `[what]_IMPLEMENTATION.md` file so any agent can instantly regain full architectural context.
+5. **Positive Lower-Lib Shim Workflow**:
+   * Direct modifications to foundational libraries (`libs/ts-gib`, `libs/core-gib`, `libs/encrypt-gib`, `libs/helper-gib`) should be avoided during application-level feature development unless explicitly authorized.
+   * When an agent encounters a limitation or missing helper in a lower-level library, the recommended workflow is to **create a local application shim** inside the application's source directory (e.g., `src/shims/core-gib/space/custom-space-helper.mts` or `src/shims/ts-gib/transforms/custom-transform-shim.mts`).
+   * If necessary, WET copy and adapt the required helper logic locally.
+   * Document all shims under the **"Upstream Upgrades & Lower-Lib PR Requests"** section in the active `[what]_IMPLEMENTATION.md` file for future upstream monorepo integration.