Merge branch 'main' into feat/optimize-naming

- Clarified DECK_FRAMEWORK_DIRECTIVE description in both English and Chinese README files to specify conditions for deck kind without a skill seed.
- Added detailed workflow instructions in deck-framework.ts to emphasize the importance of copying the framework before adding content.
- Enhanced discovery.ts to reinforce the framework-first approach for deck projects.
- Updated system.ts to ensure proper handling of deck projects with and without bound skills, preventing re-authorship of scaling and navigation logic.

README.md

@@ -211,7 +211,7 @@ DISCOVERY directives  (turn-1 form, turn-2 brand branch, TodoWrite, 5-dim critiq
   + active SKILL.md    (19 skills available)
   + project metadata   (kind, fidelity, speakerNotes, animations, inspiration ids)
   + skill side files   (auto-injected pre-flight: read assets/template.html + references/*.md)
-  + (deck mode only)   DECK_FRAMEWORK_DIRECTIVE   (nav / counter / scroll / print)
+  + (deck kind, no skill seed) DECK_FRAMEWORK_DIRECTIVE   (nav / counter / scroll / print)
 ```
 
 Every layer is composable. Every layer is a file you can edit. Read [`src/prompts/system.ts`](src/prompts/system.ts) and [`src/prompts/discovery.ts`](src/prompts/discovery.ts) to see the actual contract.

README.zh-CN.md

@@ -211,7 +211,7 @@ DISCOVERY 指令         （turn-1 表单、turn-2 品牌分支、TodoWrite、
   + 激活的 SKILL.md    （19 套备选）
   + 项目元数据          （kind、fidelity、speakerNotes、animations、灵感 system id）
   + Skill 副文件       （自动注入 pre-flight：先读 assets/template.html + references/*.md）
-  + （仅 deck 模式）    DECK_FRAMEWORK_DIRECTIVE   （nav / counter / scroll / print）
+  + （deck kind 且无 skill 种子时） DECK_FRAMEWORK_DIRECTIVE   （nav / counter / scroll / print）
 ```
 
 每一层都可组合。每一层都是一个你能改的文件。看 [`src/prompts/system.ts`](src/prompts/system.ts) 和 [`src/prompts/discovery.ts`](src/prompts/discovery.ts) 就知道真实契约长什么样。

daemon/skills.js

@@ -2,9 +2,9 @@
 // front-matter, returns listing. No watching in this MVP — re-scans on every
 // GET /api/skills, which is fine for dozens of skills.
 
-import { readdir, readFile, stat } from 'node:fs/promises';
+import { readdir, readFile, stat } from "node:fs/promises";
-import path from 'node:path';
+import path from "node:path";
-import { parseFrontmatter } from './frontmatter.js';
+import { parseFrontmatter } from "./frontmatter.js";
 
 export async function listSkills(skillsRoot) {
   const out = [];
@@ -17,26 +17,32 @@ export async function listSkills(skillsRoot) {
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     const dir = path.join(skillsRoot, entry.name);
-    const skillPath = path.join(dir, 'SKILL.md');
+    const skillPath = path.join(dir, "SKILL.md");
     try {
       const stats = await stat(skillPath);
       if (!stats.isFile()) continue;
-      const raw = await readFile(skillPath, 'utf8');
+      const raw = await readFile(skillPath, "utf8");
       const { data, body } = parseFrontmatter(raw);
       const hasAttachments = await dirHasAttachments(dir);
       const mode = data.od?.mode || inferMode(body, data.description);
       out.push({
         id: data.name || entry.name,
         name: data.name || entry.name,
-        description: data.description || '',
+        description: data.description || "",
         triggers: Array.isArray(data.triggers) ? data.triggers : [],
         mode,
-        platform: normalizePlatform(data.od?.platform, mode, body, data.description),
+        platform: normalizePlatform(
+          data.od?.platform,
+          mode,
+          body,
+          data.description
+        ),
         scenario: normalizeScenario(data.od?.scenario, body, data.description),
-        previewType: data.od?.preview?.type || 'html',
+        previewType: data.od?.preview?.type || "html",
         designSystemRequired: data.od?.design_system?.requires ?? true,
         defaultFor: normalizeDefaultFor(data.od?.default_for),
-        upstream: typeof data.od?.upstream === 'string' ? data.od.upstream : null,
+        upstream:
+          typeof data.od?.upstream === "string" ? data.od.upstream : null,
         featured: normalizeFeatured(data.od?.featured),
         // Optional metadata hints used by 'Use this prompt' fast-create so
         // the resulting project mirrors the shipped example.html. Each hint
@@ -63,15 +69,15 @@ export async function listSkills(skillsRoot) {
 // open those files via absolute paths.
 function withSkillRootPreamble(body, dir) {
   const preamble = [
-    '> **Skill root (absolute):** `' + dir + '`',
+    "> **Skill root (absolute):** `" + dir + "`",
-    '>',
+    ">",
-    '> This skill ships side files alongside `SKILL.md`. When the workflow',
+    "> This skill ships side files alongside `SKILL.md`. When the workflow",
-    '> below references relative paths such as `assets/template.html` or',
+    "> below references relative paths such as `assets/template.html` or",
-    '> `references/layouts.md`, resolve them against the skill root above and',
+    "> `references/layouts.md`, resolve them against the skill root above and",
-    '> open them via their full absolute path.',
+    "> open them via their full absolute path.",
-    '',
+    "",
-    '',
+    "",
-  ].join('\n');
+  ].join("\n");
   return preamble + body;
 }
 
@@ -79,7 +85,9 @@ async function dirHasAttachments(dir) {
   try {
     const entries = await readdir(dir, { withFileTypes: true });
     return entries.some(
-      (e) => e.name !== 'SKILL.md' && (e.isDirectory() || /\.(md|html|css|js|json|txt)$/i.test(e.name)),
+      (e) =>
+        e.name !== "SKILL.md" &&
+        (e.isDirectory() || /\.(md|html|css|js|json|txt)$/i.test(e.name))
     );
   } catch {
     return false;
@@ -96,7 +104,7 @@ function normalizeDefaultFor(value) {
 // 'high-fidelity' are meaningful — anything else collapses to null so the
 // caller falls back to the form default ('high-fidelity').
 function normalizeFidelity(value) {
-  if (value === 'wireframe' || value === 'high-fidelity') return value;
+  if (value === "wireframe" || value === "high-fidelity") return value;
   return null;
 }
 
@@ -104,11 +112,11 @@ function normalizeFidelity(value) {
 // to a real boolean. Returns null for anything we can't interpret so the
 // caller knows to fall back to the form default.
 function normalizeBoolHint(value) {
-  if (typeof value === 'boolean') return value;
+  if (typeof value === "boolean") return value;
-  if (typeof value === 'string') {
+  if (typeof value === "string") {
     const v = value.trim().toLowerCase();
-    if (v === 'true' || v === 'yes' || v === '1') return true;
+    if (v === "true" || v === "yes" || v === "1") return true;
-    if (v === 'false' || v === 'no' || v === '0') return false;
+    if (v === "false" || v === "no" || v === "0") return false;
   }
   return null;
 }
@@ -119,8 +127,8 @@ function normalizeBoolHint(value) {
 // natural alphabetical order.
 function normalizeFeatured(value) {
   if (value === true) return 1;
-  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
-  if (typeof value === 'string' && value.trim()) {
+  if (typeof value === "string" && value.trim()) {
     const n = Number(value);
     if (Number.isFinite(n)) return n;
   }
@@ -133,66 +141,70 @@ function normalizeFeatured(value) {
 // serves as a passable starter prompt.
 function derivePrompt(data) {
   const explicit = data.od?.example_prompt;
-  if (typeof explicit === 'string' && explicit.trim()) return explicit.trim();
+  if (typeof explicit === "string" && explicit.trim()) return explicit.trim();
-  const desc = typeof data.description === 'string' ? data.description.trim() : '';
+  const desc =
-  if (!desc) return '';
+    typeof data.description === "string" ? data.description.trim() : "";
-  const collapsed = desc.replace(/\s+/g, ' ').trim();
+  if (!desc) return "";
+  const collapsed = desc.replace(/\s+/g, " ").trim();
   const firstSentence = collapsed.match(/^.+?[.!?。！？](?:\s|$)/)?.[0]?.trim();
   return (firstSentence || collapsed).slice(0, 320);
 }
 
 function inferMode(body, description) {
-  const hay = `${description ?? ''}\n${body ?? ''}`.toLowerCase();
+  const hay = `${description ?? ""}\n${body ?? ""}`.toLowerCase();
-  if (/\bppt|deck|slide|presentation|幻灯|投影/.test(hay)) return 'deck';
+  if (/\bppt|deck|slide|presentation|幻灯|投影/.test(hay)) return "deck";
-  if (/\bdesign[- ]system|\bdesign\.md|\bdesign tokens/.test(hay)) return 'design-system';
+  if (/\bdesign[- ]system|\bdesign\.md|\bdesign tokens/.test(hay))
-  if (/\btemplate\b/.test(hay)) return 'template';
+    return "design-system";
-  return 'prototype';
+  if (/\btemplate\b/.test(hay)) return "template";
+  return "prototype";
 }
 
 // Validate platform tag — only desktop / mobile are meaningful for the
 // Examples gallery. Falls back to autodetecting "mobile" from descriptions
 // so legacy skills sort under the right pill without authoring changes.
 function normalizePlatform(value, mode, body, description) {
-  if (value === 'desktop' || value === 'mobile') return value;
+  if (value === "desktop" || value === "mobile") return value;
-  if (mode !== 'prototype') return null;
+  if (mode !== "prototype") return null;
-  const hay = `${description ?? ''}\n${body ?? ''}`.toLowerCase();
+  const hay = `${description ?? ""}\n${body ?? ""}`.toLowerCase();
-  if (/mobile|phone|ios|android|手机|移动端/.test(hay)) return 'mobile';
+  if (/mobile|phone|ios|android|手机|移动端/.test(hay)) return "mobile";
-  return 'desktop';
+  return "desktop";
 }
 
 // Normalise a scenario tag to a small fixed vocabulary so the filter pills
 // stay tidy. Unknown values pass through verbatim so authors can experiment;
 // missing values default to "general".
 const KNOWN_SCENARIOS = new Set([
-  'general',
+  "general",
-  'engineering',
+  "engineering",
-  'product',
+  "product",
-  'design',
+  "design",
-  'marketing',
+  "marketing",
-  'sales',
+  "sales",
-  'finance',
+  "finance",
-  'hr',
+  "hr",
-  'operations',
+  "operations",
-  'support',
+  "support",
-  'legal',
+  "legal",
-  'education',
+  "education",
-  'personal',
+  "personal",
 ]);
 function normalizeScenario(value, body, description) {
-  if (typeof value === 'string') {
+  if (typeof value === "string") {
     const v = value.trim().toLowerCase();
     if (v) return v;
   }
-  const hay = `${description ?? ''}\n${body ?? ''}`.toLowerCase();
+  const hay = `${description ?? ""}\n${body ?? ""}`.toLowerCase();
-  if (/finance|invoice|expense|budget|p&l|revenue/.test(hay)) return 'finance';
+  if (/finance|invoice|expense|budget|p&l|revenue/.test(hay)) return "finance";
-  if (/\bhr\b|onboarding|payroll|employee|人事/.test(hay)) return 'hr';
+  if (/\bhr\b|onboarding|payroll|employee|人事/.test(hay)) return "hr";
-  if (/marketing|campaign|brand|landing/.test(hay)) return 'marketing';
+  if (/marketing|campaign|brand|landing/.test(hay)) return "marketing";
-  if (/runbook|incident|deploy|engineering|sre|api/.test(hay)) return 'engineering';
+  if (/runbook|incident|deploy|engineering|sre|api/.test(hay))
-  if (/spec|prd|roadmap|product manager|product team/.test(hay)) return 'product';
+    return "engineering";
-  if (/design system|moodboard|mockup|ui kit/.test(hay)) return 'design';
+  if (/spec|prd|roadmap|product manager|product team/.test(hay))
-  if (/sales|quote|proposal|lead/.test(hay)) return 'sales';
+    return "product";
-  if (/operations|ops|logistics|inventory/.test(hay)) return 'operations';
+  if (/design system|moodboard|mockup|ui kit/.test(hay)) return "design";
-  return 'general';
+  if (/sales|quote|proposal|lead/.test(hay)) return "sales";
+  if (/operations|ops|logistics|inventory/.test(hay)) return "operations";
+  return "general";
 }
 // Surface the vocabulary so callers (frontend filter UI) could mirror it
 // later if they want to. Not exported today, kept here for documentation.

src/prompts/deck-framework.ts

@@ -313,6 +313,22 @@ Decks regress when each turn re-authors the scale-to-fit logic, the keyboard han
 
 **You do not write any of that. You do not modify any of that.** Your job is to fill content slots only.
 
+## Workflow — copy framework first, then fill content
+
+When the user asks for slides, your TodoWrite plan **must** start with "copy the deck framework verbatim" before any content step. The intended order is:
+
+\`\`\`
+1.  Bind the active direction's palette + fonts to :root in the framework
+2.  Copy the canonical skeleton below as index.html (nothing else first)
+3.  Plan the slide arc and theme rhythm (state aloud before writing)
+4.  Add per-deck classes inside the second <style> block
+5.  Replace each <section class="slide"> SLOT with real content
+6.  Self-check (no rewriting framework chrome / @media print / nav script)
+7.  Emit single <artifact>
+\`\`\`
+
+If you find yourself writing \`<style>\` rules for \`.deck-shell\`, \`.deck-stage\`, \`.slide\`, \`.canvas\`, \`fit()\`, \`@media print\`, or a keyboard handler — STOP. The framework already has them. Re-read this directive, then keep going from "fill SLOT content".
+
 ## The contract
 
 When you start a new deck, your output is a single HTML file built from the canonical skeleton below. **Copy the skeleton verbatim**, including its first \`<style>\` block, the \`.deck-shell\` / \`.deck-stage\` / \`.deck-counter\` / \`.deck-hint\` chrome, and the entire trailing \`<script>\`.

src/prompts/discovery.ts

@@ -142,6 +142,8 @@ The standard plan template (adapt the middle steps to the brief):
 - 9.  Emit single <artifact>
 \`\`\`
 
+**Decks especially — framework first, content second.** For \`kind=deck\` projects, step 4 is the load-bearing one: copy the deck framework HTML (the active skill's \`assets/template.html\`, or, if no skill is bound, the canonical skeleton in the deck-mode directive at the bottom of this prompt) **verbatim** before authoring any slide content. Do NOT write your own scale-to-fit logic, keyboard handler, slide visibility toggle, counter, or print stylesheet — every freeform attempt at this re-introduces the same iframe positioning / scaling bugs we have already fixed in the framework. Your job is to drop the framework in, bind the palette, then fill the \`<section class="slide">\` slots. That's it.
+
 After TodoWrite, immediately update — **mark step 1 \`in_progress\` before starting it, \`completed\` the moment it's done, mark step 2 \`in_progress\`**, etc. Do not batch updates at the end of the turn; the live progress is the point. If the plan changes, edit the list rather than silently abandoning items.
 
 Step 7 (checklist) and step 8 (critique) are non-negotiable.

src/prompts/system.ts

@@ -14,11 +14,17 @@
  *      (`assets/template.html`) and references (`references/layouts.md`,
  *      `references/checklist.md`), we inject a hard pre-flight rule above
  *      the skill body so the agent reads them BEFORE writing any code.
- *   4. For decks (skillMode === 'deck'), the deck framework directive
+ *   4. For decks (skillMode === 'deck' OR metadata.kind === 'deck'), the
- *      (./deck-framework.ts) is pinned LAST so it overrides any softer
+ *      deck framework directive (./deck-framework.ts) is pinned LAST so it
- *      slide-handling wording earlier in the stack — this is the
+ *      overrides any softer slide-handling wording earlier in the stack —
- *      load-bearing nav / counter / scroll JS / print stylesheet contract
+ *      this is the load-bearing nav / counter / scroll JS / print
- *      that PDF stitching depends on.
+ *      stylesheet contract that PDF stitching depends on. We also fire on
+ *      the metadata path so deck-kind projects without a bound skill
+ *      (skill_id null) still get a framework, instead of having the agent
+ *      re-author scaling / nav / print logic from scratch each turn. When
+ *      the active skill ships its own seed (skill body references
+ *      `assets/template.html`), we defer to that seed and skip the generic
+ *      skeleton — the skill's framework wins to avoid double-injection.
  *
  * The composed string is what the daemon sees as `systemPrompt` and what
  * the Anthropic path sends as `system`.
@@ -85,7 +91,23 @@ export function composeSystemPrompt({
   // Decks have a load-bearing framework (nav, counter, scroll JS, print
   // stylesheet for PDF stitching). Pin it last so it overrides any softer
   // wording earlier in the stack ("write a script that handles arrows…").
-  if (skillMode === 'deck') {
+  //
+  // We fire on either (a) the active skill is a deck skill OR (b) the
+  // project metadata declares kind=deck. Case (b) catches projects created
+  // without a skill (skill_id null) — without this, a deck-kind project
+  // with no bound skill gets neither a skill seed nor the framework
+  // skeleton, and the agent writes scaling / nav / print logic from scratch
+  // with the same buggy `place-items: center` + transform pattern we keep
+  // having to fix at runtime. Skill seeds (when present) win — they
+  // already define their own opinionated framework (simple-deck's
+  // scroll-snap, guizang-ppt's magazine layout) and re-pinning the generic
+  // skeleton would conflict. The skill-seed path takes over via
+  // `derivePreflight` above, so we only fire the generic skeleton when no
+  // skill seed is on offer.
+  const isDeckProject = skillMode === 'deck' || metadata?.kind === 'deck';
+  const hasSkillSeed =
+    !!skillBody && /assets\/template\.html/.test(skillBody);
+  if (isDeckProject && !hasSkillSeed) {
     parts.push(`\n\n---\n\n${DECK_FRAMEWORK_DIRECTIVE}`);
   }
 

src/runtime/srcdoc.ts

@@ -16,10 +16,10 @@
  */
 export function buildSrcdoc(
   html: string,
-  options: { deck?: boolean } = {},
+  options: { deck?: boolean } = {}
 ): string {
   const head = html.trimStart().slice(0, 64).toLowerCase();
-  const isFullDoc = head.startsWith('<!doctype') || head.startsWith('<html');
+  const isFullDoc = head.startsWith("<!doctype") || head.startsWith("<html");
   const wrapped = isFullDoc
     ? html
     : `<!doctype html>
@@ -68,8 +68,10 @@ function injectSandboxShim(doc: string): string {
   tryShim('localStorage');
   tryShim('sessionStorage');
 })();</script>`;
-  if (/<head[^>]*>/i.test(doc)) return doc.replace(/<head[^>]*>/i, (m) => `${m}${shim}`);
+  if (/<head[^>]*>/i.test(doc))
-  if (/<body[^>]*>/i.test(doc)) return doc.replace(/<body[^>]*>/i, (m) => `${m}${shim}`);
+    return doc.replace(/<head[^>]*>/i, (m) => `${m}${shim}`);
+  if (/<body[^>]*>/i.test(doc))
+    return doc.replace(/<body[^>]*>/i, (m) => `${m}${shim}`);
   return shim + doc;
 }
 
@@ -101,7 +103,7 @@ function injectDeckBridge(doc: string): string {
 .stage, .deck-stage, .deck-shell { place-content: center !important; }
 </style>`;
   const docWithStyle = /<\/head>/i.test(doc)
-    ? doc.replace(/<\/head>/i, styleFix + '</head>')
+    ? doc.replace(/<\/head>/i, styleFix + "</head>")
     : /<head[^>]*>/i.test(doc)
     ? doc.replace(/<head[^>]*>/i, (m) => m + styleFix)
     : styleFix + doc;
@@ -265,6 +267,7 @@ function injectDeckBridge(doc: string): string {
   }
   observeSlides();
 })();</script>`;
-  if (/<\/body>/i.test(doc)) return doc.replace(/<\/body>/i, `${script}</body>`);
+  if (/<\/body>/i.test(doc))
+    return doc.replace(/<\/body>/i, `${script}</body>`);
   return doc + script;
 }