rhachet-roles-bhrain 0.1.1 → 0.3.0

package/dist/roles/thinker/skills/brief.catalogize/.demo/persona.usecases.v2025_08_28.i2.md

@@ -0,0 +1,64 @@
+## 🧩 .brief.catalog: Use Cases for Personas
+
+## 📊 Compressed Overview
+
+| **Cluster**           | **What**                                          |
+|-----------------------|---------------------------------------------------|
+| **[Product Development]** | Using personas to guide the creation of products that meet user needs |
+| **[Marketing Strategy]**  | Leveraging personas to tailor marketing efforts and messages for target audiences |
+| **[User Experience Design]** | Employing personas to enhance the usability and accessibility of digital interfaces |
+| **[Customer Support]** | Utilizing personas to improve the effectiveness of support services |
+| **[Training and Onboarding]** | Using personas to create targeted training materials for employees |
+
+---
+
+## 🎨 Clusters
+
+### 🎨 **Product Development — Enhance Product Relevance**
+Personas help align product features with real user needs.
+- Integrate user needs and pain points into product design.
+- Prioritize features based on user motivations.
+- Validate product ideas against persona scenarios.
+
+---
+
+### 📈 **Marketing Strategy — Optimize Messaging and Reach**
+Personas aid in crafting tailored marketing messages.
+- Segment audiences by demographic and behavioral traits.
+- Refine value propositions based on persona insights.
+- Identify the most effective channels for reaching target users.
+
+---
+
+### 💻 **User Experience Design — Improve Usability**
+Personas inform interface and interaction design.
+- Align design elements with user preferences and behaviors.
+- Conduct usability testing with a focus on persona scenarios.
+- Ensure accessibility for diverse user groups.
+
+---
+
+### 🛡️ **Customer Support — Enhance Service Delivery**
+Personas support better customer interactions.
+- Customize support strategies based on persona expectations.
+- Develop FAQ and help resources tailored to common issues.
+- Train support staff to address persona-specific challenges.
+
+---
+
+### 📚 **Training and Onboarding — Targeted Learning Materials**
+Personas guide the development of training content.
+- Design training programs that meet the specific needs of different employee personas.
+- Tailor onboarding processes to align with new hires' backgrounds and skills.
+- Evaluate training effectiveness through persona-driven feedback.
+
+---
+
+## ✨ Insight
+- **Product Development optimizes relevance.**
+- **Marketing Strategy refines targeting.**
+- **User Experience Design enhances accessibility.**
+- **Customer Support boosts service delivery.**
+- **Training and Onboarding personalizes learning.**
+
+Personas serve as a valuable tool in various contexts by providing detailed insights into user behaviors and needs, ultimately enhancing effectiveness and alignment with real-world scenarios.

package/dist/roles/thinker/skills/brief.catalogize/.readme.md

@@ -0,0 +1,5 @@
+catalogs instances of a concept, to organize them
+
+---
+
+note, uses <instantiate> under the hood, to instantiate an instance of the doc.brief variant catalog

package/dist/roles/thinker/skills/brief.catalogize/stepCatalogize.skill.js

@@ -103,7 +103,7 @@ exports.SKILL_CATALOGIZE = (0, rhachet_1.genRoleSkill)({
         lookup: {
             apiKeyOpenai: {
                 source: 'process.env',
-                envar: 'PREP_OPENAI_KEY',
+                envar: 'OPENAI_API_KEY',
                 desc: 'the openai key to use',
                 type: 'string',
             },

package/dist/roles/thinker/skills/brief.catalogize/stepCatalogize.skill.js.map

@@ -1 +1 @@
-{"version":3,"file":"stepCatalogize.skill.js","sourceRoot":"","sources":["../../../../../src/roles/thinker/skills/brief.catalogize/stepCatalogize.skill.ts"],"names":[],"mappings":";;;AAAA,yCAAiC;AACjC,qCAA4E;AAC5E,+DAA6E;AAE7E,sEAAmE;AACnE,kEAA+D;AAC/D,yFAAsF;AACtF,gGAA6F;AAE7F,qDAAkD;AAErC,QAAA,gBAAgB,GAAG,IAAA,sBAAY,EAAC;IAC3C,IAAI,EAAE,YAAY;IAClB,KAAK,EAAE,+BAAc;IACrB,OAAO,EAAE;QACP,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,MAAM,EAAE,cAAc;gBACtB,IAAI,EAAE,GAAG;gBACT,IAAI,EAAE,kCAAkC;gBACxC,IAAI,EAAE,QAAQ;aACf;YACD,IAAI,EAAE;gBACJ,MAAM,EAAE,cAAc;gBACtB,IAAI,EAAE,GAAG;gBACT,IAAI,EAAE,yBAAyB;gBAC/B,IAAI,EAAE,SAAS;aAChB;YACD,UAAU,EAAE;gBACV,MAAM,EAAE,cAAc;gBACtB,IAAI,EAAE,GAAG;gBACT,IAAI,EAAE,wDAAwD;gBAC9D,IAAI,EAAE,SAAS;aAChB;YACD,MAAM,EAAE;gBACN,MAAM,EAAE,cAAc;gBACtB,IAAI,EAAE,GAAG;gBACT,IAAI,EAAE,oDAAoD;gBAC1D,IAAI,EAAE,SAAS;aAChB;SACF;QACD,MAAM,EAAE,CACN,KAAK,EAOL,EAAE,CAAC,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;QACrC,WAAW,EAAE,KAAK,EAAE,KAMnB,EAAE,EAAE;YACH,gDAAgD;YAChD,MAAM,MAAM,GAAG,IAAA,wCAAiB,EAAC,EAAE,GAAG,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;YACxD,MAAM,SAAS,GAAG;gBAChB,IAAI,EAAE;oBACJ,OAAO,EAAE,IAAA,yCAAkB,EACzB,EAAE,GAAG,EAAE,MAAM,GAAG,kBAAkB,EAAE,EACpC,EAAE,QAAQ,EAAE,IAAI,EAAE,CACnB;oBACD,OAAO,EAAE,IAAA,yCAAkB,EACzB,EAAE,GAAG,EAAE,MAAM,GAAG,kBAAkB,EAAE,EACpC,EAAE,QAAQ,EAAE,IAAI,EAAE,CACnB;iBACF;gBACD,QAAQ,EAAE,IAAA,yCAAkB,EAC1B,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,EAAE,EAChC,EAAE,QAAQ,EAAE,IAAI,EAAE,CACnB;gBACD,eAAe,EAAE,IAAA,yCAAkB,EACjC,EAAE,GAAG,EAAE,MAAM,GAAG,mBAAmB,EAAE,EACrC,EAAE,QAAQ,EAAE,IAAI,EAAE,CACnB;gBACD,eAAe,EAAE,IAAA,yCAAkB,EACjC,EAAE,GAAG,EAAE,KAAK,CAAC,MAAM,EAAE,EACrB,EAAE,QAAQ,EAAE,IAAI,EAAE,CACnB;gBACD,UAAU,EAAE,CACV,MAAM,OAAO,CAAC,GAAG,CACf,KAAK,CAAC,UAAU;oBACd,EAAE,KAAK,CAAC,GAAG,CAAC;qBACX,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;qBACtB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,MAAM,IAAA,gBAAI,EAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CACrD,CACF;qBACE,IAAI,EAAE;qBACN,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CACjB,IAAA,yCAAkB,EAAC,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAC/D;gBACH,MAAM,EACJ,KAAK,CAAC,MAAM;oBACV,EAAE,KAAK,CAAC,GAAG,CAAC;qBACX,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;qBACtB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACb,IAAA,yCAAkB,EAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAC3D,IAAI,EAAE;aACZ,CAAC;YAEF,gCAAgC;YAChC,MAAM,WAAW,GAAW,MAAM,CAAC,KAAK,IAAI,EAAE;gBAC5C,qCAAqC;gBACrC,IAAI,KAAK,CAAC,IAAI;oBACZ,OAAO,CACL,CACE,MAAM,IAAA,yCAAkB,EACtB,EAAE,GAAG,EAAE,KAAK,CAAC,IAAI,EAAE,EACnB,EAAE,MAAM,EAAE,UAAU,EAAE,CACvB,CAAC,GAAG,EAAE,CACR,EAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CACxB,CAAC;gBAEJ,gCAAgC;gBAChC,OAAO,KAAK,CAAC,GAAG,CAAC;YACnB,CAAC,CAAC,EAAE,CAAC;YACL,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;YAE3D,sCAAsC;YACtC,MAAM,IAAA,qCAAiB,EAAC,EAAE,QAAQ,EAAE,mBAAmB,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,kCAAkC;YAE3G,OAAO;gBACL,MAAM,EAAE,MAAM,IAAA,sBAAY,EAAC;oBACzB,IAAI,EAAE,QAAQ;oBACd,KAAK,EAAE;wBACL,GAAG,EAAE,EAAE;wBACP,GAAG,EAAE;4BACH,mBAAmB,EAAE,SAAS,CAAC,IAAI,CAAC,OAAO;4BAC3C,mBAAmB,EAAE,SAAS,CAAC,IAAI,CAAC,OAAO;4BAC3C,QAAQ,EAAE,SAAS,CAAC,QAAQ;yBAC7B;wBACD,IAAI,EAAE,SAAS,CAAC,UAAU;qBAC3B;iBACF,CAAC;gBACF,OAAO,EAAE,MAAM,IAAA,sBAAY,EAAC;oBAC1B,IAAI,EAAE,SAAS;oBACf,KAAK,EAAE;wBACL,GAAG,EAAE;4BACH,eAAe,EAAE,SAAS,CAAC,eAAe,CAAC;4BAC3C,eAAe,EAAE,SAAS,CAAC,eAAe,CAAC;yBAC5C;wBACD,MAAM,EAAE,SAAS,CAAC,MAAM;qBACzB;iBACF,CAAC;aACH,CAAC;QACJ,CAAC;KACF;IACD,OAAO,EAAE;QACP,MAAM,EAAE;YACN,YAAY,EAAE;gBACZ,MAAM,EAAE,aAAa;gBACrB,KAAK,EAAE,iBAAiB;gBACxB,IAAI,EAAE,uBAAuB;gBAC7B,IAAI,EAAE,QAAQ;aACf;SACF;QACD,MAAM,EAAE,CAAC,KAAK,EAAqC,EAAE,CACnD,OAAO,KAAK,CAAC,YAAY,KAAK,QAAQ;QACxC,WAAW,EAAE,GAAG,EAAE;YAChB,OAAO;gBACL,GAAG,IAAA,mCAAgB,GAAE;gBACrB,GAAG,IAAA,uCAAkB,GAAE;gBACvB,GAAG,IAAA,+BAAqB,EAAC;oBACvB,MAAM,EAAE,IAAA,6CAAqB,EAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,wBAAwB;iBAChF,CAAC;aACH,CAAC;QACJ,CAAC;KACF;IACD,MAAM,EAAE,EAAE;CACX,CAAC,CAAC"}
+{"version":3,"file":"stepCatalogize.skill.js","sourceRoot":"","sources":["../../../../../src/roles/thinker/skills/brief.catalogize/stepCatalogize.skill.ts"],"names":[],"mappings":"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"}

package/dist/roles/thinker/skills/brief.catalogize/stepCatalogize.skill.ts

@@ -0,0 +1,173 @@
+import { glob } from 'fast-glob';
+import { enrollThread, genContextStitchTrail, genRoleSkill } from 'rhachet';
+import { genArtifactGitFile, getArtifactObsDir } from 'rhachet-artifact-git';
+
+import { genContextLogTrail } from '@src/.test/genContextLogTrail';
+import { getContextOpenAI } from '@src/.test/getContextOpenAI';
+import { setSkillOutputSrc } from '@src/domain.operations/artifact/setSkillOutputSrc';
+import { genStitchStreamToDisk } from '@src/domain.operations/context/genStitchStreamToDisk';
+
+import { loopCatalogize } from './stepCatalogize';
+
+export const SKILL_CATALOGIZE = genRoleSkill({
+  slug: 'catalogize',
+  route: loopCatalogize,
+  threads: {
+    lookup: {
+      output: {
+        source: 'process.argv',
+        char: 'o',
+        desc: 'the output file to write against',
+        type: 'string',
+      },
+      goal: {
+        source: 'process.argv',
+        char: 'g',
+        desc: 'the goal of the request',
+        type: '?string',
+      },
+      references: {
+        source: 'process.argv',
+        char: 'f',
+        desc: 'reference files to to use, if any; delimit with commas',
+        type: '?string',
+      },
+      briefs: {
+        source: 'process.argv',
+        char: 'b',
+        desc: 'brief files to to use, if any; delimit with commas',
+        type: '?string',
+      },
+    },
+    assess: (
+      input,
+    ): input is {
+      output: string;
+      goal: string;
+      references: string;
+      briefs: string;
+      ask: string;
+    } => typeof input.output === 'string',
+    instantiate: async (input: {
+      output: string;
+      goal: string;
+      references: string;
+      briefs: string;
+      ask: string;
+    }) => {
+      // declare where all the artifacts will be found
+      const obsDir = getArtifactObsDir({ uri: input.output });
+      const artifacts = {
+        goal: {
+          concept: genArtifactGitFile(
+            { uri: obsDir + '.goal.concept.md' },
+            { versions: true },
+          ),
+          context: genArtifactGitFile(
+            { uri: obsDir + '.goal.context.md' },
+            { versions: true },
+          ),
+        },
+        feedback: genArtifactGitFile(
+          { uri: obsDir + '.feedback.md' },
+          { versions: true },
+        ),
+        'focus.context': genArtifactGitFile(
+          { uri: obsDir + '.focus.context.md' },
+          { versions: true },
+        ),
+        'focus.concept': genArtifactGitFile(
+          { uri: input.output },
+          { versions: true },
+        ),
+        references: (
+          await Promise.all(
+            input.references
+              ?.split(',')
+              .filter((uri) => !!uri)
+              .map(async (pattern) => await glob(pattern)) ?? [], // support glob references
+          )
+        )
+          .flat()
+          .map((reference) =>
+            genArtifactGitFile({ uri: reference }, { access: 'readonly' }),
+          ),
+        briefs:
+          input.briefs
+            ?.split(',')
+            .filter((uri) => !!uri)
+            .map((brief) =>
+              genArtifactGitFile({ uri: brief }, { access: 'readonly' }),
+            ) ?? [],
+      };
+
+      // detect the goal of the caller
+      const goalConcept: string = await (async () => {
+        // if goal explicitly defined, use it
+        if (input.goal)
+          return (
+            (
+              await genArtifactGitFile(
+                { uri: input.goal },
+                { access: 'readonly' },
+              ).get()
+            )?.content ?? input.ask
+          );
+
+        // otherwise, assume its the ask
+        return input.ask;
+      })();
+      await artifacts.goal.concept.set({ content: goalConcept });
+
+      // add an src file for historic record
+      await setSkillOutputSrc({ skillUri: 'bhrain.catalogize', opts: input }); // todo: get skillUri from context
+
+      return {
+        caller: await enrollThread({
+          role: 'caller',
+          stash: {
+            ask: '',
+            art: {
+              'foci.goal.concept': artifacts.goal.concept,
+              'foci.goal.context': artifacts.goal.context,
+              feedback: artifacts.feedback,
+            },
+            refs: artifacts.references,
+          },
+        }),
+        thinker: await enrollThread({
+          role: 'thinker',
+          stash: {
+            art: {
+              'focus.context': artifacts['focus.context'],
+              'focus.concept': artifacts['focus.concept'],
+            },
+            briefs: artifacts.briefs,
+          },
+        }),
+      };
+    },
+  },
+  context: {
+    lookup: {
+      apiKeyOpenai: {
+        source: 'process.env',
+        envar: 'OPENAI_API_KEY',
+        desc: 'the openai key to use',
+        type: 'string',
+      },
+    },
+    assess: (input): input is { apiKeyOpenai: string } =>
+      typeof input.apiKeyOpenai === 'string',
+    instantiate: () => {
+      return {
+        ...getContextOpenAI(),
+        ...genContextLogTrail(),
+        ...genContextStitchTrail({
+          stream: genStitchStreamToDisk({ dir: process.cwd() }), // stream events to disk
+        }),
+      };
+    },
+  },
+  readme: '',
+});

package/dist/roles/thinker/skills/brief.catalogize/stepCatalogize.ts

@@ -0,0 +1,132 @@
+import {
+  asStitcherFlat,
+  type GStitcher,
+  genStitchRoute,
+  type RoleContext,
+  StitchStepCompute,
+  type Threads,
+} from 'rhachet';
+import type { Artifact } from 'rhachet-artifact';
+import type { GitFile } from 'rhachet-artifact-git';
+
+import type { Focus } from '@src/_topublish/rhachet-roles-bhrain/src/domain/objects/Focus';
+import type { ContextOpenAI } from '@src/access/sdk/sdkOpenAi';
+import { genLoopFeedback } from '@src/domain.operations/artifact/genLoopFeedback';
+import { getThinkerBriefs } from '@src/roles/thinker/getThinkerBrief';
+import { stepInstantiate } from '@src/roles/thinker/skills/khue.instantiate/stepInstantiate';
+
+const BRIEFS_FOR_CATALOGIZE = getThinkerBriefs([
+  'cognition/cog021.structs.catalog.md',
+  'knowledge/kno201.documents.catalogs.[article].md',
+  'knowledge/kno201.documents._.[catalog].md',
+  'knowledge/kno301.doc.enbrief.2._.[catalog].md',
+  'knowledge/kno301.doc.enbrief.2.catalogize.[article].md',
+  'knowledge/kno301.doc.enbrief.2.catalogize.[lesson].md',
+  'knowledge/kno301.doc.enbrief.1.from_instances.[demo].color.md',
+  'knowledge/kno301.doc.enbrief.1.from_instances.[demo].gravity.md',
+  'knowledge/kno301.doc.enbrief.1.from_instances.[demo].entropy.md',
+  'knowledge/kno501.doc.enbrief.catalog.structure1.[article].md',
+  'knowledge/kno501.doc.enbrief.catalog.structure1.[lesson].template.md',
+]);
+
+type StitcherDesired = GStitcher<
+  Threads<{
+    caller: RoleContext<
+      'caller',
+      {
+        art: {
+          feedback: Artifact<typeof GitFile>;
+          'foci.goal.concept': Focus['concept'];
+          'foci.goal.context': Focus['context'];
+        };
+        refs: Artifact<typeof GitFile>[];
+      }
+    >;
+    thinker: RoleContext<
+      'thinker',
+      {
+        art: {
+          'focus.concept': Focus['concept'];
+          'focus.context': Focus['context'];
+        };
+        briefs: Artifact<typeof GitFile>[];
+      }
+    >;
+  }>,
+  ContextOpenAI & GStitcher['context'],
+  { content: string }
+>;
+
+const stepAddThinkerBriefs = new StitchStepCompute<
+  GStitcher<
+    StitcherDesired['threads'],
+    GStitcher['context'],
+    { briefs: { before: string[]; after: string[] } }
+  >
+>({
+  slug: '@[thinker]<getBriefs>',
+  readme: "adds a set of briefs to the @[thinker]'s context",
+  form: 'COMPUTE',
+  stitchee: 'thinker',
+  invoke: async ({ threads }) => {
+    // identify the prior briefs
+    const briefsBeforeUnsanitized = threads.thinker.context.stash.briefs;
+
+    // drop the briefs if they were already included (we'll put them at the end again, so they're the last thought)
+    const briefsBefore = briefsBeforeUnsanitized.filter(
+      (b) => !BRIEFS_FOR_CATALOGIZE.includes(b),
+    );
+
+    // append these briefs
+    const briefsAfter = [...briefsBefore, ...BRIEFS_FOR_CATALOGIZE];
+
+    // add the briefs to the thinker's context
+    threads.thinker.context.stash.briefs = briefsAfter;
+
+    // extend the focus context to explicitly know to use these briefs; // todo: put this into its own step for observability in stitch trail
+    const focusContextBefore = (
+      await threads.thinker.context.stash.art['focus.context'].get()
+    )?.content;
+    const focusContextToAdd = `
+instantiate the concept as a [catalog] via the <catalogize> mechanism, defined in your briefs.
+
+in particular, leverage 'catalog.structure.s1' when possible
+    `.trim();
+    const focusContextAfter = [
+      focusContextBefore,
+      '',
+      '---',
+      '',
+      focusContextToAdd,
+    ].join('\n');
+    await threads.thinker.context.stash.art['focus.context'].set({
+      content: focusContextAfter,
+    });
+
+    // and then report that we did so
+    return {
+      input: null,
+      output: {
+        briefs: {
+          before: briefsBefore.map((artifact) => artifact.ref.uri),
+          after: briefsAfter.map((artifact) => artifact.ref.uri),
+        },
+      },
+    };
+  },
+});
+
+export const stepCatalogize = asStitcherFlat<StitcherDesired>(
+  genStitchRoute({
+    slug: '@[thinker]<catalogize>',
+    readme:
+      '@[thinker]<getBriefs> -> @[thinker]<instantiate>[catalog] -> [instance][catalog]',
+    sequence: [stepAddThinkerBriefs, stepInstantiate],
+  }),
+);
+
+export const loopCatalogize = genLoopFeedback({
+  stitchee: 'thinker',
+  artee: 'focus.concept',
+  repeatee: stepCatalogize,
+});

package/dist/roles/thinker/skills/brief.demonstrate/.demo/user.journey.roadtrip.input.example.i4.md

@@ -0,0 +1,3 @@
+concept = user journey
+
+demonstrate via `walkthrough` = `a road tripper planning a route with a digital map for scenic stops`

package/dist/roles/thinker/skills/brief.demonstrate/.demo/user.journey.roadtrip.input.example.i5.md

@@ -0,0 +1,3 @@
+concept = [user journey] x [a road tripper planning a route with a digital map for scenic stops]
+
+demonstrate via `walkthrough`

package/dist/roles/thinker/skills/brief.demonstrate/.demo/user.journey.roadtrip.input.example.i6.md

@@ -0,0 +1,3 @@
+concept = [user journey]
+
+demonstrate via `walkthrough` = [a road tripper planning a route with a digital map for scenic stops]

package/dist/roles/thinker/skills/brief.demonstrate/.demo/user.journey.roadtrip.input.example.md

@@ -0,0 +1,3 @@
+concept = [user journey]
+
+demonstrate via `walkthrough` = [a road tripper planning a route with a digital map for scenic stops]

package/dist/roles/thinker/skills/brief.demonstrate/.demo/user.journey.roadtrip.v2025_08_27.i1.md

@@ -0,0 +1,52 @@
+# 🧩 .brief.demo: `road trip planning` via `example` = `digital map for scenic stops`
+
+## 💡 concept
+
+road trip planning involves designing a journey that includes specific routes, stops, and schedules, optimized for a desired travel experience. digital maps enhance this process by providing real-time navigation, route customization, and access to information on scenic and practical stops.
+
+## ❓ question
+
+> what is an example of road trip planning?
+
+## 📌 example: using a digital map for scenic stops
+
+### 📌.📖 what
+
+> what does using a digital map for scenic stops entail?
+
+using a digital map for planning a road trip focuses on selecting routes that accommodate scenic stops, enhancing travel experiences with curated detours and sights along the journey. it involves inputting start and end points, and choosing routes that prioritize scenic value or landmark visits, supported by digital mapping features.
+
+- **route selection**
+  - selecting pathways that maximize scenic value over directness
+    - *example:* choosing coastal highways over interstates for ocean views
+  - adjusting the route for side trips to landmarks or attractions
+
+- **integration of technology**
+  - using apps like google maps or waze to identify scenic spots and detours
+    - *example:* employing satellite view to spot parks or bodies of water
+  - accessing real-time traffic updates to adjust plans dynamically
+    
+- **planning stops**
+  - identifying notable stops for rest, photos, or local experiences
+    - *example:* marking national parks or historical sites as waypoints
+  - arranging timing to ensure stops align with daylight or operational hours
+
+### 📌.🔍 how
+
+> how is using a digital map for scenic stops an example of road trip planning?
+
+using a digital map to plan a road trip with scenic stops exemplifies effective journey design by incorporating technology to enhance traveler experience and optimize route efficiency.
+
+- **experience enhancement**
+  - improves the quality of the journey by including scenic and cultural landmarks
+  - offers flexibility in planning, allowing for spontaneous detours based on interest
+
+- **efficiency and convenience**
+  - digital route planning minimizes travel stress with instant updates and alternative routing
+  - streamlines location scouting, reducing the need for manual guidebooks or paper maps
+
+- **technology integration**
+  - leverages apps for multiple purposes: navigation, traffic management, and sightseeing
+  - supports informed choices with access to reviews, ratings, and user-generated content
+
+together, these aspects create a comprehensive example of utilizing contemporary tools to refine and enrich the road trip experience.

package/dist/roles/thinker/skills/brief.demonstrate/.demo/user.journey.roadtrip.v2025_08_27.i2.md

@@ -0,0 +1,51 @@
+# 🧩 .brief.demo: `road trip planning` via `walkthrough` = `scenic stops with a digital map`
+
+## 💡 concept
+road trip planning involves organizing a journey by selecting routes, destinations, and activities that align with the traveler's interests, using tools such as digital maps to enhance the overall experience.
+
+## ❓ question
+> how can a road tripper plan a route using a digital map for scenic stops?
+
+## 📌 walkthrough: planning a route with scenic stops
+
+### 📌.📖 what
+
+> what is involved in planning a scenic road trip route using a digital map?
+
+this planning process involves utilizing a digital map to identify and select scenic stops along a road trip path. it requires understanding both the map's functionalities and the tripper's preferences to create a satisfying and memorable travel experience.
+
+- **digital map features**
+  - **search and discovery**: enter destinations and view routes; use filters to find scenic stops
+    - example: input "scenic highways" or "national parks" into the search bar to see options along the route
+  - **custom markers and notes**: pin locations and add personal notes for future reference
+    - example: mark "lookout point" and add a note: "great for sunsets"
+  - **real-time updates**: access live traffic conditions and estimated travel times
+    - example: toggle real-time traffic to avoid congested areas
+  
+- **trip optimization**
+  - **route customization**: adjust the path for desired stops and detours
+    - example: drag route line to include a favorite hiking trail
+  - **itinerary planning**: set time slots for each stop to maximize the day
+    - example: plan a morning stop at a lakeside park, followed by a lunch break at a local diner
+  - **alternative routes**: explore multiple paths to balance scenic beauty with travel efficiency
+    - example: compare scenic coastal routes vs. direct highways for time and experience balance
+
+### 📌.🔍 how
+
+> how does this walkthrough demonstrate effective road trip planning with a digital map?
+
+this walkthrough showcases road trip planning by illustrating the integration of technology, personal interests, and logistical considerations. it highlights the map's role in facilitating a personalized, efficient journey while maintaining flexibility.
+
+- **technology integration**
+  - **enhanced exploration**: digital maps provide comprehensive visual data and search capabilities to uncover less-known scenic spots
+  - **real-time adaptability**: live traffic and weather updates allow for dynamic adjustments, ensuring a smooth journey
+  
+- **personalized travel experience**
+  - **interest alignment**: filtering for scenic stops ensures visits to places that match personal preferences
+  - **documenting and sharing**: custom markers and notes allow for shared experiences and future trip reference, enriching the travel narrative
+
+- **logistical balance**
+  - **optimized scheduling**: itinerary tools balance time at each stop with overall trip progress, preventing rushed or leisurely days
+  - **efficient navigation**: contour the route with both speed and scenic enjoyment, leveraging real-time feedback for the best path forward
+
+together, these elements articulate a seamless approach to road trip planning that combines strategy with spontaneity, all anchored by digital map tools.

package/dist/roles/thinker/skills/brief.demonstrate/.demo/user.journey.roadtrip.v2025_08_27.i3.md

@@ -0,0 +1,47 @@
+# 🧩 .brief.demo: `user journey` via `walkthrough`
+
+## 💡 concept
+
+a user journey represents the experience and steps a user takes to achieve a specific goal within a system or service, often visualized in stages to improve understanding of user interactions and touchpoints.
+
+## ❓ question
+
+> how is the user journey demonstrated via a walkthrough?
+
+## 📌 example: road tripper planning a route with a digital map for scenic stops
+
+### 📌.📖 what
+
+> what is the road tripper planning journey?
+
+a road tripper uses a digital map application to plan a route that includes scenic stops. the journey involves several stages, from initial setup to final navigation, focusing on interaction points with the application.
+
+- **initial setup**:
+  - **goal identification**: user decides on a scenic road trip and opens the digital map app.
+  - **preferences input**: user selects preferences for scenic spots and desired driving distance per day.
+  
+- **route planning**:
+  - **exploration and selection**: user explores available scenic stops suggested by the app, using filters for categories like nature, historical sites, or local cuisine.
+  - **itinerary building**: user selects preferred stops and adds them to the route.
+
+- **navigation**:
+  - **real-time directions**: user follows turn-by-turn navigation provided by the app.
+  - **adaptive updates**: app suggests alternate routes or stops based on current traffic or user preferences.
+
+### 📌.🔍 how
+
+> how does the user journey exemplify its concept via a walkthrough?
+
+the user journey map illustrates touchpoints and decisions a road tripper encounters within the digital map app, providing practical insights into user interaction:
+
+- **touchpoints**: 
+  - engaging with app features like inputting preferences, exploring options, and building a route shows how users move through phases.
+  
+- **interaction flow**: 
+  - navigating the map and making decisions on stops offers insight into user decision-making processes and potential friction points.
+  
+- **user engagement**: 
+  - the seamless process from initial setup to navigation demonstrates user experience and app functionality, revealing areas for enhancement or innovation.
+  
+- **feedback loops**: 
+  - how the app adapts based on user feedback (e.g., preferences and real-time navigation changes) illustrates user-centered design's importance in enhancing journey satisfaction.

package/dist/roles/thinker/skills/brief.demonstrate/.demo/user.journey.roadtrip.v2025_08_27.i4.md

@@ -0,0 +1,62 @@
+# 🧩 .brief.demo: `user journey` via `walkthrough` = `a road tripper planning a route with a digital map for scenic stops`
+
+## 💡 concept
+
+a user journey is a sequence of interactions a user experiences when engaging with a product or service to achieve a specific goal. it focuses on the touchpoints between the user and the system that facilitate the user's end goal, illustrating the user's needs, actions, emotions, and perceptions.
+
+## ❓ question
+
+> how can we demonstrate a user journey through a walkthrough?
+
+## 📌 walkthrough: planning a road trip with a digital map
+
+### 📌.📖 what
+
+> what is the user journey of planning a road trip with a digital map?
+
+a digital map is used by a road tripper to plan a route with scenic spots, aligning with the essence of a user journey through sequential, user-centric touchpoints. this journey involves:
+
+- **initial decision**
+  - the road tripper decides to embark on a scenic road trip and needs to plan the route.
+  - emotionally, the user is excited and anticipates discovering new places.
+  
+- **launching the map**
+  - the user opens a digital map application to begin the planning process.
+  - the interface is the first point of interaction, offering a familiar and intuitive layout, generating comfort.
+  
+- **entering the start and end points**
+  - the user inputs their current location and desired endpoint to generate potential routes.
+  - user feels engaged and hopeful as multiple route options are presented.
+  
+- **selecting a scenic route**
+  - the map suggests alternative routes emphasizing scenic views and attractions.
+  - by filtering for scenic routes, the user feels adventurous and curious.
+  
+- **adding stops**
+  - user explores the map to add points of interest like parks, historical sites, and diners along the route.
+  - excitement grows as the user customizes the trip, adding layers of experiences.
+  
+- **adjusting for time and preferences**
+  - user evaluates travel time and makes adjustments based on personal preferences for driving duration and stop frequency.
+  - combination of relaxation and control as the trip is tailored further.
+  
+- **final review and saving the itinerary**
+  - user reviews the completed itinerary within the app and saves it for navigation.
+  - satisfaction is high due to the interactive nature and personalized trip ahead.
+  
+- **embarking on the journey**
+  - the final step involves activating navigation and starting the adventure.
+  - anticipatory thrill evident as the journey formally begins.
+
+### 📌.🔍 how
+
+> how does this journey exemplify a user journey?
+
+the road trip planning journey exemplifies a user journey by showcasing:
+
+- **goal-oriented interaction**: at each stage, the user's actions are directed towards the ultimate goal of creating a memorable road trip.
+- **touchpoints and feedback loops**: interactions with the digital map generate continuous feedback, enhancing user satisfaction and decision-making.
+- **emotional progression**: from excitement and curiosity at inception to satisfaction and anticipation at realization, the journey encapsulates the user's emotional landscape.
+- **user-centered design**: the map app is designed to surface scenic options, allow customization, and assist in trip optimization, all centered around enhancing user experience.
+
+this walkthrough renders abstract elements of user journeys tangible through a scenario many can relate to, enhancing understanding via a concrete instance.