Release PPT workflow 0.7.2 with text and container constraints

README.md

@@ -1,6 +1,6 @@
 # Templated-PPT-Master
 
-可独立安装的 `ppt-template-workflow` Skill，当前版本 **0.7.1**。仓库根目录就是唯一安装单元：[SKILL.md](SKILL.md)。它提供模板选择、逐页设计、素材上色、原生 PPTX、图表与表格、页面协作和可重建工程；无需另装其他 Skill。template、theme、组织素材和字体独立提供。
+可独立安装的 `ppt-template-workflow` Skill，当前源码版本 **0.7.2**。仓库根目录就是唯一安装单元：[SKILL.md](SKILL.md)。它提供模板选择、逐页设计、素材上色、原生 PPTX、图表与表格、页面协作和可重建工程；无需另装其他 Skill。template、theme、组织素材和字体独立提供。
 
 在支持本地文件和命令执行的 Agent 中输入：
 
@@ -14,4 +14,6 @@ Agent 应读取本页和 [INSTALL.md](INSTALL.md)，通过 Git 克隆这个地
 
 首次使用见 [USAGE.md](USAGE.md)。[生产规则](references/production-rules.md)区分硬约束和推荐；[组件](references/components.md)、[图表](references/charts.md)、[图标](references/icon-production.md)、[页面库](references/page-library.md)和[页面分工](references/page-collaboration.md)按需读取。每次只激活一个外部 template 和一个 theme。
 
+0.7.2新增[文字与容器硬约束](references/text-and-containers.md)：段落优先使用一个原生文本框，必要拆分保持逻辑统一；实质说明不放小号灰字；同容器不同文字角色不能只靠字体区分；同类容器共用内部排版实现，调用者不得逐例摆放内部文字和图标。
+
 包内 `runtime/ppt-master/` 保留 280 个未修改的 MIT 上游文件，包括用于署名的嵌套 SKILL.md；它不是第二个可安装 Skill。[来源和校验](runtime/provenance.json)、[运行库与边界](references/runtime-and-provenance.md)、[版本变化](UPDATES.md)一并保留。

SKILL.md

@@ -2,7 +2,7 @@
 name: ppt-template-workflow
 description: Create and revise template-based editable PPTX decks, design page mockups and materials, reconstruct visual pages into native objects, and maintain portable source projects. Select one external template and theme at a time; includes its own native compiler and workflows without requiring another installed Skill.
 metadata:
-  version: "0.7.1"
+  version: "0.7.2"
 ---
 
 # PPT Template Workflow
@@ -13,6 +13,8 @@ Use **template → theme → layout** as versioned inputs. A catalog can contain
 
 Read [production rules](references/production-rules.md) for the whole workflow. Preserve source meaning, provenance, real data, implementation claims and rebuildable inputs as requirements; use its planning and design methods as recommendations. Reuse settled choices and review at the authorized granularity. Record justified design exceptions without adding approval gates.
 
+For every authored or reconstructed page, apply the required [text and container rules](references/text-and-containers.md): prefer one native text frame per paragraph; any necessary fragments must remain one logical text block with unified content and layout. Keep substantive explanations out of small muted notes, distinguish different text roles by size/weight/color, and use one shared internal layout implementation per container type/variant. Authors supply content and whole-container bounds, never instance-specific child positions.
+
 ## Select and review
 
 Read the supplied catalog or manifest with `scripts/template_ref.py`. For a foundation project, start with its README consumer links. If the task needs a template and no source is specified, ask once for the source instead of guessing a global library.

UPDATES.md

@@ -1,5 +1,11 @@
 # 版本变化
 
+## 0.7.2
+
+增加C16—C19文字与容器硬约束：段落优先单个原生文本框，必要拆分保持完整内容、整体边界和统一排版的逻辑文本块；小号灰字不得承载实质解释、关键条件／时机、结论或影响解释的限定；不同文字角色通过字号、字重和／或颜色区分；同类容器共用内部排版实现，禁止逐例手动摆放文字和图标。补齐SVG到PPTX的段落结构检查、组件使用、重建和按页协作的执行说明；不将导出成功视为语义或应用验收。
+
+修复主题整理步骤按字体族默认字重覆盖已解析行内字重的问题，保留正文显式加粗和标题显式常规字重；按编译器语义补全实际run的常规字重，字体族默认仅补充缺失的默认文字样式，不再抹去作者声明的层级。上游编译器快照不变。
+
 ## 0.7.1
 
 新增仓库根 README、安装与使用说明，以及标准库本地安装器。支持独立 Git 服务、显式目标、保留备份的升级、精确运行库检查和 Codex 嵌套署名入口排除。template 与 theme 继续独立提供；不预设组织或模板。

USAGE.md

@@ -37,6 +37,8 @@ PPT_SKILL=/path/to/installed/ppt-template-workflow
 
 Agent 读取导出的调色板、字体、网格、素材 paint 契约、结构和版式容量，按模板槽位制作当前页 SVG。页面库存在时先检查其设计思路、实现方法和预览，再适配；参考页不改变模板几何和审阅顺序。`resolve` 只绑定完整的正式模板，提案可以 `inspect`／`export-style`，不能绕过发行状态制作。
 
+制作与重建均遵循[文字与容器硬约束](references/text-and-containers.md)。段落优先一个原生文本框；确需拆分时共用完整文本、整体边界、阅读顺序和排版实现，不逐行维护。关键解释、流程条件／时机、结论与影响解释的限定不得藏在小号灰字。容器中的不同文字角色需用字号、字重和／或颜色区分；同类容器由共享实现计算内部位置，作者只填内容、选择已声明变体并放置整体容器。
+
 ```sh
 "$PPT_PYTHON" "$PPT_SKILL/scripts/native_export.py" \
   --manifest /path/to/template/manifest.json --theme THEME \

references/charts.md

@@ -26,6 +26,8 @@ JSON顶层字段：`schema_version: 1`，`data_kind`（`synthetic-demo`／`obser
 
 `source`只作为显示文字与元数据保留，工具不会读取链接、补充出处或证明其真实性。所有原始数据同时放入marker的`component_data`，供工程审计；原生图表cache及内嵌XLSX保存未缩放的实际数值。
 
+遵循[文字与容器约束](text-and-containers.md)：小号灰色／弱化说明只承载补充背景、来源或非关键口径。图表的实质性解释、关键条件和时机、结论，以及影响解释范围的限定或免责说明，必须进入可读的主体层级，不得塞进`source`、小字或仅存讲稿。关键单位和口径也不能因字段名被降级。图表标题、说明和正文承担不同作用时，用字号、字重和／或调色板颜色作出明确区分，不能只换字体。
+
 ## 样式来源
 
 `style`和`theme`分别使用`template_ref.py export-style`的`style`、`theme_data`。字体从`typography.families.body`取得，字号默认取`caption`角色，缺少时取`label`；按`canvas.pt_to_px`换算。组件没有组织、字体名或十六进制配色的固定默认值。
@@ -80,6 +82,8 @@ slot.append(component)
 
 `render_chart(data, style, theme, bounds, component_id) -> xml.etree.ElementTree.Element`返回SVG `g`。使用当前页真实槽位的bounds；确认当前template确实有该槽位，不能把示例中的ID、坐标当通用约定。component_id在整页必须唯一。生成后不要单独改fallback图形或marker数据；修改JSON并重新生成，保持fallback指纹和元数据一致。
 
+同一种图表容器／变体共用内部排版实现，调用者只提供内容和整体bounds，不逐例移动标题、图例、图标或说明。需要新的说明区时定义共享组合规则，并重新生成整组；一个连续段落优先保持为一个原生文本框，必要拆分也必须共用一个逻辑文本块和换行规则。
+
 图例、标题、单位及来源位于marker外，编译为独立可编辑对象；marker内转换为真正的Chart和内嵌XLSX。此安排保持页面文字位置受模板控制。若在PowerPoint内改图表数据，外部图例或构成数量文字不会自动更新，需要一起修改，或从工程JSON重建。将图表JSON和生成工具声明为工程输入并锁定，可在迁移后重建；不能只交付生成的SVG与PPTX。
 
 ## 验证与限制

references/components.md

@@ -14,6 +14,8 @@ Each JSON uses `schema_version: 1` and `kind`. Examples are marked `data_kind: s
 
 The table uses `style.components.table`, including theme-indexed header colors and padding. Text uses `typography.roles.label`, `caption` and `number`, their declared font families and `canvas.pt_to_px`. Other component colors use `dk1`, `dk2`, `accent1`, `line` and `lt1` from the palette. Internal spacing uses fixed 8px modules; derived equal columns/centers do not introduce new page alignment guides. Width checks are conservative estimates, not a font renderer. The tool rejects excess capacity instead of shrinking text. Rephrase, enlarge a slot, change layout or split content; inspect actual application output.
 
+Apply the required [text and container rules](text-and-containers.md). Callers provide data, declared style/variant and whole-component bounds; do not move generated child text/icons or add per-instance internal offsets. Custom containers need a shared renderer too. Distinct functions such as heading/body must differ perceptibly in size, weight and/or palette color, not just family. The `detail`/`caption` name does not authorize essential conditions, conclusions or limitations to become small muted notes. Choose a suitable main-text component or extend the shared renderer when the existing field/role cannot carry the content appropriately.
+
 ## Grouped table
 
 The default table remains unchanged. Select `kind: table, variant: grouped` for a denser comparison with two header levels. Each column is `{id, label, unit?, format?}` with a unique stable ID. `format` is `text` (default), `integer` (integral numbers only, with thousands separators), or `one-decimal`. Formatting changes display text, never original `rows`. `numeric_columns` contains zero-based indices and right-aligns those headers and values. Numeric columns require actual finite numbers rather than formatted strings.
@@ -40,4 +42,4 @@ The CLI protects existing files and symlinked output paths. The output canvas fo
 
 For Python composition, add the Skill's `scripts` directory to `sys.path`, import `render_component` from `basic_component`, and call `render_component(data, style, theme_data, (x,y,width,height), component_id)`. Take `style` and `theme_data` from `template_ref.py export-style`. Insert the returned `g` into the current template page's slot while retaining its existing Master/Layout/placeholder attributes and full roster. A slot label or example content must be removed as part of filling that slot, without removing inherited UI.
 
-After composition, validate native marker payloads using [native objects](native-objects.md). Compile with `native_export.py`, check `a:tbl` for the table and text/shapes/connectors for the other components, then inspect current renders. Keep separate evidence for native structure, application appearance, editing and projection. General architectures, branched flows and custom comparisons can be composed from the same native primitives; this limited helper is not a requirement to fit every diagram into a linear chain.
+After composition, validate native marker payloads using [native objects](native-objects.md). Compile with `native_export.py`, check `a:tbl` for the table and text/shapes/connectors for the other components, then inspect current renders. Keep separate evidence for native structure, application appearance, editing and projection. General architectures, branched flows and custom comparisons can use the same native primitives through shared container/node recipes; this limited helper is not a requirement to fit every diagram into a linear chain.

references/native-authoring.md

@@ -6,6 +6,8 @@ Start the current page from its selected layout source. Retain inheritance metad
 
 Use the template's discrete typography, grid, fixed content region and spacing. Resolve overflow by choosing a suitable layout, shortening content or dividing the page according to the user's workflow. Do not infer ad hoc font sizes and alignment guides from mockup pixels. Keep text as text, simple panels and connectors as geometry, and exact image exceptions as independent assets. Tables, charts and formulas must retain their required native object type; a collection of lines/text or a formula picture does not automatically qualify.
 
+Apply [text and container rules](text-and-containers.md) before authoring: prefer one native frame per paragraph, use a unified logical block for any necessary fragments, distinguish text functions by size/weight/color and instantiate repeated containers through a shared renderer. Inspect actual native paragraph structure after export; positional SVG spans can otherwise be split by the compiler.
+
 ## Current-page export
 
 The installer provides Python 3.12+ and [runtime requirements](../runtime/requirements.txt). Metadata-only selection and project commands use Python 3.10+ without third-party packages.
@@ -25,7 +27,7 @@ The exporter consumes released v2 manifests and retains all native layout defini
 
 Page SVG viewBox and layout ID must match the selected template. Source assets are only relative local PNG/JPEG references or embedded PNG/JPEG data. Fragment references are supported; external images, active SVG elements, document entities and external CSS URLs are refused. Default author resource boundary is each SVG's directory; template-internal sources use the template package root. For portable project pages that intentionally reference `../../assets/...`, pass `--source-root /path/to/project`. Boundaries and symlink checks apply before compilation. Other visual formats should be prepared as native geometry or explicit supported bitmap assets.
 
-The exporter embeds images in temporary source copies, preserving canonical source bytes. It runs the bundled attribution guard, serial compiler and declared-font preservation context, then applies the external palette/theme fonts and verifies slide/Layout/Master links, placeholders and supplied notes. Existing output is protected, including a concurrent writer appearing during compilation. A failed build does not replace old output.
+The exporter embeds images in temporary source copies, preserving canonical source bytes. It runs the bundled attribution guard, serial compiler and declared-font preservation context, then applies the external palette/theme fonts without overwriting resolved run weights, and verifies slide/Layout/Master links, placeholders and supplied notes. Authors/renderers must apply their selected role's actual size, weight and color to the source; family identity alone does not select a text function. Existing output is protected, including a concurrent writer appearing during compilation. A failed build does not replace old output.
 
 ## Template authors and review prototypes
 

references/object-reconstruction.md

@@ -14,6 +14,8 @@ Keep exact supplied logos, figures and screenshots as independent source assets.
 
 Start from the selected template layout source, retaining its Master/Layout/placeholder metadata. Recreate normal text as native text with the external style's font family, discrete size, line spacing and alignment. Build simple panels, rules, arrows and diagram nodes as separate structural objects. Fit to the declared grid, not pixel-by-pixel ad hoc anchors.
 
+Apply [text and container rules](text-and-containers.md) even when the reference image was built differently. Reconstruct a paragraph as one logical text block, preferably one native frame; do not turn each visible source line into an independently positioned box. Repeated container internals use one shared recipe. Essential explanations and limitations stay in the main information hierarchy, and different text functions need size/weight/color distinctions.
+
 Use actual data for native charts; if source values are unavailable, preserve the chart as an evidence image and say why. A native table uses native cells; native formulas require actual editable equation objects where the chosen compiler supports them. A formula bitmap, SVG picture or vector outline is still a picture/path exception. Preserve formula meaning and verify symbols against the source before conversion.
 
 Preserve crop, aspect ratio and source meaning for image objects. Independently editable text over an unchanged full-page screenshot is not a reconstructed page. Keep repeated UI in inherited layers, rather than covering it with copied slide objects.

references/page-collaboration.md

@@ -8,6 +8,8 @@ Agree audience, deck argument, page order and review cadence. Define stable IDs
 
 Freeze one template/version/theme, manifest and style input hashes, roster, fonts, glossary, shared data/assets. Use the project tools for the template snapshot and builder. Give each worker the same baseline, a visual reference when available, page brief and write allowlist. Read library examples from the selected template. Route shared changes to the coordinator before implementation.
 
+Freeze shared container renderers/recipes, named text roles and supported variants as part of that baseline. Workers instantiate them with content and whole-container bounds; they cannot hand-position child text/icons or create private offsets. Include the [text/container constraints](text-and-containers.md) in page review. Any necessary paragraph fragments retain one logical text source/frame and a documented layout implementation; route shared recipe changes to the coordinator.
+
 Adapt [plan.example.json](../assets/collaboration/plan.example.json) into `collaboration/plan.json` and [page-packet.example.json](../assets/collaboration/page-packet.example.json) into `pages/<id>/packet.json`. These are handoff examples, not files interpreted automatically by the compiler. Replace every placeholder with real inputs and project-relative paths. Include the plan in `build.inputs` and packets in each page's `data` list when they must travel in the source lock/package. Do not create a second event store.
 
 ## Write ownership

references/powerpoint-checks.md

@@ -6,6 +6,8 @@ Open the current generated file, verify the visible filename and page thumbnails
 
 For rendered evidence, export this file to PDF through PowerPoint's own export dialog using the intended quality setting and a task-owned destination. Check the export exists and belongs to the current file, render its pages and inspect the images. Compare page geometry, text wrapping, typography, images, transparent edges, alignment and separators. Confirm actual PDF font identities when font rendering is disputed; a declared PowerPoint face alone does not prove which font the application rendered.
 
+Use the four-part [text/container review](text-and-containers.md#review-before-delivery): paragraph frame or justified logical-block fallback, no substantive statements in small muted notes, visible size/weight/color hierarchy within containers, and one shared internal layout implementation per type/variant. Review content/source and native objects as well as the render. A screenshot cannot prove a shared renderer or unified text source; grouping cannot prove native paragraph flow. Test fragment reflow in the application only when that editing behavior is part of the requested evidence.
+
 Opening and exporting are distinct from actual editing. When editing evidence is requested, use a disposable task-owned copy: select a representative text/shape/placeholder, change it through the UI, save or export, and verify the resulting independent object/content change. Check an appropriate inherited object separately if template behavior is in scope. Do not alter the authoritative source project or a user's finished original merely to demonstrate editing.
 
 Report the evidence actually obtained: source/reference validation, native structure and object types, current-page rendering, PowerPoint opening, actual object editing, or projection readability. A successful export cannot establish every later level. If the host application or UI capability is unavailable, deliver the validated source and PPTX with that specific unresolved application check.

references/production-rules.md

@@ -1,6 +1,6 @@
 # Production rules
 
-These rules apply across templates and authoring routes. **Required** rules protect content, provenance, implementation claims and rebuildable inputs. **Recommended** methods can change for a content reason; record the reason and relevant validation. Template parameters remain external. Follow explicit user instructions and settled authorization; these rules add no approval gate.
+These rules apply across templates and authoring routes. **Required** rules protect content, provenance, implementation claims, rebuildable inputs and the explicit text/container constraints below. **Recommended** methods can change for a content reason; record the reason and relevant validation. Template parameters remain external. Follow explicit user instructions and settled authorization; these rules add no approval gate. C16–C19 are requirements, including where C04–C06 offer broader design recommendations.
 
 ## Understand and compose
 
@@ -29,4 +29,11 @@ These rules apply across templates and authoring routes. **Required** rules prot
 - **C14 · Required:** before delivery, check missing pages, example residue, text overflow, occlusion, font substitution, chart data, asset resolution, alignment and object types as relevant to the change. Inspect actual current page renders. If a needed host check is unavailable, state it as unverified; old previews cannot replace new render evidence. Reuse unchanged evidence instead of repeating unrelated checks. See [PowerPoint checks](powerpoint-checks.md).
 - **C15 · Recommended:** identify affected pages after shared-input changes and rebuild/recheck them. Retain recoverable sources and accepted versions. Report versions, selected theme, object exceptions, evidence and remaining issues. Record content reasons and validation for departures from recommendations. Version new components/library entries independently; preserve frozen releases.
 
-Technical helpers enforce supported inputs, path safety, object consistency and capacity. They do not establish factual truth, design quality or application acceptance, and do not convert all recommendations into CLI errors.
+## Text and containers
+
+- **C16 · Required:** keep a paragraph as one logical text block, preferably one native text frame with wrapping, line breaks and styled runs. If a technical constraint requires several native frames, use one complete content source, one overall frame, one reading order and one layout implementation to generate and update all fragments together. Independent line strings/positions, or merely grouping manually positioned frames, do not satisfy this rule.
+- **C17 · Required:** small muted notes may supply nonessential background, sources or definitions. They must not carry substantive explanations of a chart/visualization, key process conditions or timing, conclusions, or qualifications/disclaimers that affect interpretation. Put those statements in the main information hierarchy; do not hide them in notes or metadata instead. Classify by meaning, not by a field named `detail`, `caption` or `source`.
+- **C18 · Required:** different text functions inside one container, such as subheading and body, must have a perceptible distinction in declared size, weight and/or palette color. A font-family change alone is insufficient. Bind functions to named text roles and apply the same distinction to all instances.
+- **C19 · Required:** every instance of a container type/variant uses the same shared layout implementation for padding, slots, text roles, wrapping, icon placement and alignment. Authors provide content and whole-container placement/bounds; the implementation computes internal geometry. Do not hand-position/nudge text or icons per instance. Resolve capacity through the shared layout's content-driven rules, a meaningful shared variant, rewriting or page/layout changes, never a one-off override. See [implementation and review](text-and-containers.md).
+
+Technical helpers enforce supported inputs, path safety, object consistency and capacity. They do not infer paragraph identity, explanation importance or semantic text roles, and do not automatically enforce all four text/container rules. Inspect source and current native/rendered output; export success alone is insufficient.

references/text-and-containers.md

@@ -0,0 +1,65 @@
+# Text blocks and container layout
+
+Apply C16–C19 in [production rules](production-rules.md) to page authoring, reconstruction, reusable components and collaboration. These are required constraints. A page-library example is a design reference, not an exemption from current rules. Keep fonts, sizes, colors, grid and spacing tied to the selected external template.
+
+## One paragraph, one logical text block
+
+Prefer one native text frame for each paragraph, including a continuous multi-line heading or label. Use wrapping, internal line breaks and styled runs inside that frame. Separate subheadings, separate list items, table cells, axis labels and independently meaningful node labels may be separate objects; a visual line break does not create a new semantic item. Do not split a paragraph across independent boxes to fit a container or imitate a mockup.
+
+If the selected route has a concrete technical reason to fragment the text, preserve all of these properties:
+
+- One stable logical block ID and one complete text/runs source. Store line breaks as part of that source or compute them from it, never as independent authored line strings.
+- One overall frame, text-role contract, alignment, line spacing and reading order. A shared layout implementation derives fragment positions and wrapping from the whole block; the page author cannot override individual fragment coordinates or styles.
+- One update operation: changing text, width or typography regenerates the whole block. Preserve the logical ID and fragment mapping in project inputs; group exported fragments as one movable unit where the route supports it.
+- Record the reason for fragmentation and actual object behavior. Source-level unified editing does not prove PowerPoint-native text flow; if edits in PowerPoint cannot reflow across fragments, disclose that limit. Grouping existing independently authored lines alone does not create a logical text block.
+
+The project content model may represent this as `{id, content, runs?, bounds, text_role, layout_rule}`. This is an authoring pattern, not new compiler metadata or an automatically interpreted schema. The shared renderer consumes the block. Fragments, if necessary, are derived output and are never independently maintained content.
+
+### SVG and the bundled native route
+
+Use a single SVG `text` for the paragraph. For authored visual rows, use direct-child `tspan` elements: repeat the parent's `x`, start at `dy="0"`, then use the same positive line step. Inline styling may use nested spans without baseline jumps. Take all coordinates and text styles from the selected layout/renderer, not hand-measured mockup offsets.
+
+The bundled compiler's default `preserve` text flow retains eligible stacked rows as one native frame, with internal breaks. Arbitrary per-line `y`, unequal `x`, nested baseline jumps or prior line-flattening may produce separate frames. Do not assume that one SVG `text` guarantees one PPTX frame. Inspect the actual native object structure. Do not select split text flow for ordinary paragraph authoring.
+
+For an object check, find the text-bearing `p:sp` objects and their `p:txBody` in the current slide XML. A normal paragraph should occupy one text-bearing shape; multiple `a:r` runs, `a:br` breaks or `a:p` elements inside the same `p:txBody` are internal text structure. Distinct semantic labels remain independent. If the fallback is used, check the whole-block source and fragment mapping as well as native counts. Group/native XML checks do not establish actual application editing or appearance.
+
+## Keep substantive explanations visible
+
+Determine importance before assigning `caption`, `detail` or muted styles. Small muted text is for supplementary background, provenance and nonessential definitions. Key conditions, timing, dependencies, conclusions and interpretation-changing limitations belong in readable body, node, callout or heading roles. A qualifying statement is not supplementary merely because it sounds cautious.
+
+| Statement | Treatment |
+|---|---|
+| Data source, collection date or a nonessential terminology expansion | Supplementary note is allowed; retain source metadata too |
+| “Only proceed after approval”, “retry after timeout” | Main process/node text; the viewer needs it to follow the process |
+| “Method B is faster” | Main comparison/conclusion hierarchy |
+| “Only measured on this dataset; does not establish general performance” | Visible limitation alongside the claim, not small muted text or speaker-notes-only |
+| A unit/definition that changes what a chart means | Keep it visibly associated with the chart at a suitable readable level |
+
+Read the page without the small muted notes. Its workflow, conclusion and scope must still be accurate and complete. This check also applies to any field named `source`: the field name cannot make a substantive claim into provenance.
+
+## Different roles inside a container
+
+Assign named roles before rendering: for example `card_heading`, `card_body`, `value`, `unit` and `source_note`, mapped to the external template's declared typography and palette. If subheading and body have different functions, distinguish them perceptibly with size, weight and/or color. Using serif for one and sans serif for the other at otherwise identical styling is insufficient. Do not introduce arbitrary sizes or literal colors to create the difference.
+
+The required distinction is between functions, not every string. Peers with the same function share a role. Verify the distinction in the actual theme and normal viewing scale; two almost identical colors are not a useful hierarchy. A substantive statement remains a body/callout role even when the component offers a small `detail` field.
+
+## A shared layout implementation for each container type
+
+Reuse a template/component renderer when it fits. For a new container, define one shared recipe/function and a content interface before placing its instances. The same type/variant must use the same padding, slot order, text roles, wrapping/height policy, icon size/alignment and spacing rules across pages and authors.
+
+The caller may pass semantic content, an icon asset/role, a declared variant and the whole container's bounds/placement. Internal `title_x`, `body_y`, `icon_offset`, per-line coordinates and similar instance-level overrides are prohibited. The renderer may compute geometry from bounds, content and common style; deterministic calculation is how the rule is implemented. A shared content-driven height/wrapping policy can produce different heights for different text lengths.
+
+If content does not fit, use the recipe's supported wrapping/height rules, rewrite, enlarge the whole slot or change the page/layout. Add a named shared variant only for a meaningful repeated need; do not disguise each instance's manual offsets as its own variant. Do not stretch generated text or icons with a group transform to make them fit. Regenerate from new bounds.
+
+Diagram nodes may be arranged to express the actual topology. Each repeated node's internal label/icon layout still comes from the shared node recipe. Custom diagrams do not justify hand-positioning the contents of every repeated card or node.
+
+Keep the recipe, parameters, content and assets in the portable project's declared inputs. For multiple authors, the coordinator freezes the shared implementation/style/variant set; page workers only instantiate it. Shared changes return to the coordinator and trigger checks on affected pages.
+
+## Review before delivery
+
+1. Compare the complete paragraph source with native text frames. Confirm one frame, or the justified whole-block fallback with derived fragments; inspect actual breaks, reading order and edit behavior at the requested evidence level.
+2. Review every small muted note for meaning. Move essential statements into the main hierarchy and verify no qualification disappeared in the move.
+3. Compare subheading/body and other distinct roles within each container at normal viewing scale. Font family alone cannot pass.
+4. Compare all instances of each type/variant and inspect their creation calls/source. Confirm one shared implementation, no child-coordinate overrides and no post-generation nudges. Equal-looking screenshots alone cannot prove this.
+
+The compiler cannot reliably infer these semantic properties from arbitrary SVG. Combine source review, native object checks and current rendered-page review; mark unavailable application checks explicitly.

scripts/finalize_theme.py

@@ -112,11 +112,17 @@ def finalize(path: Path, theme: dict, style: dict):
                 if ea is not None and len(fallbacks) == 1:
                     ea.set("typeface", next(iter(fallbacks)))
                     changed = True
-                # Weight is role metadata, not an inference that all titles bold.
+                # The compiler resolves source weight for every actual run;
+                # it emits b="1" for bold and omits b for regular. Materialize
+                # regular explicitly so a bold family/master cannot override it.
                 weights = {entry.get("weight_number") for entry in entries}
-                if len(weights) == 1 and None not in weights:
-                    run.set("b", "1" if next(iter(weights)) >= 600 else "0")
-                    changed = True
+                if run.get("b") is None:
+                    if run.tag == "{" + NS["a"] + "}rPr":
+                        run.set("b", "0")
+                        changed = True
+                    elif len(weights) == 1 and None not in weights:
+                        run.set("b", "1" if next(iter(weights)) >= 600 else "0")
+                        changed = True
             if changed:
                 tree.write(str(part), encoding="utf-8", xml_declaration=True)
         # A template's body size is its default at each nesting level. The author