Link report structure and production guidance (0.8.0)

references/charts.md

@@ -2,6 +2,14 @@
 
 `chart_component.py`把明确的数据生成一个独立 SVG `g`：其中包含原生 Chart metadata、同源的可见 SVG fallback，以及标题、单位、图例和来源文字。把它组合进所选 template 的页面；组件不复制母版、版式或页面 UI。它是技术组件接口，不替调用者决定报告应使用哪些图表。
 
+## 按判断任务选图
+
+先说明当前图表支撑哪个判断、所需数据和比较口径，再选择表达方式。内容方案可能建议箱线图、小提琴图等；这些是表达任务的建议，不表示本组件已支持。当前原生接口只支持下表七类。
+
+建议类型不受支持时，判断已选制作路线能否用原生对象或可验证的 SVG 图示保真实现；明确其实际对象类型和编辑范围。若不能实现，返回受影响页 ID、缺少的能力及具体内容选项。不能把分布静默改成均值、遗漏会改变判断的对照，或以图片宣称原生 Chart；也不静默更换后端、在线服务或安装其他 Skill。
+
+比较前优先统一对象、定义、单位、分母／基线、时间范围、样本和统计方法；保留有效换算、重算或区间对齐的依据。确实无法统一时，分开展示或限定可比较的情境，让结论与实际证据范围一致；仅标“口径不同”不能支撑排名。
+
 ## 支持范围
 
 | type／示例数据 | 用途与适配 | 当前技术边界 |
@@ -26,7 +34,7 @@ JSON顶层字段：`schema_version: 1`，`data_kind`（`synthetic-demo`／`obser
 
 `source`只作为显示文字与元数据保留，工具不会读取链接、补充出处或证明其真实性。所有原始数据同时放入marker的`component_data`，供工程审计；原生图表cache及内嵌XLSX保存未缩放的实际数值。
 
-遵循[文字与容器约束](text-and-containers.md)：小号灰色／弱化说明只承载补充背景、来源或非关键口径。图表的实质性解释、关键条件和时机、结论，以及影响解释范围的限定或免责说明，必须进入可读的主体层级，不得塞进`source`、小字或仅存讲稿。关键单位和口径也不能因字段名被降级。图表标题、说明和正文承担不同作用时，用字号、字重和／或调色板颜色作出明确区分，不能只换字体。
+遵循[文字与容器约束](text-and-containers.md)：数据源、一般范围、统计口径与引用定位可使用小字；直接影响核心判断的条件、实质解释与结论放在相关主体中。先修正有歧义或过强的正文，删除无助于理解的预防性辩解；具体、有用的警示按作用适度表达。字段名不能把必要信息降级为`source`，也不把正常来源文字改成警告。图表标题、说明和正文承担不同作用时，用字号、字重和／或调色板颜色作出明确区分，不能只换字体。
 
 ## 样式来源
 

references/content-handoff.md

@@ -0,0 +1,21 @@
+# Content handoff
+
+Report structure and production are separate responsibilities. The optional `report-structure` Skill maintains report logic, chapter relationships, page order, page content allocation and learning from user examples. This Skill owns template selection, visual composition, native objects, shared layout recipes, source projects and production evidence. Neither requires the other to be installed.
+
+## Receive a plan
+
+Accept a readable outline or page plan; no special file schema or compiler integration is required. Reuse stable page IDs and the user's agreed review sequence. For the current page, identify its purpose, what the audience should understand, content, evidence, necessary qualifications, progression within the page, relationship to adjacent pages, and allocation between visible content and speaker notes or appendix. A summary that introduces groups should match the actual groups and their organizing basis.
+
+For reasoning or mathematical derivation, retain the necessary premises, definitions, key steps and conditions that make the next step valid. Show the exact premises again where the audience needs them. A task that explicitly needs only results may omit the derivation; keep the result's meaning, conditions and sources. Identify which evidence supports each conclusion and how the page should make that association visible. These details can live in the existing brief rather than additional required fields. A time constraint concerns the overall report or relevant sections; a time budget for every page is not required.
+
+Select layout and composition from those information relationships under the chosen template. Check the actual page's reading order, information burden and conclusion-to-evidence associations. Keep essential explanations and qualifications in the related main information; small text may retain sources, ranges, references and supplementary definitions. Fix ambiguous or overstrong body text directly, and remove preventive disclaimers that add no useful understanding or action. Preserve facts, numbers, source meaning and content boundaries even when the plan came from another Skill. A supplied plan is input, not proof of truth or authorization to generate all pages.
+
+Without a plan, establish enough content context to complete the authorized page or deck request. Do not stop ordinary production merely because `report-structure` is unavailable. Use that Skill when the task calls for substantive report planning, restructuring or learning from examples; avoid duplicating its evolving rules here.
+
+## Return a content issue
+
+When the declared typography, spacing and supported layouts cannot accommodate the content, report the affected page IDs, missing relationship or capacity issue and a concrete content option. Options may include removing a true duplicate, using a supported layout, moving optional detail, or splitting a complete argument with a clear transition. Preserve the user's locked content and existing authorization; do not shrink fonts, alter fixed gaps or conceal key conditions to make a page fit.
+
+The content owner resolves chapter/order/selection changes. For one Agent handling both responsibilities, revise the content plan first and then produce the affected authorized pages; no extra peer or approval round is required for settled, reversible work. When order or page allocation changes, synchronize stable IDs and their destinations, page numbers, references and speaker notes. Keep necessary premises and key steps connected across a split.
+
+User feedback about report logic goes to the structure Skill's maintained example/rule source when authorized. Feedback about fonts, spacing, layout recipes or template geometry stays with the production/template maintainer. A content-plan review does not establish visual, native-editing or projection acceptance.

references/page-collaboration.md

@@ -4,7 +4,7 @@ Use one coordinator and one active writer per page. The coordinator owns narrati
 
 ## Freeze and assign
 
-Agree audience, deck argument, page order and review cadence. Define stable IDs and a brief per page: one message, evidence, data/units, capacity, transition and notes. Assign only pages authorized to proceed. Under `interactive-page`, review gates still apply; parallel workers do not authorize future pages or a batch.
+Consume the agreed audience, deck argument, page order and review cadence through [content handoff](content-handoff.md). Define stable IDs and a brief per page: its task, intended understanding, evidence, data/units, necessary premises and key steps, progression, conclusion-to-evidence associations, capacity, transition and content/notes/appendix allocation. Express these in the existing brief as relevant to the task; no new compiler schema or mandatory page-by-page time budget is needed. Report structure may come from the optional `report-structure` Skill or the user's own plan. Assign only pages authorized to proceed. Under `interactive-page`, review gates still apply; parallel workers do not authorize future pages or a batch.
 
 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.
 
@@ -27,7 +27,7 @@ For separate worktrees/devices, return an assigned source diff or directory arch
 
 Deliver source/content/notes, private assets and a packet recording ID, owner, revision, baseline hashes, layout, purpose, origin, source/asset hashes, preview renderer/hash, native objects, picture exceptions and unresolved issues. State source/static, native structure, SVG render, actual PowerPoint render, editing and projection individually; unavailable checks stay `not-run` with a reason. A PNG does not prove editability. Ready means ready for integration review.
 
-Source, content and notes must agree. Update table/chart metadata with data; preserve evidence labels, numbers and units. Match fonts, grid, fixed body area and palette; remove placeholders/example text. Keep resources within the assigned page directory.
+Source, content and notes must agree. Update table/chart metadata with data; preserve evidence labels, numbers, units, necessary premises and key steps. Check actual reading order and the visual association between conclusions and evidence. Match fonts, grid, fixed body area and palette; remove placeholders/example text. Keep resources within the assigned page directory.
 
 ## Integrate and revise
 
@@ -37,7 +37,9 @@ Source, content and notes must agree. Update table/chart metadata with data; pre
 4. Review the integrated deck for narrative, terminology, units, title rhythm, density, figure scale, repeated icons and navigation state. Render it: per-page static checks cannot establish visual consistency. Shared-style changes require affected pages to rebase and rerender.
 5. Keep the agreed user acceptance granularity. Record accepted/revision-needed with evidence, then proceed to the next authorized pages. Pack after locks/integration pass. Another device supplies declared dependencies/fonts and runs its own application checks.
 
-Reauthor or repair only affected pages; integrated export still compiles the completed SVG set together. Reuse unchanged page content and valid prior checks. For shared changes identify affected pages before repeating checks. Author completion, integrated render and user acceptance remain separate states.
+Reauthor or repair only affected pages; integrated export still compiles the completed SVG set together. If content allocation or order changes, synchronize stable IDs and destinations, page numbers, references and notes with the plan, including links across split arguments. Reuse unchanged page content and valid prior checks. For shared changes identify affected pages before repeating checks. Author completion, integrated render and user acceptance remain separate states.
+
+Use independent review when it can resolve a meaningful understanding gap; it is not a fixed multi-Agent pipeline. Save new reference implementations only from actual received or produced material, with source, method and the scope of acceptance. Template geometry feedback stays with the template maintainer; report-logic examples and rule learning stay with the structure maintainer.
 
 ## Research basis
 

references/production-rules.md

@@ -4,9 +4,9 @@ These rules apply across templates and authoring routes. **Required** rules prot
 
 ## Understand and compose
 
-- **C01 · Recommended:** form a brief from the audience, purpose, setting, supplied material, content boundary, output route, length/time, template and review rhythm. Reuse known answers. Ask only for consequential information that cannot reasonably be inferred; do not turn the brief into a questionnaire.
+- **C01 · Recommended:** consume the supplied audience, purpose, material boundary and page content plan, including the intended understanding, necessary premises and progression within the current page. Establish the production route, template and review rhythm from settled choices. If no plan is provided, form only the brief needed for the current authorized work; substantial report planning and example-derived content rules belong to the optional `report-structure` Skill. See [content handoff](content-handoff.md).
 - **C02 · Required:** preserve facts, numbers, conditions, causal relationships and strength of conclusions. Distinguish source statements, inference and added material. Do not invent unknown values. Identify synthetic examples and retain traceable sources for material claims.
-- **C03 · Recommended:** establish the presentation's main judgment and progression before filling pages. Give each page a purpose and reading order, with as many supporting points as the content needs. Summarize without changing meaning.
+- **C03 · Required meaning and visual correspondence, recommended composition:** preserve the supplied page purpose, intended understanding, evidence and key steps. Make the association between each conclusion and its evidence visible, and check the actual page's progression and necessary context. Choose a suitable composition and reading order for those relationships; concrete layout methods may vary. Do not silently change chapter order or move essential content to notes. Return meaningful omissions, contradictions or capacity conflicts to the content plan; do not create a parallel report-structure rule library. Summarize only within the authorized content scope and without changing meaning; C02 governs required content fidelity.
 - **C04 · Recommended:** keep hierarchy, color semantics, terminology, units, legends, strokes, icon grammar and component scale consistent across pages. Use declared template exceptions where needed.
 - **C05 · Recommended:** choose layout and columns from content relationships, then place components. Maintain grouping, alignment, spacing, reading order and moderate density. Add decoration for a purpose. Resolve excess content through the template's rewrite/layout/split policy; keep its declared typography and grid rules.
 - **C06 · Recommended:** inspect suitable components and page-library examples before authoring. Read their rationale and method; adapt, combine or create as needed. Remove example content, update data and metadata, and preserve reference attribution.
@@ -15,24 +15,24 @@ These rules apply across templates and authoring routes. **Required** rules prot
 
 - **C07 · Recommended priority, required paint contract:** reuse suitable template icons; draw new simple icons as SVG/native shapes; use ImageGen for complex icon imagery; use external ready icons as a supplement. Every route must finish with the selected icon production contract: stable semantic parts, permitted whole/partial palette binding, fixed details and transparent structure. Generated or external source material is not exempt. See [icon production](icon-production.md).
 - **C08 · Required truthfulness, recommended selection:** choose photos, evidence figures, illustrations and decoration by their information role. Use supplied/trustworthy originals for exact identity and real evidence. Identify generated material; do not present it as official marks, real scenes or experimental results. Keep originals, derivative/generation provenance and needed production inputs. Preserve proportions and critical evidence when cropping.
-- **C09 · Required data fidelity, recommended expression:** retain data, units, definitions, time range, missing-value policy and sources. Select comparison, trend, distribution, composition or relationship views accordingly. Keep related comparisons semantically and numerically comparable; normally avoid misleading truncation, meaningless dual axes and 3D ornament. Sources may live in notes/metadata; do not introduce a forbidden footer. See [charts](charts.md) and [components](components.md).
-- **C10 · Required semantics, recommended implementation:** nodes, links, arrows, groups and legends represent actual relationships. Distinguish data flow, control flow, dependency and time sequence. Do not turn unordered peers into a causal chain. Prefer native objects/SVG for technical diagrams; preserve code symbols, indentation and necessary context. State the actual formula object type.
+- **C09 · Required data fidelity, recommended expression:** retain data, units, definitions, time range, missing-value policy and sources. Before drawing comparisons, check compatible objects, denominators/baselines, samples or workloads and statistical methods. Resolve differences with valid conversion, recalculation or comparable subsets where possible, retaining the basis. If they cannot be aligned, use separate views or a justified limited comparison and state the remaining scope; a difference label alone cannot justify a ranking. Select comparison, trend, distribution, composition or relationship views accordingly; normally avoid misleading truncation, meaningless dual axes and 3D ornament. Sources may live in notes/metadata; necessary conditions for interpreting the comparison remain visible. Do not introduce a forbidden footer. See [charts](charts.md) and [components](components.md).
+- **C10 · Required semantics, recommended implementation:** nodes, links, arrows, groups and legends represent actual relationships. Distinguish peers, classification/containment, comparison, time/process, cause, condition/dependency, reasoning, data flow and control flow as relevant. Adjacency, grouping, correlation or time order alone does not establish cause; an arrow must express an identified relationship. Prefer native objects/SVG for technical diagrams; preserve code symbols, indentation and necessary context. State the actual formula object type.
 
 ## Implement and retain
 
 - **C11 · Required:** implement text, shapes, connectors, tables and charts according to the selected route. Do not claim a full-page screenshot is editable completion. Use supported tools and disclose technical limits; do not silently change backend, depend on another installed Skill or introduce an online provider. [Native objects](native-objects.md) describes actual object support.
 - **C12 · Required:** retain source data, page content/code, notes, assets, generation parameters, template version, environment and necessary metadata. When content changes, synchronize chart cache/workbook, SVG fallback and current previews. Use relocatable project paths. A cached export or final PPTX alone is not a rebuildable project. See [project workspace](project-workspace.md).
-- **C13 · Recommended:** complete content, visual and implementation checks at the authorized review granularity. Even an authorized batch needs page checks. Multiple authors share a frozen brief/style; the coordinator checks cross-page story, terminology and appearance. Existing page-by-page authorization remains binding. See [page collaboration](page-collaboration.md).
+- **C13 · Recommended:** complete content, visual and implementation checks at the authorized review granularity. Even an authorized batch needs page checks. Multiple authors share a frozen brief/style; the coordinator checks cross-page progression, terminology and appearance. Revisions preserve premises, key steps, evidence associations and agreed content destinations across source, page and notes. Existing page-by-page authorization remains binding. See [page collaboration](page-collaboration.md).
 
 ## Verify, revise and deliver
 
 - **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.
+- **C15 · Recommended:** identify affected pages after shared-input changes and rebuild/recheck them. When order or allocation changes, synchronize stable page IDs, destinations, page references and notes with the content plan. Retain recoverable sources, provenance 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.
 
 ## 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`.
+- **C17 · Required:** small muted notes may supply background, data sources, ranges, measurement definitions and citation details. A condition that changes the core conclusion or required action belongs with the related main information, as do substantive chart explanations, key process conditions/timing and conclusions. Fix ambiguous or overstrong body text, supplement evidence or integrate necessary conditions before adding a disclaimer. Remove disclaimers that only anticipate hypothetical objections and do not aid understanding, judgment or action; retain specific useful warnings with proportionate emphasis. Do not hide necessary meaning in notes/metadata or promote ordinary provenance into a warning. Classify by meaning, not by a field named `detail`, `caption` or `source`. See [text hierarchy](text-and-containers.md#keep-substantive-explanations-visible).
 - **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).
 - **C20 · Required:** paragraph lines obey punctuation rules for line starts and ends. Do not leave a line containing only one substantive character, whether alone, followed by punctuation, or surrounded by punctuation; this applies to every line, including the final line. Keep closing punctuation with preceding content and opening punctuation with following content; preserve unbreakable marks and words. Reflow the complete logical paragraph under its shared layout, then check the actual rendered lines. Do not fix this by deleting/changing content, splitting independent text boxes, or introducing undeclared font sizes, character spacing or per-line offsets. See [paragraph line breaking](text-and-containers.md#paragraph-line-breaking-rules).

references/text-and-containers.md

@@ -51,17 +51,19 @@ Preserve separate paragraphs as separate complete strings or explicit paragraph
 
 ## 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.
+Determine importance before assigning `caption`, `detail` or muted styles. Small muted text can carry background, data sources, data ranges, measurement definitions and citation details. A condition that directly changes the core conclusion or required action belongs with the related main information. Keep substantive chart explanations, key process conditions/timing, dependencies and conclusions readable as body, node text or a substantive callout heading.
+
+Fix ambiguous or overstrong body text directly, supplement the evidence or integrate the necessary condition. Remove disclaimers that only anticipate hypothetical objections and add no useful understanding, judgment or action. A small note or warning box does not justify keeping an unnecessary statement. Retain concrete useful warnings with emphasis suited to their role; ordinary source and range notes do not need to become warnings.
 
 | Statement | Treatment |
 |---|---|
-| Data source, collection date or a nonessential terminology expansion | Supplementary note is allowed; retain source metadata too |
+| Data source, collection date, citation locator or supplementary range/measurement definition | Small supplementary text 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 |
+| The measured dataset defines the scope of the core performance claim | State that scope in the claim or its related main information; detailed dataset provenance may remain small |
 | 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.
+Read the page without the small muted notes. Its workflow, conclusion and necessary scope must remain understandable and accurate. Then check the notes for useful supporting detail rather than repeated disclaimers. This check also applies to any field named `source`: the field name cannot make a substantive claim into provenance.
 
 ## Different roles inside a container
 

references/visual-design.md

@@ -1,15 +1,24 @@
 # Page mockups and visual materials
 
-Reuse the user's settled template, theme, route and page workflow. Define the current page's title/message, supporting evidence, content groups, notes, layout, asset roles and required native objects before generating its mockup. Review only consequential decisions that remain open; do not restart settled outline or style choices. A request to review one page does not authorize a full-deck generation run.
+Reuse the user's settled template, theme, route and page workflow. Receive the current page's title/message, evidence, content groups and notes through [content handoff](content-handoff.md), then define its layout, asset roles and required native objects before generating its mockup. Establish a minimal page brief if none is supplied. Review only consequential decisions that remain open; do not restart settled outline or style choices. A request to review one page does not authorize a full-deck generation run.
 
 When extracting style from an existing presentation or PDF, render representative pages and inspect the actual images. XML/object counts alone cannot establish density, hierarchy, ornament or spacing. Keep style references separate from strict source assets. Use existing accepted references; a rejected mockup does not remain a design baseline.
 
+## Page composition and HTML boundary
+
+Choose text, figures, diagrams and their arrangement from the current information relationship. Pure text can serve a short question, quotation or conclusion; a picture or icon needs a useful role. Do not mechanically reuse website hero sections, selling cards or dashboards as report layouts. The page's main meaning must be readable without scrolling, hovering or clicking.
+
+Make conclusions and their supporting evidence visibly correspond through proximity, a shared heading, matching labels, annotations, highlighting or a necessary connector. Use only connections that express real relationships. Preserve exact premises and key reasoning/derivation steps where the audience needs them; check progression and information burden in the actual composition. Internal item counts, maintenance IDs and authoring decisions stay in process material unless the audience needs them for the report itself.
+
+Do not use HTML/DOM/CSS to lay out report pages, including layouts later captured as screenshots, printed or converted to another format. HTML may contain a JavaScript visualization itself and its necessary runtime container. This exception does not cover surrounding titles, prose, columns or page UI; produce those through the permitted native/SVG route. A direct SVG diagram is allowed. Keep the selected route's editability claims accurate for any visualization asset.
+
 ## Mockup prompt inputs
 
 Use the host image-generation tool directly for requested raster page samples. Supply:
 
 - The selected canvas/aspect ratio, template palette, typography intent, grid and fixed content regions.
 - The exact current-page text and moderate content density, with a declared hierarchy and clear content division.
+- The intended page progression, necessary premises or key steps, and the association between conclusions and evidence.
 - Approved representative images as style references, with the current layout allowed to differ.
 - Supplied logos, figures and screenshots as strict identity/evidence assets. Preserve values, axes, labels, proportions and scientific meaning; do not synthesize substitute evidence.
 - The editable reconstruction plan: decorative pictures may remain assets, while title/body, controls, separators and diagrams must later become independent native objects as required.