rhachet-roles-bhrain 0.2.0 → 0.3.0

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.

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

@@ -0,0 +1,47 @@
+# 🧩 .brief.demo: `user journey` via `walkthrough` = `a road tripper planning a route with a digital map for scenic stops`
+
+## 💡 Concept
+
+A user journey is the complete experience a user has when interacting with a product or service, from initial discovery through usage and beyond. It maps every touchpoint and path a user may take, often represented visually to understand and improve user experiences.
+
+## ❓ Question
+
+> How does a road tripper plan a route with a digital map for scenic stops?
+
+## 📌 Walkthrough: Planning a Scenic Road Trip with a Digital Map
+
+### 📌.📖 What
+
+> What does the road trip planning journey involve?
+
+1. **Preparation Phase**
+   - **Define Goals**: The road tripper determines the primary goal of the trip (e.g., visiting national parks, coastal drives).
+   - **Select Tools**: They choose a digital mapping tool (e.g., Google Maps, Waze) for route planning, considering features like traffic updates, offline maps, and user reviews.
+
+2. **Route Planning Phase**
+   - **Initial Route Input**: The road tripper inputs starting point and destination into the mapping tool.
+   - **Customizing the Path**: They explore suggested routes, comparing distance, time, and scenic detour options.
+   - **Scenic Stops Identification**: Using the map’s search features, they identify scenic spots along the route, such as trails, overlooks, and local attractions.
+   - **Incorporate Stops**: Selected stops are added to the itinerary, balancing desired locations with travel time.
+
+3. **Logistical Coordination**
+   - **Accommodation Search**: Based on route and stops, find accommodations for overnight stays, factoring in proximity to scenic locations.
+   - **Optimize for Time and Experience**: Adjust departure times for optimal arrival at stops during peak scenic conditions (e.g., sunset views).
+   - **Resource Planning**: Check for necessary resources (e.g., fuel stations, rest areas) along the planned route.
+
+4. **Execution Phase**
+   - **Real-Time Navigation**: During the trip, they use GPS for real-time updates and re-routing if needed due to traffic or spontaneous detours.
+   - **Experience Amplification**: Leverage map features like user reviews and photos to enhance visits to planned scenic stops.
+
+### 📌.🔍 How
+
+> How does this planning exemplify a user journey?
+
+This user journey exemplifies the concept through the following elements:
+
+- **Touchpoints Mapping**: Every interaction with the digital map, from initial search to real-time navigation, is a touchpoint designed for seamless user experience.
+- **Goal-Oriented Interaction**: The journey is aligned with the user’s goal of exploring scenic stops, driving their engagement and decision-making processes.
+- **Iterative Path Customization**: The use of real-time data and user feedback loops within the digital tool allows for dynamic and responsive journey customization, enhancing user satisfaction.
+- **Experience Personalization**: Incorporates personalized preferences for scenic routes versus faster routes, illustrating user-centric design.
+
+This walkthrough comprehensively captures how the digital mapping tool facilitates a meaningful user journey for road trippers focusing on scenic stops.

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

@@ -0,0 +1,53 @@
+# 🧩 .brief.demo: `user journey` via `walkthrough`
+
+## 💡 Concept
+
+A user journey is the path a user takes when interacting with a service or product to achieve a specific goal, mapped out to understand user experiences, touchpoints, and obstacles.
+
+## ❓ Question
+
+> How can a user journey be demonstrated via a walkthrough?
+
+## 📌 Walkthrough: A Road Tripper Planning a Route with a Digital Map for Scenic Stops
+
+### 📌.📖 What
+
+> What is the scenario?
+
+- **Context**: A road tripper named Alex uses a digital map service to plan a route featuring scenic stops across the country.
+- **Purpose**: To ensure the journey is enjoyable, with opportunities to experience nature, culture, and landmarks.
+- **Tools**: A smartphone with a digital map application loaded with features like route planning, attraction highlights, and user reviews.
+
+### Key Steps in the Walkthrough:
+
+1. **Initial Planning**
+   - Alex opens the digital map application and inputs the destination city.
+   - The app displays multiple route options with estimated travel times and scenic ratings.
+
+2. **Route Selection**
+   - Alex selects a route optimized for scenic beauty, as indicated by user reviews and attraction icons along the map.
+   - The chosen route includes highlights like National Parks, quaint towns, and roadside attractions.
+
+3. **Customization**
+   - Alex uses the "Add Stops" feature to integrate recommended scenic viewpoints and rest areas into the trip.
+   - The map recalculates the journey with these additional waypoints, showing updated travel times.
+
+4. **Live Navigation**
+   - During the trip, Alex uses turn-by-turn navigation, which provides audio cues for upcoming attractions.
+   - Real-time traffic updates and road conditions adjust the route dynamically to avoid delays.
+
+5. **Feedback and Reflection**
+   - Post-trip, Alex uses the app to rate the attractions and route experience, contributing to the community insights.
+   - The app prompts Alex to save the trip as a future reference or share with other users planning similar journeys.
+
+### 📌.🔍 How
+
+> How does this walkthrough demonstrate a user journey?
+
+- **Engagement with Technology**: Highlights interaction with the app's features to plan and execute an enriching journey.
+- **User-Centric Design**: Shows how the app assists in optimizing the journey, suggesting alternatives and customizations tailored to user preferences.
+- **Experience Enrichment**: Demonstrates how digital tools enhance the journey by integrating real-time data and community feedback.
+- **Journey Mapping**: Captures the essence of a user journey by following Alex's experiences from planning to execution, reflecting the stages of exploration, decision-making, and reflection.
+- **Feedback Loop**: Illustrates the app's role in creating a seamless experience while encouraging continuous improvement through user insights.
+
+This walkthrough encapsulates the user journey of leveraging technology for enhanced trip experiences, reflecting the interplay between user actions, technology, and feedback mechanisms.

package/dist/roles/thinker/skills/brief.demonstrate/.readme

@@ -0,0 +1,3 @@
+purpose = explain a concept, via demonstration
+
+produces .brief.demo's which can be used to provision context

package/dist/roles/thinker/skills/brief.demonstrate/stepDemonstrate.skill.js

@@ -119,7 +119,7 @@ exports.SKILL_DEMONSTRATE = (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',
             },