octwin-cli 0.1.5 → 0.1.6

package/dist/index.js

@@ -148,7 +148,7 @@ function cmdInit(flags) {
     }, null, 2) + '\n', 'utf8');
     writeFileSync(join(dir, '.gitignore'), 'node_modules/\n.pack-bundles/\n.octwin/\n', 'utf8');
     if (!existsSync(join(dir, 'README.md'))) {
-        writeFileSync(join(dir, 'README.md'), `# ${id}\n\nA pure-YAML pack for the Octwin platform.\n\n- Edit \`manifest.yaml\`, \`flows/tools/main.flow.yaml\`, \`prompts/identity.md\`\n- \`octwin validate\` — check it locally\n- \`octwin deploy\` — deploy + install onto your tenant\n`, 'utf8');
+        writeFileSync(join(dir, 'README.md'), `# ${id}\n\nA pure-YAML pack for the Octwin platform.\n\n- \`flows/tools/home.flow.yaml\` — the menu hub (your front door); add a row + tool per journey\n- Edit \`manifest.yaml\`, \`prompts/identity.md\`\n- \`octwin validate --remote\` — full platform check before deploy\n- \`octwin deploy\` — deploy + install onto your tenant\n`, 'utf8');
     }
     console.log(`✓ Scaffolded pure-YAML pack '${id}' at ${dir}`);
     console.log('\nNext:');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {

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

@@ -0,0 +1,24 @@
+# An example capability the home hub invokes. Replace this with your real tool
+# (record_list + a carousel, a collect: intake, a case_open, …). Kept trivial here
+# so the scaffold is chattable end-to-end: home menu → tap "browse" → this renders.
+flow_id:     browse
+version:     1
+description: An example capability, reached from the home menu. Replace with your real tool.
+
+input:
+  message:
+    type:     string
+    optional: true
+    describe: 'Optional note from the user.'
+
+entry:
+  - else: true
+    goto: show
+
+steps:
+  show:
+    - render:
+        render_intent: text_card
+        body: '{$t("browse.body")}'
+      memory_note: '{$t("browse.memory_note")}'
+    - end: applied

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

@@ -0,0 +1,5 @@
+flow_id: browse
+
+strings:
+  body:        'هنا يظهر المحتوى ✨ عدّل أداة "browse" لتبني ميزتك الحقيقية.'
+  memory_note: 'Showed the browse example.'

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

@@ -0,0 +1,32 @@
+# 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

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

@@ -0,0 +1,9 @@
+# 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: '📦 تصفّح'

package/templates/starter/manifest.yaml

@@ -17,10 +17,12 @@ required_adapters:  [messaging]
 default_settings:
   locale: ar
 
-# Agent-callable flow tools. Each id maps to
-# `flows/tools/<id>.flow.yaml` + `<id>.primitives.ts`.
+# 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.
 flows:
-  - main
+  - home      # the menu / navigation hub (see references/ux-patterns.md)
+  - browse    # an example tool the hub invokes — replace with your real capability
 
 # One agent. The platform's universal agent protocol is auto-appended by
 # `createPackAgents` — `instructions:` carries only pack-supplied parts.
@@ -30,9 +32,10 @@ agents:
     # `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).
+    # Flow tools this agent can call (subset of `flows:` above; hub first).
     tools:
-      - main
+      - home
+      - browse
     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}}.

package/templates/starter/prompts/identity.md

@@ -1,5 +1,5 @@
-You are the Starter Assistant — a tiny example bot that ships with the platform as a reference pack.
-
-For any user message, call the `main` tool to greet them. Pass the user's message as the `message` argument when they say something specific you can echo back; otherwise call `main` with no arguments.
-
-Keep replies short and friendly. This pack exists to be copied and customized — once you scaffold your own pack, replace this prompt and the `main` flow with your real domain.
+You are the Starter Assistant — a tiny example bot that ships as a reference pack.
+
+On a greeting, an unclear or off-topic message, or "what can you do?", call the `home` tool — it shows the menu (the pack's front door). Pass a short one-line greeting as `message` when you can personalize it (e.g. greet the user by name); otherwise call `home` with no arguments.
+
+`browse` is an example capability reached from the menu — replace it, and add a row + tool per journey as you build your domain (see the home flow's comments). Keep replies short and friendly.

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

@@ -1,39 +0,0 @@
-# main — the starter greeting flow.
-#
-# The canonical pack-author shape, in miniature — PURE YAML, no TypeScript:
-#   • input:  the tool's schema (drives the LLM tool catalogue + validation)
-#   • entry:  routing rules (here: always go to `greet`)
-#   • steps:  compute the card body with an `assign` expr → render → end
-#   • all user-visible copy lives in main.locale.ar.yaml (never inline here)
-#
-# Conventions worth copying:
-#   • Build data with expr builtins (`$trim`/`$coalesce`/`$t`) — reach for a
-#     pack TS primitive only for logic the expr grammar genuinely can't express.
-#   • `{$body}` interpolates the assigned value into the card.
-#   • `memory_note` leaves the agent a breadcrumb of what the user saw.
-
-flow_id:     main
-version:     1
-description: Greet the user. Call for any message while building out this pack.
-
-input:
-  message:
-    type:     string
-    optional: true
-    describe: 'Optional note from the user to echo back in the greeting.'
-
-entry:
-  - else: true
-    goto: greet
-
-steps:
-  greet:
-    # Echo the user's note when present, else the default greeting — a ternary
-    # over `$trim` + `$t(key, { … })`. (Was a `build_greeting` primitive.)
-    - assign:
-        body: '$trim($coalesce($input.message, "")) != "" ? $t("main.body_with_note", { note: $trim($input.message) }) : $t("main.body_default")'
-    - render:
-        render_intent: text_card
-        body: '{$body}'
-      memory_note: '{$t("main.memory_note")}'
-    - end: applied

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

@@ -1,16 +0,0 @@
-# main — Arabic copy.
-#
-# Every user-facing string for the `main` flow lives here, keyed by a stable
-# name. The flow YAML references each via `$t("main.<key>", { … })`.
-# Placeholder syntax: `{var}` — substituted from the second arg of `$t()`.
-# Adding a new locale = drop a sibling `main.locale.<lang>.yaml` with the same
-# keys translated.
-
-flow_id: main
-
-strings:
-  body_default:   'أهلاً بك 👋 أنا بوت البداية. اكتب أي رسالة لنبدأ.'
-  body_with_note: 'أهلاً بك 👋 قلت: "{note}". أنا بوت البداية — جاهز نبدأ.'
-
-  # Agent breadcrumb (kept in English like other packs' memory notes).
-  memory_note: 'Showed starter greeting card'