refactor(templates): unify naming, single-source metadata, honest AI copy

README.md

@@ -48,13 +48,15 @@ that an LLM can read, diff, and safely modify without breaking the runtime.
 | [`packages/contracts/`](./packages/contracts) | Post-signature contract lifecycle (CLM) — AI-extracted metadata, approvals, renewal alerts | ✅ v0 | 4003 | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/objectstack-ai/templates/tree/main/packages/contracts) |
 | [`packages/procurement/`](./packages/procurement) | Vendors, purchase requests, POs, goods receipt, 3-way-match rollup | ✅ v0 | 4004 | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/objectstack-ai/templates/tree/main/packages/procurement) |
 | [`packages/compliance/`](./packages/compliance) | SOC 2 / ISO 27001 controls, evidence with expiry, assessments | ✅ v0 | 4005 | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/objectstack-ai/templates/tree/main/packages/compliance) |
-| [`packages/helpdesk/`](./packages/helpdesk) | AI-first customer support — auto-triage, suggested replies, KB recall, sentiment escalation | ✅ v0 | 4006 | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/objectstack-ai/templates/tree/main/packages/helpdesk) |
+| [`packages/helpdesk/`](./packages/helpdesk) | Customer support — tickets, SLA, escalation, KB, portal; AI triage scaffolded | ✅ v0 | 4006 | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/objectstack-ai/templates/tree/main/packages/helpdesk) |
 | [`packages/content/`](./packages/content) | Content marketing engine — editorial calendar, competitive signals, channel ROI, 8-state piece lifecycle | ✅ v0 | 4008 | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/objectstack-ai/templates/tree/main/packages/content) |
 | [`packages/hr/`](./packages/hr) | People Ops — employee directory, org chart, time-off approvals, document expiry alerts | ✅ v0 | 4009 | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/objectstack-ai/templates/tree/main/packages/hr) |
-| [`packages/project/`](./packages/project) | AI Project Management — portfolio tracking with AI risk prediction, delay forecasting, resource conflict detection | 🚧 v0.1-wip | 4010 | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/objectstack-ai/templates/tree/main/packages/project) |
+| [`packages/project/`](./packages/project) | Project Management — PMO portfolio, milestones, risks; AI forecasting scaffolded | 🚧 v0.1-wip | 4010 | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/objectstack-ai/templates/tree/main/packages/project) |
 | [`packages/expense/`](./packages/expense) | Employee expense & reimbursement — multi-line reports, category policy, amount-tiered approval, reimbursement tracking | ✅ v0 | 4011 | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/objectstack-ai/templates/tree/main/packages/expense) |
 | `packages/sales-pipeline/` | Lite CRM (leads, opportunities, accounts) | 🚧 planned | 4007 | — |
 
+> 📍 Planned work — including the **AI implementation plan** (several templates ship AI as a scaffold today) — lives in [docs/ROADMAP.md](./docs/ROADMAP.md).
+
 ### Run them all at once
 
 Want every template in **one runtime, one app launcher** — as if you installed

docs/ROADMAP.md

@@ -0,0 +1,58 @@
+# Roadmap
+
+Planned work across the template collection. This file tracks what's **coming**;
+each template's `README.md` describes what it does **today**. Keep the two in
+sync — when a feature ships, move it from here into the template and its README.
+If it's still a scaffold, it belongs here, not in present-tense marketing copy.
+
+## AI
+
+Several templates lead with AI in their pitch. The honest current state is mixed,
+so it's tracked here as a plan rather than implied as delivered.
+
+### Current state
+
+| Template | AI surface | Status today |
+|---|---|---|
+| contracts | `extract_terms` — AI metadata extraction | **Real** — calls `api.openai.com` directly ([extract_terms.action.ts](../packages/contracts/src/actions/extract_terms.action.ts)). Dark without an `OPENAI_API_KEY`. |
+| content | `draft_outline_from_topic`, `suggest_cta`, `summarize_competitor_signal` | **Real** — same raw OpenAI calls. Dark without a key. |
+| helpdesk | ticket triage (`ai_summary` / `ai_category` / `ai_sentiment` / `ai_suggested_reply` / `ai_suggested_kb_ids`) | **Scaffold** — deterministic baseline (`ai_summary = description.slice(0, 280)`); [`ai_triage_on_create.flow.ts`](../packages/helpdesk/src/flows/ai_triage_on_create.flow.ts) is an "insert your LLM here" stub. |
+| project | risk / delay / budget forecasting (`ai_*` fields) | **Scaffold** — the flow prediction node is labelled `STUB`; seed values are illustrative, not computed. |
+| todo, expense, hr, compliance, procurement | — | No AI; deterministic by design. |
+
+### Plan
+
+1. **Route AI through the platform model registry, not raw `api.openai.com`.**
+   Replace the direct `fetch()` calls (contracts, content) with ObjectStack's
+   AI / model-registry services (see the `objectstack-ai` skill). Payoff:
+   provider-agnostic (OpenAI, **Anthropic / Claude**, Bedrock, local), central
+   key management, and it actually demonstrates the "AI-native" platform instead
+   of bypassing it.
+
+2. **Degrade honestly.** With no model configured, AI fields/actions should show
+   an explicit "configure AI to enable" state — never a silent stub output
+   (helpdesk's substring) or a failing network call (contracts/content without a
+   key). A user must never mistake a placeholder for a prediction.
+
+3. **Pick one AI flagship and finish it.** `helpdesk` is the best candidate:
+   real triage → `ai_summary` / `ai_category` / `ai_sentiment` /
+   `ai_suggested_reply`, plus embedding-based KB recall for `ai_suggested_kb_ids`,
+   shipped end-to-end through (1) and (2). Let the others stay honest
+   deterministic starters until each earns the same treatment.
+
+4. **Stop shipping seeded numbers that look computed.** project's
+   `ai_completion_probability` etc. are hand-authored demo values. Once (3)'s
+   pattern exists, either compute them or keep them clearly marked as samples
+   (the field group is now labelled "AI Predictions (scaffolded)").
+
+## Non-AI
+
+- **project** — Gantt rendering (schema ready, UI pending platform); resolve the
+  scope overlap with `todo` (task-level vs portfolio-level).
+- **content** — trim toward the starter charter; at 9 objects / ~5,200 `src` LOC
+  it is over the ≤6 objects / ≤2,500 LOC budget in
+  [TEMPLATE_GUIDE.md](../TEMPLATE_GUIDE.md).
+- **Marketplace category facets** — labels render inconsistently (Title Case for
+  some categories, lowercase for others). The fix belongs in the marketplace
+  UI's category → label map, not in the template manifests (which all use
+  lowercase slugs).

packages/compliance/package.json

@@ -40,16 +40,5 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@10.33.0",
-  "objectstack": {
-    "marketplace": {
-      "manifestId": "app.objectstack.template.compliance",
-      "displayName": "Compliance",
-      "description": "Compliance posture & evidence management: SOC 2 / ISO 27001 / GDPR frameworks, controls, evidence with expiry tracking, and assessments.",
-      "category": "starter",
-      "iconUrl": "https://cdn.objectos.app/icons/compliance.svg",
-      "homepageUrl": "https://github.com/objectstack-ai/templates/tree/main/packages/compliance",
-      "readmePath": "README.md"
-    }
-  }
+  "packageManager": "pnpm@10.33.0"
 }

packages/content/package.json

@@ -40,16 +40,5 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@10.33.0",
-  "objectstack": {
-    "marketplace": {
-      "manifestId": "app.objectstack.template.content",
-      "displayName": "Content",
-      "description": "Content marketing engine: pipeline → publish → measure. Editorial calendar, competitive signal capture, channel ROI rollups, and an 8-state piece workflow with approval gates.",
-      "category": "starter",
-      "iconUrl": "https://cdn.objectos.app/icons/content.svg",
-      "homepageUrl": "https://github.com/objectstack-ai/templates/tree/main/packages/content",
-      "readmePath": "README.md"
-    }
-  }
+  "packageManager": "pnpm@10.33.0"
 }

packages/contracts/package.json

@@ -40,16 +40,5 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@10.33.0",
-  "objectstack": {
-    "marketplace": {
-      "manifestId": "app.objectstack.template.contracts",
-      "displayName": "Contracts",
-      "description": "Post-signature contract lifecycle: AI-extracted metadata, multi-step approvals, obligation tracking, and renewal alerts. Bring your own Word + DocuSign.",
-      "category": "starter",
-      "iconUrl": "https://cdn.objectos.app/icons/contracts.svg",
-      "homepageUrl": "https://github.com/objectstack-ai/templates/tree/main/packages/contracts",
-      "readmePath": "README.md"
-    }
-  }
+  "packageManager": "pnpm@10.33.0"
 }

packages/expense/package.json

@@ -40,16 +40,5 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@10.33.0",
-  "objectstack": {
-    "marketplace": {
-      "manifestId": "app.objectstack.template.expense",
-      "displayName": "Expense",
-      "description": "Employee expense & reimbursement: multi-line expense reports, category policy, amount-tiered approvals, and reimbursement tracking.",
-      "category": "starter",
-      "iconUrl": "https://cdn.objectos.app/icons/expense.svg",
-      "homepageUrl": "https://github.com/objectstack-ai/templates/tree/main/packages/expense",
-      "readmePath": "README.md"
-    }
-  }
+  "packageManager": "pnpm@10.33.0"
 }

packages/helpdesk/README.md

@@ -1,6 +1,6 @@
 # @objectlab/helpdesk — AI-First Customer Support
 
-> Customer support template where **AI is a first-class citizen**, not a paid add-on. Native fields for triage, sentiment, suggested replies, and KB recall — driven by your choice of LLM provider.
+> Customer support template that treats **AI as a first-class schema citizen**: triage, sentiment, suggested replies, and KB recall are native ticket fields. A deterministic baseline ships so it runs today — wire your LLM provider to make the AI fields smart.
 
 [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/objectstack-ai/templates/tree/main/packages/helpdesk)
 
@@ -19,6 +19,8 @@ Click the StackBlitz badge above to launch this template in a WebContainer. It u
 | Data is locked in vendor cloud | Open SQL, exportable, no lock-in |
 | English-first, others bolt-on | en + zh-CN shipped; ja/ko trivial to add |
 
+> **On the AI:** the rows above describe the *schema / architecture*. The `ai_*` behaviors ship as a deterministic baseline + flow scaffold — wire your LLM to populate them (see [Plugging in your LLM](#plugging-in-your-llm)).
+
 ## What's in the box
 
 **6 objects**

packages/helpdesk/objectstack.config.ts

@@ -26,9 +26,9 @@ export default defineStack({
     namespace: 'helpdesk',
     version: '0.1.0',
     type: 'app',
-    name: 'AI Helpdesk',
+    name: 'Helpdesk',
     description:
-      'AI-first customer support: native AI triage, suggested replies, KB recall, sentiment-driven escalation, customer portal via permissions.',
+      'Customer support starter on ObjectStack: tickets, SLA, sentiment-based escalation, KB, and a customer portal; AI triage fields ship with a deterministic baseline you extend with your own LLM.',
   },
 
   requires: ['automation', 'triggers', 'analytics', 'auth', 'ui', 'sharing'],

packages/helpdesk/objectstack.manifest.json

@@ -3,8 +3,8 @@
   "name": "helpdesk",
   "specVersion": "^6.1.0",
   "manifestId": "app.objectstack.template.helpdesk",
-  "displayName": "AI Helpdesk",
-  "description": "AI-first customer support: native AI triage, suggested replies, KB recall, sentiment-driven escalation, customer portal via permissions.",
+  "displayName": "Helpdesk",
+  "description": "Customer support starter: tickets, SLA tracking, sentiment-based escalation, knowledge base, and a permission-based customer portal. AI triage, suggested replies, and KB recall are first-class ticket fields with a deterministic baseline — wire your own LLM to make them smart.",
   "category": "operations",
   "isStarter": true,
   "publisher": "objectstack",
@@ -21,9 +21,9 @@
   "readmePath": "README.md",
   "translations": {
     "zh-CN": {
-      "displayName": "AI 客服台",
-      "description": "AI 优先的客户支持：原生 AI 工单分诊、建议回复、知识库召回、基于情绪的升级，权限驱动的客户门户。",
-      "tagline": "AI 是一等公民的客服台。"
+      "displayName": "客服台",
+      "description": "客户支持起步模板：工单、SLA、情绪驱动升级、知识库与权限制客户门户。AI 分诊、建议回复、知识库召回为一等工单字段，内置确定性基线——接上你的 LLM 即可智能化。",
+      "tagline": "工单 + SLA + 升级 + 知识库 + 门户；AI 分诊预留接口。"
     }
   }
 }

packages/helpdesk/package.json

@@ -40,16 +40,5 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@10.33.0",
-  "objectstack": {
-    "marketplace": {
-      "manifestId": "app.objectstack.template.helpdesk",
-      "displayName": "AI Helpdesk",
-      "description": "Customer support with AI as a first-class citizen: auto-triage, suggested replies, KB recall, sentiment-driven escalation. Customer portal included via permissions.",
-      "category": "starter",
-      "iconUrl": "https://cdn.objectos.app/icons/helpdesk.svg",
-      "homepageUrl": "https://github.com/objectstack-ai/templates/tree/main/packages/helpdesk",
-      "readmePath": "README.md"
-    }
-  }
+  "packageManager": "pnpm@10.33.0"
 }

packages/helpdesk/src/apps/helpdesk.app.ts

@@ -4,7 +4,7 @@ import { App } from '@objectstack/spec/ui';
 
 export const HelpdeskApp = App.create({
   name: 'helpdesk',
-  label: 'AI Helpdesk',
+  label: 'Helpdesk',
   description: 'AI-first customer support on ObjectStack.',
   icon: 'life-buoy',
   branding: { primaryColor: '#A855F7' },

packages/helpdesk/src/portals/customer.portal.ts

@@ -32,7 +32,7 @@ export const HelpdeskCustomerPortal = definePortal({
   kind: 'portal',
   id: 'helpdesk_customer',
   label: 'Help Center',
-  description: 'Customer-facing help center for the AI Helpdesk template.',
+  description: 'Customer-facing help center for the Helpdesk template.',
 
   // -------- Routing --------
   routePrefix: '/portal/helpdesk',

packages/helpdesk/src/translations/en.ts

@@ -214,7 +214,7 @@ export const en: TranslationData = {
   },
   apps: {
     helpdesk: {
-      label: 'AI Helpdesk',
+      label: 'Helpdesk',
       description: 'AI-first customer support on ObjectStack.',
       navigation: {
         nav_workbench: { label: 'My Workbench' },

packages/helpdesk/src/translations/zh-CN.ts

@@ -198,7 +198,7 @@ export const zhCN: TranslationData = {
   },
   apps: {
     helpdesk: {
-      label: 'AI 客服工单',
+      label: '客服台',
       description: '基于 ObjectStack 的 AI 优先客户支持系统。',
       navigation: {
         nav_workbench: { label: '我的工作台' },

packages/hr/objectstack.config.ts

@@ -21,7 +21,7 @@ export default defineStack({
     namespace: 'hr',
     version: '0.1.0',
     type: 'app',
-    name: 'HR',
+    name: 'Human Resources',
     description:
       'Starter template — people directory, time-off, and document expiry on ObjectStack.',
   },

packages/hr/package.json

@@ -41,16 +41,5 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@10.33.0",
-  "objectstack": {
-    "marketplace": {
-      "manifestId": "app.objectstack.template.hr",
-      "displayName": "HR",
-      "description": "People Ops starter — employee directory, org chart, time-off approvals, and document expiry alerts on ObjectStack.",
-      "category": "starter",
-      "iconUrl": "https://cdn.objectos.app/icons/hr.svg",
-      "homepageUrl": "https://github.com/objectstack-ai/templates/tree/main/packages/hr",
-      "readmePath": "README.md"
-    }
-  }
+  "packageManager": "pnpm@10.33.0"
 }

packages/procurement/package.json

@@ -40,16 +40,5 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@10.33.0",
-  "objectstack": {
-    "marketplace": {
-      "manifestId": "app.objectstack.template.procurement",
-      "displayName": "Procurement",
-      "description": "Source-to-pay procurement: vendor master, purchase requests with amount-tiered approvals, purchase orders, goods receipts, and 3-way-match rollup.",
-      "category": "starter",
-      "iconUrl": "https://cdn.objectos.app/icons/procurement.svg",
-      "homepageUrl": "https://github.com/objectstack-ai/templates/tree/main/packages/procurement",
-      "readmePath": "README.md"
-    }
-  }
+  "packageManager": "pnpm@10.33.0"
 }