docs: structured Markdown standard for APPHUB.yaml description

CONTRIBUTING.md

@@ -105,7 +105,7 @@ required fields must be present and non-empty for App Hub submission.
 friendly_id: ""              # {folder-slug}-playbook (e.g. epic-ehr-playbook, my-crm-playbook)
 title: ""                    # Display name for the Playbook (matches ContentStack field)
 tag_line: ""                 # Short tagline for App Hub detail page (required, max 128 chars)
-description: ""              # 1–2 sentences, used as App Hub listing copy
+description: ""              # App Hub supports Markdown; use YAML | block (opening + Why + What); see Field Rules
 
 product_types: []            # Array: one or more of teams | meetings | calling | rooms | contact_center
 
@@ -139,6 +139,17 @@ submission_date: ""          # ISO date (e.g. 2025-03-01)
 - **tag_line** — Short tagline displayed on the App Hub detail page. Required.
   Max 128 characters.
 
+- **description** — App Hub supports **Markdown**. Use a YAML block scalar
+  (`description: |`) with **blank lines** between sections: an opening paragraph
+  (**bold** key terms such as Webex product, flow, and stack), a
+  **Why use this playbook** heading with 3–5 outcome-focused bullets, and a
+  **What it does** heading with bullets for concrete behaviors and endpoints.
+  Stay accurate to the playbook. Do **not** use this field for canonical upstream
+  repository URLs, clone or package-install instructions, or “code lives
+  elsewhere”—document that in **README** and, for reference playbooks, in
+  **`src/README.md`**. Full importer checklist and example shape:
+  [import_playbook.md — APPHUB.yaml](docs/commands/import_playbook.md#apphubyaml).
+
 - **product_types** — Array of one or more of: `teams`, `meetings`, `calling`,
   `rooms`, `contact_center`. Playbooks can span multiple products (e.g.
   `["meetings", "teams"]` appears on both /meetings and /messaging).

PLAYBOOK_TEMPLATE/APPHUB.yaml

@@ -18,12 +18,32 @@ title: "MyCRM + Webex Contact Center Integration"
 tag_line: "Connect MyCRM to Webex Contact Center for screen pop and customer context"
 
 # -----------------------------------------------------------------------------
-# description — 1–2 sentences, used as App Hub listing copy
+# description — App Hub supports Markdown. Use a block scalar (description: |) with
+# blank lines between sections: opening paragraph (bold key terms), **Why use this
+# playbook** (3–5 outcome bullets), **What it does** (concrete behaviors/endpoints).
+# Do not put upstream repo URLs or install-only instructions here—use README and
+# src/README.md for reference playbooks. See docs/commands/import_playbook.md.
 # -----------------------------------------------------------------------------
 description: |
-  This sample demonstrates how to build an integration between MyCRM and Webex Contact Center.
-  Agents receive customer context and screen pop when handling calls. The code includes
-  webhook handling, REST API calls, and Agent Desktop configuration.
+  A **Node.js** sample that connects **MyCRM** to **Webex Contact Center** for agent
+  **screen pop**: webhooks, customer lookup, and context surfaced in **Agent Desktop**.
+
+  **Why use this playbook**
+
+  - **Faster delivery:** Start from a working **Express** service instead of an empty
+    repo when you need CRM context on a call.
+  - **Fewer integration mistakes:** Shows the expected **REST** payloads and **Webex**
+    API usage so you are not guessing field names or auth order.
+  - **Secrets handled safely:** **Client ID**, **client secret**, and tokens load from
+    **environment variables**, matching how you will configure non-dev environments.
+  - **Easy to verify:** Local run plus simple HTTP checks so you can confirm the flow
+    before wiring production routing or scaling.
+
+  **What it does**
+
+  - Accepts **MyCRM** events over HTTP and validates incoming requests.
+  - Calls documented **Webex** APIs to resolve or push customer context for **WxCC**.
+  - Returns structured data your **Agent Desktop** or flow can display to agents.
 
 # -----------------------------------------------------------------------------
 # product_types — Where this Playbook appears. Pick one or more.

docs/commands/import_playbook.md

@@ -241,7 +241,61 @@ Use the full schema from PLAYBOOK_TEMPLATE/APPHUB.yaml. **Preserve the section c
   `meetings-exporter-playbook`) to reduce App Hub name collisions with actual integrations
 - `title` — `{ThirdPartyTool} + Webex {Product} Integration`
 - `tag_line` — one-line value proposition (required, max 128 chars)
-- `description` — 1–2 sentences for App Hub listing
+- `description` — App Hub **supports Markdown** in this field. Use a YAML block scalar
+  (`description: |`) and separate sections with **blank lines**. Do **not** use
+  `description` for canonical upstream URLs, clone or install commands, or
+  “source lives elsewhere”—put those in **README** (and in **`src/README.md`** for
+  [reference imports](import_playbook_reference.md)). Keep **`tag_line`** as the short
+  one-liner (max 128 characters); `description` carries the expanded detail.
+
+  **Structure**
+
+  - **Opening paragraph:** Short summary of what the playbook offers; use **bold**
+    on key terms (Webex product, integration flow, language or stack).
+  - **Why use this playbook:** A line `**Why use this playbook**`, then **3–5
+    bullets** focused on user outcomes—for example faster delivery, fewer auth
+    mistakes, correct token or API usage, framework fit, a workable test path,
+    secrets loaded from environment variables.
+  - **What it does:** A line `**What it does**` (or equivalent), then bullets for
+    **concrete behaviors**: OAuth or callback handling, REST calls, named routes or
+    endpoints the sample exposes, configuration the reader can verify.
+
+  **Importer checklist**
+
+  - [ ] `description: |` with blank lines between the opening paragraph, Why, and What
+  - [ ] Opening paragraph uses **bold** on product, flow, and stack terms where helpful
+  - [ ] **Why use this playbook** has 3–5 outcome-oriented bullets
+  - [ ] **What it does** lists behaviors and endpoints that match the actual playbook
+  - [ ] No upstream repo links, package install lines, or pointer-only copy in
+    `description`
+
+  **Example shape:** For pacing, depth, and Markdown formatting, compare
+  [`playbooks/wxcc-token-java-sample/APPHUB.yaml`](../../playbooks/wxcc-token-java-sample/APPHUB.yaml)
+  (`description`). Generic pattern (substitute your integration’s facts):
+
+  ```yaml
+  description: |
+    A **Node.js** sample that wires **MyCRM** into **Webex Contact Center** for
+    agent screen pop: webhook intake, customer lookup, and Agent Desktop context.
+
+    **Why use this playbook**
+
+    - **Ship faster:** Reuse a minimal **Express** service pattern instead of
+      designing the flow from a blank editor.
+    - **Fewer auth mistakes:** Shows how to validate **Webex** signatures and store
+      tokens using **environment variables** only.
+    - **Right API shape:** Demonstrates the exact **REST** calls and payloads your
+      flow needs before you harden for production.
+    - **Testable path:** Includes a local run and curl-friendly checks so you can
+      confirm behavior before deploying.
+
+    **What it does**
+
+    - Receives **MyCRM**-originated events and normalizes them for **WxCC**.
+    - Calls documented **Webex** APIs with the scoped **access token** from your app.
+    - Returns structured customer context your **Agent Desktop** or flow can consume.
+  ```
+
 - `product_types` — from integration type mapping (Step 2)
 - `categories` — default `["productivity", "developer-tools"]`; include verticals
   (healthcare, financial-services, retail-ecommerce) and app categories as appropriate

docs/commands/import_playbook_reference.md

@@ -160,7 +160,16 @@ items where relevant:
 
 ### APPHUB.yaml
 
-Same rules as [import_playbook.md — APPHUB.yaml](import_playbook.md#apphubyaml).
+Same rules as [import_playbook.md — APPHUB.yaml](import_playbook.md#apphubyaml),
+including the structured Markdown `description` (`description: |`, **Why use this
+playbook**, **What it does**). Reference-upstream playbooks use the **same**
+description quality bar as standard imports.
+
+Do **not** use App Hub `description` to point at the canonical upstream GitHub repo,
+package install commands, or “get the code from upstream”—that belongs in **README**
+and in **`src/README.md`**. Keep `description` focused on outcomes and concrete
+behaviors this Playbook documents, like any other playbook.
+
 `product_url` remains
 `https://github.com/webex/WebexPlaybooks/tree/main/playbooks/<slug>`.