octwin-cli 0.8.16 → 0.9.0

package/dist/lib/refusal.js

@@ -0,0 +1,56 @@
+/**
+ * A deploy the platform's checks refused — told the way the console tells it
+ * (`docs/design/pack-findings/`, capture 04): first what did NOT change (the live version keeps
+ * running), then what to fix, grouped by what a customer feels, then the author's own messages under
+ * each. It used to print the raw JSON body, which read like a crash.
+ *
+ * The body's `details` carry each finding's `kind` — the owner's sentence and whether customers notice it
+ * now — when the platform has one (`DryRunValidationError`); a detail without one is listed under
+ * "Also fix", never dropped. Pure, so the shape is tested without a network.
+ */
+/** Messages shown per group — `octwin validate` lists every one. */
+const PER_GROUP = 10;
+export function formatChecksRefusal(body) {
+    const b = body;
+    if (!b || !Array.isArray(b.details) || b.details.length === 0)
+        return null;
+    const details = b.details.filter(d => d && typeof d.message === 'string');
+    const live = typeof b.live_version === 'string' ? b.live_version : null;
+    const groups = new Map();
+    const other = [];
+    for (const d of details) {
+        if (!d.kind) {
+            other.push(d);
+            continue;
+        }
+        const g = groups.get(d.kind.key);
+        if (g)
+            g.items.push(d);
+        else
+            groups.set(d.kind.key, { owner: d.kind.owner, now: d.kind.impact === 'now', items: [d] });
+    }
+    const ordered = [...groups.values()].sort((a, b2) => Number(b2.now) - Number(a.now) || b2.items.length - a.items.length);
+    const things = ordered.length + (other.length > 0 ? 1 : 0);
+    const lines = [
+        live
+            ? `✗ Not deployed — your live version ${live} keeps running, unchanged.`
+            : '✗ Not deployed — nothing on the platform changed.',
+        `  Fix ${things === 1 ? 'this' : `these ${things} things`}, then deploy again:`,
+        '',
+    ];
+    const messages = (items) => {
+        for (const d of items.slice(0, PER_GROUP))
+            lines.push(`      [${d.where}] ${d.message}`);
+        if (items.length > PER_GROUP)
+            lines.push(`      … and ${items.length - PER_GROUP} more — \`octwin validate\` lists them all`);
+    };
+    for (const g of ordered) {
+        lines.push(`  ${g.now ? '!' : '·'} ${g.owner}${g.items.length > 1 ? `  (${g.items.length} places)` : ''}${g.now ? '' : '  (tidy-up)'}`);
+        messages(g.items);
+    }
+    if (other.length > 0) {
+        lines.push(ordered.length > 0 ? '  · Also fix:' : '  · Fix:');
+        messages(other);
+    }
+    return lines;
+}

package/dist/lib/rename.js

@@ -5,7 +5,7 @@
  * vendored copy of ~~`scripts/pack-scaffold/rename.ts`~~, deleted with the in-repo packs;
  * this is the only copy now.) `octwin init` copies the in-package
  * `templates/starter/` tree (packId `starter-kit`, agent `assistant`, flows
- * `home` + `browse`) then this rewrites the copy into a fresh pack:
+ * `home` + `request`) then this rewrites the copy into a fresh pack:
  *   • `starter-kit` → <pack-id>            (manifest id, comments, README)
  *   • agent display name                   (when --display-name given)
  *   • manifest description                 (when --description given)

package/dist/lib/rules.js

@@ -0,0 +1,36 @@
+/**
+ * What `octwin automation` needs to speak RULES — the project's rules as the platform's Automatic tab reads them
+ * (`/api/self/p/automation/…`). Pure, so the two decisions it makes are tested on their own:
+ *
+ * - **which rule an author means** (`resolveRuleKey`) — the key `octwin automation` prints, or the key of the older
+ *   `automation.yaml` job it was compiled from: a `segment` job `cart_nudge` runs as the rule `segment:cart_nudge`,
+ *   and the job key is what the author has in their own YAML;
+ * - **the server's words** (`phraseText`) — a rule's sentence and a line's headline arrive as `Phrase`s (text, a
+ *   strong part, a quote with named slots), the same the console draws; the terminal prints them flat.
+ */
+/** A sentence of `Phrase`s as one line of text — a quote in quotes, a slot as `{name}`. */
+export function phraseText(phrases) {
+    return (phrases ?? []).map(p => p.text ?? p.strong
+        ?? (p.quote ? `"${p.quote.map(q => q.text ?? `{${q.slot ?? ''}}`).join('')}"` : '')).join('');
+}
+/**
+ * The rule an author typed: its key exactly, else the one rule whose key ends in `:<typed>` (an older job's key, or a
+ * hook's moment). Two such rules, or none, is an answer that names what does exist.
+ */
+export function resolveRuleKey(typed, keys) {
+    if (keys.includes(typed))
+        return { key: typed };
+    const hits = keys.filter(k => k.endsWith(`:${typed}`));
+    if (hits.length === 1)
+        return { key: hits[0] };
+    if (hits.length > 1)
+        return { error: `'${typed}' could be ${hits.length} rules — ${hits.join(', ')}. Use the full key.` };
+    return { error: `no rule '${typed}' in this project.` + (keys.length ? ` Rules: ${keys.join(', ')}` : ' It runs none.') };
+}
+/** A time as the terminal shows it — `2026-10-22 09:00Z`; a missing one is a dash. */
+export function shortTime(iso) {
+    if (!iso)
+        return '—';
+    const d = new Date(iso);
+    return Number.isNaN(d.getTime()) ? iso : `${d.toISOString().slice(0, 16).replace('T', ' ')}Z`;
+}

package/package.json

@@ -1,46 +1,46 @@
-{
-  "name": "octwin-cli",
-  "version": "0.8.16",
-  "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
-  "type": "module",
-  "bin": {
-    "octwin": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "templates",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=22"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "yaml": "^2.6.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.7.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "octwin",
-    "cequens",
-    "cli",
-    "whatsapp",
-    "chatbot",
-    "pack",
-    "conversational-ai",
-    "yaml"
-  ],
-  "author": "CEQUENS",
-  "homepage": "https://octwin.ai",
-  "license": "MIT"
-}
+{
+  "name": "octwin-cli",
+  "version": "0.9.0",
+  "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
+  "type": "module",
+  "bin": {
+    "octwin": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "octwin",
+    "cequens",
+    "cli",
+    "whatsapp",
+    "chatbot",
+    "pack",
+    "conversational-ai",
+    "yaml"
+  ],
+  "author": "CEQUENS",
+  "homepage": "https://octwin.ai",
+  "license": "MIT"
+}

package/templates/starter/automation.yaml

@@ -0,0 +1,10 @@
+# What the pack does by itself — rules: WHEN something changes (`on:`) or a time arrives (`at:`), FOR a
+# record, DO actions. Guide: `craft-automation`; every change, time and action: `rules-guide`.
+rules:
+  # The journey's goal, reached by the RECORD — so a request an operator creates counts too, not
+  # only chat ones. Guide: `craft-measure`.
+  - key: request_made
+    for: request
+    on: created
+    do:
+      - track: { journey: request, goal_reached: requested }

package/templates/starter/commands.yaml

@@ -1,14 +1,13 @@
-# Pack-level slash-command declarations (OPTIONAL but recommended).
+# Slash commands — matched BEFORE the AI Agent sees the message. Without this file a pack has none,
+# and `/clear` reaches the agent as ordinary text. Guide: `craft-ux` §7 (the escape hatch).
 #
-# The platform's default `systemCommand` matches inbound text against these
-# BEFORE normal agent dispatch. Without a `commands.yaml`, a pack has NO slash
-# commands — e.g. `/clear` silently does nothing (it just goes to the agent as
-# text). Ship this file if you want `/clear` (and friends) to work like the
-# other packs.
-#
-# action: `close_conversation` (reset the conversation) | `noop` (reply only).
+# action: `close_conversation` (start over) | `noop` (reply only) | `cancel_handoff` (a customer
+#         waiting for a person goes back to the AI Agent; takes no `reply:`).
+# `reply:` is one text per language this pack speaks; each customer reads theirs.
 
-- match:    '/clear'
-  action:   close_conversation
-  reply: 'تم مسح المحادثة ✅ تقدر تبدأ من جديد.'
-  source:   '/clear'
+- match:  '/clear'
+  action: close_conversation
+  reply:
+    ar: 'تم مسح المحادثة ✅ ماذا تريد أن تفعل؟'
+    en: 'Cleared ✅ — what would you like to do?'
+  source: '/clear'

package/templates/starter/flows/tools/home.flow.yaml

@@ -1,32 +1,34 @@
-# The HOME hub — your pack's front door / menu, and the FIRST tool the agent calls
-# on a greeting or an unclear message. A pure-render `list_picker`: one row per
-# primary capability, each routing a tap STRAIGHT to that tool via `on_select.invoke`
-# (no LLM turn). Add a row as you add each journey. Every shipped reference pack
-# ships a home flow like this — see references/ux-patterns.md in the octwin-pack skill.
-flow_id:     home
-version:     1
-description: Main menu / welcome. Call on a greeting, an unclear or off-topic message, or "what can you do?".
-
-input:
-  message:
-    type:     string
-    optional: true
-    describe: 'Optional ONE short greeting line YOU compose for this user (e.g. greet them by name).'
-
-entry:
-  - else: true
-    goto: show
-
-steps:
-  show:
-    - render:
-        render_intent: list_picker              # the universal chooser (WhatsApp list / web menu)
-        header: '{$t("home.header")}'
-        body:   '$coalesce($input.message, $t("home.greeting"))'   # agent line if given, else the default
-        cta:    '{$t("home.cta")}'               # the WhatsApp list-button label (required for list_picker)
-        items:                                   # ONE row per capability — the tap routes via on_select
-          - { title: '{$t("home.row_browse")}', on_select: { invoke: 'browse' } }
-          # Add a row per tool as you build them, e.g.:
-          # - { title: '{$t("home.row_x")}', on_select: { invoke: 'some-tool', with: { mode: x } } }
-      memory_note: 'Showed the home menu.'       # English breadcrumb — surfaced to the agent next turn
-    - end: applied
+# The HOME hub — the pack's front door, and the FIRST tool the agent calls on a greeting or an
+# unclear message. A pure-render list: one row per capability, each tap routed STRAIGHT to its tool
+# (no AI Agent turn). Add a row as you add each journey. Guide: `craft-ux` §1.
+flow_id:     home
+version:     1
+description: Main menu / welcome. Call on a greeting, an unclear or off-topic message, or "what can you do?".
+
+input:
+  message:
+    type:     string
+    optional: true
+    describe: 'Optional ONE short greeting line YOU compose for this customer (e.g. greet them by name).'
+
+entry:
+  - else: true
+    goto: show
+
+steps:
+  show:
+    # Marks the funnel's first stage — what the customer DID, not what the flow did. The goal is
+    # reached by the request record's own hook (xrm.yaml). Guide: `craft-measure`.
+    - track: { journey: request, stage_enter: menu }
+    - render:
+        render_intent: list_picker
+        header: '{$t("home.header")}'
+        body:   '$coalesce($input.message, $t("home.greeting"))'
+        footer: '{$t("home.footer")}'
+        cta:    '{$t("home.cta")}'
+        items:
+          - { title: '{$t("home.row_request")}', description: '{$t("home.row_request_about")}', on_select: { invoke: request } }
+          # A row per journey you add, e.g.:
+          # - { title: '{$t("home.row_x")}', on_select: { invoke: some-tool } }
+      memory_note: 'Showed the home menu.'
+    - end: applied

package/templates/starter/flows/tools/home.locale.ar.yaml

@@ -1,9 +1,8 @@
-# Every user-visible string for the home flow, keyed by `$t("home.<key>")`.
-# Lead labels with an emoji — it makes the menu scannable (all reference packs do this).
-flow_id: home
-
-strings:
-  header:     'القائمة الرئيسية'
-  greeting:   'أهلاً بك 👋 اختر من القائمة:'
-  cta:        'اختر'
-  row_browse: '📦 تصفّح'
+flow_id: home
+strings:
+  header:            '👋 أهلاً بك'
+  greeting:          'كيف نقدر نساعدك اليوم؟'
+  footer:            'اكتب /clear في أي وقت لتبدأ من جديد'
+  cta:               '📋 القائمة'
+  row_request:       '🔧 طلب زيارة'
+  row_request_about: 'فني يأتي إليك'

package/templates/starter/flows/tools/home.locale.en.yaml

@@ -0,0 +1,8 @@
+flow_id: home
+strings:
+  header:            '👋 Welcome'
+  greeting:          'How can we help you today?'
+  footer:            'Type /clear any time to start over'
+  cta:               '📋 Menu'
+  row_request:       '🔧 Request a visit'
+  row_request_about: 'A technician comes to you'

package/templates/starter/flows/tools/request.flow.yaml

@@ -0,0 +1,95 @@
+flow_id:     request
+version:     1
+description: Ask for a technician's visit. Call when the customer reports a problem at home. Pass `issue` only when they named it.
+
+input:
+  area:  { type: string, agent_fillable: false }   # an area record id — only a tapped row sets it
+  issue: { type: string, optional: true, enum: [leak, power, ac, other] }
+
+entry:
+  - else: true
+    goto: intake
+
+steps:
+  intake:
+    - collect:
+        fields:
+          # A fetched picker that holds an ID: `bind:` named, `rows:` read off it, `page: true`
+          # (free when the list fits), `on_empty:` because a typed area name is not an area id,
+          # and `selection:` so the label travels with the id for the summary.
+          - field: area
+            label: '$t("request.ask_area")'
+            options:
+              body:  '{$t("request.ask_area")}'
+              fetch: { do: record_list, args: { entity: area, all: true, limit: 50 }, bind: areas }
+              rows:  '$areas.rows'
+              map:   { value: '$item.id', label: '$item.fields.name', selection: { area_name: '$item.fields.name' } }
+              page:  true
+              on_empty: no_areas
+          # A fixed set: `type: choice` with an `enum:` — the labels are `<pack_id>.issue.<value>` in
+          # the pack-level locale file, and `$enum_label` reads them back. A typed answer matches too.
+          - field: issue
+            type:  choice
+            label: '$t("request.ask_issue")'
+            options:
+              body:   '{$t("request.ask_issue")}'
+              enum:   issue
+              values: [leak, power, ac, other]
+          # A phone: the native share on WhatsApp, a typed local number everywhere; `dial_code` reads
+          # 01005551111 as +20…
+          - field: phone
+            type:  phone
+            dial_code: '20'
+            label: '$t("request.ask_phone")'
+          # A number with a reject rule. `when` is TRUE when the value is WRONG, and it runs only once
+          # the field has a value — so it needs no null guard.
+          - field: floor
+            type:  number
+            label: '$t("request.ask_floor")'
+            validate:
+              when:  '$state.floor < 0 || $state.floor > 60'
+              error: '{$t("request.floor_error")}'
+          # Optional: never blocks `complete`, never asked on its own — filled when the customer
+          # volunteers it or the agent passes it. (An optional `type: media` IS offered, with Skip.)
+          - field: notes
+            required: false
+            label: '$t("request.ask_notes")'
+        complete: [{ goto: confirm }]
+
+  confirm:
+    - use: approve_apply
+      with:
+        header:       '{$t("request.confirm_header")}'
+        preview:      '{$t("request.preview", { area: $state.area_name, issue: $enum_label($state.issue, "issue"), phone: $state.phone, floor: $state.floor, notes: $coalesce($state.notes, "—") })}'
+        apply:        save
+        abort_render: { render_intent: text_card, body: '{$t("request.not_sent")}' }
+        on_other:     intake           # a typed correction re-enters the collect; filled fields are skipped
+        memory_note:  'Asked the customer to confirm the visit request.'
+
+  save:
+    - do: record_save
+      args:
+        entity: request
+        fields:
+          area:  '$state.area'
+          issue: '$state.issue'
+          phone: '$state.phone'
+          floor: '$state.floor'
+          notes: '$coalesce($state.notes, "")'
+      bind: saved
+      outputs:
+        ok:
+          - render:
+              render_intent: detail_card
+              body: '{$t("request.saved", { number: $saved.record_number })}'
+              buttons:
+                - { title: '{$t("request.btn_home")}', on_select: { invoke: home } }
+            memory_note: 'Saved visit request #{$saved.record_number}.'
+          - end: applied
+        invalid:
+          - assign: { state.phone: null }
+          - goto: intake
+        failed: [{ end: failed }]
+
+  no_areas:
+    - end: { status: aborted, body: '{$t("request.no_areas")}' }

package/templates/starter/flows/tools/request.locale.ar.yaml

@@ -0,0 +1,14 @@
+flow_id: request
+strings:
+  ask_area:       '📍 في أي منطقة أنت؟'
+  ask_issue:      '🔧 ما المشكلة؟'
+  ask_phone:      '📱 رقم موبايلك، ليتصل بك الفني؟'
+  ask_floor:      '🏢 في أي دور؟'
+  floor_error:    'من فضلك اكتب دورًا بين 0 و60.'
+  ask_notes:      'هل هناك شيء آخر يجب أن نعرفه؟'
+  confirm_header: '📋 من فضلك راجع طلبك'
+  preview:        "📍 {area}\n🔧 {issue}\n📱 {phone}\n🏢 الدور {floor}\n📝 {notes}"
+  not_sent:       'حسنًا، لم نرسل أي طلب.'
+  saved:          "✅ رقم الطلب {number}. سيتصل بك الفني لتحديد موعد."
+  btn_home:       '🏠 القائمة'
+  no_areas:       'لا نستقبل طلبات في أي منطقة حتى الآن. من فضلك تحدث مع الاستقبال من القائمة.'

package/templates/starter/flows/tools/request.locale.en.yaml

@@ -0,0 +1,14 @@
+flow_id: request
+strings:
+  ask_area:       '📍 Which area are you in?'
+  ask_issue:      '🔧 What is the problem?'
+  ask_phone:      '📱 Your mobile number, so the technician can call you?'
+  ask_floor:      '🏢 Which floor?'
+  floor_error:    'A floor between 0 and 60, please.'
+  ask_notes:      'Anything else we should know?'
+  confirm_header: '📋 Please check your request'
+  preview:        "📍 {area}\n🔧 {issue}\n📱 {phone}\n🏢 Floor {floor}\n📝 {notes}"
+  not_sent:       'OK, nothing was sent.'
+  saved:          "✅ Request number {number}. A technician will call you to agree a time."
+  btn_home:       '🏠 Menu'
+  no_areas:       'We are not taking requests in any area yet. Please talk to reception from the menu.'

package/templates/starter/journeys/request.journey.yaml

@@ -0,0 +1,12 @@
+# A journey is the funnel the owner reads on the Analytics and Performance pages: stages are what
+# the customer did; the goal is the outcome. Guide: `craft-measure` (the journey recipe).
+id: request
+label: { en: 'Asking for a visit', ar: 'طلب زيارة' }
+lifecycle:
+  reentry:  after_exit            # a customer who asks again later is a second run
+  terminal: { goal: requested }   # what completes a run
+stages:
+  - { id: menu,      order: 1, label: { en: 'Opened the menu',   ar: 'فتح القائمة' } }
+  - { id: requested, order: 2, label: { en: 'Requested a visit', ar: 'طلب زيارة' } }
+goals:
+  - { id: requested, stage: requested, label: { en: 'Visit requested', ar: 'تم طلب الزيارة' } }

package/templates/starter/locale.ar.yaml

@@ -1,13 +1,9 @@
-# starter-kit — pack-wide Arabic strings.
-#
-# Entries here are shared across ALL flows in this pack (cross-flow labels,
-# common error messages, status verbs). Flow-specific strings live in
-# `flows/tools/<flow>.locale.ar.yaml`. Reference these via `$t("starter-kit.<key>")`
-# — every key is namespaced (pack-level by `pack_id`; flow-level by `flow_id`).
-# A bare `$t("<key>")` does NOT resolve (returns the raw key); the flow linter's
-# `locale-key-not-namespaced` rule fails the build on a bare key.
+# Pack-wide Arabic strings, read as `$t("starter-kit.<key>")` — or by `$enum_label` for a `choice`
+# field's labels (`issue.<value>`). A flow's own strings live beside the flow. Guide: `craft-language`.
 
 pack_id: starter-kit
 strings:
-  # Example pack-level string — reference as `$t("starter-kit.greeting")`.
-  greeting: 'أهلاً! إزاي أقدر أساعدك؟'
+  issue.leak:  '💧 تسريب مياه'
+  issue.power: '⚡ الكهرباء'
+  issue.ac:    '❄️ التكييف'
+  issue.other: '🔧 شيء آخر'

package/templates/starter/locale.en.yaml

@@ -0,0 +1,9 @@
+# Pack-wide English strings, read as `$t("starter-kit.<key>")` — or by `$enum_label` for a `choice`
+# field's labels (`issue.<value>`). A flow's own strings live beside the flow. Guide: `craft-language`.
+
+pack_id: starter-kit
+strings:
+  issue.leak:  '💧 Water leak'
+  issue.power: '⚡ Power'
+  issue.ac:    '❄️ Air conditioning'
+  issue.other: '🔧 Something else'

package/templates/starter/manifest.yaml

@@ -1,65 +1,64 @@
-# manifest.yaml — your pack is declared entirely by this one file. Required:
-# id, version (a STRING, e.g. '1.0.0'), description. Everything else is optional
-# and grows with your domain. `octwin validate` checks it locally; the platform
-# re-validates the full schema on `octwin deploy`.
+# manifest.yaml — the one file that declares your pack. Required: id, version (a STRING,
+# e.g. '1.0.0'), description. Everything else grows with your domain. `octwin validate` runs the
+# platform's full check. Guide: `octwin platform-kb pull`, then read `craft-manifest`.
 
 id:          starter-kit
-version:     1.0.0
-description: 'A hello bot — edit this to build your pack.'
+version:     '1.0.0'
+description: 'A starter pack — a home menu and a visit request. Edit it into your business.'
 
-# Channels this pack supports + platform capabilities it needs. A pack with
-# no media or search only needs `messaging`. Add embedding / vision / storage
-# as your domain grows. (Your data model goes in `xrm.yaml` — packs have no
-# database of their own.)
 supported_channels: [whatsapp, web]
 required_adapters:  [messaging]
 
-# What to do with a VOICE NOTE. WhatsApp cannot stop customers sending them, and an
-# ABSENT block is not "nothing happens" — it means `passthrough`, i.e. no
-# speech-to-text, so the agent gets "a voice message arrived, no transcript" and has
-# to improvise. `transcribe` is the right default for a conversational pack; use
-# `passthrough` when you handle the audio ref yourself, or `decline` (with a
-# `notice:`) to ask for text instead.
+# The languages this pack speaks — held to the root locale.<lang>.yaml files, and every customer
+# string must exist in each (a missing key refuses the deploy). Guide: `craft-language`.
+supported_languages: [ar, en]
+
+default_settings:
+  locale: ar          # the language a customer reads before the platform knows theirs
+
+# A VOICE NOTE cannot be blocked on WhatsApp, and an absent block means `passthrough` — no
+# speech-to-text, so the AI Agent gets "a voice message arrived" and has to improvise.
+# `transcribe` is right for a conversational pack. Guide: `craft-ux` §5.
 inbound_preprocessing:
   voicenote:
     mode: transcribe
 
-# Default locale for platform-emitted copy + this pack's `$t()` lookups.
-default_settings:
-  locale: ar
+# How the pack looks in a catalog a business browses. Optional; without it the catalog shows your
+# id and description. Guide: `craft-manifest` (listing).
+# listing:
+#   title:    'My business'
+#   tagline:  'The one line a buyer reads first'
+#   category: retail
+
+# Your chat face — the name, colour and welcome the web widget shows. It SEEDS the project's settings
+# at install only, so get it right before the first install. Guide: `craft-manifest` (widget).
+# widget:
+#   name:   'My business'
+#   accent: '#0369a1'
+#   welcome:
+#     en: 'Hi! How can we help?'
+#     ar: 'أهلاً! كيف نقدر نساعدك؟'
 
-# Agent-callable flow tools. Each id maps to `flows/tools/<id>.flow.yaml`
-# (+ its `<id>.locale.<lang>.yaml`). List the HOME hub first — it's the pack's
-# front door; add each new tool here as you build it.
+# The flow tools. Each id is `flows/tools/<id>.flow.yaml` with a locale file per language. The HOME
+# hub comes first — it is the pack's front door. Guide: `craft-ux` §1.
 flows:
-  - home      # the menu / navigation hub (see references/ux-patterns.md)
-  - browse    # an EXAMPLE tool the hub invokes — replace it, or delete this line AND flows/tools/browse.*
+  - home       # the menu
+  - request    # a visit request — the `craft-collect` recipe; replace it with your own journey
 
-# One agent. The platform's universal agent protocol is auto-appended by
-# `createPackAgents` — `instructions:` carries only pack-supplied parts.
 agents:
-  - id:                assistant
-    display_name:      'Starter Assistant'
-    # `openrouter/` prefix routes via OpenRouter. Operators override the
-    # model per-project from the console.
-    default_model:     'openrouter/google/gemini-3.1-flash-lite-preview'
-    # Flow tools this agent can call (subset of `flows:` above; hub first).
+  - id:           assistant
+    display_name: 'Assistant'
+    # A model id names its provider: `openrouter/<vendor>/<model>`. A bare id is refused.
+    # Operators can override the model per project in the console.
+    default_model: 'openrouter/google/gemini-3.1-flash-lite-preview'
+    # The flows this agent may call — its whole world. List the hub first. Guide: `craft-manifest`.
     tools:
       - home
-      - browse
+      - request
     include_platform_protocol: true
-    # Instruction parts, joined with '\n\n'. `file:` paths are pack-root
-    # relative; `.md` files may use built-in placeholders like {{pack.id}}.
     instructions:
       - file: prompts/identity.md
-    # No working_memory block — deliberate, and you should keep it that way.
-    # Declaring one makes the platform add Mastra's updateWorkingMemory tool +
-    # a "call it every turn" instruction: an extra LLM generation on most turns,
-    # and small models (like the lite default above) parrot the
-    # <working_memory_data> envelope straight into user-visible replies. Session
-    # identity (name/lang/phone) already reaches the model via the platform's
-    # first-turn [ctx: …] header, and tools read it from the request context —
-    # so you gain nothing here. Leave it off unless you're on a large model and
-    # have a concrete slot schema to maintain.
+    # No `working_memory:` — it adds a tool call on most turns and small models echo it to the
+    # customer. The platform already gives the agent the customer's name, language and phone.
     default_memory:
-      lastMessages: 10   # size of the recalled message window
+      lastMessages: 10