alran 0.0.0-stage → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (506) hide show
  1. package/ALRAN_TOOLS_NOTICES.md +64 -0
  2. package/LICENSE +27 -0
  3. package/LICENSE-STATUS.md +21 -0
  4. package/NOTICE +6 -0
  5. package/README.md +289 -2
  6. package/THIRD_PARTY_NOTICES.md +113 -0
  7. package/alran-tools.js +3 -0
  8. package/assets/agents/_default/prompt-auto_classifier.md +185 -0
  9. package/assets/agents/_default/prompt-auto_classifier_extras.md +17 -0
  10. package/assets/agents/_default/prompt-base-all.md +133 -0
  11. package/assets/agents/_default/prompt-base-all.md.hbs +228 -0
  12. package/assets/agents/_default/prompt-base-windows.md +5 -0
  13. package/assets/agents/_default/prompt-base-windows.md.hbs +5 -0
  14. package/assets/agents/_default/prompt-base-worker.md +10 -0
  15. package/assets/agents/_default/prompt-base-worker.md.hbs +27 -0
  16. package/assets/agents/_default/prompt-compact.md +76 -0
  17. package/assets/agents/_default/prompt-compact_continue.md +9 -0
  18. package/assets/agents/_default/prompt-git.md +8 -0
  19. package/assets/agents/_default/prompt-goal.md +13 -0
  20. package/assets/agents/_default/prompt-session-branch.md +3 -0
  21. package/assets/agents/_default/prompt-session-branch.md.hbs +30 -0
  22. package/assets/agents/_default/prompt-session-root.md +3 -0
  23. package/assets/agents/_default/prompt-session-root.md.hbs +32 -0
  24. package/assets/agents/_default/prompt-title.md +11 -0
  25. package/assets/agents/_default/prompt-tool_agent.md +22 -0
  26. package/assets/agents/_migration/README.md +20 -0
  27. package/assets/agents/_migration/coder/PERSONA.md +11 -0
  28. package/assets/agents/_migration/coder/system-prompt.md.hbs +42 -0
  29. package/assets/agents/_migration/general/PERSONA.md +11 -0
  30. package/assets/agents/_migration/general/system-prompt.md.hbs +49 -0
  31. package/assets/agents/_v2/AGENT_CONTEXT.md.hbs +245 -0
  32. package/assets/agents/_v2/PTC_TOOL_CALLS.md.hbs +35 -0
  33. package/assets/agents/_v2/coding/SYSTEM.md.hbs +173 -0
  34. package/assets/agents/_v2/explore.md.hbs +38 -0
  35. package/assets/agents/_v2/tui/SYSTEM.md.hbs +211 -0
  36. package/assets/agents/_v2/verifier.md.hbs +32 -0
  37. package/assets/agents/_v2/work/SYSTEM.md.hbs +186 -0
  38. package/assets/agents/_v2/worker.md.hbs +27 -0
  39. package/assets/agents/alran/PERSONA.md +7 -0
  40. package/assets/agents/alran/features/cron.md.hbs +0 -0
  41. package/assets/agents/alran/features/delegation.md.hbs +56 -0
  42. package/assets/agents/alran/features/memory.md.hbs +61 -0
  43. package/assets/agents/alran/features/recoverable-deletion.md.hbs +10 -0
  44. package/assets/agents/alran/features/task-management.md.hbs +11 -0
  45. package/assets/agents/alran/features/web-search.md.hbs +11 -0
  46. package/assets/agents/alran/modes/coding/online/PERSONA.md.hbs +20 -0
  47. package/assets/agents/alran/modes/coding/online/SYSTEM.md.hbs +158 -0
  48. package/assets/agents/alran/modes/work/online/PERSONA.md.hbs +20 -0
  49. package/assets/agents/alran/modes/work/online/SYSTEM.md.hbs +160 -0
  50. package/assets/agents/alran/prompt-session-root.md +4 -0
  51. package/assets/agents/alran/prompt-session-root.md.hbs +4 -0
  52. package/assets/agents/alran/skills/alran-code-product/SKILL.md +72 -0
  53. package/assets/agents/alran/skills/alran-code-product/references/account-models.md +61 -0
  54. package/assets/agents/alran/skills/alran-code-product/references/agents.md +34 -0
  55. package/assets/agents/alran/skills/alran-code-product/references/extensions.md +46 -0
  56. package/assets/agents/alran/skills/alran-code-product/references/workflows.md +56 -0
  57. package/assets/agents/alran/skills/control-in-app-browser/SKILL.md +590 -0
  58. package/assets/agents/alran/system-prompt.md.hbs +97 -0
  59. package/assets/agents/builtin-agents.json +1 -0
  60. package/assets/agents/desktop-task/archive-title/system-en.md +1 -0
  61. package/assets/agents/desktop-task/checkpoint/system.md +19 -0
  62. package/assets/agents/desktop-task/output-revision/system.md +1 -0
  63. package/assets/agents/desktop-task/retry/continuation.md +4 -0
  64. package/assets/agents/desktop-task/session-title/system.md +41 -0
  65. package/assets/agents/explore/PERSONA.md +8 -0
  66. package/assets/agents/explore/agent.md +14 -0
  67. package/assets/agents/explore/system-prompt.md.hbs +35 -0
  68. package/assets/agents/greeting.md +61 -0
  69. package/assets/agents/managed-prompts.json +47 -0
  70. package/assets/agents/prompt-exemptions.json +36 -0
  71. package/assets/agents/verifier/PERSONA.md +8 -0
  72. package/assets/agents/verifier/agent.md +17 -0
  73. package/assets/agents/verifier/system-prompt.md.hbs +28 -0
  74. package/assets/agents/worker/PERSONA.md +8 -0
  75. package/assets/agents/worker/agent.md +18 -0
  76. package/assets/agents/worker/system-prompt.md.hbs +22 -0
  77. package/assets/agents/workflow/code-review/review-candidates.md +120 -0
  78. package/assets/agents/workflow/code-review/reviewer-system.md +75 -0
  79. package/assets/agents/workflow/goal/budget-limit.md +16 -0
  80. package/assets/agents/workflow/goal/continuation.md +62 -0
  81. package/assets/agents/workflow/goal/objective-updated.md +16 -0
  82. package/assets/agents/workflow/goal/recovery-terminal-audit.md +13 -0
  83. package/assets/agents/workflow/goal/recovery.md +11 -0
  84. package/assets/agents/workflow/goal/terminal-audit.md +10 -0
  85. package/assets/agents/workflow/plan-mode/agent-entry.md +72 -0
  86. package/assets/agents/workflow/prompt-hook/system.md +0 -0
  87. package/assets/models-dev-catalog.json.gz +0 -0
  88. package/assets/prompts/code-review/review-candidates.md +120 -0
  89. package/assets/prompts/code-review/reviewer-system.md +75 -0
  90. package/assets/skills/alran-tools-master/SKILL.md +127 -0
  91. package/assets/skills/code-review/SKILL.md +51 -0
  92. package/assets/skills/cu-desktop/SKILL.md +255 -0
  93. package/assets/skills/deep-research/SKILL.md +30 -0
  94. package/assets/skills/deploy-website/SKILL.md +52 -0
  95. package/assets/skills/docx/LICENSE +21 -0
  96. package/assets/skills/docx/SKILL.md +259 -0
  97. package/assets/skills/docx/assets/styles/academic_styles.xml +250 -0
  98. package/assets/skills/docx/assets/styles/corporate_styles.xml +284 -0
  99. package/assets/skills/docx/assets/styles/default_styles.xml +449 -0
  100. package/assets/skills/docx/assets/xsd/aesthetic-rules.xsd +470 -0
  101. package/assets/skills/docx/assets/xsd/business-rules.xsd +130 -0
  102. package/assets/skills/docx/assets/xsd/common-types.xsd +159 -0
  103. package/assets/skills/docx/assets/xsd/wml-subset.xsd +589 -0
  104. package/assets/skills/docx/docs/acceptance-checklists/create.md +7 -0
  105. package/assets/skills/docx/docs/acceptance-checklists/edit.md +6 -0
  106. package/assets/skills/docx/docs/acceptance-checklists/layout-repair.md +7 -0
  107. package/assets/skills/docx/docs/acceptance-checklists/template.md +6 -0
  108. package/assets/skills/docx/docs/acceptance.md +139 -0
  109. package/assets/skills/docx/docs/anti-patterns.md +14 -0
  110. package/assets/skills/docx/docs/backends.md +116 -0
  111. package/assets/skills/docx/docs/evidence.md +73 -0
  112. package/assets/skills/docx/docs/failure-taxonomy.md +71 -0
  113. package/assets/skills/docx/docs/index.md +50 -0
  114. package/assets/skills/docx/docs/rendered-delivery.md +125 -0
  115. package/assets/skills/docx/docs/router.md +122 -0
  116. package/assets/skills/docx/docs/tables-and-numbering.md +27 -0
  117. package/assets/skills/docx/docs/task-apply-template.md +141 -0
  118. package/assets/skills/docx/docs/task-compare-two-docx.md +48 -0
  119. package/assets/skills/docx/docs/task-create.md +124 -0
  120. package/assets/skills/docx/docs/task-edit-fill.md +69 -0
  121. package/assets/skills/docx/docs/task-read-content.md +148 -0
  122. package/assets/skills/docx/docs/task-read-rendered.md +78 -0
  123. package/assets/skills/docx/docs/task-read-structure.md +93 -0
  124. package/assets/skills/docx/docs/task-repair-layout.md +70 -0
  125. package/assets/skills/docx/docs/template-dsl.md +32 -0
  126. package/assets/skills/docx/docs/track-changes.md +15 -0
  127. package/assets/skills/docx/docs/xml-patch-dsl.md +33 -0
  128. package/assets/skills/docx/references/cjk_typography.md +357 -0
  129. package/assets/skills/docx/references/cjk_university_template_guide.md +184 -0
  130. package/assets/skills/docx/references/comments_guide.md +191 -0
  131. package/assets/skills/docx/references/design_good_bad_examples.md +829 -0
  132. package/assets/skills/docx/references/design_principles.md +819 -0
  133. package/assets/skills/docx/references/openxml_element_order.md +308 -0
  134. package/assets/skills/docx/references/openxml_encyclopedia_part1.md +4061 -0
  135. package/assets/skills/docx/references/openxml_encyclopedia_part2.md +2820 -0
  136. package/assets/skills/docx/references/openxml_encyclopedia_part3.md +3381 -0
  137. package/assets/skills/docx/references/openxml_namespaces.md +82 -0
  138. package/assets/skills/docx/references/openxml_units.md +72 -0
  139. package/assets/skills/docx/references/sample-patch-plans.json +22 -0
  140. package/assets/skills/docx/references/sample-task-intents.json +5 -0
  141. package/assets/skills/docx/references/sample-template-manifests.json +21 -0
  142. package/assets/skills/docx/references/scenario_a_create.md +284 -0
  143. package/assets/skills/docx/references/scenario_b_edit_content.md +295 -0
  144. package/assets/skills/docx/references/scenario_c_apply_template.md +456 -0
  145. package/assets/skills/docx/references/track_changes_guide.md +200 -0
  146. package/assets/skills/docx/references/troubleshooting.md +506 -0
  147. package/assets/skills/docx/references/typography_guide.md +294 -0
  148. package/assets/skills/docx/references/xsd_validation_guide.md +158 -0
  149. package/assets/skills/docx/scripts/build_patch_plan.py +29 -0
  150. package/assets/skills/docx/scripts/diff_docx_structure.py +61 -0
  151. package/assets/skills/docx/scripts/doc_to_docx.ps1 +85 -0
  152. package/assets/skills/docx/scripts/doc_to_docx.sh +40 -0
  153. package/assets/skills/docx/scripts/docx_preview.ps1 +76 -0
  154. package/assets/skills/docx/scripts/docx_preview.sh +37 -0
  155. package/assets/skills/docx/scripts/docx_to_pdf.py +87 -0
  156. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Cli/AlranAIDocx.Cli.csproj +19 -0
  157. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Cli/Program.cs +18 -0
  158. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/AlranAIDocx.Core.csproj +15 -0
  159. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/AnalyzeCommand.cs +147 -0
  160. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/ApplyTemplateCommand.cs +322 -0
  161. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/CreateCommand.cs +324 -0
  162. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/DiffCommand.cs +155 -0
  163. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/EditContentCommand.cs +487 -0
  164. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/FixOrderCommand.cs +108 -0
  165. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/MergeRunsCommand.cs +122 -0
  166. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/ValidateCommand.cs +107 -0
  167. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/CommentSynchronizer.cs +169 -0
  168. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/ElementOrder.cs +80 -0
  169. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/NamespaceConstants.cs +42 -0
  170. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/RunMerger.cs +81 -0
  171. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/StyleAnalyzer.cs +81 -0
  172. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/TrackChangesHelper.cs +99 -0
  173. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/UnitConverter.cs +23 -0
  174. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples.cs +1832 -0
  175. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch1.cs +910 -0
  176. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch2.cs +999 -0
  177. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch3.cs +1048 -0
  178. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch4.cs +1038 -0
  179. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/CharacterFormattingSamples.cs +1020 -0
  180. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/DocumentCreationSamples.cs +1121 -0
  181. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/FieldAndTocSamples.cs +624 -0
  182. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/FootnoteAndCommentSamples.cs +675 -0
  183. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/HeaderFooterSamples.cs +838 -0
  184. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ImageSamples.cs +917 -0
  185. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ListAndNumberingSamples.cs +826 -0
  186. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ParagraphFormattingSamples.cs +1199 -0
  187. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/StyleSystemSamples.cs +1487 -0
  188. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/TableSamples.cs +1163 -0
  189. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/TrackChangesSamples.cs +595 -0
  190. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/CjkHelper.cs +39 -0
  191. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/FontDefaults.cs +24 -0
  192. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/PageSizes.cs +20 -0
  193. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/BusinessRuleValidator.cs +224 -0
  194. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/GateCheckValidator.cs +148 -0
  195. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/ValidationResult.cs +23 -0
  196. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/XsdValidator.cs +69 -0
  197. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.slnx +4 -0
  198. package/assets/skills/docx/scripts/env_check.ps1 +327 -0
  199. package/assets/skills/docx/scripts/env_check.sh +340 -0
  200. package/assets/skills/docx/scripts/extract_docx_text.py +1075 -0
  201. package/assets/skills/docx/scripts/pack_docx.py +31 -0
  202. package/assets/skills/docx/scripts/read_docx_structure.py +1032 -0
  203. package/assets/skills/docx/scripts/render_docx_pages.py +147 -0
  204. package/assets/skills/docx/scripts/rendered_report.py +609 -0
  205. package/assets/skills/docx/scripts/setup.ps1 +542 -0
  206. package/assets/skills/docx/scripts/setup.sh +537 -0
  207. package/assets/skills/docx/scripts/unpack_docx.py +29 -0
  208. package/assets/skills/docx/scripts/validate_template_manifest.py +60 -0
  209. package/assets/skills/docx/scripts/verify_anchor_atomicity.py +87 -0
  210. package/assets/skills/edit-deployed-website/SKILL.md +27 -0
  211. package/assets/skills/init/SKILL.md +135 -0
  212. package/assets/skills/llm-call/SKILL.md +48 -0
  213. package/assets/skills/llm-call/scripts/llm_call.py +458 -0
  214. package/assets/skills/pdf/SKILL.md +280 -0
  215. package/assets/skills/pdf/docs/advanced-reference.md +711 -0
  216. package/assets/skills/pdf/docs/create-guide.md +437 -0
  217. package/assets/skills/pdf/docs/design-guide.md +204 -0
  218. package/assets/skills/pdf/docs/forms-guide.md +462 -0
  219. package/assets/skills/pdf/docs/html-pdf-spec.md +500 -0
  220. package/assets/skills/pdf/docs/latex-academic-thesis-guide.md +233 -0
  221. package/assets/skills/pdf/docs/latex-technical-book-guide.md +112 -0
  222. package/assets/skills/pdf/docs/pitfalls-index.md +792 -0
  223. package/assets/skills/pdf/docs/read-guide.md +358 -0
  224. package/assets/skills/pdf/docs/reformat-guide.md +238 -0
  225. package/assets/skills/pdf/docs/skill-readme-archive.md +151 -0
  226. package/assets/skills/pdf/docs/troubleshooting.md +86 -0
  227. package/assets/skills/pdf/docs/vision-guide.md +188 -0
  228. package/assets/skills/pdf/scripts/__init__.py +0 -0
  229. package/assets/skills/pdf/scripts/_pdf_read_lib.py +284 -0
  230. package/assets/skills/pdf/scripts/fill/__init__.py +0 -0
  231. package/assets/skills/pdf/scripts/fill/acroform_apply.py +153 -0
  232. package/assets/skills/pdf/scripts/fill/overlay_apply.py +109 -0
  233. package/assets/skills/pdf/scripts/lib/__init__.py +0 -0
  234. package/assets/skills/pdf/scripts/lib/acroform_io.py +170 -0
  235. package/assets/skills/pdf/scripts/lib/cli_utils.py +41 -0
  236. package/assets/skills/pdf/scripts/lib/geometry.py +79 -0
  237. package/assets/skills/pdf/scripts/make.sh +388 -0
  238. package/assets/skills/pdf/scripts/merge.py +112 -0
  239. package/assets/skills/pdf/scripts/pdf_inspect/__init__.py +0 -0
  240. package/assets/skills/pdf/scripts/pdf_inspect/acroform_inspect.py +52 -0
  241. package/assets/skills/pdf/scripts/pdf_inspect/acroform_probe.py +57 -0
  242. package/assets/skills/pdf/scripts/pdf_inspect/layout_scan.py +164 -0
  243. package/assets/skills/pdf/scripts/read_pdf_vision.py +473 -0
  244. package/assets/skills/pdf/scripts/reformat_parse.py +181 -0
  245. package/assets/skills/pdf/scripts/render/__init__.py +0 -0
  246. package/assets/skills/pdf/scripts/render/overlay_preview.py +86 -0
  247. package/assets/skills/pdf/scripts/render/page_rasterize.py +85 -0
  248. package/assets/skills/pdf/scripts/render_html.cjs +205 -0
  249. package/assets/skills/pdf/scripts/validate/__init__.py +0 -0
  250. package/assets/skills/pdf/scripts/validate/geometry_lint.py +124 -0
  251. package/assets/skills/pdf/templates/INDEX.md +90 -0
  252. package/assets/skills/pdf/templates/bilingual-menu-premium/README.md +175 -0
  253. package/assets/skills/pdf/templates/bilingual-menu-premium/skeleton.html +343 -0
  254. package/assets/skills/pdf/templates/brand-guide-2page/README.md +140 -0
  255. package/assets/skills/pdf/templates/brand-guide-2page/skeleton.html +264 -0
  256. package/assets/skills/pdf/templates/data-viz-report/README.md +234 -0
  257. package/assets/skills/pdf/templates/data-viz-report/skeleton.html +835 -0
  258. package/assets/skills/pdf/templates/form-fill-acroform/README.md +195 -0
  259. package/assets/skills/pdf/templates/form-fill-acroform/field_values.template.json +118 -0
  260. package/assets/skills/pdf/templates/latex-academic-thesis/README.md +146 -0
  261. package/assets/skills/pdf/templates/latex-academic-thesis/source.tex +334 -0
  262. package/assets/skills/pdf/templates/latex-technical-book/README.md +130 -0
  263. package/assets/skills/pdf/templates/latex-technical-book/README.template-source.md +62 -0
  264. package/assets/skills/pdf/templates/latex-technical-book/source.tex +439 -0
  265. package/assets/skills/pdf/templates/multi-article-aggregator/README.md +148 -0
  266. package/assets/skills/pdf/templates/multi-article-aggregator/pipeline.md +223 -0
  267. package/assets/skills/pdf/templates/multilang-research-report/README.md +136 -0
  268. package/assets/skills/pdf/templates/multilang-research-report/skeleton.html +242 -0
  269. package/assets/skills/pdf/templates/reformat-default/README.md +136 -0
  270. package/assets/skills/pdf/templates/reformat-default/skeleton.html +204 -0
  271. package/assets/skills/pdf/templates/translate-preserve-layout/README.md +136 -0
  272. package/assets/skills/pdf/templates/translate-preserve-layout/skeleton.html +96 -0
  273. package/assets/skills/pdf/templates/translate-preserve-layout/terminology.template.json +66 -0
  274. package/assets/skills/pptx/SKILL.md +283 -0
  275. package/assets/skills/pptx/references/design-system.md +424 -0
  276. package/assets/skills/pptx/references/editing.md +162 -0
  277. package/assets/skills/pptx/references/element-map.md +229 -0
  278. package/assets/skills/pptx/references/pitfalls.md +205 -0
  279. package/assets/skills/pptx/references/pptxgenjs.md +420 -0
  280. package/assets/skills/pptx/references/preview-selection-writeback.md +65 -0
  281. package/assets/skills/pptx/references/python-pptx-recipes.md +63 -0
  282. package/assets/skills/pptx/references/slide-types.md +413 -0
  283. package/assets/skills/pptx/scripts/alran-ppt-map.cjs +280 -0
  284. package/assets/skills/pptx/scripts/audit_pptx.py +708 -0
  285. package/assets/skills/pptx/scripts/extract_comments.py +468 -0
  286. package/assets/skills/pptx/scripts/extract_images.py +226 -0
  287. package/assets/skills/pptx/scripts/extract_pptx.py +285 -0
  288. package/assets/skills/pptx/scripts/pdf2png.swift +203 -0
  289. package/assets/skills/pptx/scripts/pptx-screenshot.sh +105 -0
  290. package/assets/skills/resume-codex/SKILL.md +53 -0
  291. package/assets/skills/resume-codex/scripts/session-reader.mjs +445 -0
  292. package/assets/skills/skill-creator/SKILL.md +188 -0
  293. package/assets/skills/skill-creator/references/anti-patterns.md +149 -0
  294. package/assets/skills/skill-creator/references/commands-macos-linux.md +38 -0
  295. package/assets/skills/skill-creator/references/commands-windows-powershell.md +48 -0
  296. package/assets/skills/skill-creator/references/description-rubric.md +83 -0
  297. package/assets/skills/skill-creator/references/skill-template.md +101 -0
  298. package/assets/skills/skill-creator/references/when-to-bundle-scripts.md +139 -0
  299. package/assets/skills/skill-creator/scripts/lint-skill.js +226 -0
  300. package/assets/skills/skill-refiner/SKILL.md +137 -0
  301. package/assets/skills/visual-page/SKILL.md +194 -0
  302. package/assets/skills/x-link-reader/SKILL.md +108 -0
  303. package/assets/skills/xlsx/SKILL.md +498 -0
  304. package/assets/skills/xlsx/docs/advanced-reference.md +410 -0
  305. package/assets/skills/xlsx/docs/conventions-guide.md +217 -0
  306. package/assets/skills/xlsx/docs/create-edit-guide.md +410 -0
  307. package/assets/skills/xlsx/docs/pitfalls-index.md +759 -0
  308. package/assets/skills/xlsx/docs/raw-xml-escape-hatch.md +201 -0
  309. package/assets/skills/xlsx/docs/recalc-guide.md +295 -0
  310. package/assets/skills/xlsx/scripts/office/helpers/__init__.py +0 -0
  311. package/assets/skills/xlsx/scripts/office/helpers/merge_runs.py +199 -0
  312. package/assets/skills/xlsx/scripts/office/helpers/simplify_redlines.py +197 -0
  313. package/assets/skills/xlsx/scripts/office/pack.py +159 -0
  314. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chart.xsd +1499 -0
  315. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd +146 -0
  316. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd +1085 -0
  317. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd +11 -0
  318. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-main.xsd +3081 -0
  319. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-picture.xsd +23 -0
  320. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd +185 -0
  321. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd +287 -0
  322. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/pml.xsd +1676 -0
  323. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd +28 -0
  324. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd +144 -0
  325. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd +174 -0
  326. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd +25 -0
  327. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd +18 -0
  328. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd +59 -0
  329. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd +56 -0
  330. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd +195 -0
  331. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-math.xsd +582 -0
  332. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd +25 -0
  333. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/sml.xsd +4439 -0
  334. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-main.xsd +570 -0
  335. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd +509 -0
  336. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd +12 -0
  337. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd +108 -0
  338. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd +96 -0
  339. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/wml.xsd +3646 -0
  340. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/xml.xsd +116 -0
  341. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-contentTypes.xsd +42 -0
  342. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-coreProperties.xsd +50 -0
  343. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-digSig.xsd +49 -0
  344. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-relationships.xsd +33 -0
  345. package/assets/skills/xlsx/scripts/office/schemas/mce/mc.xsd +75 -0
  346. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2010.xsd +560 -0
  347. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2012.xsd +67 -0
  348. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2018.xsd +14 -0
  349. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-cex-2018.xsd +20 -0
  350. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-cid-2016.xsd +13 -0
  351. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-sdtdatahash-2020.xsd +4 -0
  352. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-symex-2015.xsd +8 -0
  353. package/assets/skills/xlsx/scripts/office/soffice.py +191 -0
  354. package/assets/skills/xlsx/scripts/office/unpack.py +132 -0
  355. package/assets/skills/xlsx/scripts/office/validate.py +117 -0
  356. package/assets/skills/xlsx/scripts/office/validators/__init__.py +15 -0
  357. package/assets/skills/xlsx/scripts/office/validators/base.py +851 -0
  358. package/assets/skills/xlsx/scripts/office/validators/docx.py +446 -0
  359. package/assets/skills/xlsx/scripts/office/validators/pptx.py +275 -0
  360. package/assets/skills/xlsx/scripts/office/validators/redlining.py +247 -0
  361. package/assets/skills/xlsx/scripts/recalc.py +450 -0
  362. package/chunks/account-commands-JZ6NXTTK.js +2 -0
  363. package/chunks/anthropic-MN33DP4E.js +2 -0
  364. package/chunks/application-ITGAJ4HC.js +2 -0
  365. package/chunks/auth-command-V3RVPLZO.js +2 -0
  366. package/chunks/azure-openai-responses-OWHMUNKC.js +2 -0
  367. package/chunks/chunk-2TF6JAQM.js +2 -0
  368. package/chunks/chunk-33CNY6GP.js +2 -0
  369. package/chunks/chunk-3AODGLMF.js +2 -0
  370. package/chunks/chunk-44VPC5LA.js +38 -0
  371. package/chunks/chunk-4CN3IJFH.js +2 -0
  372. package/chunks/chunk-4PDIO3M6.js +2 -0
  373. package/chunks/chunk-4X22UJQH.js +164 -0
  374. package/chunks/chunk-6255CZPL.js +2 -0
  375. package/chunks/chunk-6P4UKHGR.js +2 -0
  376. package/chunks/chunk-7QLAXRD2.js +1085 -0
  377. package/chunks/chunk-7XYOYZX2.js +2 -0
  378. package/chunks/chunk-A7GMJNA2.js +29 -0
  379. package/chunks/chunk-AGUSPIUP.js +2 -0
  380. package/chunks/chunk-BQ3CF3KE.js +2 -0
  381. package/chunks/chunk-C3CMJAAV.js +3 -0
  382. package/chunks/chunk-CJM7ZJ6W.js +7 -0
  383. package/chunks/chunk-CSOUJVKM.js +2 -0
  384. package/chunks/chunk-D66ZSHXR.js +2 -0
  385. package/chunks/chunk-D7MGU75P.js +2 -0
  386. package/chunks/chunk-E3GLGDGC.js +5 -0
  387. package/chunks/chunk-ENHOPPS7.js +16 -0
  388. package/chunks/chunk-EOR6EDNR.js +2 -0
  389. package/chunks/chunk-EYK25HWR.js +2 -0
  390. package/chunks/chunk-F46IELF5.js +2 -0
  391. package/chunks/chunk-FC4M2B7E.js +2 -0
  392. package/chunks/chunk-FSNYOJPJ.js +2 -0
  393. package/chunks/chunk-FUERW2DW.js +3 -0
  394. package/chunks/chunk-FXOH6TEQ.js +21 -0
  395. package/chunks/chunk-GP52JZMY.js +2 -0
  396. package/chunks/chunk-GRXX6I72.js +2 -0
  397. package/chunks/chunk-GSYHBK5Q.js +6 -0
  398. package/chunks/chunk-HNWBFJNO.js +2 -0
  399. package/chunks/chunk-IIE366LR.js +6706 -0
  400. package/chunks/chunk-IWK7PZP7.js +207 -0
  401. package/chunks/chunk-J3KCPYZT.js +2 -0
  402. package/chunks/chunk-KCLRJQ53.js +59 -0
  403. package/chunks/chunk-LU4RPLJ3.js +2 -0
  404. package/chunks/chunk-LZJYNT32.js +2 -0
  405. package/chunks/chunk-M7GW4VMR.js +27 -0
  406. package/chunks/chunk-MACBL5HF.js +2 -0
  407. package/chunks/chunk-N5NTXCJI.js +2 -0
  408. package/chunks/chunk-N5SVBCUB.js +7 -0
  409. package/chunks/chunk-N6W7ZL26.js +2 -0
  410. package/chunks/chunk-NWB7LFOK.js +131 -0
  411. package/chunks/chunk-OIQ336YE.js +16 -0
  412. package/chunks/chunk-OQNU3VPS.js +30 -0
  413. package/chunks/chunk-OTDNOWXG.js +16 -0
  414. package/chunks/chunk-PNXZWSWT.js +3 -0
  415. package/chunks/chunk-QFUV5PX6.js +2 -0
  416. package/chunks/chunk-QIN5ZBE2.js +2 -0
  417. package/chunks/chunk-QKBN5CGI.js +2 -0
  418. package/chunks/chunk-QPGTKSIQ.js +2 -0
  419. package/chunks/chunk-SIOLUFGG.js +2 -0
  420. package/chunks/chunk-TW23QKAD.js +3 -0
  421. package/chunks/chunk-U3RMPDXU.js +2 -0
  422. package/chunks/chunk-U7U3DJHF.js +2 -0
  423. package/chunks/chunk-VLXX22YO.js +2 -0
  424. package/chunks/chunk-WHD2XVT2.js +2 -0
  425. package/chunks/chunk-WTAJMYF2.js +249 -0
  426. package/chunks/chunk-WWNUAU4P.js +29 -0
  427. package/chunks/chunk-WYANV3IX.js +4 -0
  428. package/chunks/chunk-XAGZ6ZEU.js +9 -0
  429. package/chunks/chunk-XFCC2CI2.js +24 -0
  430. package/chunks/chunk-XQK7JM66.js +2 -0
  431. package/chunks/chunk-YLQXZBEL.js +2 -0
  432. package/chunks/chunk-YPV2X2RG.js +2 -0
  433. package/chunks/chunk-Z6BHCXKT.js +25 -0
  434. package/chunks/chunk-Z6HBNJCA.js +8 -0
  435. package/chunks/chunk-ZQKVUPKA.js +2 -0
  436. package/chunks/chunk-ZQOALVGL.js +2 -0
  437. package/chunks/clipboard-image-PQPC4EHR.js +2 -0
  438. package/chunks/data-dir-LDVKDCJ2.js +2 -0
  439. package/chunks/dist-2BRD4JFU.js +11 -0
  440. package/chunks/dist-EXKHRFQO.js +5 -0
  441. package/chunks/emscripten-module-RD6P2XH5.js +2 -0
  442. package/chunks/emscripten-module-WYNDFH3N.js +2 -0
  443. package/chunks/emscripten-module-XPTEOIWW.js +2 -0
  444. package/chunks/emscripten-module-ZS3PMSDF.js +2 -0
  445. package/chunks/ffi-IO7WZQNG.js +2 -0
  446. package/chunks/ffi-M5UP5J6C.js +2 -0
  447. package/chunks/ffi-ORLOPBB3.js +2 -0
  448. package/chunks/ffi-OUPK6AY6.js +2 -0
  449. package/chunks/google-UJAPMFAB.js +2 -0
  450. package/chunks/google-vertex-VLSF55PW.js +2 -0
  451. package/chunks/install-source-JTIUC4G4.js +2 -0
  452. package/chunks/launcher-FCZ3EDBF.js +61 -0
  453. package/chunks/lifecycle-GY435YMF.js +2 -0
  454. package/chunks/main-TQGGRHTS.js +13 -0
  455. package/chunks/mistral-ZJZUEF2X.js +3 -0
  456. package/chunks/module-6F3E5H7Y-BN7QWGYB.js +2 -0
  457. package/chunks/module-asyncify-R6PWJ6ZV-P4FWSBAY.js +2 -0
  458. package/chunks/multipart-parser-L6M455MS.js +2 -0
  459. package/chunks/network-proxy-U72JCK2I.js +2 -0
  460. package/chunks/openai-codex-responses-FPCDNRL5.js +2 -0
  461. package/chunks/openai-completions-D32YW6KL.js +2 -0
  462. package/chunks/openai-responses-ZCGSENM4.js +2 -0
  463. package/chunks/openrouter-G2EHY5BD.js +2 -0
  464. package/chunks/otel-OHXIZ666.js +2 -0
  465. package/chunks/package-contract-GVXTMJ3N.js +2 -0
  466. package/chunks/pdfjs-SHZAF7PF.js +107 -0
  467. package/chunks/photon_rs-C52RL4CI.js +3 -0
  468. package/chunks/plugin-command-OSAFHS7C.js +2 -0
  469. package/chunks/provider-command-SKTCHD4E.js +2 -0
  470. package/chunks/questionnaire-bridge-ISQOCYWY.js +2 -0
  471. package/chunks/run-acp-command-SG2BDMFJ.js +2 -0
  472. package/chunks/run-exec-command-5ADSQR2Z.js +15 -0
  473. package/chunks/skills-command-XXXEZAG6.js +2 -0
  474. package/chunks/src-DNIDEMVV.js +2 -0
  475. package/chunks/src-IBHIRTD7.js +2 -0
  476. package/chunks/telemetry-J7ZLGF5X.js +2 -0
  477. package/chunks/telemetry-command-COQG2AKK.js +5 -0
  478. package/chunks/tools-WDBB2JKV.js +2 -0
  479. package/chunks/undici-TUGHZJSA.js +2 -0
  480. package/chunks/update-NB6OD572.js +14 -0
  481. package/chunks/update-hint-ED7O67WU.js +3 -0
  482. package/chunks/wechat-onboard-UWXQW2HT.js +2 -0
  483. package/cli.js +5 -0
  484. package/configs/data-minimal.yaml +50 -0
  485. package/embedded/alran-tools/cli.mjs +4961 -0
  486. package/embedded/alran-tools/manifest.json +25 -0
  487. package/emscripten-module.wasm +0 -0
  488. package/image-preview-worker.js +2 -0
  489. package/internal-bin/alran-tools +9 -0
  490. package/internal-bin/alran-tools.cmd +8 -0
  491. package/matrix-mcp-stdio.js +4 -0
  492. package/native/darwin/prebuilds/darwin-arm64/darwin-modifiers.node +0 -0
  493. package/native/darwin/prebuilds/darwin-x64/darwin-modifiers.node +0 -0
  494. package/native/win32/prebuilds/win32-arm64/win32-console-mode.node +0 -0
  495. package/native/win32/prebuilds/win32-x64/win32-console-mode.node +0 -0
  496. package/package.json +38 -4
  497. package/photon_rs_bg.wasm +0 -0
  498. package/quickjs-worker.js +152 -0
  499. package/vendor/java-proxy-agent/build.ts +97 -0
  500. package/vendor/java-proxy-agent/srt-proxy-agent.jar +0 -0
  501. package/vendor/seccomp/arm64/apply-seccomp +0 -0
  502. package/vendor/seccomp/build.ts +74 -0
  503. package/vendor/seccomp/x64/apply-seccomp +0 -0
  504. package/vendor/srt-win/arm64/srt-win.exe +0 -0
  505. package/vendor/srt-win/build.ts +40 -0
  506. package/vendor/srt-win/x64/srt-win.exe +0 -0
@@ -0,0 +1,759 @@
1
+ # Pitfalls Index — Canonical Query Templates
2
+
3
+ > **Match-and-fuse, don't read-and-think.** Each entry below is a
4
+ > production-ready prompt template. When the user's incoming query
5
+ > matches a `Match signatures` block, **copy the matching canonical
6
+ > query**, substitute the `Slots` with the user's actual values,
7
+ > and execute it verbatim. Each canonical query already encodes every
8
+ > known pitfall, every verification gate, and every fall-back path
9
+ > for that scenario — there is no extra "trace" to look up.
10
+ >
11
+ > If no signature matches, fall back to [`../SKILL.md`](../SKILL.md) routing.
12
+ > If a partial match (one of two slots fits), prefer **fusing** the
13
+ > matching template's verifications into your own plan rather than
14
+ > writing a new one from scratch.
15
+ >
16
+ > **Universal slot placeholders below** — these are referenced inside
17
+ > every canonical query and resolve at execution time:
18
+ >
19
+ > - `<SKILL>` → `{{DATA_DIR}}/.builtin-skills/xlsx`
20
+ > - `<SKILL_PDF>` → `{{DATA_DIR}}/.builtin-skills/pdf`
21
+ > - `<TMP>` → a writable scratch dir (e.g. `/tmp/xlsx-task-<ts>`)
22
+
23
+ ---
24
+
25
+ ## Quick lookup — match user query to a case
26
+
27
+ | # | Match keywords | Slots | Canonical §|
28
+ |---|---|---|---|
29
+ | **X1** | financial PDF → Excel analysis / 财报分析 / 10-K → xlsx with formulas + charts | `PDF_PATHS[]`, `COMPANY`, `METRICS[]`, `OUTPUT_XLSX` | §X1 |
30
+ | **X2** | Excel + PDF + Word multi-format deliverable / 多格式产出 / dashboard + report + memo | `INPUT_DATA`, `ANALYSIS_DIMS[]`, `OUTPUT_DIR`, `DOTNET_BUDGET_MIN(default 5)` | §X2 |
31
+ | **X3** | 500k+ row dataset → pivot tables + dashboard + slicers / 大数据透视 / RFM | `INPUT`, `KEY_COLS[]`, `METRICS[]`, `PIVOT_AXES[]`, `SLICERS[]`, `OUTPUT_XLSX` | §X3 |
32
+ | **X4** | 240-page financial report → Excel preserving every table / 复杂金融 PDF→Excel | `PDF_PATH`, `STATEMENTS[]`, `OUTPUT_XLSX` | §X4 |
33
+ | **X5** | multi-year financial analysis / 财务分析 / revenue/margin/growth/segment trends | `COMPANY`, `YEAR_RANGE`, `PDF_PATHS[]`, `METRICS[]`, `OUTPUT_XLSX` | §X5 |
34
+ | **X6** | composite score / index / ranking with stated range / 综合评分 0-100 | `INPUT_XLSX`, `SCORE_COLS[]`, `WEIGHTS[]`, `TARGET_RANGE`, `OUTPUT_XLSX` | §X6 |
35
+ | **X7** | cross-sheet dynamic formulas / Inputs → Summary auto-update / 跨 sheet 引用 | `INPUT_LAYOUT`, `SUMMARY_LAYOUT`, `OUTPUT_XLSX` | §X7 |
36
+
37
+ ---
38
+
39
+ ## X1 — Financial PDF → Excel analysis with formulas + charts
40
+
41
+ ### Match signatures
42
+
43
+ - "读 {COMPANY} 的 {YEAR_RANGE} 年报 PDF,提取 {METRICS},输出 Excel 含公式和图表"
44
+ - "build an Excel analysis of {COMPANY}'s {years} from these annual reports"
45
+ - "extract revenue / EPS / store count / segment data from {PDF}, build xlsx"
46
+
47
+ ### Canonical query
48
+
49
+ ```
50
+ TASK: From {PDF_PATHS[]} (annual reports of {COMPANY}), extract
51
+ {METRICS[]} and build a formula-first Excel analysis at {OUTPUT_XLSX}
52
+ with cross-year derived metrics + charts.
53
+
54
+ STEP 1 — PDF read: ALWAYS go through [pdf] §P6 + §P7
55
+ # §P6 = locate-first (build heading index before any extraction).
56
+ # §P7 = vision per page for any financial-table page (balance sheet,
57
+ # income statement, cash flow, debt schedule).
58
+ # Do NOT pdfplumber over financial tables — see [pdf] P7 for why.
59
+ # Output: a flat list of {year, metric, value, source_page} tuples.
60
+
61
+ STEP 2 — Build the workbook structure
62
+ Sheets:
63
+ - Inputs / Raw (blue text #0000FF, primary values from PDF)
64
+ - Calculations (black text #000000, all = formulas)
65
+ - Summary (green text #008000 for cross-sheet refs)
66
+ - Charts (visual, data sources point at formula cells)
67
+
68
+ python3 <<EOF
69
+ from openpyxl import Workbook
70
+ from openpyxl.styles import Font, PatternFill
71
+ book = Workbook()
72
+ inputs = book.active; inputs.title = "Inputs"
73
+ blue = Font(color="0000FF")
74
+ black = Font(color="000000")
75
+ # Header
76
+ inputs.append(["Year"] + ["{COMPANY} {m}" for m in METRICS])
77
+ for y in years:
78
+ row = [y] + [extracted[(y, m)] for m in METRICS]
79
+ inputs.append(row)
80
+ for cell in inputs[inputs.max_row]:
81
+ cell.font = blue
82
+ EOF
83
+
84
+ STEP 3 — Derived metrics (every cell MUST be a = formula, not a literal)
85
+ python3 <<EOF
86
+ calc = book.create_sheet("Calculations")
87
+ calc.append(["Year", "Revenue Growth", "Operating Margin", "EPS Growth"])
88
+ for r_idx in range(2, len(years) + 2):
89
+ calc.append([
90
+ f"=Inputs!A{r_idx}",
91
+ f"=(Inputs!B{r_idx} - Inputs!B{r_idx-1}) / Inputs!B{r_idx-1}",
92
+ f"=Inputs!C{r_idx} / Inputs!B{r_idx}",
93
+ f"=(Inputs!D{r_idx} - Inputs!D{r_idx-1}) / Inputs!D{r_idx-1}",
94
+ ])
95
+ EOF
96
+ # NEVER pre-compute these in Python and write_number them. The user
97
+ # must be able to flip an Inputs cell, recalc, and see Calculations move.
98
+
99
+ STEP 4 — Charts (data sources point at FORMULA cells, not literals)
100
+ python3 <<EOF
101
+ from openpyxl.chart import LineChart, BarChart, Reference
102
+ ch = LineChart()
103
+ ch.title = "{COMPANY} Revenue Trend"
104
+ data = Reference(inputs, min_col=2, min_row=1, max_col=2, max_row=len(years)+1)
105
+ cats = Reference(inputs, min_col=1, min_row=2, max_row=len(years)+1)
106
+ ch.add_data(data, titles_from_data=True)
107
+ ch.set_categories(cats)
108
+ book["Calculations"].add_chart(ch, "F2")
109
+ EOF
110
+
111
+ STEP 5 — Save + recalc
112
+ book.save("{OUTPUT_XLSX}")
113
+ python <SKILL>/scripts/recalc.py "{OUTPUT_XLSX}" 60 2><TMP>/recalc.log
114
+
115
+ STEP 6 — VERIFY (mandatory two-gate)
116
+ # Gate 1: total_errors == 0
117
+ # Gate 2: total_formulas > 0 AND > expected_min (e.g. years × metrics × 2)
118
+ jq '.status, .total_errors, .total_formulas' <recalc-stdout>
119
+ # status != "success" → fix per recalc-guide.md §3 error table.
120
+ # total_formulas == 0 → DELIVERY FAILED, rewrite STEP 3 with = formulas.
121
+
122
+ STEP 7 — Spot-check formula correctness (not just count)
123
+ python3 <<EOF
124
+ from openpyxl import load_workbook
125
+ book = load_workbook("{OUTPUT_XLSX}", data_only=True)
126
+ # Pick 1-2 derived cells and compare to a Python re-computation
127
+ # from the Inputs sheet. Mismatch → wrong formula references.
128
+ EOF
129
+
130
+ CONSTRAINTS:
131
+ - PDF reading: §P6 + §P7, never pdfplumber on financial tables.
132
+ - Every derived value: = formula, not literal. No exceptions.
133
+ - recalc → total_formulas == 0 is FAILURE, not success.
134
+ - Don't 2>/dev/null vision calls or recalc — log to <TMP>/.
135
+ ```
136
+
137
+ ---
138
+
139
+ ## X2 — Multi-format deliverable (Excel + PDF + Word) via parallel sub-agents
140
+
141
+ ### Match signatures
142
+
143
+ - "分析 {DATA},产出 Excel dashboard + PDF report + Word memo"
144
+ - "build me a triple deliverable: spreadsheet + presentation PDF + Word"
145
+ - "用户退款 / 业务三件套 / 完整分析包"
146
+
147
+ ### Canonical query
148
+
149
+ ```
150
+ TASK: Produce three coordinated deliverables for {ANALYSIS_TOPIC} in
151
+ {OUTPUT_DIR}: dashboard.xlsx + report.pdf + memo.docx.
152
+
153
+ STEP 1 — Pre-flight: confirm dotnet for docx
154
+ which dotnet 2><TMP>/which.log
155
+ # If missing: install IS POSSIBLE but takes ~5 minutes (200 MB download).
156
+ # Either pre-install before launching sub-agents, OR the docx sub-agent
157
+ # prompt must explicitly budget setup time per STEP 2.
158
+
159
+ STEP 2 — Launch 3 background sub-agents (task tool, run_in_background: true)
160
+ # Foreground task calls run sequentially — background mode is what
161
+ # makes the three deliverables build in parallel. Track with
162
+ # task_query / task_output.
163
+ # CRITICAL: the Word sub-agent prompt must include:
164
+ # "Setup may take up to {DOTNET_BUDGET_MIN} minutes for dotnet install
165
+ # if not already present. Do NOT abort during steady network activity.
166
+ # Only consider yourself stalled if no progress for >10 minutes."
167
+
168
+ Sub-agent prompts:
169
+ - dashboard: <follow X1 / X3 / X5 canonical query for the data shape>
170
+ → write {OUTPUT_DIR}/dashboard.xlsx
171
+ - report-pdf: <follow [pdf] §P3 canonical for chart-rich PDF>
172
+ → write {OUTPUT_DIR}/report.pdf
173
+ - memo-docx: <docx canonical>
174
+ "Setup may take {DOTNET_BUDGET_MIN}min for dotnet — wait it
175
+ out. If install genuinely fails, fall back to python-docx
176
+ and EXPLICITLY note 'docx unavailable, python-docx used,
177
+ formatting fidelity reduced' in the deliverable."
178
+
179
+ STEP 3 — Cross-check (yourself, after all three return)
180
+ Spot-check 3 numbers that appear in all three deliverables. They MUST
181
+ be identical. If any differ, identify the divergent figure and relaunch
182
+ the sub-agent whose input data feed was wrong.
183
+
184
+ STEP 4 — Final deliverables verification
185
+ ls -lh {OUTPUT_DIR}/dashboard.xlsx {OUTPUT_DIR}/report.pdf {OUTPUT_DIR}/memo.docx
186
+ # xlsx: total_formulas > 0 (per X1 STEP 6)
187
+ # pdf: pdfimages count > 0 (per [pdf] P3 STEP 5)
188
+ # docx: spot-check via word/document.xml unzip → confirm formatting present
189
+
190
+ STEP 5 — Cross-deliverable consistency report
191
+ Pick 3 KPIs (e.g. total revenue, top segment, growth rate). They must
192
+ appear identically in xlsx Summary, pdf KPI grid, and docx executive
193
+ summary. Mismatch → which one is wrong? Fix that sub-agent's input data
194
+ feed, never patch the deliverable manually.
195
+
196
+ CONSTRAINTS:
197
+ - dotnet install ≠ stall. Budget {DOTNET_BUDGET_MIN}min + 10min slack.
198
+ - python-docx fallback IS allowed but MUST be flagged in the deliverable.
199
+ - Cross-deliverable numbers MUST match — that's the whole point of one batch.
200
+ - Sub-agent prompts: never `2>/dev/null` any setup or build step.
201
+ ```
202
+
203
+ ---
204
+
205
+ ## X3 — 500k+ row dataset → pivot / dashboard / slicers
206
+
207
+ ### Match signatures
208
+
209
+ - "处理 {INPUT}(54万行 / 500k+ rows)做透视 / dashboard / RFM"
210
+ - "clean + pivot + slicer dashboard from {large_dataset}"
211
+ - "Online Retail / 电商交易明细 → 完整分析"
212
+
213
+ ### Canonical query
214
+
215
+ ```
216
+ TASK: From {INPUT} (~{ROW_COUNT} rows), build a formula-first dashboard
217
+ at {OUTPUT_XLSX} with pivots over {PIVOT_AXES[]} and slicers on
218
+ {SLICERS[]}.
219
+
220
+ STEP 1 — Read with pandas by default (polars if pandas is memory-bound)
221
+ # For 500k+ rows, do NOT inspect/transform source data with openpyxl row loops.
222
+ # Use pandas for ordinary large tabular work; switch to polars for memory/latency pressure.
223
+ python3 <<EOF
224
+ import pandas as pd
225
+ frame = pd.read_excel("{INPUT}", engine="openpyxl")
226
+ print("Loaded rows:", len(frame))
227
+ # If this is too slow or memory-bound, rerun with:
228
+ # import polars as pl
229
+ # frame = pl.read_excel("{INPUT}")
230
+ EOF
231
+
232
+ STEP 2 — Clean (RECORD what you removed; report counts)
233
+ python3 <<EOF
234
+ # Cleaning rules — report row counts at each step:
235
+ before = len(frame)
236
+ frame = frame.filter(~pl.col("InvoiceNo").str.starts_with("C")) # cancellations
237
+ print("After dropping cancellations:", len(frame), "removed:", before - len(frame))
238
+ before = len(frame)
239
+ frame = frame.filter(pl.col("Quantity") > 0)
240
+ frame = frame.filter(pl.col("UnitPrice") > 0)
241
+ print("After dropping non-positive:", len(frame), "removed:", before - len(frame))
242
+ before = len(frame)
243
+ frame = frame.filter(pl.col("CustomerID").is_not_null())
244
+ print("After dropping null CustomerID:", len(frame), "removed:", before - len(frame))
245
+ EOF
246
+
247
+ STEP 3 — WRITE FULL CLEANED ROWS (NEVER df.sample / df.head!)
248
+ # The most critical step. df.sample(100k) on a 397k-row frame breaks
249
+ # every downstream pivot and SUMIF without raising any error.
250
+ # If openpyxl's default writer is too slow, use write_only mode below.
251
+
252
+ python3 <<EOF
253
+ from openpyxl import Workbook
254
+ from openpyxl.cell import WriteOnlyCell
255
+ book = Workbook(write_only=True) # streaming writer; ~4× faster
256
+ raw = book.create_sheet("Raw")
257
+ raw.append(list(frame.columns))
258
+ for row in frame.iter_rows(): # ALL rows — no slicing
259
+ raw.append([WriteOnlyCell(raw, value=v) for v in row])
260
+ book.save("<TMP>/raw.xlsx")
261
+ EOF
262
+ # Confirm row count matches:
263
+ python3 -c "from openpyxl import load_workbook; wb=load_workbook('<TMP>/raw.xlsx', read_only=True); print(wb['Raw'].max_row)"
264
+
265
+ STEP 4 — Derived columns as = formulas
266
+ # Reopen with default reader to add formulas + pivot/slicer scaffolding.
267
+ python3 <<EOF
268
+ from openpyxl import load_workbook
269
+ book = load_workbook("<TMP>/raw.xlsx")
270
+ raw = book["Raw"]
271
+ # Add Revenue = Quantity * UnitPrice as a formula column
272
+ last = raw.max_row
273
+ raw.cell(row=1, column=raw.max_column + 1, value="Revenue")
274
+ for r in range(2, last + 1):
275
+ raw.cell(row=r, column=raw.max_column,
276
+ value=f"=B{r}*C{r}") # adjust col letters to schema
277
+ EOF
278
+
279
+ STEP 5 — Summary sheet: Excel-NATIVE aggregation only
280
+ # Choose by structure complexity (see <SKILL>/docs/advanced-reference.md §6.2):
281
+ # - Single-axis aggregation → =SUMIFS / =COUNTIFS / =AVERAGEIFS
282
+ # - Multi-axis cross-tab + drilldown → pivot table
283
+
284
+ Single-axis example:
285
+ summary.cell(row=r, column=2,
286
+ value=f"=SUMIFS(Raw!{rev_col}:{rev_col}, Raw!{cat_col}:{cat_col}, A{r})")
287
+
288
+ # NEVER do: frame.group_by("category").sum() → write_number(...).
289
+ # That ships a static snapshot and the recalc gate will not catch it.
290
+
291
+ STEP 6 — Slicers (openpyxl CANNOT create from scratch)
292
+ # Two production paths — pick one:
293
+
294
+ Path A (RECOMMENDED) — template inheritance:
295
+ # Pre-author template.xlsx ONCE in Excel/LibreOffice with the pivot
296
+ # and slicer wired to a named range "DataRange". Per run:
297
+ book = load_workbook("<SKILL>/templates/with-slicer.xlsx")
298
+ # Write Raw rows into the named range; pivot + slicer auto-refresh on recalc.
299
+
300
+ Path B — surgical XML transplant from a known-good template:
301
+ # See <SKILL>/docs/raw-xml-escape-hatch.md §1 + §3.
302
+ # Copy xl/pivotTables/*.xml + xl/pivotCaches/*.xml + xl/slicers/*.xml
303
+ # via scripts/office/{unpack,pack}.py.
304
+
305
+ IF NEITHER PATH IS AVAILABLE:
306
+ # Tell the user explicitly: "No slicer template available; falling back
307
+ # to a static dropdown filter on the Summary sheet. Slicer cannot be
308
+ # authored from scratch by openpyxl."
309
+ # Do NOT silently downgrade.
310
+
311
+ STEP 7 — Save + recalc
312
+ book.save("{OUTPUT_XLSX}")
313
+ python <SKILL>/scripts/recalc.py "{OUTPUT_XLSX}" 120 2><TMP>/recalc.log
314
+
315
+ STEP 8 — VERIFY (4 mandatory checks)
316
+ # 1. row count: Raw sheet matches the cleaned frame
317
+ # 2. total_errors == 0
318
+ # 3. total_formulas substantial (e.g. > #pivot_cells + #derived_cols)
319
+ # 4. summary correctness: spot-check 1-2 cells against polars on FULL frame
320
+ python3 <<EOF
321
+ from openpyxl import load_workbook
322
+ book = load_workbook("{OUTPUT_XLSX}", data_only=True)
323
+ print("Raw rows:", book["Raw"].max_row - 1)
324
+ # Compare a SUMIF result to the same aggregation on the FULL pandas/polars frame
325
+ EOF
326
+
327
+ CONSTRAINTS:
328
+ - 500k+ row source inspection/cleaning: pandas/polars default; openpyxl row-by-row source traversal is forbidden unless preserving workbook objects is the explicit goal.
329
+ - df.sample / df.head / per-category truncation on the raw sheet = forbidden.
330
+ - Summaries: pivot table or =SUMIFS only. Python groupby write-back = forbidden.
331
+ - Slicers: template-inherit OR XML-transplant OR explicit user notification.
332
+ NEVER silently downgrade.
333
+ - 4-check verification is mandatory; row count is the canary.
334
+ ```
335
+
336
+ ---
337
+
338
+ ## X4 — Complex financial PDF → Excel preserving every table
339
+
340
+ ### Match signatures
341
+
342
+ - "把这份 {PDF_PATH}(240页 financial report / HKEx 2024)转成 Excel"
343
+ - "convert balance sheet / income statement / cash flow PDF to xlsx"
344
+ - "金融年报 → Excel,要保留所有 table 结构"
345
+
346
+ ### Canonical query
347
+
348
+ ```
349
+ TASK: Convert {STATEMENTS[]} from {PDF_PATH} into {OUTPUT_XLSX}, one
350
+ sheet per statement, preserving multi-level headers and footnotes.
351
+
352
+ STEP 1 — Locate financial-table pages
353
+ Run [pdf] §P6 first → list of pages per statement.
354
+
355
+ STEP 2 — Vision per page (per [pdf] §P7)
356
+ # pdfplumber FORBIDDEN on financial tables even when text-native.
357
+ # Output: per-page TSV with header_l1 | header_l2 | label | value | footnote_ref
358
+
359
+ STEP 3 — Parse vision output to a normalised frame
360
+ python3 <<EOF
361
+ rows = []
362
+ for p in pages:
363
+ data = json.loads(open(f"<TMP>/vision-p{p}.json").read())
364
+ for line in data["chunks"][0]["text"].splitlines():
365
+ parts = line.split("\t")
366
+ if len(parts) == 5:
367
+ rows.append({"page": p, "l1": parts[0], "l2": parts[1],
368
+ "label": parts[2], "value": parts[3],
369
+ "footnote_ref": parts[4]})
370
+ EOF
371
+
372
+ STEP 4 — Write to xlsx (one sheet per statement)
373
+ python3 <<EOF
374
+ from openpyxl import Workbook
375
+ from openpyxl.styles import Font
376
+ book = Workbook()
377
+ book.remove(book.active)
378
+ bold = Font(bold=True)
379
+ for stmt in STATEMENTS:
380
+ ws = book.create_sheet(stmt[:31])
381
+ stmt_rows = [r for r in rows if r["statement"] == stmt]
382
+ # Multi-level header
383
+ ws.append(["", *[r["l1"] for r in unique_columns]])
384
+ ws.append(["Label", *[r["l2"] for r in unique_columns]])
385
+ for header_cell in ws[1] + ws[2]:
386
+ header_cell.font = bold
387
+ # Data
388
+ for row in stmt_rows:
389
+ ws.append([row["label"], row["value"], row["footnote_ref"]])
390
+ # Footnotes sheet (separate, keyed by ref number)
391
+ fn = book.create_sheet("Footnotes")
392
+ fn.append(["Ref", "Text"])
393
+ # ... populate from vision-extracted footnote glossary ...
394
+ book.save("{OUTPUT_XLSX}")
395
+ EOF
396
+
397
+ STEP 5 — VERIFY (cross-check 3 sub-totals against source)
398
+ # Pick a known sub-total line per statement (e.g. "Total assets",
399
+ # "Net income", "Net cash from operations"). Compare the value in
400
+ # {OUTPUT_XLSX} to the value visible in the source PDF on the
401
+ # corresponding page. Mismatch → re-run vision on that page with a
402
+ # more explicit prompt. NEVER patch the xlsx by hand.
403
+
404
+ CONSTRAINTS:
405
+ - Pure data dump — no derived values to compute on this leg.
406
+ If the user wants margins / ratios on top, switch to X5.
407
+ - Don't hand-fix vision misreads in xlsx; re-prompt vision instead.
408
+ - Don't 2>/dev/null vision calls.
409
+ ```
410
+
411
+ ---
412
+
413
+ ## X5 — Multi-year financial analysis (Formula-first hot spot)
414
+
415
+ ### Match signatures
416
+
417
+ - "{COMPANY} {YEAR_RANGE} 财务分析 Excel,含 revenue / margin / growth / segment 趋势"
418
+ - "build a financial-analysis xlsx for {COMPANY} covering {years}"
419
+ - "腾讯 / Alibaba / Apple 多年财报对比 + 派生指标"
420
+
421
+ ### Canonical query
422
+
423
+ ```
424
+ TASK: Build a formula-first multi-year financial analysis for {COMPANY}
425
+ covering {YEAR_RANGE}, output to {OUTPUT_XLSX}, including:
426
+ revenue, gross margin, operating margin, net margin, EPS, EPS growth,
427
+ revenue growth, CAGR, segment breakdown.
428
+
429
+ STEP 1 — PDF read: §P6 + §P7 per [pdf]
430
+ Output: tuples of (year, segment, metric, value, source_page).
431
+
432
+ STEP 2 — Inputs sheet (raw values, blue text)
433
+ See X1 STEP 2.
434
+
435
+ STEP 3 — Derived sheets (every cell = formula, no exceptions)
436
+ python3 <<EOF
437
+ calc = book.create_sheet("Derived")
438
+ calc.append(["Year", "Revenue Growth", "Gross Margin", "Op Margin",
439
+ "Net Margin", "EPS Growth", "Revenue CAGR (5y)"])
440
+ n = len(years)
441
+ for i, y in enumerate(years, start=2):
442
+ calc.append([
443
+ f"=Inputs!A{i}",
444
+ f"=IFERROR((Inputs!B{i}-Inputs!B{i-1})/Inputs!B{i-1}, \"\")" if i > 2 else "",
445
+ f"=Inputs!C{i}/Inputs!B{i}", # gross / revenue
446
+ f"=Inputs!D{i}/Inputs!B{i}",
447
+ f"=Inputs!E{i}/Inputs!B{i}",
448
+ f"=IFERROR((Inputs!F{i}-Inputs!F{i-1})/Inputs!F{i-1}, \"\")" if i > 2 else "",
449
+ f"=IFERROR((Inputs!B{1+n}/Inputs!B{2})^(1/{n-1})-1, \"\")" if i == 2 else "",
450
+ ])
451
+ EOF
452
+ # Wrap divisions with IFERROR to prevent #DIV/0! poisoning the recalc gate.
453
+
454
+ STEP 4 — Charts (data sources reference Derived sheet formula cells)
455
+ See X1 STEP 4.
456
+
457
+ STEP 5 — Save + recalc
458
+ book.save("{OUTPUT_XLSX}")
459
+ python <SKILL>/scripts/recalc.py "{OUTPUT_XLSX}" 60 2><TMP>/recalc.log
460
+
461
+ STEP 6 — VERIFY (mandatory two-gate + formula-count check)
462
+ # Gate 1: total_errors == 0
463
+ # Gate 2: total_formulas > 0 ← THE CRITICAL CHECK
464
+ jq -r '.status, .total_errors, .total_formulas' <recalc-stdout>
465
+
466
+ # If total_formulas is 0 OR less than #years × #metrics × 2:
467
+ # → DELIVERY FAILED. The workbook is a static snapshot, not a model.
468
+ # → Re-do STEP 3 with = formulas. Don't ship anyway.
469
+
470
+ # Per-sheet formula count (catches "0 formulas in Derived"):
471
+ python3 <<EOF
472
+ from openpyxl import load_workbook
473
+ book = load_workbook("{OUTPUT_XLSX}")
474
+ for ws in book.worksheets:
475
+ n = sum(1 for row in ws.iter_rows() for c in row
476
+ if isinstance(c.value, str) and c.value.startswith("="))
477
+ print(ws.title, "=", n, "formulas")
478
+ EOF
479
+
480
+ STEP 7 — Spot-check a derived value against an external recompute
481
+ # Pick one growth rate. Compute it manually from the source PDF values.
482
+ # Compare to the Derived sheet output. Mismatch → wrong column reference.
483
+
484
+ CONSTRAINTS:
485
+ - total_formulas == 0 OR << expected = DELIVERY FAILURE. Rewrite.
486
+ - Don't 2>/dev/null any vision call or recalc — log and grep on demand.
487
+ - All divisions wrapped with IFERROR.
488
+ - Color: blue for Inputs, black for Derived, green for Summary cross-refs.
489
+ ```
490
+
491
+ ---
492
+
493
+ ## X6 — Composite score / index with stated range
494
+
495
+ ### Match signatures
496
+
497
+ - "做一个 composite score / 综合评分 from {COLS}, normalised {0-100 / 1-10}"
498
+ - "build a risk index / ranking, normalised to {RANGE}"
499
+ - "{Financial_Sample_with_PI} 综合评分要 0-100"
500
+
501
+ ### Canonical query
502
+
503
+ ```
504
+ TASK: Build a composite score on {INPUT_XLSX} using {SCORE_COLS[]} with
505
+ weights {WEIGHTS[]}, normalised to {TARGET_RANGE} (e.g. 0-100),
506
+ output to {OUTPUT_XLSX}.
507
+
508
+ STEP 1 — Open + add Score column
509
+ python3 <<EOF
510
+ from openpyxl import load_workbook
511
+ book = load_workbook("{INPUT_XLSX}")
512
+ ws = book.active
513
+ last_col = ws.max_column
514
+ score_col = last_col + 1
515
+ ws.cell(row=1, column=score_col, value="Composite Score")
516
+ EOF
517
+
518
+ STEP 2 — Choose normalization formula (CLAMP to TARGET_RANGE in formula)
519
+
520
+ # Two patterns — pick one based on score nature:
521
+
522
+ # Pattern A — weighted sum then CLAMP (when raw is unbounded):
523
+ for r in range(2, ws.max_row + 1):
524
+ raw_expr = " + ".join(f"{w}*{col_letter}{r}" for w, col_letter in zip(WEIGHTS, SCORE_COLS))
525
+ formula = f"=ROUND(MIN(MAX(({raw_expr}), {LO}), {HI}), 1)"
526
+ ws.cell(row=r, column=score_col, value=formula)
527
+
528
+ # Pattern B — min-max normalization to TARGET_RANGE:
529
+ raw_col = chr(ord('A') + last_col) # the unnormalized raw composite
530
+ formula = (f"=ROUND(({raw_col}{r} - MIN(${raw_col}$2:${raw_col}${ws.max_row}))"
531
+ f" / (MAX(${raw_col}$2:${raw_col}${ws.max_row})"
532
+ f" - MIN(${raw_col}$2:${raw_col}${ws.max_row}))"
533
+ f" * {HI - LO} + {LO}, 1)")
534
+
535
+ STEP 3 — Save + recalc
536
+ book.save("{OUTPUT_XLSX}")
537
+ python <SKILL>/scripts/recalc.py "{OUTPUT_XLSX}" 60 2><TMP>/recalc.log
538
+
539
+ STEP 4 — IMMEDIATE range verification (the critical step)
540
+ python3 <<EOF
541
+ from openpyxl import load_workbook
542
+ book = load_workbook("{OUTPUT_XLSX}", data_only=True)
543
+ ws = book.active
544
+ scores = [ws.cell(row=r, column=score_col).value
545
+ for r in range(2, ws.max_row + 1)
546
+ if isinstance(ws.cell(row=r, column=score_col).value, (int, float))]
547
+ print("MIN:", min(scores), "MAX:", max(scores))
548
+ # MIN must be >= LO; MAX must be <= HI.
549
+ # If MAX = 1804 when user asked for 0-100 → STEP 2 formula missing CLAMP.
550
+ # FIX THE FORMULA, do NOT blame "data anomaly". Re-recalc.
551
+ EOF
552
+
553
+ STEP 5 — Methodology sheet (audit trail)
554
+ meth = book.create_sheet("Methodology")
555
+ meth.append(["Score Formula", "Weights", "Source Columns", "Range"])
556
+ meth.append([formula_template, str(WEIGHTS), str(SCORE_COLS), f"{LO}-{HI}"])
557
+ book.save("{OUTPUT_XLSX}")
558
+
559
+ CONSTRAINTS:
560
+ - When user states a target range, ENFORCE it in the formula.
561
+ Don't ship a wider range and blame "data anomaly".
562
+ - The verification in STEP 4 is mandatory; without it the formula bug
563
+ won't be caught until the user reports it.
564
+ - Document the formula in a Methodology sheet so the user can audit.
565
+ ```
566
+
567
+ ---
568
+
569
+ ## X7 — Cross-sheet dynamic formulas (modelling)
570
+
571
+ ### Match signatures
572
+
573
+ - "wire up Inputs tab so Summary cells auto-update when Inputs change"
574
+ - "build a model where Summary references Inputs via formulas"
575
+ - "跨 sheet 动态引用 / dynamic linkage"
576
+
577
+ ### Canonical query
578
+
579
+ ```
580
+ TASK: Build {OUTPUT_XLSX} where every Summary cell references the Inputs
581
+ sheet via formulas, with full color-code conventions.
582
+
583
+ STEP 1 — Sheet structure
584
+ python3 <<EOF
585
+ from openpyxl import Workbook
586
+ from openpyxl.styles import Font
587
+ book = Workbook()
588
+ inputs = book.active; inputs.title = "Inputs"
589
+ summary = book.create_sheet("Summary")
590
+ blue = Font(color="0000FF") # primary inputs
591
+ black = Font(color="000000") # in-sheet formulas
592
+ green = Font(color="008000") # cross-sheet references
593
+ EOF
594
+
595
+ STEP 2 — Inputs sheet
596
+ # Column A: label, Column B: value (blue), Column C: source/note
597
+ for label, value, src in INPUT_ROWS:
598
+ inputs.append([label, value, src])
599
+ inputs.cell(row=inputs.max_row, column=2).font = blue
600
+
601
+ STEP 3 — Summary sheet (every cell = =Inputs!ref or = derivation)
602
+ python3 <<EOF
603
+ summary.append(["Metric", "Value"])
604
+ for s in SUMMARY_ROWS:
605
+ # s = (label, formula) where formula references Inputs
606
+ r = summary.max_row + 1
607
+ summary.cell(row=r, column=1, value=s["label"])
608
+ cell = summary.cell(row=r, column=2, value=s["formula"])
609
+ # Color: green if cross-sheet ref, black if same-sheet derivation
610
+ cell.font = green if "Inputs!" in s["formula"] else black
611
+ EOF
612
+
613
+ STEP 4 — Save + recalc
614
+ book.save("{OUTPUT_XLSX}")
615
+ python <SKILL>/scripts/recalc.py "{OUTPUT_XLSX}" 30 2><TMP>/recalc.log
616
+
617
+ STEP 5 — VERIFY linkage (the live-model test)
618
+ python3 <<EOF
619
+ from openpyxl import load_workbook
620
+ # 1. Open data-only, capture a Summary value
621
+ book = load_workbook("{OUTPUT_XLSX}", data_only=True)
622
+ v_before = book["Summary"]["B2"].value
623
+ # 2. Open in formula mode, flip an Inputs value
624
+ book2 = load_workbook("{OUTPUT_XLSX}")
625
+ book2["Inputs"]["B2"] = book2["Inputs"]["B2"].value * 1.10
626
+ book2.save("<TMP>/test.xlsx")
627
+ # 3. Recalc, reopen data-only, confirm Summary moved
628
+ EOF
629
+ python <SKILL>/scripts/recalc.py "<TMP>/test.xlsx" 30 2><TMP>/recalc2.log
630
+ python3 -c "from openpyxl import load_workbook; print(load_workbook('<TMP>/test.xlsx', data_only=True)['Summary']['B2'].value)"
631
+ # Should differ from v_before. If not → Summary cell was a literal,
632
+ # not a formula. Go back to STEP 3.
633
+
634
+ CONSTRAINTS:
635
+ - All Summary cells: formula referencing Inputs, never literal.
636
+ - Color code is part of the deliverable — review at-a-glance audits this.
637
+ - The "flip an input, see Summary move" verification is mandatory.
638
+ ```
639
+
640
+ ---
641
+
642
+ ## X8 — xlsx ↔ csv ↔ json ↔ pdf with print settings
643
+
644
+ ### Match signatures
645
+
646
+ - "把 {INPUT_XLSX} 转成 csv + json + pdf,PDF 要横向 + 重复表头"
647
+ - "export to multiple formats with landscape, repeat header"
648
+ - "Superstore / 多格式数据转换"
649
+
650
+ ### Canonical query
651
+
652
+ ```
653
+ TASK: Convert {INPUT_XLSX} into each format in {OUTPUT_FORMATS[]} with
654
+ print settings {PRINT_SETTINGS}, output to {OUTPUT_DIR}.
655
+
656
+ STEP 0 — Strict Superstore / XML-template / HTML→PDF route check
657
+ If the user requires all of these at once:
658
+ - Excel → CSV + JSON + PDF;
659
+ - CSV → Excel reverse validation;
660
+ - PDF: A4 landscape + repeated headers + all columns visible;
661
+ - CSV→Excel via XML template / direct OOXML, not openpyxl full read-write;
662
+ - PDF via HTML→PDF, not screenshot or LibreOffice conversion;
663
+ then load and follow (a case study that is no longer shipped).
664
+ That case replaces the simpler pandas/soffice path below.
665
+
666
+ STEP 1 — Sanity probe
667
+ python3 -c "import pandas as pd; df=pd.read_excel('{INPUT_XLSX}'); print('Rows:', len(df)); print('Cols:', list(df.columns)); print('Dtypes:', df.dtypes.to_dict())"
668
+
669
+ STEP 2 — Per-format conversion (parallel where independent)
670
+
671
+ CSV:
672
+ python3 -c "import pandas as pd; pd.read_excel('{INPUT_XLSX}').to_csv('{OUTPUT_DIR}/data.csv', index=False, encoding='utf-8', date_format='%Y-%m-%d')"
673
+
674
+ JSON:
675
+ python3 <<EOF
676
+ import pandas as pd, json, pathlib
677
+ df = pd.read_excel("{INPUT_XLSX}")
678
+ payload = df.to_dict(orient="records")
679
+ pathlib.Path("{OUTPUT_DIR}/data.json").write_text(
680
+ json.dumps(payload, ensure_ascii=False, indent=2, default=str),
681
+ encoding="utf-8",
682
+ )
683
+ EOF
684
+ # For strict "data types correct" requirements, prefer the explicit
685
+ # typed-record pattern in (a case study that is no longer shipped)
686
+ # instead of relying on default=str for timestamps.
687
+
688
+ PDF (with print settings → see [pdf] §P9 canonical):
689
+ # Configure print settings via openpyxl, then convert via soffice.
690
+ # If acceptance requires HTML→PDF or all columns visible in a 10k-row
691
+ # landscape table, use (a case study that is no longer shipped).
692
+ # Verification on PDF is MANDATORY — soffice may ignore some settings.
693
+
694
+ STEP 3 — Reverse-validation (round-trip integrity)
695
+ python3 <<EOF
696
+ import pandas as pd
697
+ orig = pd.read_excel("{INPUT_XLSX}")
698
+ back = pd.read_csv("{OUTPUT_DIR}/data.csv")
699
+ print("Row count match:", len(orig) == len(back))
700
+ print("Col count match:", len(orig.columns) == len(back.columns))
701
+ # Date columns become strings in CSV — that's expected.
702
+ EOF
703
+
704
+ STEP 4 — PDF visual verification (PRINT-SETTINGS GATE)
705
+ # Per [pdf] §P9 STEP 4. NEVER trust openpyxl print settings without
706
+ # opening the converted PDF and visually checking page 1 + last page:
707
+ pdfinfo {OUTPUT_DIR}/data.pdf | grep -E "Pages|Page size"
708
+ ls -lh {OUTPUT_DIR}/data.pdf
709
+ # If size > 50 MB and user wanted preview → mode mismatch.
710
+ pdftoppm -r 100 -png -f 1 -l 1 {OUTPUT_DIR}/data.pdf <TMP>/p1
711
+ pdftoppm -r 100 -png -f LAST -l LAST {OUTPUT_DIR}/data.pdf <TMP>/last
712
+ # Confirm: page 1 has the header; last page rows not truncated;
713
+ # orientation matches request.
714
+
715
+ STEP 5 — Deliverable summary
716
+ Print:
717
+ - Conversion success / failure per format
718
+ - File sizes
719
+ - PDF page count + page size
720
+ - Any data type changes flagged (date → string in CSV is expected;
721
+ flag anything unexpected)
722
+
723
+ CONSTRAINTS:
724
+ - Row count > 500 + no mode → ASK before producing a 50+ MB PDF.
725
+ - JSON: ensure_ascii=False; for strict type requirements, convert dates
726
+ explicitly and verify numeric fields remain JSON numbers.
727
+ - CSV→Excel reverse validation with XML-template requirement means direct
728
+ OOXML package generation; do not use openpyxl full read-write.
729
+ - PDF print settings: NEVER ship without visual page-1 + last-page check.
730
+ - Don't 2>/dev/null soffice/render commands — stderr explains failures.
731
+ ```
732
+
733
+ ---
734
+
735
+ ## How to use this index
736
+
737
+ 1. **Read the user's incoming query.** Match it against each `Match signatures` block.
738
+ 2. **One match → copy the full Canonical query.** Substitute Slots
739
+ verbatim from the user's actual values. Execute step-by-step. Do not
740
+ skip verification steps (recalc + total_formulas + spot-check).
741
+ 3. **Multiple partial matches → fuse.** Take the strictest verification
742
+ from each matched canonical query; never relax a constraint.
743
+ 4. **No match → fall back** to [`../SKILL.md`](../SKILL.md) Operational rules and
744
+ §2 Decision Tree. Don't force-fit a wrong canonical query.
745
+
746
+ ## Universal constraints (apply to every canonical query above)
747
+
748
+ - **Don't `2>/dev/null`.** Redirect to `<TMP>/<step>.log`, grep on demand.
749
+ - **JSON files via `json.dumps(payload, ensure_ascii=False, indent=2)`.**
750
+ - **Formula-first.** Every derived value = `=` formula, never a literal.
751
+ - **`recalc.py` total_formulas == 0 = delivery failure.** Rewrite, don't ship.
752
+ - **Never `df.sample` / `df.head` on the raw sheet** when a summary will
753
+ aggregate over it. Always write the full row count.
754
+ - **Summaries: pivot tables or `=SUMIFS`/`=COUNTIFS` only.** Python
755
+ groupby written back as values is forbidden.
756
+ - **Slicers: template-inheritance OR XML transplant OR explicit user
757
+ notification.** Never silently downgrade.
758
+ - **When user states a numeric range, enforce it in the formula** with
759
+ `=ROUND(MIN(MAX(raw, LO), HI), 1)`. Spot-check MIN/MAX after recalc.