Update README and documentation for deck framework directives

- 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) 就知道真实契约长什么样。

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
- *      (./deck-framework.ts) is pinned LAST so it overrides any softer
- *      slide-handling wording earlier in the stack — this is the
- *      load-bearing nav / counter / scroll JS / print stylesheet contract
- *      that PDF stitching depends on.
+ *   4. For decks (skillMode === 'deck' OR metadata.kind === 'deck'), the
+ *      deck framework directive (./deck-framework.ts) is pinned LAST so it
+ *      overrides any softer slide-handling wording earlier in the stack —
+ *      this is the load-bearing nav / counter / scroll JS / print
+ *      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}`);
   }