From e74dafcd36edbe62412e4552e505ea212e07f4b4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=9B=B7=E7=94=B5=E8=8A=BD=E8=A1=A3?=
 <zhangyanghaha0407@outlook.com>
Date: Mon, 20 Apr 2026 08:13:48 -0400
Subject: [PATCH] Silence render-disposed spam, unbreak bundled skills, drop
 board wake
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three independently ugly bugs that all fed the same log flood:

* Electron's `WebFrameMain.send` writes every "Render frame was disposed"
  to stderr via `console.error`. When the worker fans a second
  agent-event past a reloading renderer, we produced thousands of
  identical lines and stalled the main loop on stderr I/O. Added a
  `mainFrame.detached` guard so the send is short-circuited before
  Electron's own catch block fires, and installed a targeted filter in
  `suppress-warnings.ts` (now actually imported from the entry point)
  so the specific `console.error("Error sending from webFrameMain:"…)`
  noise never reaches the terminal. Any other payload still surfaces.

* `dispatchAgentMessage` accepted the human-reader sentinel as a wake
  target when an agent replied to `__board__` — `wakeAgentIfPossible`
  then called `db.getAgent("__board__")`, threw, and the dispatcher
  kept repeating on every send. Strip `HUMAN_SENDER_ID` at
  `resolveMessageWakeTargets`, and keep a defense-in-depth guard in the
  heartbeat so a stray caller (future automation fan-out) cannot
  reintroduce the crash.

* Pi's skills loader rejects any SKILL.md whose frontmatter `name`
  diverges from its parent directory. The four bundled `my-writing-style`
  copies declared `name: writing-style-skill`, so every install emitted
  a warning and dropped the skill. They also lived as orphan gitlinks
  (mode 160000 without .gitmodules), and the global `*.md` gitignore
  hid every other SKILL.md from version control. Fixed the frontmatter
  to match the dir, converted the dangling submodules to plain trees,
  and allowlisted `builtin-skills/**/*.md` so a fresh clone carries the
  catalogue instead of silently losing it.
---
 .gitignore                                    |    5 +
 .../remotion-best-practices/SKILL.md          |   61 +
 .../remotion-best-practices/rules/3d.md       |   86 +
 .../rules/animations.md                       |   27 +
 .../remotion-best-practices/rules/assets.md   |   78 +
 .../rules/audio-visualization.md              |  198 +
 .../remotion-best-practices/rules/audio.md    |  169 +
 .../rules/calculate-metadata.md               |  134 +
 .../rules/can-decode.md                       |   81 +
 .../remotion-best-practices/rules/charts.md   |  120 +
 .../rules/compositions.md                     |  154 +
 .../rules/display-captions.md                 |  184 +
 .../rules/extract-frames.md                   |  229 +
 .../remotion-best-practices/rules/ffmpeg.md   |   38 +
 .../remotion-best-practices/rules/fonts.md    |  152 +
 .../rules/get-audio-duration.md               |   58 +
 .../rules/get-video-dimensions.md             |   68 +
 .../rules/get-video-duration.md               |   60 +
 .../remotion-best-practices/rules/gifs.md     |  141 +
 .../remotion-best-practices/rules/images.md   |  134 +
 .../rules/import-srt-captions.md              |   69 +
 .../rules/light-leaks.md                      |   73 +
 .../remotion-best-practices/rules/lottie.md   |   70 +
 .../remotion-best-practices/rules/maps.md     |  412 ++
 .../rules/measuring-dom-nodes.md              |   34 +
 .../rules/measuring-text.md                   |  140 +
 .../rules/parameters.md                       |  109 +
 .../rules/sequencing.md                       |  118 +
 .../remotion-best-practices/rules/sfx.md      |   30 +
 .../rules/subtitles.md                        |   36 +
 .../remotion-best-practices/rules/tailwind.md |   11 +
 .../rules/text-animations.md                  |   20 +
 .../remotion-best-practices/rules/timing.md   |  179 +
 .../rules/transcribe-captions.md              |   70 +
 .../rules/transitions.md                      |  197 +
 .../rules/transparent-videos.md               |  106 +
 .../remotion-best-practices/rules/trimming.md |   51 +
 .../remotion-best-practices/rules/videos.md   |  171 +
 .../rules/voiceover.md                        |   99 +
 .../basic-for-all/deep-research/SKILL.md      |  281 ++
 builtin-skills/basic-for-all/my-writing-style |    1 -
 .../basic-for-all/my-writing-style/README.md  |   71 +
 .../basic-for-all/my-writing-style/SKILL.md   |  206 +
 .../my-writing-style/scripts/improve.py       |  426 ++
 .../my-writing-style/scripts/observe.py       |  309 ++
 builtin-skills/basic-for-all/nopua/SKILL.md   |  456 ++
 .../systematic-debugging/CREATION-LOG.md      |  119 +
 .../systematic-debugging/SKILL.md             |  296 ++
 .../condition-based-waiting.md                |  115 +
 .../systematic-debugging/defense-in-depth.md  |  122 +
 .../root-cause-tracing.md                     |  169 +
 .../systematic-debugging/test-academic.md     |   14 +
 .../systematic-debugging/test-pressure-1.md   |   58 +
 .../systematic-debugging/test-pressure-2.md   |   68 +
 .../systematic-debugging/test-pressure-3.md   |   69 +
 builtin-skills/document-process/docx/SKILL.md |  590 +++
 .../document-process/minimax-docx/SKILL.md    |  274 ++
 .../minimax-docx/references/cjk_typography.md |  357 ++
 .../cjk_university_template_guide.md          |  184 +
 .../minimax-docx/references/comments_guide.md |  191 +
 .../references/design_good_bad_examples.md    |  829 ++++
 .../references/design_principles.md           |  819 ++++
 .../references/openxml_element_order.md       |  308 ++
 .../references/openxml_encyclopedia_part1.md  | 4061 +++++++++++++++++
 .../references/openxml_encyclopedia_part2.md  | 2820 ++++++++++++
 .../references/openxml_encyclopedia_part3.md  | 3381 ++++++++++++++
 .../references/openxml_namespaces.md          |   82 +
 .../minimax-docx/references/openxml_units.md  |   72 +
 .../references/scenario_a_create.md           |  284 ++
 .../references/scenario_b_edit_content.md     |  295 ++
 .../references/scenario_c_apply_template.md   |  456 ++
 .../references/track_changes_guide.md         |  200 +
 .../references/troubleshooting.md             |  506 ++
 .../references/typography_guide.md            |  294 ++
 .../references/xsd_validation_guide.md        |  158 +
 .../document-process/minimax-pdf/README.md    |  222 +
 .../document-process/minimax-pdf/SKILL.md     |  192 +
 .../minimax-pdf/design/design.md              |  381 ++
 .../document-process/minimax-xlsx/SKILL.md    |  138 +
 .../minimax-xlsx/references/create.md         |  691 +++
 .../minimax-xlsx/references/edit.md           |  684 +++
 .../minimax-xlsx/references/fix.md            |   37 +
 .../minimax-xlsx/references/format.md         |  768 ++++
 .../references/ooxml-cheatsheet.md            |  231 +
 .../minimax-xlsx/references/read-analyze.md   |   97 +
 .../minimax-xlsx/references/validate.md       |  772 ++++
 .../document-process/my-writing-style         |    1 -
 .../my-writing-style/README.md                |   71 +
 .../my-writing-style/SKILL.md                 |  206 +
 .../my-writing-style/scripts/improve.py       |  426 ++
 .../my-writing-style/scripts/observe.py       |  309 ++
 .../document-process/pptx-generator/SKILL.md  |  249 +
 .../references/design-system.md               |  392 ++
 .../pptx-generator/references/editing.md      |  162 +
 .../pptx-generator/references/pitfalls.md     |  112 +
 .../pptx-generator/references/pptxgenjs.md    |  420 ++
 .../pptx-generator/references/slide-types.md  |  413 ++
 .../wechat-article-writer/SKILL.md            |   62 +
 .../writing-clearly-and-concisely/README.md   |  157 +
 .../writing-clearly-and-concisely/SKILL.md    |   93 +
 .../elements-of-style/01-introductory.md      |    3 +
 .../02-elementary-rules-of-usage.md           |  214 +
 ...03-elementary-principles-of-composition.md |  398 ++
 .../04-a-few-matters-of-form.md               |   89 +
 ...-words-and-expressions-commonly-misused.md |  348 ++
 .../signs-of-ai-writing.md                    |  901 ++++
 builtin-skills/document-process/xlsx/SKILL.md |  292 ++
 .../frontend-design/canvas-design/SKILL.md    |  130 +
 .../frontend-design/design-dna/README.md      |  109 +
 .../design-dna/README.zh-CN.md                |   99 +
 .../frontend-design/design-dna/SKILL.md       |  104 +
 .../design-dna/references/generation-guide.md |  209 +
 .../design-dna/references/schema.md           |  366 ++
 .../design-taste-frontend/SKILL.md            |  226 +
 .../frontend-design/frontend-design/SKILL.md  |   42 +
 .../high-end-visual-design/SKILL.md           |   98 +
 .../frontend-design/senior-frontend/SKILL.md  |  473 ++
 .../references/frontend_best_practices.md     |  806 ++++
 .../references/nextjs_optimization_guide.md   |  724 +++
 .../references/react_patterns.md              |  746 +++
 .../stitch-design-taste/DESIGN.md             |  121 +
 .../stitch-design-taste/SKILL.md              |  184 +
 .../iOS-Dev/app-icon-generator/SKILL.md       |  526 +++
 .../iOS-Dev/app-store-screenshots/SKILL.md    |  647 +++
 .../iOS-Dev/icon-generator/SKILL.md           |   48 +
 .../icon-generator/references/icon-sizes.md   |   39 +
 .../references/unreal-engine.md               |   29 +
 .../icon-generator/references/web-ui-ux.md    |   56 +
 .../iOS-Dev/ios-swift-development/SKILL.md    |  101 +
 .../references/mvvm-architecture-setup.md     |   60 +
 .../network-service-with-urlsession.md        |   99 +
 .../references/swiftui-views.md               |  112 +
 .../iOS-Dev/mobile-development/SKILL.md       |  261 ++
 .../references/MOBILE_GUIDE.md                |   73 +
 .../marketing/clean-general/SKILL.md          |   97 +
 builtin-skills/marketing/my-writing-style     |    1 -
 .../marketing/my-writing-style/README.md      |   71 +
 .../marketing/my-writing-style/SKILL.md       |  206 +
 .../my-writing-style/scripts/improve.py       |  426 ++
 .../my-writing-style/scripts/observe.py       |  309 ++
 .../marketing/wechat-article-writer/SKILL.md  |   62 +
 .../writing-clearly-and-concisely/README.md   |  157 +
 .../writing-clearly-and-concisely/SKILL.md    |   93 +
 .../elements-of-style/01-introductory.md      |    3 +
 .../02-elementary-rules-of-usage.md           |  214 +
 ...03-elementary-principles-of-composition.md |  398 ++
 .../04-a-few-matters-of-form.md               |   89 +
 ...-words-and-expressions-commonly-misused.md |  348 ++
 .../signs-of-ai-writing.md                    |  901 ++++
 builtin-skills/my-writing-style               |    1 -
 builtin-skills/my-writing-style/README.md     |   71 +
 builtin-skills/my-writing-style/SKILL.md      |  206 +
 .../my-writing-style/scripts/improve.py       |  426 ++
 .../my-writing-style/scripts/observe.py       |  309 ++
 .../ai-coding-discipline/SKILL.md             |  215 +
 .../api-design-principles/SKILL.md            |  518 +++
 .../assets/api-design-checklist.md            |  155 +
 .../references/graphql-schema-design.md       |  583 +++
 .../references/rest-best-practices.md         |  408 ++
 .../clean-architecture/SKILL.md               |  113 +
 .../assets/templates/_template.md             |   40 +
 .../references/_sections.md                   |   46 +
 .../references/adapt-anti-corruption-layer.md |  112 +
 .../references/adapt-controller-thin.md       |  101 +
 .../references/adapt-gateway-abstraction.md   |  119 +
 .../references/adapt-mapper-translation.md    |  119 +
 .../references/adapt-presenter-formats.md     |  109 +
 .../bound-boundary-cost-awareness.md          |  105 +
 .../references/bound-defer-decisions.md       |  105 +
 .../references/bound-humble-object.md         |  108 +
 .../references/bound-main-component.md        |  106 +
 .../references/bound-partial-boundaries.md    |   84 +
 .../bound-service-internal-architecture.md    |   94 +
 .../references/comp-common-closure.md         |   62 +
 .../references/comp-common-reuse.md           |   71 +
 .../comp-reuse-release-equivalence.md         |   70 +
 .../references/comp-screaming-architecture.md |   77 +
 .../references/comp-stable-dependencies.md    |   69 +
 .../references/dep-acyclic-dependencies.md    |   84 +
 .../dep-data-crossing-boundaries.md           |   61 +
 .../references/dep-interface-ownership.md     |   60 +
 .../references/dep-inward-only.md             |   69 +
 .../references/dep-no-framework-imports.md    |   69 +
 .../references/dep-stable-abstractions.md     |   76 +
 .../entity-encapsulate-invariants.md          |   83 +
 .../entity-no-persistence-awareness.md        |   90 +
 .../references/entity-pure-business-rules.md  |   68 +
 .../references/entity-rich-not-anemic.md      |  106 +
 .../references/entity-value-objects.md        |  100 +
 .../references/frame-di-container-edge.md     |  116 +
 .../references/frame-domain-purity.md         |  121 +
 .../references/frame-logging-abstraction.md   |  127 +
 .../references/frame-orm-in-infrastructure.md |  103 +
 .../references/frame-web-in-infrastructure.md |  132 +
 .../references/test-boundary-verification.md  |  106 +
 .../references/test-layer-isolation.md        |  121 +
 .../references/test-testable-design.md        |  104 +
 .../references/test-tests-are-architecture.md |  106 +
 .../usecase-explicit-dependencies.md          |  104 +
 .../references/usecase-input-output-ports.md  |   98 +
 .../usecase-no-presentation-logic.md          |  101 +
 .../usecase-orchestrates-not-implements.md    |  102 +
 .../usecase-single-responsibility.md          |   96 +
 .../usecase-transaction-boundary.md           |   80 +
 .../software-engineer/clean-code/SKILL.md     |  128 +
 .../clean-code/assets/templates/_template.md  |   30 +
 .../clean-code/references/_sections.md        |   56 +
 .../references/bound-learning-tests.md        |   59 +
 .../references/bound-wrap-third-party.md      |   77 +
 .../clean-code/references/class-cohesion.md   |   66 +
 .../references/class-isolate-from-change.md   |   76 +
 .../references/class-organize-for-change.md   |   70 +
 .../references/class-separate-concerns.md     |   74 +
 .../clean-code/references/class-small.md      |   63 +
 .../cmt-avoid-commented-out-code.md           |   48 +
 .../references/cmt-avoid-redundant.md         |   68 +
 .../references/cmt-explain-intent.md          |   54 +
 .../references/cmt-express-in-code.md         |   58 +
 .../references/cmt-warning-consequences.md    |   66 +
 .../references/emerge-expressiveness.md       |   52 +
 .../references/emerge-simple-design.md        |   59 +
 .../clean-code/references/err-avoid-null.md   |   78 +
 .../references/err-define-by-caller-needs.md  |   67 +
 .../references/err-provide-context.md         |   53 +
 .../references/err-use-exceptions.md          |   88 +
 .../references/err-write-try-catch-first.md   |   53 +
 .../references/fmt-horizontal-alignment.md    |   59 +
 .../clean-code/references/fmt-indentation.md  |   60 +
 .../clean-code/references/fmt-team-rules.md   |   67 +
 .../references/fmt-vertical-formatting.md     |   72 +
 .../references/func-abstraction-level.md      |   68 +
 .../func-command-query-separation.md          |   57 +
 .../clean-code/references/func-dry.md         |   70 +
 .../references/func-minimize-arguments.md     |   56 +
 .../references/func-no-side-effects.md        |   67 +
 .../clean-code/references/func-one-thing.md   |   77 +
 .../clean-code/references/func-small.md       |   71 +
 .../references/name-avoid-disinformation.md   |   44 +
 .../references/name-avoid-encodings.md        |   66 +
 .../clean-code/references/name-class-noun.md  |   54 +
 .../references/name-intention-revealing.md    |   47 +
 .../name-meaningful-distinctions.md           |   54 +
 .../clean-code/references/name-method-verb.md |   55 +
 .../references/name-pronounceable.md          |   38 +
 .../clean-code/references/name-searchable.md  |   39 +
 .../references/obj-avoid-hybrids.md           |   69 +
 .../references/obj-data-abstraction.md        |   51 +
 .../references/obj-data-object-asymmetry.md   |   72 +
 .../clean-code/references/obj-dto.md          |   63 +
 .../references/obj-law-of-demeter.md          |   45 +
 .../references/test-build-operate-check.md    |   78 +
 .../clean-code/references/test-first-law.md   |   68 +
 .../references/test-first-principles.md       |   80 +
 .../clean-code/references/test-keep-clean.md  |   75 +
 .../clean-code/references/test-one-assert.md  |   65 +
 .../software-engineer/clean-comments/SKILL.md |   52 +
 .../clean-functions/SKILL.md                  |   66 +
 .../software-engineer/clean-general/SKILL.md  |   97 +
 .../software-engineer/clean-names/SKILL.md    |  136 +
 .../software-engineer/clean-tests/SKILL.md    |  196 +
 .../coding-guidelines/SKILL.md                |   95 +
 .../coding-guidelines/clippy-lints/_index.md  |   16 +
 .../coding-guidelines/index/rules-index.md    |    6 +
 .../ddia-principles/SKILL.md                  |  421 ++
 .../devops-engineer/SKILL.md                  |  144 +
 .../references/deployment-strategies.md       |  241 +
 .../references/docker-patterns.md             |  113 +
 .../references/github-actions.md              |  139 +
 .../references/incident-response.md           |  331 ++
 .../devops-engineer/references/kubernetes.md  |  154 +
 .../references/platform-engineering.md        |  417 ++
 .../references/release-automation.md          |  527 +++
 .../references/terraform-iac.md               |  141 +
 .../e2e-testing-patterns/SKILL.md             |  535 +++
 .../mobile-development/SKILL.md               |  261 ++
 .../references/MOBILE_GUIDE.md                |   73 +
 .../openapi-spec-generation/SKILL.md          | 1017 +++++
 .../optimize-cicd-pipeline/SKILL.md           |   36 +
 .../senior-architect/SKILL.md                 |  343 ++
 .../references/architecture_patterns.md       |  470 ++
 .../references/system_design_workflows.md     |  536 +++
 .../references/tech_decision_guide.md         |  412 ++
 src/main/index.ts                             |    1 +
 src/main/ipc-support.ts                       |   13 +-
 src/main/message-dispatch.ts                  |    7 +
 src/main/orchestration/heartbeat.ts           |    7 +
 src/main/suppress-warnings.ts                 |   43 +-
 287 files changed, 59858 insertions(+), 10 deletions(-)
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/SKILL.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/3d.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/animations.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/assets.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/audio-visualization.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/audio.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/calculate-metadata.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/can-decode.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/charts.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/compositions.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/display-captions.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/extract-frames.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/ffmpeg.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/fonts.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/get-audio-duration.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/get-video-dimensions.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/get-video-duration.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/gifs.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/images.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/import-srt-captions.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/light-leaks.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/lottie.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/maps.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/measuring-dom-nodes.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/measuring-text.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/parameters.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/sequencing.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/sfx.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/subtitles.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/tailwind.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/text-animations.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/timing.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/transcribe-captions.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/transitions.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/transparent-videos.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/trimming.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/videos.md
 create mode 100644 builtin-skills/Video-maker/remotion-best-practices/rules/voiceover.md
 create mode 100644 builtin-skills/basic-for-all/deep-research/SKILL.md
 delete mode 160000 builtin-skills/basic-for-all/my-writing-style
 create mode 100644 builtin-skills/basic-for-all/my-writing-style/README.md
 create mode 100644 builtin-skills/basic-for-all/my-writing-style/SKILL.md
 create mode 100644 builtin-skills/basic-for-all/my-writing-style/scripts/improve.py
 create mode 100644 builtin-skills/basic-for-all/my-writing-style/scripts/observe.py
 create mode 100644 builtin-skills/basic-for-all/nopua/SKILL.md
 create mode 100644 builtin-skills/basic-for-all/systematic-debugging/CREATION-LOG.md
 create mode 100644 builtin-skills/basic-for-all/systematic-debugging/SKILL.md
 create mode 100644 builtin-skills/basic-for-all/systematic-debugging/condition-based-waiting.md
 create mode 100644 builtin-skills/basic-for-all/systematic-debugging/defense-in-depth.md
 create mode 100644 builtin-skills/basic-for-all/systematic-debugging/root-cause-tracing.md
 create mode 100644 builtin-skills/basic-for-all/systematic-debugging/test-academic.md
 create mode 100644 builtin-skills/basic-for-all/systematic-debugging/test-pressure-1.md
 create mode 100644 builtin-skills/basic-for-all/systematic-debugging/test-pressure-2.md
 create mode 100644 builtin-skills/basic-for-all/systematic-debugging/test-pressure-3.md
 create mode 100644 builtin-skills/document-process/docx/SKILL.md
 create mode 100644 builtin-skills/document-process/minimax-docx/SKILL.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/cjk_typography.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/cjk_university_template_guide.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/comments_guide.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/design_good_bad_examples.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/design_principles.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/openxml_element_order.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/openxml_encyclopedia_part1.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/openxml_encyclopedia_part2.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/openxml_encyclopedia_part3.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/openxml_namespaces.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/openxml_units.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/scenario_a_create.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/scenario_b_edit_content.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/scenario_c_apply_template.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/track_changes_guide.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/troubleshooting.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/typography_guide.md
 create mode 100644 builtin-skills/document-process/minimax-docx/references/xsd_validation_guide.md
 create mode 100644 builtin-skills/document-process/minimax-pdf/README.md
 create mode 100644 builtin-skills/document-process/minimax-pdf/SKILL.md
 create mode 100644 builtin-skills/document-process/minimax-pdf/design/design.md
 create mode 100644 builtin-skills/document-process/minimax-xlsx/SKILL.md
 create mode 100644 builtin-skills/document-process/minimax-xlsx/references/create.md
 create mode 100644 builtin-skills/document-process/minimax-xlsx/references/edit.md
 create mode 100644 builtin-skills/document-process/minimax-xlsx/references/fix.md
 create mode 100644 builtin-skills/document-process/minimax-xlsx/references/format.md
 create mode 100644 builtin-skills/document-process/minimax-xlsx/references/ooxml-cheatsheet.md
 create mode 100644 builtin-skills/document-process/minimax-xlsx/references/read-analyze.md
 create mode 100644 builtin-skills/document-process/minimax-xlsx/references/validate.md
 delete mode 160000 builtin-skills/document-process/my-writing-style
 create mode 100644 builtin-skills/document-process/my-writing-style/README.md
 create mode 100644 builtin-skills/document-process/my-writing-style/SKILL.md
 create mode 100644 builtin-skills/document-process/my-writing-style/scripts/improve.py
 create mode 100644 builtin-skills/document-process/my-writing-style/scripts/observe.py
 create mode 100644 builtin-skills/document-process/pptx-generator/SKILL.md
 create mode 100644 builtin-skills/document-process/pptx-generator/references/design-system.md
 create mode 100644 builtin-skills/document-process/pptx-generator/references/editing.md
 create mode 100644 builtin-skills/document-process/pptx-generator/references/pitfalls.md
 create mode 100644 builtin-skills/document-process/pptx-generator/references/pptxgenjs.md
 create mode 100644 builtin-skills/document-process/pptx-generator/references/slide-types.md
 create mode 100644 builtin-skills/document-process/wechat-article-writer/SKILL.md
 create mode 100644 builtin-skills/document-process/writing-clearly-and-concisely/README.md
 create mode 100644 builtin-skills/document-process/writing-clearly-and-concisely/SKILL.md
 create mode 100644 builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/01-introductory.md
 create mode 100644 builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/02-elementary-rules-of-usage.md
 create mode 100644 builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/03-elementary-principles-of-composition.md
 create mode 100644 builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/04-a-few-matters-of-form.md
 create mode 100644 builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/05-words-and-expressions-commonly-misused.md
 create mode 100644 builtin-skills/document-process/writing-clearly-and-concisely/signs-of-ai-writing.md
 create mode 100644 builtin-skills/document-process/xlsx/SKILL.md
 create mode 100644 builtin-skills/frontend-design/canvas-design/SKILL.md
 create mode 100644 builtin-skills/frontend-design/design-dna/README.md
 create mode 100644 builtin-skills/frontend-design/design-dna/README.zh-CN.md
 create mode 100644 builtin-skills/frontend-design/design-dna/SKILL.md
 create mode 100644 builtin-skills/frontend-design/design-dna/references/generation-guide.md
 create mode 100644 builtin-skills/frontend-design/design-dna/references/schema.md
 create mode 100644 builtin-skills/frontend-design/design-taste-frontend/SKILL.md
 create mode 100644 builtin-skills/frontend-design/frontend-design/SKILL.md
 create mode 100644 builtin-skills/frontend-design/high-end-visual-design/SKILL.md
 create mode 100644 builtin-skills/frontend-design/senior-frontend/SKILL.md
 create mode 100644 builtin-skills/frontend-design/senior-frontend/references/frontend_best_practices.md
 create mode 100644 builtin-skills/frontend-design/senior-frontend/references/nextjs_optimization_guide.md
 create mode 100644 builtin-skills/frontend-design/senior-frontend/references/react_patterns.md
 create mode 100644 builtin-skills/frontend-design/stitch-design-taste/DESIGN.md
 create mode 100644 builtin-skills/frontend-design/stitch-design-taste/SKILL.md
 create mode 100644 builtin-skills/iOS-Dev/app-icon-generator/SKILL.md
 create mode 100644 builtin-skills/iOS-Dev/app-store-screenshots/SKILL.md
 create mode 100644 builtin-skills/iOS-Dev/icon-generator/SKILL.md
 create mode 100644 builtin-skills/iOS-Dev/icon-generator/references/icon-sizes.md
 create mode 100644 builtin-skills/iOS-Dev/icon-generator/references/unreal-engine.md
 create mode 100644 builtin-skills/iOS-Dev/icon-generator/references/web-ui-ux.md
 create mode 100644 builtin-skills/iOS-Dev/ios-swift-development/SKILL.md
 create mode 100644 builtin-skills/iOS-Dev/ios-swift-development/references/mvvm-architecture-setup.md
 create mode 100644 builtin-skills/iOS-Dev/ios-swift-development/references/network-service-with-urlsession.md
 create mode 100644 builtin-skills/iOS-Dev/ios-swift-development/references/swiftui-views.md
 create mode 100644 builtin-skills/iOS-Dev/mobile-development/SKILL.md
 create mode 100644 builtin-skills/iOS-Dev/mobile-development/references/MOBILE_GUIDE.md
 create mode 100644 builtin-skills/marketing/clean-general/SKILL.md
 delete mode 160000 builtin-skills/marketing/my-writing-style
 create mode 100644 builtin-skills/marketing/my-writing-style/README.md
 create mode 100644 builtin-skills/marketing/my-writing-style/SKILL.md
 create mode 100644 builtin-skills/marketing/my-writing-style/scripts/improve.py
 create mode 100644 builtin-skills/marketing/my-writing-style/scripts/observe.py
 create mode 100644 builtin-skills/marketing/wechat-article-writer/SKILL.md
 create mode 100644 builtin-skills/marketing/writing-clearly-and-concisely/README.md
 create mode 100644 builtin-skills/marketing/writing-clearly-and-concisely/SKILL.md
 create mode 100644 builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/01-introductory.md
 create mode 100644 builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/02-elementary-rules-of-usage.md
 create mode 100644 builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/03-elementary-principles-of-composition.md
 create mode 100644 builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/04-a-few-matters-of-form.md
 create mode 100644 builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/05-words-and-expressions-commonly-misused.md
 create mode 100644 builtin-skills/marketing/writing-clearly-and-concisely/signs-of-ai-writing.md
 delete mode 160000 builtin-skills/my-writing-style
 create mode 100644 builtin-skills/my-writing-style/README.md
 create mode 100644 builtin-skills/my-writing-style/SKILL.md
 create mode 100644 builtin-skills/my-writing-style/scripts/improve.py
 create mode 100644 builtin-skills/my-writing-style/scripts/observe.py
 create mode 100644 builtin-skills/software-engineer/ai-coding-discipline/SKILL.md
 create mode 100644 builtin-skills/software-engineer/api-design-principles/SKILL.md
 create mode 100644 builtin-skills/software-engineer/api-design-principles/assets/api-design-checklist.md
 create mode 100644 builtin-skills/software-engineer/api-design-principles/references/graphql-schema-design.md
 create mode 100644 builtin-skills/software-engineer/api-design-principles/references/rest-best-practices.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/SKILL.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/assets/templates/_template.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/_sections.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/adapt-anti-corruption-layer.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/adapt-controller-thin.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/adapt-gateway-abstraction.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/adapt-mapper-translation.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/adapt-presenter-formats.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/bound-boundary-cost-awareness.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/bound-defer-decisions.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/bound-humble-object.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/bound-main-component.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/bound-partial-boundaries.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/bound-service-internal-architecture.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/comp-common-closure.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/comp-common-reuse.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/comp-reuse-release-equivalence.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/comp-screaming-architecture.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/comp-stable-dependencies.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/dep-acyclic-dependencies.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/dep-data-crossing-boundaries.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/dep-interface-ownership.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/dep-inward-only.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/dep-no-framework-imports.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/dep-stable-abstractions.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/entity-encapsulate-invariants.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/entity-no-persistence-awareness.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/entity-pure-business-rules.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/entity-rich-not-anemic.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/entity-value-objects.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/frame-di-container-edge.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/frame-domain-purity.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/frame-logging-abstraction.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/frame-orm-in-infrastructure.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/frame-web-in-infrastructure.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/test-boundary-verification.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/test-layer-isolation.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/test-testable-design.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/test-tests-are-architecture.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/usecase-explicit-dependencies.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/usecase-input-output-ports.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/usecase-no-presentation-logic.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/usecase-orchestrates-not-implements.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/usecase-single-responsibility.md
 create mode 100644 builtin-skills/software-engineer/clean-architecture/references/usecase-transaction-boundary.md
 create mode 100644 builtin-skills/software-engineer/clean-code/SKILL.md
 create mode 100644 builtin-skills/software-engineer/clean-code/assets/templates/_template.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/_sections.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/bound-learning-tests.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/bound-wrap-third-party.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/class-cohesion.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/class-isolate-from-change.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/class-organize-for-change.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/class-separate-concerns.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/class-small.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/cmt-avoid-commented-out-code.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/cmt-avoid-redundant.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/cmt-explain-intent.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/cmt-express-in-code.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/cmt-warning-consequences.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/emerge-expressiveness.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/emerge-simple-design.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/err-avoid-null.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/err-define-by-caller-needs.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/err-provide-context.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/err-use-exceptions.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/err-write-try-catch-first.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/fmt-horizontal-alignment.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/fmt-indentation.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/fmt-team-rules.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/fmt-vertical-formatting.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/func-abstraction-level.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/func-command-query-separation.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/func-dry.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/func-minimize-arguments.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/func-no-side-effects.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/func-one-thing.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/func-small.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/name-avoid-disinformation.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/name-avoid-encodings.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/name-class-noun.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/name-intention-revealing.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/name-meaningful-distinctions.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/name-method-verb.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/name-pronounceable.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/name-searchable.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/obj-avoid-hybrids.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/obj-data-abstraction.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/obj-data-object-asymmetry.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/obj-dto.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/obj-law-of-demeter.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/test-build-operate-check.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/test-first-law.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/test-first-principles.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/test-keep-clean.md
 create mode 100644 builtin-skills/software-engineer/clean-code/references/test-one-assert.md
 create mode 100644 builtin-skills/software-engineer/clean-comments/SKILL.md
 create mode 100644 builtin-skills/software-engineer/clean-functions/SKILL.md
 create mode 100644 builtin-skills/software-engineer/clean-general/SKILL.md
 create mode 100644 builtin-skills/software-engineer/clean-names/SKILL.md
 create mode 100644 builtin-skills/software-engineer/clean-tests/SKILL.md
 create mode 100644 builtin-skills/software-engineer/coding-guidelines/SKILL.md
 create mode 100644 builtin-skills/software-engineer/coding-guidelines/clippy-lints/_index.md
 create mode 100644 builtin-skills/software-engineer/coding-guidelines/index/rules-index.md
 create mode 100644 builtin-skills/software-engineer/ddia-principles/SKILL.md
 create mode 100644 builtin-skills/software-engineer/devops-engineer/SKILL.md
 create mode 100644 builtin-skills/software-engineer/devops-engineer/references/deployment-strategies.md
 create mode 100644 builtin-skills/software-engineer/devops-engineer/references/docker-patterns.md
 create mode 100644 builtin-skills/software-engineer/devops-engineer/references/github-actions.md
 create mode 100644 builtin-skills/software-engineer/devops-engineer/references/incident-response.md
 create mode 100644 builtin-skills/software-engineer/devops-engineer/references/kubernetes.md
 create mode 100644 builtin-skills/software-engineer/devops-engineer/references/platform-engineering.md
 create mode 100644 builtin-skills/software-engineer/devops-engineer/references/release-automation.md
 create mode 100644 builtin-skills/software-engineer/devops-engineer/references/terraform-iac.md
 create mode 100644 builtin-skills/software-engineer/e2e-testing-patterns/SKILL.md
 create mode 100644 builtin-skills/software-engineer/mobile-development/SKILL.md
 create mode 100644 builtin-skills/software-engineer/mobile-development/references/MOBILE_GUIDE.md
 create mode 100644 builtin-skills/software-engineer/openapi-spec-generation/SKILL.md
 create mode 100644 builtin-skills/software-engineer/optimize-cicd-pipeline/SKILL.md
 create mode 100644 builtin-skills/software-engineer/senior-architect/SKILL.md
 create mode 100644 builtin-skills/software-engineer/senior-architect/references/architecture_patterns.md
 create mode 100644 builtin-skills/software-engineer/senior-architect/references/system_design_workflows.md
 create mode 100644 builtin-skills/software-engineer/senior-architect/references/tech_decision_guide.md

diff --git a/.gitignore b/.gitignore
index 8f35c826..cb1621da 100644
--- a/.gitignore
+++ b/.gitignore
@@ -57,6 +57,11 @@ oldreference/
 !/CLAUDE.md
 !/.planning/**/*.md
 !/src/main/prompt-builder/**/*.md
+# Bundled Agent Skills ship their SKILL.md / README.md as source of truth.
+# The Pi skills loader rejects entries whose frontmatter `name` diverges from
+# the parent directory; losing SKILL.md to the blanket *.md ignore meant a
+# fresh checkout silently dropped every skill from the catalogue.
+!/builtin-skills/**/*.md
 *.zip
 *.blockmap
 *.exe
diff --git a/builtin-skills/Video-maker/remotion-best-practices/SKILL.md b/builtin-skills/Video-maker/remotion-best-practices/SKILL.md
new file mode 100644
index 00000000..7ddaa0fd
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: remotion-best-practices
+description: Best practices for Remotion - Video creation in React
+metadata:
+  tags: remotion, video, react, animation, composition
+---
+
+## When to use
+
+Use this skills whenever you are dealing with Remotion code to obtain the domain-specific knowledge.
+
+## Captions
+
+When dealing with captions or subtitles, load the [./rules/subtitles.md](./rules/subtitles.md) file for more information.
+
+## Using FFmpeg
+
+For some video operations, such as trimming videos or detecting silence, FFmpeg should be used. Load the [./rules/ffmpeg.md](./rules/ffmpeg.md) file for more information.
+
+## Audio visualization
+
+When needing to visualize audio (spectrum bars, waveforms, bass-reactive effects), load the [./rules/audio-visualization.md](./rules/audio-visualization.md) file for more information.
+
+## Sound effects
+
+When needing to use sound effects, load the [./rules/sound-effects.md](./rules/sound-effects.md) file for more information.
+
+## How to use
+
+Read individual rule files for detailed explanations and code examples:
+
+- [rules/3d.md](rules/3d.md) - 3D content in Remotion using Three.js and React Three Fiber
+- [rules/animations.md](rules/animations.md) - Fundamental animation skills for Remotion
+- [rules/assets.md](rules/assets.md) - Importing images, videos, audio, and fonts into Remotion
+- [rules/audio.md](rules/audio.md) - Using audio and sound in Remotion - importing, trimming, volume, speed, pitch
+- [rules/calculate-metadata.md](rules/calculate-metadata.md) - Dynamically set composition duration, dimensions, and props
+- [rules/can-decode.md](rules/can-decode.md) - Check if a video can be decoded by the browser using Mediabunny
+- [rules/charts.md](rules/charts.md) - Chart and data visualization patterns for Remotion (bar, pie, line, stock charts)
+- [rules/compositions.md](rules/compositions.md) - Defining compositions, stills, folders, default props and dynamic metadata
+- [rules/extract-frames.md](rules/extract-frames.md) - Extract frames from videos at specific timestamps using Mediabunny
+- [rules/fonts.md](rules/fonts.md) - Loading Google Fonts and local fonts in Remotion
+- [rules/get-audio-duration.md](rules/get-audio-duration.md) - Getting the duration of an audio file in seconds with Mediabunny
+- [rules/get-video-dimensions.md](rules/get-video-dimensions.md) - Getting the width and height of a video file with Mediabunny
+- [rules/get-video-duration.md](rules/get-video-duration.md) - Getting the duration of a video file in seconds with Mediabunny
+- [rules/gifs.md](rules/gifs.md) - Displaying GIFs synchronized with Remotion's timeline
+- [rules/images.md](rules/images.md) - Embedding images in Remotion using the Img component
+- [rules/light-leaks.md](rules/light-leaks.md) - Light leak overlay effects using @remotion/light-leaks
+- [rules/lottie.md](rules/lottie.md) - Embedding Lottie animations in Remotion
+- [rules/measuring-dom-nodes.md](rules/measuring-dom-nodes.md) - Measuring DOM element dimensions in Remotion
+- [rules/measuring-text.md](rules/measuring-text.md) - Measuring text dimensions, fitting text to containers, and checking overflow
+- [rules/sequencing.md](rules/sequencing.md) - Sequencing patterns for Remotion - delay, trim, limit duration of items
+- [rules/tailwind.md](rules/tailwind.md) - Using TailwindCSS in Remotion
+- [rules/text-animations.md](rules/text-animations.md) - Typography and text animation patterns for Remotion
+- [rules/timing.md](rules/timing.md) - Interpolation curves in Remotion - linear, easing, spring animations
+- [rules/transitions.md](rules/transitions.md) - Scene transition patterns for Remotion
+- [rules/transparent-videos.md](rules/transparent-videos.md) - Rendering out a video with transparency
+- [rules/trimming.md](rules/trimming.md) - Trimming patterns for Remotion - cut the beginning or end of animations
+- [rules/videos.md](rules/videos.md) - Embedding videos in Remotion - trimming, volume, speed, looping, pitch
+- [rules/parameters.md](rules/parameters.md) - Make a video parametrizable by adding a Zod schema
+- [rules/maps.md](rules/maps.md) - Add a map using Mapbox and animate it
+- [rules/voiceover.md](rules/voiceover.md) - Adding AI-generated voiceover to Remotion compositions using ElevenLabs TTS
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/3d.md b/builtin-skills/Video-maker/remotion-best-practices/rules/3d.md
new file mode 100644
index 00000000..c9d254f1
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/3d.md
@@ -0,0 +1,86 @@
+---
+name: 3d
+description: 3D content in Remotion using Three.js and React Three Fiber.
+metadata:
+  tags: 3d, three, threejs
+---
+
+# Using Three.js and React Three Fiber in Remotion
+
+Follow React Three Fiber and Three.js best practices.  
+Only the following Remotion-specific rules need to be followed:
+
+## Prerequisites
+
+First, the `@remotion/three` package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/three # If project uses npm
+bunx remotion add @remotion/three # If project uses bun
+yarn remotion add @remotion/three # If project uses yarn
+pnpm exec remotion add @remotion/three # If project uses pnpm
+```
+
+## Using ThreeCanvas
+
+You MUST wrap 3D content in `<ThreeCanvas>` and include proper lighting.  
+`<ThreeCanvas>` MUST have a `width` and `height` prop.
+
+```tsx
+import { ThreeCanvas } from "@remotion/three";
+import { useVideoConfig } from "remotion";
+
+const { width, height } = useVideoConfig();
+
+<ThreeCanvas width={width} height={height}>
+  <ambientLight intensity={0.4} />
+  <directionalLight position={[5, 5, 5]} intensity={0.8} />
+  <mesh>
+    <sphereGeometry args={[1, 32, 32]} />
+    <meshStandardMaterial color="red" />
+  </mesh>
+</ThreeCanvas>;
+```
+
+## No animations not driven by `useCurrentFrame()`
+
+Shaders, models etc MUST NOT animate by themselves.  
+No animations are allowed unless they are driven by `useCurrentFrame()`.  
+Otherwise, it will cause flickering during rendering.
+
+Using `useFrame()` from `@react-three/fiber` is forbidden.
+
+## Animate using `useCurrentFrame()`
+
+Use `useCurrentFrame()` to perform animations.
+
+```tsx
+const frame = useCurrentFrame();
+const rotationY = frame * 0.02;
+
+<mesh rotation={[0, rotationY, 0]}>
+  <boxGeometry args={[2, 2, 2]} />
+  <meshStandardMaterial color="#4a9eff" />
+</mesh>;
+```
+
+## Using `<Sequence>` inside `<ThreeCanvas>`
+
+The `layout` prop of any `<Sequence>` inside a `<ThreeCanvas>` must be set to `none`.
+
+```tsx
+import { Sequence } from "remotion";
+import { ThreeCanvas } from "@remotion/three";
+
+const { width, height } = useVideoConfig();
+
+<ThreeCanvas width={width} height={height}>
+  <Sequence layout="none">
+    <mesh>
+      <boxGeometry args={[2, 2, 2]} />
+      <meshStandardMaterial color="#4a9eff" />
+    </mesh>
+  </Sequence>
+</ThreeCanvas>;
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/animations.md b/builtin-skills/Video-maker/remotion-best-practices/rules/animations.md
new file mode 100644
index 00000000..619591e8
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/animations.md
@@ -0,0 +1,27 @@
+---
+name: animations
+description: Fundamental animation skills for Remotion
+metadata:
+  tags: animations, transitions, frames, useCurrentFrame
+---
+
+All animations MUST be driven by the `useCurrentFrame()` hook.  
+Write animations in seconds and multiply them by the `fps` value from `useVideoConfig()`.
+
+```tsx
+import { useCurrentFrame } from "remotion";
+
+export const FadeIn = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const opacity = interpolate(frame, [0, 2 * fps], [0, 1], {
+    extrapolateRight: "clamp",
+  });
+
+  return <div style={{ opacity }}>Hello World!</div>;
+};
+```
+
+CSS transitions or animations are FORBIDDEN - they will not render correctly.  
+Tailwind animation class names are FORBIDDEN - they will not render correctly.
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/assets.md b/builtin-skills/Video-maker/remotion-best-practices/rules/assets.md
new file mode 100644
index 00000000..a5d40152
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/assets.md
@@ -0,0 +1,78 @@
+---
+name: assets
+description: Importing images, videos, audio, and fonts into Remotion
+metadata:
+  tags: assets, staticFile, images, fonts, public
+---
+
+# Importing assets in Remotion
+
+## The public folder
+
+Place assets in the `public/` folder at your project root.
+
+## Using staticFile()
+
+You MUST use `staticFile()` to reference files from the `public/` folder:
+
+```tsx
+import { Img, staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Img src={staticFile("logo.png")} />;
+};
+```
+
+The function returns an encoded URL that works correctly when deploying to subdirectories.
+
+## Using with components
+
+**Images:**
+
+```tsx
+import { Img, staticFile } from "remotion";
+
+<Img src={staticFile("photo.png")} />;
+```
+
+**Videos:**
+
+```tsx
+import { Video } from "@remotion/media";
+import { staticFile } from "remotion";
+
+<Video src={staticFile("clip.mp4")} />;
+```
+
+**Audio:**
+
+```tsx
+import { Audio } from "@remotion/media";
+import { staticFile } from "remotion";
+
+<Audio src={staticFile("music.mp3")} />;
+```
+
+**Fonts:**
+
+```tsx
+import { staticFile } from "remotion";
+
+const fontFamily = new FontFace("MyFont", `url(${staticFile("font.woff2")})`);
+await fontFamily.load();
+document.fonts.add(fontFamily);
+```
+
+## Remote URLs
+
+Remote URLs can be used directly without `staticFile()`:
+
+```tsx
+<Img src="https://example.com/image.png" />
+<Video src="https://remotion.media/video.mp4" />
+```
+
+## Important notes
+
+- Remotion components (`<Img>`, `<Video>`, `<Audio>`) ensure assets are fully loaded before rendering
+- Special characters in filenames (`#`, `?`, `&`) are automatically encoded
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/audio-visualization.md b/builtin-skills/Video-maker/remotion-best-practices/rules/audio-visualization.md
new file mode 100644
index 00000000..733b0d35
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/audio-visualization.md
@@ -0,0 +1,198 @@
+---
+name: audio-visualization
+description: Audio visualization patterns - spectrum bars, waveforms, bass-reactive effects
+metadata:
+  tags: audio, visualization, spectrum, waveform, bass, music, audiogram, frequency
+---
+
+# Audio Visualization in Remotion
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/media-utils
+```
+
+## Loading Audio Data
+
+Use `useWindowedAudioData()` (https://www.remotion.dev/docs/use-windowed-audio-data) to load audio data:
+
+```tsx
+import { useWindowedAudioData } from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+  src: staticFile("podcast.wav"),
+  frame,
+  fps,
+  windowInSeconds: 30,
+});
+```
+
+## Spectrum Bar Visualization
+
+Use `visualizeAudio()` (https://www.remotion.dev/docs/visualize-audio) to get frequency data for bar charts:
+
+```tsx
+import { useWindowedAudioData, visualizeAudio } from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+  src: staticFile("music.mp3"),
+  frame,
+  fps,
+  windowInSeconds: 30,
+});
+
+if (!audioData) {
+  return null;
+}
+
+const frequencies = visualizeAudio({
+  fps,
+  frame,
+  audioData,
+  numberOfSamples: 256,
+  optimizeFor: "speed",
+  dataOffsetInSeconds,
+});
+
+return (
+  <div style={{ display: "flex", alignItems: "flex-end", height: 200 }}>
+    {frequencies.map((v, i) => (
+      <div
+        key={i}
+        style={{
+          flex: 1,
+          height: `${v * 100}%`,
+          backgroundColor: "#0b84f3",
+          margin: "0 1px",
+        }}
+      />
+    ))}
+  </div>
+);
+```
+
+- `numberOfSamples` must be power of 2 (32, 64, 128, 256, 512, 1024)
+- Values range 0-1; left of array = bass, right = highs
+- Use `optimizeFor: "speed"` for Lambda or high sample counts
+
+**Important:** When passing `audioData` to child components, also pass the `frame` from the parent. Do not call `useCurrentFrame()` in each child - this causes discontinuous visualization when children are inside `<Sequence>` with offsets.
+
+## Waveform Visualization
+
+Use `visualizeAudioWaveform()` (https://www.remotion.dev/docs/media-utils/visualize-audio-waveform) with `createSmoothSvgPath()` (https://www.remotion.dev/docs/media-utils/create-smooth-svg-path) for oscilloscope-style displays:
+
+```tsx
+import {
+  createSmoothSvgPath,
+  useWindowedAudioData,
+  visualizeAudioWaveform,
+} from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { width, fps } = useVideoConfig();
+const HEIGHT = 200;
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+  src: staticFile("voice.wav"),
+  frame,
+  fps,
+  windowInSeconds: 30,
+});
+
+if (!audioData) {
+  return null;
+}
+
+const waveform = visualizeAudioWaveform({
+  fps,
+  frame,
+  audioData,
+  numberOfSamples: 256,
+  windowInSeconds: 0.5,
+  dataOffsetInSeconds,
+});
+
+const path = createSmoothSvgPath({
+  points: waveform.map((y, i) => ({
+    x: (i / (waveform.length - 1)) * width,
+    y: HEIGHT / 2 + (y * HEIGHT) / 2,
+  })),
+});
+
+return (
+  <svg width={width} height={HEIGHT}>
+    <path d={path} fill="none" stroke="#0b84f3" strokeWidth={2} />
+  </svg>
+);
+```
+
+## Bass-Reactive Effects
+
+Extract low frequencies for beat-reactive animations:
+
+```tsx
+const frequencies = visualizeAudio({
+  fps,
+  frame,
+  audioData,
+  numberOfSamples: 128,
+  optimizeFor: "speed",
+  dataOffsetInSeconds,
+});
+
+const lowFrequencies = frequencies.slice(0, 32);
+const bassIntensity =
+  lowFrequencies.reduce((sum, v) => sum + v, 0) / lowFrequencies.length;
+
+const scale = 1 + bassIntensity * 0.5;
+const opacity = Math.min(0.6, bassIntensity * 0.8);
+```
+
+## Volume-Based Waveform
+
+Use `getWaveformPortion()` (https://www.remotion.dev/docs/get-waveform-portion) when you need simplified volume data instead of frequency spectrum:
+
+```tsx
+import { getWaveformPortion } from "@remotion/media-utils";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+const currentTimeInSeconds = frame / fps;
+
+const waveform = getWaveformPortion({
+  audioData,
+  startTimeInSeconds: currentTimeInSeconds,
+  durationInSeconds: 5,
+  numberOfSamples: 50,
+});
+
+// Returns array of { index, amplitude } objects (amplitude: 0-1)
+waveform.map((bar) => (
+  <div key={bar.index} style={{ height: bar.amplitude * 100 }} />
+));
+```
+
+## Postprocessing
+
+Low frequencies naturally dominate. Apply logarithmic scaling for visual balance:
+
+```tsx
+const minDb = -100;
+const maxDb = -30;
+
+const scaled = frequencies.map((value) => {
+  const db = 20 * Math.log10(value);
+  return (db - minDb) / (maxDb - minDb);
+});
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/audio.md b/builtin-skills/Video-maker/remotion-best-practices/rules/audio.md
new file mode 100644
index 00000000..1097c70e
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/audio.md
@@ -0,0 +1,169 @@
+---
+name: audio
+description: Using audio and sound in Remotion - importing, trimming, volume, speed, pitch
+metadata:
+  tags: audio, media, trim, volume, speed, loop, pitch, mute, sound, sfx
+---
+
+# Using audio in Remotion
+
+## Prerequisites
+
+First, the @remotion/media package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/media
+```
+
+## Importing Audio
+
+Use `<Audio>` from `@remotion/media` to add audio to your composition.
+
+```tsx
+import { Audio } from "@remotion/media";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Audio src={staticFile("audio.mp3")} />;
+};
+```
+
+Remote URLs are also supported:
+
+```tsx
+<Audio src="https://remotion.media/audio.mp3" />
+```
+
+By default, audio plays from the start, at full volume and full length.
+Multiple audio tracks can be layered by adding multiple `<Audio>` components.
+
+## Trimming
+
+Use `trimBefore` and `trimAfter` to remove portions of the audio. Values are in frames.
+
+```tsx
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    trimBefore={2 * fps} // Skip the first 2 seconds
+    trimAfter={10 * fps} // End at the 10 second mark
+  />
+);
+```
+
+The audio still starts playing at the beginning of the composition - only the specified portion is played.
+
+## Delaying
+
+Wrap the audio in a `<Sequence>` to delay when it starts:
+
+```tsx
+import { Sequence, staticFile } from "remotion";
+import { Audio } from "@remotion/media";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Sequence from={1 * fps}>
+    <Audio src={staticFile("audio.mp3")} />
+  </Sequence>
+);
+```
+
+The audio will start playing after 1 second.
+
+## Volume
+
+Set a static volume (0 to 1):
+
+```tsx
+<Audio src={staticFile("audio.mp3")} volume={0.5} />
+```
+
+Or use a callback for dynamic volume based on the current frame:
+
+```tsx
+import { interpolate } from "remotion";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    volume={(f) =>
+      interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
+    }
+  />
+);
+```
+
+The value of `f` starts at 0 when the audio begins to play, not the composition frame.
+
+## Muting
+
+Use `muted` to silence the audio. It can be set dynamically:
+
+```tsx
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    muted={frame >= 2 * fps && frame <= 4 * fps} // Mute between 2s and 4s
+  />
+);
+```
+
+## Speed
+
+Use `playbackRate` to change the playback speed:
+
+```tsx
+<Audio src={staticFile("audio.mp3")} playbackRate={2} /> {/* 2x speed */}
+<Audio src={staticFile("audio.mp3")} playbackRate={0.5} /> {/* Half speed */}
+```
+
+Reverse playback is not supported.
+
+## Looping
+
+Use `loop` to loop the audio indefinitely:
+
+```tsx
+<Audio src={staticFile("audio.mp3")} loop />
+```
+
+Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
+
+- `"repeat"`: Frame count resets to 0 each loop (default)
+- `"extend"`: Frame count continues incrementing
+
+```tsx
+<Audio
+  src={staticFile("audio.mp3")}
+  loop
+  loopVolumeCurveBehavior="extend"
+  volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
+/>
+```
+
+## Pitch
+
+Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
+
+```tsx
+<Audio
+  src={staticFile("audio.mp3")}
+  toneFrequency={1.5} // Higher pitch
+/>
+<Audio
+  src={staticFile("audio.mp3")}
+  toneFrequency={0.8} // Lower pitch
+/>
+```
+
+Pitch shifting only works during server-side rendering, not in the Remotion Studio preview or in the `<Player />`.
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/calculate-metadata.md b/builtin-skills/Video-maker/remotion-best-practices/rules/calculate-metadata.md
new file mode 100644
index 00000000..eef564fa
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/calculate-metadata.md
@@ -0,0 +1,134 @@
+---
+name: calculate-metadata
+description: Dynamically set composition duration, dimensions, and props
+metadata:
+  tags: calculateMetadata, duration, dimensions, props, dynamic
+---
+
+# Using calculateMetadata
+
+Use `calculateMetadata` on a `<Composition>` to dynamically set duration, dimensions, and transform props before rendering.
+
+```tsx
+<Composition
+  id="MyComp"
+  component={MyComponent}
+  durationInFrames={300}
+  fps={30}
+  width={1920}
+  height={1080}
+  defaultProps={{ videoSrc: "https://remotion.media/video.mp4" }}
+  calculateMetadata={calculateMetadata}
+/>
+```
+
+## Setting duration based on a video
+
+Use the [`getVideoDuration`](./get-video-duration.md) and [`getVideoDimensions`](./get-video-dimensions.md) skills to get the video duration and dimensions:
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+import { getVideoDuration } from "./get-video-duration";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const durationInSeconds = await getVideoDuration(props.videoSrc);
+
+  return {
+    durationInFrames: Math.ceil(durationInSeconds * 30),
+  };
+};
+```
+
+## Matching dimensions of a video
+
+Use the [`getVideoDimensions`](./get-video-dimensions.md) skill to get the video dimensions:
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+import { getVideoDuration } from "./get-video-duration";
+import { getVideoDimensions } from "./get-video-dimensions";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const dimensions = await getVideoDimensions(props.videoSrc);
+
+  return {
+    width: dimensions.width,
+    height: dimensions.height,
+  };
+};
+```
+
+## Setting duration based on multiple videos
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const metadataPromises = props.videos.map((video) =>
+    getVideoDuration(video.src),
+  );
+  const allMetadata = await Promise.all(metadataPromises);
+
+  const totalDuration = allMetadata.reduce(
+    (sum, durationInSeconds) => sum + durationInSeconds,
+    0,
+  );
+
+  return {
+    durationInFrames: Math.ceil(totalDuration * 30),
+  };
+};
+```
+
+## Setting a default outName
+
+Set the default output filename based on props:
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultOutName: `video-${props.id}.mp4`,
+  };
+};
+```
+
+## Transforming props
+
+Fetch data or transform props before rendering:
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+  abortSignal,
+}) => {
+  const response = await fetch(props.dataUrl, { signal: abortSignal });
+  const data = await response.json();
+
+  return {
+    props: {
+      ...props,
+      fetchedData: data,
+    },
+  };
+};
+```
+
+The `abortSignal` cancels stale requests when props change in the Studio.
+
+## Return value
+
+All fields are optional. Returned values override the `<Composition>` props:
+
+- `durationInFrames`: Number of frames
+- `width`: Composition width in pixels
+- `height`: Composition height in pixels
+- `fps`: Frames per second
+- `props`: Transformed props passed to the component
+- `defaultOutName`: Default output filename
+- `defaultCodec`: Default codec for rendering
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/can-decode.md b/builtin-skills/Video-maker/remotion-best-practices/rules/can-decode.md
new file mode 100644
index 00000000..7abc7f6c
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/can-decode.md
@@ -0,0 +1,81 @@
+---
+name: can-decode
+description: Check if a video can be decoded by the browser using Mediabunny
+metadata:
+  tags: decode, validation, video, audio, compatibility, browser
+---
+
+# Checking if a video can be decoded
+
+Use Mediabunny to check if a video can be decoded by the browser before attempting to play it.
+
+First, install the right version of Mediabunny:
+
+```bash
+npx remotion add mediabunny
+```
+
+## The `canDecode()` function
+
+This function can be copy-pasted into any project.
+
+```tsx
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const canDecode = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  try {
+    await input.getFormat();
+  } catch {
+    return false;
+  }
+
+  const videoTrack = await input.getPrimaryVideoTrack();
+  if (videoTrack && !(await videoTrack.canDecode())) {
+    return false;
+  }
+
+  const audioTrack = await input.getPrimaryAudioTrack();
+  if (audioTrack && !(await audioTrack.canDecode())) {
+    return false;
+  }
+
+  return true;
+};
+```
+
+## Usage
+
+```tsx
+const src = "https://remotion.media/video.mp4";
+const isDecodable = await canDecode(src);
+
+if (isDecodable) {
+  console.log("Video can be decoded");
+} else {
+  console.log("Video cannot be decoded by this browser");
+}
+```
+
+## Using with Blob
+
+For file uploads or drag-and-drop, use `BlobSource`:
+
+```tsx
+import { Input, ALL_FORMATS, BlobSource } from "mediabunny";
+
+export const canDecodeBlob = async (blob: Blob) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new BlobSource(blob),
+  });
+
+  // Same validation logic as above
+};
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/charts.md b/builtin-skills/Video-maker/remotion-best-practices/rules/charts.md
new file mode 100644
index 00000000..f0364858
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/charts.md
@@ -0,0 +1,120 @@
+---
+name: charts
+description: Chart and data visualization patterns for Remotion. Use when creating bar charts, pie charts, line charts, stock graphs, or any data-driven animations.
+metadata:
+  tags: charts, data, visualization, bar-chart, pie-chart, line-chart, stock-chart, svg-paths, graphs
+---
+
+# Charts in Remotion
+
+Create charts using React code - HTML, SVG, and D3.js are all supported.
+
+Disable all animations from third party libraries - they cause flickering.  
+Drive all animations from `useCurrentFrame()`.
+
+## Bar Chart
+
+```tsx
+const STAGGER_DELAY = 5;
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const bars = data.map((item, i) => {
+  const height = spring({
+    frame,
+    fps,
+    delay: i * STAGGER_DELAY,
+    config: { damping: 200 },
+  });
+  return <div style={{ height: height * item.value }} />;
+});
+```
+
+## Pie Chart
+
+Animate segments using stroke-dashoffset, starting from 12 o'clock:
+
+```tsx
+const progress = interpolate(frame, [0, 100], [0, 1]);
+const circumference = 2 * Math.PI * radius;
+const segmentLength = (value / total) * circumference;
+const offset = interpolate(progress, [0, 1], [segmentLength, 0]);
+
+<circle
+  r={radius}
+  cx={center}
+  cy={center}
+  fill="none"
+  stroke={color}
+  strokeWidth={strokeWidth}
+  strokeDasharray={`${segmentLength} ${circumference}`}
+  strokeDashoffset={offset}
+  transform={`rotate(-90 ${center} ${center})`}
+/>;
+```
+
+## Line Chart / Path Animation
+
+Use `@remotion/paths` for animating SVG paths (line charts, stock graphs, signatures).
+
+Install: `npx remotion add @remotion/paths`  
+Docs: https://remotion.dev/docs/paths.md
+
+### Convert data points to SVG path
+
+```tsx
+type Point = { x: number; y: number };
+
+const generateLinePath = (points: Point[]): string => {
+  if (points.length < 2) return "";
+  return points.map((p, i) => `${i === 0 ? "M" : "L"} ${p.x} ${p.y}`).join(" ");
+};
+```
+
+### Draw path with animation
+
+```tsx
+import { evolvePath } from "@remotion/paths";
+
+const path = "M 100 200 L 200 150 L 300 180 L 400 100";
+const progress = interpolate(frame, [0, 2 * fps], [0, 1], {
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+  easing: Easing.out(Easing.quad),
+});
+
+const { strokeDasharray, strokeDashoffset } = evolvePath(progress, path);
+
+<path
+  d={path}
+  fill="none"
+  stroke="#FF3232"
+  strokeWidth={4}
+  strokeDasharray={strokeDasharray}
+  strokeDashoffset={strokeDashoffset}
+/>;
+```
+
+### Follow path with marker/arrow
+
+```tsx
+import {
+  getLength,
+  getPointAtLength,
+  getTangentAtLength,
+} from "@remotion/paths";
+
+const pathLength = getLength(path);
+const point = getPointAtLength(path, progress * pathLength);
+const tangent = getTangentAtLength(path, progress * pathLength);
+const angle = Math.atan2(tangent.y, tangent.x);
+
+<g
+  style={{
+    transform: `translate(${point.x}px, ${point.y}px) rotate(${angle}rad)`,
+    transformOrigin: "0 0",
+  }}
+>
+  <polygon points="0,0 -20,-10 -20,10" fill="#FF3232" />
+</g>;
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/compositions.md b/builtin-skills/Video-maker/remotion-best-practices/rules/compositions.md
new file mode 100644
index 00000000..0db5f602
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/compositions.md
@@ -0,0 +1,154 @@
+---
+name: compositions
+description: Defining compositions, stills, folders, default props and dynamic metadata
+metadata:
+  tags: composition, still, folder, props, metadata
+---
+
+A `<Composition>` defines the component, width, height, fps and duration of a renderable video.
+
+It normally is placed in the `src/Root.tsx` file.
+
+```tsx
+import { Composition } from "remotion";
+import { MyComposition } from "./MyComposition";
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComposition}
+      durationInFrames={100}
+      fps={30}
+      width={1080}
+      height={1080}
+    />
+  );
+};
+```
+
+## Default Props
+
+Pass `defaultProps` to provide initial values for your component.  
+Values must be JSON-serializable (`Date`, `Map`, `Set`, and `staticFile()` are supported).
+
+```tsx
+import { Composition } from "remotion";
+import { MyComposition, MyCompositionProps } from "./MyComposition";
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComposition}
+      durationInFrames={100}
+      fps={30}
+      width={1080}
+      height={1080}
+      defaultProps={
+        {
+          title: "Hello World",
+          color: "#ff0000",
+        } satisfies MyCompositionProps
+      }
+    />
+  );
+};
+```
+
+Use `type` declarations for props rather than `interface` to ensure `defaultProps` type safety.
+
+## Folders
+
+Use `<Folder>` to organize compositions in the sidebar.  
+Folder names can only contain letters, numbers, and hyphens.
+
+```tsx
+import { Composition, Folder } from "remotion";
+
+export const RemotionRoot = () => {
+  return (
+    <>
+      <Folder name="Marketing">
+        <Composition id="Promo" /* ... */ />
+        <Composition id="Ad" /* ... */ />
+      </Folder>
+      <Folder name="Social">
+        <Folder name="Instagram">
+          <Composition id="Story" /* ... */ />
+          <Composition id="Reel" /* ... */ />
+        </Folder>
+      </Folder>
+    </>
+  );
+};
+```
+
+## Stills
+
+Use `<Still>` for single-frame images. It does not require `durationInFrames` or `fps`.
+
+```tsx
+import { Still } from "remotion";
+import { Thumbnail } from "./Thumbnail";
+
+export const RemotionRoot = () => {
+  return (
+    <Still id="Thumbnail" component={Thumbnail} width={1280} height={720} />
+  );
+};
+```
+
+## Calculate Metadata
+
+Use `calculateMetadata` to make dimensions, duration, or props dynamic based on data.
+
+```tsx
+import { Composition, CalculateMetadataFunction } from "remotion";
+import { MyComposition, MyCompositionProps } from "./MyComposition";
+
+const calculateMetadata: CalculateMetadataFunction<
+  MyCompositionProps
+> = async ({ props, abortSignal }) => {
+  const data = await fetch(`https://api.example.com/video/${props.videoId}`, {
+    signal: abortSignal,
+  }).then((res) => res.json());
+
+  return {
+    durationInFrames: Math.ceil(data.duration * 30),
+    props: {
+      ...props,
+      videoUrl: data.url,
+    },
+  };
+};
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComposition}
+      durationInFrames={100} // Placeholder, will be overridden
+      fps={30}
+      width={1080}
+      height={1080}
+      defaultProps={{ videoId: "abc123" }}
+      calculateMetadata={calculateMetadata}
+    />
+  );
+};
+```
+
+The function can return `props`, `durationInFrames`, `width`, `height`, `fps`, and codec-related defaults. It runs once before rendering begins.
+
+## Nesting compositions within another
+
+To add a composition within another composition, you can use the `<Sequence>` component with a `width` and `height` prop to specify the size of the composition.
+
+```tsx
+<AbsoluteFill>
+  <Sequence width={COMPOSITION_WIDTH} height={COMPOSITION_HEIGHT}>
+    <CompositionComponent />
+  </Sequence>
+</AbsoluteFill>
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/display-captions.md b/builtin-skills/Video-maker/remotion-best-practices/rules/display-captions.md
new file mode 100644
index 00000000..f9cb0f05
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/display-captions.md
@@ -0,0 +1,184 @@
+---
+name: display-captions
+description: Displaying captions in Remotion with TikTok-style pages and word highlighting
+metadata:
+  tags: captions, subtitles, display, tiktok, highlight
+---
+
+# Displaying captions in Remotion
+
+This guide explains how to display captions in Remotion, assuming you already have captions in the [`Caption`](https://www.remotion.dev/docs/captions/caption) format.
+
+## Prerequisites
+
+Read [Transcribing audio](transcribe-captions.md) for how to generate captions.
+
+First, the [`@remotion/captions`](https://www.remotion.dev/docs/captions) package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/captions
+```
+
+## Fetching captions
+
+First, fetch your captions JSON file. Use [`useDelayRender()`](https://www.remotion.dev/docs/use-delay-render) to hold the render until the captions are loaded:
+
+```tsx
+import { useState, useEffect, useCallback } from "react";
+import { AbsoluteFill, staticFile, useDelayRender } from "remotion";
+import type { Caption } from "@remotion/captions";
+
+export const MyComponent: React.FC = () => {
+  const [captions, setCaptions] = useState<Caption[] | null>(null);
+  const { delayRender, continueRender, cancelRender } = useDelayRender();
+  const [handle] = useState(() => delayRender());
+
+  const fetchCaptions = useCallback(async () => {
+    try {
+      // Assuming captions.json is in the public/ folder.
+      const response = await fetch(staticFile("captions123.json"));
+      const data = await response.json();
+      setCaptions(data);
+      continueRender(handle);
+    } catch (e) {
+      cancelRender(e);
+    }
+  }, [continueRender, cancelRender, handle]);
+
+  useEffect(() => {
+    fetchCaptions();
+  }, [fetchCaptions]);
+
+  if (!captions) {
+    return null;
+  }
+
+  return <AbsoluteFill>{/* Render captions here */}</AbsoluteFill>;
+};
+```
+
+## Creating pages
+
+Use `createTikTokStyleCaptions()` to group captions into pages. The `combineTokensWithinMilliseconds` option controls how many words appear at once:
+
+```tsx
+import { useMemo } from "react";
+import { createTikTokStyleCaptions } from "@remotion/captions";
+import type { Caption } from "@remotion/captions";
+
+// How often captions should switch (in milliseconds)
+// Higher values = more words per page
+// Lower values = fewer words (more word-by-word)
+const SWITCH_CAPTIONS_EVERY_MS = 1200;
+
+const { pages } = useMemo(() => {
+  return createTikTokStyleCaptions({
+    captions,
+    combineTokensWithinMilliseconds: SWITCH_CAPTIONS_EVERY_MS,
+  });
+}, [captions]);
+```
+
+## Rendering with Sequences
+
+Map over the pages and render each one in a `<Sequence>`. Calculate the start frame and duration from the page timing:
+
+```tsx
+import { Sequence, useVideoConfig, AbsoluteFill } from "remotion";
+import type { TikTokPage } from "@remotion/captions";
+
+const CaptionedContent: React.FC = () => {
+  const { fps } = useVideoConfig();
+
+  return (
+    <AbsoluteFill>
+      {pages.map((page, index) => {
+        const nextPage = pages[index + 1] ?? null;
+        const startFrame = (page.startMs / 1000) * fps;
+        const endFrame = Math.min(
+          nextPage ? (nextPage.startMs / 1000) * fps : Infinity,
+          startFrame + (SWITCH_CAPTIONS_EVERY_MS / 1000) * fps,
+        );
+        const durationInFrames = endFrame - startFrame;
+
+        if (durationInFrames <= 0) {
+          return null;
+        }
+
+        return (
+          <Sequence
+            key={index}
+            from={startFrame}
+            durationInFrames={durationInFrames}
+          >
+            <CaptionPage page={page} />
+          </Sequence>
+        );
+      })}
+    </AbsoluteFill>
+  );
+};
+```
+
+## White-space preservation
+
+The captions are whitespace sensitive. You should include spaces in the `text` field before each word. Use `whiteSpace: "pre"` to preserve the whitespace in the captions.
+
+## Separate component for captions
+
+Put captioning logic in a separate component.  
+Make a new file for it.
+
+## Word highlighting
+
+A caption page contains `tokens` which you can use to highlight the currently spoken word:
+
+```tsx
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
+import type { TikTokPage } from "@remotion/captions";
+
+const HIGHLIGHT_COLOR = "#39E508";
+
+const CaptionPage: React.FC<{ page: TikTokPage }> = ({ page }) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  // Current time relative to the start of the sequence
+  const currentTimeMs = (frame / fps) * 1000;
+  // Convert to absolute time by adding the page start
+  const absoluteTimeMs = page.startMs + currentTimeMs;
+
+  return (
+    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
+      <div style={{ fontSize: 80, fontWeight: "bold", whiteSpace: "pre" }}>
+        {page.tokens.map((token) => {
+          const isActive =
+            token.fromMs <= absoluteTimeMs && token.toMs > absoluteTimeMs;
+
+          return (
+            <span
+              key={token.fromMs}
+              style={{ color: isActive ? HIGHLIGHT_COLOR : "white" }}
+            >
+              {token.text}
+            </span>
+          );
+        })}
+      </div>
+    </AbsoluteFill>
+  );
+};
+```
+
+## Display captions alongside video content
+
+By default, put the captions alongside the video content, so the captions are in sync.  
+For each video, make a new captions JSON file.
+
+```tsx
+<AbsoluteFill>
+  <Video src={staticFile("video.mp4")} />
+  <CaptionPage page={page} />
+</AbsoluteFill>
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/extract-frames.md b/builtin-skills/Video-maker/remotion-best-practices/rules/extract-frames.md
new file mode 100644
index 00000000..1a8a0c89
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/extract-frames.md
@@ -0,0 +1,229 @@
+---
+name: extract-frames
+description: Extract frames from videos at specific timestamps using Mediabunny
+metadata:
+  tags: frames, extract, video, thumbnail, filmstrip, canvas
+---
+
+# Extracting frames from videos
+
+Use Mediabunny to extract frames from videos at specific timestamps. This is useful for generating thumbnails, filmstrips, or processing individual frames.
+
+## The `extractFrames()` function
+
+This function can be copy-pasted into any project.
+
+```tsx
+import {
+  ALL_FORMATS,
+  Input,
+  UrlSource,
+  VideoSample,
+  VideoSampleSink,
+} from "mediabunny";
+
+type Options = {
+  track: { width: number; height: number };
+  container: string;
+  durationInSeconds: number | null;
+};
+
+export type ExtractFramesTimestampsInSecondsFn = (
+  options: Options,
+) => Promise<number[]> | number[];
+
+export type ExtractFramesProps = {
+  src: string;
+  timestampsInSeconds: number[] | ExtractFramesTimestampsInSecondsFn;
+  onVideoSample: (sample: VideoSample) => void;
+  signal?: AbortSignal;
+};
+
+export async function extractFrames({
+  src,
+  timestampsInSeconds,
+  onVideoSample,
+  signal,
+}: ExtractFramesProps): Promise<void> {
+  using input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src),
+  });
+
+  const [durationInSeconds, format, videoTrack] = await Promise.all([
+    input.computeDuration(),
+    input.getFormat(),
+    input.getPrimaryVideoTrack(),
+  ]);
+
+  if (!videoTrack) {
+    throw new Error("No video track found in the input");
+  }
+
+  if (signal?.aborted) {
+    throw new Error("Aborted");
+  }
+
+  const timestamps =
+    typeof timestampsInSeconds === "function"
+      ? await timestampsInSeconds({
+          track: {
+            width: videoTrack.displayWidth,
+            height: videoTrack.displayHeight,
+          },
+          container: format.name,
+          durationInSeconds,
+        })
+      : timestampsInSeconds;
+
+  if (timestamps.length === 0) {
+    return;
+  }
+
+  if (signal?.aborted) {
+    throw new Error("Aborted");
+  }
+
+  const sink = new VideoSampleSink(videoTrack);
+
+  for await (using videoSample of sink.samplesAtTimestamps(timestamps)) {
+    if (signal?.aborted) {
+      break;
+    }
+
+    if (!videoSample) {
+      continue;
+    }
+
+    onVideoSample(videoSample);
+  }
+}
+```
+
+## Basic usage
+
+Extract frames at specific timestamps:
+
+```tsx
+await extractFrames({
+  src: "https://remotion.media/video.mp4",
+  timestampsInSeconds: [0, 1, 2, 3, 4],
+  onVideoSample: (sample) => {
+    const canvas = document.createElement("canvas");
+    canvas.width = sample.displayWidth;
+    canvas.height = sample.displayHeight;
+    const ctx = canvas.getContext("2d");
+    sample.draw(ctx!, 0, 0);
+  },
+});
+```
+
+## Creating a filmstrip
+
+Use a callback function to dynamically calculate timestamps based on video metadata:
+
+```tsx
+const canvasWidth = 500;
+const canvasHeight = 80;
+const fromSeconds = 0;
+const toSeconds = 10;
+
+await extractFrames({
+  src: "https://remotion.media/video.mp4",
+  timestampsInSeconds: async ({ track, durationInSeconds }) => {
+    const aspectRatio = track.width / track.height;
+    const amountOfFramesFit = Math.ceil(
+      canvasWidth / (canvasHeight * aspectRatio),
+    );
+    const segmentDuration = toSeconds - fromSeconds;
+    const timestamps: number[] = [];
+
+    for (let i = 0; i < amountOfFramesFit; i++) {
+      timestamps.push(
+        fromSeconds + (segmentDuration / amountOfFramesFit) * (i + 0.5),
+      );
+    }
+
+    return timestamps;
+  },
+  onVideoSample: (sample) => {
+    console.log(`Frame at ${sample.timestamp}s`);
+
+    const canvas = document.createElement("canvas");
+    canvas.width = sample.displayWidth;
+    canvas.height = sample.displayHeight;
+    const ctx = canvas.getContext("2d");
+    sample.draw(ctx!, 0, 0);
+  },
+});
+```
+
+## Cancellation with AbortSignal
+
+Cancel frame extraction after a timeout:
+
+```tsx
+const controller = new AbortController();
+
+setTimeout(() => controller.abort(), 5000);
+
+try {
+  await extractFrames({
+    src: "https://remotion.media/video.mp4",
+    timestampsInSeconds: [0, 1, 2, 3, 4],
+    onVideoSample: (sample) => {
+      using frame = sample;
+      const canvas = document.createElement("canvas");
+      canvas.width = frame.displayWidth;
+      canvas.height = frame.displayHeight;
+      const ctx = canvas.getContext("2d");
+      frame.draw(ctx!, 0, 0);
+    },
+    signal: controller.signal,
+  });
+
+  console.log("Frame extraction complete!");
+} catch (error) {
+  console.error("Frame extraction was aborted or failed:", error);
+}
+```
+
+## Timeout with Promise.race
+
+```tsx
+const controller = new AbortController();
+
+const timeoutPromise = new Promise<never>((_, reject) => {
+  const timeoutId = setTimeout(() => {
+    controller.abort();
+    reject(new Error("Frame extraction timed out after 10 seconds"));
+  }, 10000);
+
+  controller.signal.addEventListener("abort", () => clearTimeout(timeoutId), {
+    once: true,
+  });
+});
+
+try {
+  await Promise.race([
+    extractFrames({
+      src: "https://remotion.media/video.mp4",
+      timestampsInSeconds: [0, 1, 2, 3, 4],
+      onVideoSample: (sample) => {
+        using frame = sample;
+        const canvas = document.createElement("canvas");
+        canvas.width = frame.displayWidth;
+        canvas.height = frame.displayHeight;
+        const ctx = canvas.getContext("2d");
+        frame.draw(ctx!, 0, 0);
+      },
+      signal: controller.signal,
+    }),
+    timeoutPromise,
+  ]);
+
+  console.log("Frame extraction complete!");
+} catch (error) {
+  console.error("Frame extraction was aborted or failed:", error);
+}
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/ffmpeg.md b/builtin-skills/Video-maker/remotion-best-practices/rules/ffmpeg.md
new file mode 100644
index 00000000..57936902
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/ffmpeg.md
@@ -0,0 +1,38 @@
+---
+name: ffmpeg
+description: Using FFmpeg and FFprobe in Remotion
+metadata:
+  tags: ffmpeg, ffprobe, video, trimming
+---
+
+## FFmpeg in Remotion
+
+`ffmpeg` and `ffprobe` do not need to be installed. They are available via the `bunx remotion ffmpeg` and `bunx remotion ffprobe`:
+
+```bash
+bunx remotion ffmpeg -i input.mp4 output.mp3
+bunx remotion ffprobe input.mp4
+```
+
+### Trimming videos
+
+You have 2 options for trimming videos:
+
+1. Use the FFmpeg command line. You MUST re-encode the video to avoid frozen frames at the start of the video.
+
+```bash
+# Re-encodes from the exact frame
+bunx remotion ffmpeg -ss 00:00:05 -i public/input.mp4 -to 00:00:10 -c:v libx264 -c:a aac public/output.mp4
+```
+
+2. Use the `trimBefore` and `trimAfter` props of the `<Video>` component. The benefit is that this is non-destructive and you can change the trim at any time.
+
+```tsx
+import { Video } from "@remotion/media";
+
+<Video
+  src={staticFile("video.mp4")}
+  trimBefore={5 * fps}
+  trimAfter={10 * fps}
+/>;
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/fonts.md b/builtin-skills/Video-maker/remotion-best-practices/rules/fonts.md
new file mode 100644
index 00000000..c10cd83e
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/fonts.md
@@ -0,0 +1,152 @@
+---
+name: fonts
+description: Loading Google Fonts and local fonts in Remotion
+metadata:
+  tags: fonts, google-fonts, typography, text
+---
+
+# Using fonts in Remotion
+
+## Google Fonts with @remotion/google-fonts
+
+The recommended way to use Google Fonts. It's type-safe and automatically blocks rendering until the font is ready.
+
+### Prerequisites
+
+First, the @remotion/google-fonts package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/google-fonts # If project uses npm
+bunx remotion add @remotion/google-fonts # If project uses bun
+yarn remotion add @remotion/google-fonts # If project uses yarn
+pnpm exec remotion add @remotion/google-fonts # If project uses pnpm
+```
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Lobster";
+
+const { fontFamily } = loadFont();
+
+export const MyComposition = () => {
+  return <div style={{ fontFamily }}>Hello World</div>;
+};
+```
+
+Preferrably, specify only needed weights and subsets to reduce file size:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Roboto";
+
+const { fontFamily } = loadFont("normal", {
+  weights: ["400", "700"],
+  subsets: ["latin"],
+});
+```
+
+### Waiting for font to load
+
+Use `waitUntilDone()` if you need to know when the font is ready:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Lobster";
+
+const { fontFamily, waitUntilDone } = loadFont();
+
+await waitUntilDone();
+```
+
+## Local fonts with @remotion/fonts
+
+For local font files, use the `@remotion/fonts` package.
+
+### Prerequisites
+
+First, install @remotion/fonts:
+
+```bash
+npx remotion add @remotion/fonts # If project uses npm
+bunx remotion add @remotion/fonts # If project uses bun
+yarn remotion add @remotion/fonts # If project uses yarn
+pnpm exec remotion add @remotion/fonts # If project uses pnpm
+```
+
+### Loading a local font
+
+Place your font file in the `public/` folder and use `loadFont()`:
+
+```tsx
+import { loadFont } from "@remotion/fonts";
+import { staticFile } from "remotion";
+
+await loadFont({
+  family: "MyFont",
+  url: staticFile("MyFont-Regular.woff2"),
+});
+
+export const MyComposition = () => {
+  return <div style={{ fontFamily: "MyFont" }}>Hello World</div>;
+};
+```
+
+### Loading multiple weights
+
+Load each weight separately with the same family name:
+
+```tsx
+import { loadFont } from "@remotion/fonts";
+import { staticFile } from "remotion";
+
+await Promise.all([
+  loadFont({
+    family: "Inter",
+    url: staticFile("Inter-Regular.woff2"),
+    weight: "400",
+  }),
+  loadFont({
+    family: "Inter",
+    url: staticFile("Inter-Bold.woff2"),
+    weight: "700",
+  }),
+]);
+```
+
+### Available options
+
+```tsx
+loadFont({
+  family: "MyFont", // Required: name to use in CSS
+  url: staticFile("font.woff2"), // Required: font file URL
+  format: "woff2", // Optional: auto-detected from extension
+  weight: "400", // Optional: font weight
+  style: "normal", // Optional: normal or italic
+  display: "block", // Optional: font-display behavior
+});
+```
+
+## Using in components
+
+Call `loadFont()` at the top level of your component or in a separate file that's imported early:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Montserrat";
+
+const { fontFamily } = loadFont("normal", {
+  weights: ["400", "700"],
+  subsets: ["latin"],
+});
+
+export const Title: React.FC<{ text: string }> = ({ text }) => {
+  return (
+    <h1
+      style={{
+        fontFamily,
+        fontSize: 80,
+        fontWeight: "bold",
+      }}
+    >
+      {text}
+    </h1>
+  );
+};
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/get-audio-duration.md b/builtin-skills/Video-maker/remotion-best-practices/rules/get-audio-duration.md
new file mode 100644
index 00000000..35ef7471
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/get-audio-duration.md
@@ -0,0 +1,58 @@
+---
+name: get-audio-duration
+description: Getting the duration of an audio file in seconds with Mediabunny
+metadata:
+  tags: duration, audio, length, time, seconds, mp3, wav
+---
+
+# Getting audio duration with Mediabunny
+
+Mediabunny can extract the duration of an audio file. It works in browser, Node.js, and Bun environments.
+
+## Getting audio duration
+
+```tsx title="get-audio-duration.ts"
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getAudioDuration = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  const durationInSeconds = await input.computeDuration();
+  return durationInSeconds;
+};
+```
+
+## Usage
+
+```tsx
+const duration = await getAudioDuration("https://remotion.media/audio.mp3");
+console.log(duration); // e.g. 180.5 (seconds)
+```
+
+## Using with staticFile in Remotion
+
+Make sure to wrap the file path in `staticFile()`:
+
+```tsx
+import { staticFile } from "remotion";
+
+const duration = await getAudioDuration(staticFile("audio.mp3"));
+```
+
+## In Node.js and Bun
+
+Use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+  formats: ALL_FORMATS,
+  source: new FileSource(file), // File object from input or drag-drop
+});
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/get-video-dimensions.md b/builtin-skills/Video-maker/remotion-best-practices/rules/get-video-dimensions.md
new file mode 100644
index 00000000..746c09fb
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/get-video-dimensions.md
@@ -0,0 +1,68 @@
+---
+name: get-video-dimensions
+description: Getting the width and height of a video file with Mediabunny
+metadata:
+  tags: dimensions, width, height, resolution, size, video
+---
+
+# Getting video dimensions with Mediabunny
+
+Mediabunny can extract the width and height of a video file. It works in browser, Node.js, and Bun environments.
+
+## Getting video dimensions
+
+```tsx
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getVideoDimensions = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  const videoTrack = await input.getPrimaryVideoTrack();
+  if (!videoTrack) {
+    throw new Error("No video track found");
+  }
+
+  return {
+    width: videoTrack.displayWidth,
+    height: videoTrack.displayHeight,
+  };
+};
+```
+
+## Usage
+
+```tsx
+const dimensions = await getVideoDimensions("https://remotion.media/video.mp4");
+console.log(dimensions.width); // e.g. 1920
+console.log(dimensions.height); // e.g. 1080
+```
+
+## Using with local files
+
+For local files, use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+  formats: ALL_FORMATS,
+  source: new FileSource(file), // File object from input or drag-drop
+});
+
+const videoTrack = await input.getPrimaryVideoTrack();
+const width = videoTrack.displayWidth;
+const height = videoTrack.displayHeight;
+```
+
+## Using with staticFile in Remotion
+
+```tsx
+import { staticFile } from "remotion";
+
+const dimensions = await getVideoDimensions(staticFile("video.mp4"));
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/get-video-duration.md b/builtin-skills/Video-maker/remotion-best-practices/rules/get-video-duration.md
new file mode 100644
index 00000000..10ab735d
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/get-video-duration.md
@@ -0,0 +1,60 @@
+---
+name: get-video-duration
+description: Getting the duration of a video file in seconds with Mediabunny
+metadata:
+  tags: duration, video, length, time, seconds
+---
+
+# Getting video duration with Mediabunny
+
+Mediabunny can extract the duration of a video file. It works in browser, Node.js, and Bun environments.
+
+## Getting video duration
+
+```tsx
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getVideoDuration = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  const durationInSeconds = await input.computeDuration();
+  return durationInSeconds;
+};
+```
+
+## Usage
+
+```tsx
+const duration = await getVideoDuration("https://remotion.media/video.mp4");
+console.log(duration); // e.g. 10.5 (seconds)
+```
+
+## Video files from the public/ directory
+
+Make sure to wrap the file path in `staticFile()`:
+
+```tsx
+import { staticFile } from "remotion";
+
+const duration = await getVideoDuration(staticFile("video.mp4"));
+```
+
+## In Node.js and Bun
+
+Use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+  formats: ALL_FORMATS,
+  source: new FileSource(file), // File object from input or drag-drop
+});
+
+const durationInSeconds = await input.computeDuration();
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/gifs.md b/builtin-skills/Video-maker/remotion-best-practices/rules/gifs.md
new file mode 100644
index 00000000..042647f6
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/gifs.md
@@ -0,0 +1,141 @@
+---
+name: gif
+description: Displaying GIFs, APNG, AVIF and WebP in Remotion
+metadata:
+  tags: gif, animation, images, animated, apng, avif, webp
+---
+
+# Using Animated images in Remotion
+
+## Basic usage
+
+Use `<AnimatedImage>` to display a GIF, APNG, AVIF or WebP image synchronized with Remotion's timeline:
+
+```tsx
+import { AnimatedImage, staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return (
+    <AnimatedImage src={staticFile("animation.gif")} width={500} height={500} />
+  );
+};
+```
+
+Remote URLs are also supported (must have CORS enabled):
+
+```tsx
+<AnimatedImage
+  src="https://example.com/animation.gif"
+  width={500}
+  height={500}
+/>
+```
+
+## Sizing and fit
+
+Control how the image fills its container with the `fit` prop:
+
+```tsx
+// Stretch to fill (default)
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="fill" />
+
+// Maintain aspect ratio, fit inside container
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="contain" />
+
+// Fill container, crop if needed
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="cover" />
+```
+
+## Playback speed
+
+Use `playbackRate` to control the animation speed:
+
+```tsx
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} playbackRate={2} /> {/* 2x speed */}
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} playbackRate={0.5} /> {/* Half speed */}
+```
+
+## Looping behavior
+
+Control what happens when the animation finishes:
+
+```tsx
+// Loop indefinitely (default)
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="loop" />
+
+// Play once, show final frame
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="pause-after-finish" />
+
+// Play once, then clear canvas
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="clear-after-finish" />
+```
+
+## Styling
+
+Use the `style` prop for additional CSS (use `width` and `height` props for sizing):
+
+```tsx
+<AnimatedImage
+  src={staticFile("animation.gif")}
+  width={500}
+  height={500}
+  style={{
+    borderRadius: 20,
+    position: "absolute",
+    top: 100,
+    left: 50,
+  }}
+/>
+```
+
+## Getting GIF duration
+
+Use `getGifDurationInSeconds()` from `@remotion/gif` to get the duration of a GIF.
+
+```bash
+npx remotion add @remotion/gif
+```
+
+```tsx
+import { getGifDurationInSeconds } from "@remotion/gif";
+import { staticFile } from "remotion";
+
+const duration = await getGifDurationInSeconds(staticFile("animation.gif"));
+console.log(duration); // e.g. 2.5
+```
+
+This is useful for setting the composition duration to match the GIF:
+
+```tsx
+import { getGifDurationInSeconds } from "@remotion/gif";
+import { staticFile, CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction = async () => {
+  const duration = await getGifDurationInSeconds(staticFile("animation.gif"));
+  return {
+    durationInFrames: Math.ceil(duration * 30),
+  };
+};
+```
+
+## Alternative
+
+If `<AnimatedImage>` does not work (only supported in Chrome and Firefox), you can use `<Gif>` from `@remotion/gif` instead.
+
+```bash
+npx remotion add @remotion/gif # If project uses npm
+bunx remotion add @remotion/gif # If project uses bun
+yarn remotion add @remotion/gif # If project uses yarn
+pnpm exec remotion add @remotion/gif # If project uses pnpm
+```
+
+```tsx
+import { Gif } from "@remotion/gif";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Gif src={staticFile("animation.gif")} width={500} height={500} />;
+};
+```
+
+The `<Gif>` component has the same props as `<AnimatedImage>` but only supports GIF files.
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/images.md b/builtin-skills/Video-maker/remotion-best-practices/rules/images.md
new file mode 100644
index 00000000..3b031944
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/images.md
@@ -0,0 +1,134 @@
+---
+name: images
+description: Embedding images in Remotion using the <Img> component
+metadata:
+  tags: images, img, staticFile, png, jpg, svg, webp
+---
+
+# Using images in Remotion
+
+## The `<Img>` component
+
+Always use the `<Img>` component from `remotion` to display images:
+
+```tsx
+import { Img, staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Img src={staticFile("photo.png")} />;
+};
+```
+
+## Important restrictions
+
+**You MUST use the `<Img>` component from `remotion`.** Do not use:
+
+- Native HTML `<img>` elements
+- Next.js `<Image>` component
+- CSS `background-image`
+
+The `<Img>` component ensures images are fully loaded before rendering, preventing flickering and blank frames during video export.
+
+## Local images with staticFile()
+
+Place images in the `public/` folder and use `staticFile()` to reference them:
+
+```
+my-video/
+├─ public/
+│  ├─ logo.png
+│  ├─ avatar.jpg
+│  └─ icon.svg
+├─ src/
+├─ package.json
+```
+
+```tsx
+import { Img, staticFile } from "remotion";
+
+<Img src={staticFile("logo.png")} />;
+```
+
+## Remote images
+
+Remote URLs can be used directly without `staticFile()`:
+
+```tsx
+<Img src="https://example.com/image.png" />
+```
+
+Ensure remote images have CORS enabled.
+
+For animated GIFs, use the `<Gif>` component from `@remotion/gif` instead.
+
+## Sizing and positioning
+
+Use the `style` prop to control size and position:
+
+```tsx
+<Img
+  src={staticFile("photo.png")}
+  style={{
+    width: 500,
+    height: 300,
+    position: "absolute",
+    top: 100,
+    left: 50,
+    objectFit: "cover",
+  }}
+/>
+```
+
+## Dynamic image paths
+
+Use template literals for dynamic file references:
+
+```tsx
+import { Img, staticFile, useCurrentFrame } from "remotion";
+
+const frame = useCurrentFrame();
+
+// Image sequence
+<Img src={staticFile(`frames/frame${frame}.png`)} />
+
+// Selecting based on props
+<Img src={staticFile(`avatars/${props.userId}.png`)} />
+
+// Conditional images
+<Img src={staticFile(`icons/${isActive ? "active" : "inactive"}.svg`)} />
+```
+
+This pattern is useful for:
+
+- Image sequences (frame-by-frame animations)
+- User-specific avatars or profile images
+- Theme-based icons
+- State-dependent graphics
+
+## Getting image dimensions
+
+Use `getImageDimensions()` to get the dimensions of an image:
+
+```tsx
+import { getImageDimensions, staticFile } from "remotion";
+
+const { width, height } = await getImageDimensions(staticFile("photo.png"));
+```
+
+This is useful for calculating aspect ratios or sizing compositions:
+
+```tsx
+import {
+  getImageDimensions,
+  staticFile,
+  CalculateMetadataFunction,
+} from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction = async () => {
+  const { width, height } = await getImageDimensions(staticFile("photo.png"));
+  return {
+    width,
+    height,
+  };
+};
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/import-srt-captions.md b/builtin-skills/Video-maker/remotion-best-practices/rules/import-srt-captions.md
new file mode 100644
index 00000000..333c9621
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/import-srt-captions.md
@@ -0,0 +1,69 @@
+---
+name: import-srt-captions
+description: Importing .srt subtitle files into Remotion using @remotion/captions
+metadata:
+  tags: captions, subtitles, srt, import, parse
+---
+
+# Importing .srt subtitles into Remotion
+
+If you have an existing `.srt` subtitle file, you can import it into Remotion using `parseSrt()` from `@remotion/captions`.
+
+If you don't have a .srt file, read [Transcribing audio](transcribe-captions.md) for how to generate captions instead.
+
+## Prerequisites
+
+First, the @remotion/captions package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/captions # If project uses npm
+bunx remotion add @remotion/captions # If project uses bun
+yarn remotion add @remotion/captions # If project uses yarn
+pnpm exec remotion add @remotion/captions # If project uses pnpm
+```
+
+## Reading an .srt file
+
+Use `staticFile()` to reference an `.srt` file in your `public` folder, then fetch and parse it:
+
+```tsx
+import { useState, useEffect, useCallback } from "react";
+import { AbsoluteFill, staticFile, useDelayRender } from "remotion";
+import { parseSrt } from "@remotion/captions";
+import type { Caption } from "@remotion/captions";
+
+export const MyComponent: React.FC = () => {
+  const [captions, setCaptions] = useState<Caption[] | null>(null);
+  const { delayRender, continueRender, cancelRender } = useDelayRender();
+  const [handle] = useState(() => delayRender());
+
+  const fetchCaptions = useCallback(async () => {
+    try {
+      const response = await fetch(staticFile("subtitles.srt"));
+      const text = await response.text();
+      const { captions: parsed } = parseSrt({ input: text });
+      setCaptions(parsed);
+      continueRender(handle);
+    } catch (e) {
+      cancelRender(e);
+    }
+  }, [continueRender, cancelRender, handle]);
+
+  useEffect(() => {
+    fetchCaptions();
+  }, [fetchCaptions]);
+
+  if (!captions) {
+    return null;
+  }
+
+  return <AbsoluteFill>{/* Use captions here */}</AbsoluteFill>;
+};
+```
+
+Remote URLs are also supported - you can `fetch()` a remote file via URL instead of using `staticFile()`.
+
+## Using imported captions
+
+Once parsed, the captions are in the `Caption` format and can be used with all `@remotion/captions` utilities.
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/light-leaks.md b/builtin-skills/Video-maker/remotion-best-practices/rules/light-leaks.md
new file mode 100644
index 00000000..354b9566
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/light-leaks.md
@@ -0,0 +1,73 @@
+---
+name: light-leaks
+description: Light leak overlay effects for Remotion using @remotion/light-leaks.
+metadata:
+  tags: light-leaks, overlays, effects, transitions
+---
+
+## Light Leaks
+
+This only works from Remotion 4.0.415 and up. Use `npx remotion versions` to check your Remotion version and `npx remotion upgrade` to upgrade your Remotion version.
+
+`<LightLeak>` from `@remotion/light-leaks` renders a WebGL-based light leak effect. It reveals during the first half of its duration and retracts during the second half.
+
+Typically used inside a `<TransitionSeries.Overlay>` to play over the cut point between two scenes. See the **transitions** rule for `<TransitionSeries>` and overlay usage.
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/light-leaks
+```
+
+## Basic usage with TransitionSeries
+
+```tsx
+import { TransitionSeries } from "@remotion/transitions";
+import { LightLeak } from "@remotion/light-leaks";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Overlay durationInFrames={30}>
+    <LightLeak />
+  </TransitionSeries.Overlay>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Props
+
+- `durationInFrames?` — defaults to the parent sequence/composition duration. The effect reveals during the first half and retracts during the second half.
+- `seed?` — determines the shape of the light leak pattern. Different seeds produce different patterns. Default: `0`.
+- `hueShift?` — rotates the hue in degrees (`0`–`360`). Default: `0` (yellow-to-orange). `120` = green, `240` = blue.
+
+## Customizing the look
+
+```tsx
+import { LightLeak } from "@remotion/light-leaks";
+
+// Blue-tinted light leak with a different pattern
+<LightLeak seed={5} hueShift={240} />;
+
+// Green-tinted light leak
+<LightLeak seed={2} hueShift={120} />;
+```
+
+## Standalone usage
+
+`<LightLeak>` can also be used outside of `<TransitionSeries>`, for example as a decorative overlay in any composition:
+
+```tsx
+import { AbsoluteFill } from "remotion";
+import { LightLeak } from "@remotion/light-leaks";
+
+const MyComp: React.FC = () => (
+  <AbsoluteFill>
+    <MyContent />
+    <LightLeak durationInFrames={60} seed={3} />
+  </AbsoluteFill>
+);
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/lottie.md b/builtin-skills/Video-maker/remotion-best-practices/rules/lottie.md
new file mode 100644
index 00000000..4b0c4ee5
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/lottie.md
@@ -0,0 +1,70 @@
+---
+name: lottie
+description: Embedding Lottie animations in Remotion.
+metadata:
+  category: Animation
+---
+
+# Using Lottie Animations in Remotion
+
+## Prerequisites
+
+First, the @remotion/lottie package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/lottie # If project uses npm
+bunx remotion add @remotion/lottie # If project uses bun
+yarn remotion add @remotion/lottie # If project uses yarn
+pnpm exec remotion add @remotion/lottie # If project uses pnpm
+```
+
+## Displaying a Lottie file
+
+To import a Lottie animation:
+
+- Fetch the Lottie asset
+- Wrap the loading process in `delayRender()` and `continueRender()`
+- Save the animation data in a state
+- Render the Lottie animation using the `Lottie` component from the `@remotion/lottie` package
+
+```tsx
+import { Lottie, LottieAnimationData } from "@remotion/lottie";
+import { useEffect, useState } from "react";
+import { cancelRender, continueRender, delayRender } from "remotion";
+
+export const MyAnimation = () => {
+  const [handle] = useState(() => delayRender("Loading Lottie animation"));
+
+  const [animationData, setAnimationData] =
+    useState<LottieAnimationData | null>(null);
+
+  useEffect(() => {
+    fetch("https://assets4.lottiefiles.com/packages/lf20_zyquagfl.json")
+      .then((data) => data.json())
+      .then((json) => {
+        setAnimationData(json);
+        continueRender(handle);
+      })
+      .catch((err) => {
+        cancelRender(err);
+      });
+  }, [handle]);
+
+  if (!animationData) {
+    return null;
+  }
+
+  return <Lottie animationData={animationData} />;
+};
+```
+
+## Styling and animating
+
+Lottie supports the `style` prop to allow styles and animations:
+
+```tsx
+return (
+  <Lottie animationData={animationData} style={{ width: 400, height: 400 }} />
+);
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/maps.md b/builtin-skills/Video-maker/remotion-best-practices/rules/maps.md
new file mode 100644
index 00000000..1e4818cc
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/maps.md
@@ -0,0 +1,412 @@
+---
+name: maps
+description: Make map animations with Mapbox
+metadata:
+  tags: map, map animation, mapbox
+---
+
+Maps can be added to a Remotion video with Mapbox.  
+The [Mapbox documentation](https://docs.mapbox.com/mapbox-gl-js/api/) has the API reference.
+
+## Prerequisites
+
+Mapbox and `@turf/turf` need to be installed.
+
+Search the project for lockfiles and run the correct command depending on the package manager:
+
+If `package-lock.json` is found, use the following command:
+
+```bash
+npm i mapbox-gl @turf/turf @types/mapbox-gl
+```
+
+If `bun.lock` is found, use the following command:
+
+```bash
+bun i mapbox-gl @turf/turf @types/mapbox-gl
+```
+
+If `yarn.lock` is found, use the following command:
+
+```bash
+yarn add mapbox-gl @turf/turf @types/mapbox-gl
+```
+
+If `pnpm-lock.yaml` is found, use the following command:
+
+```bash
+pnpm i mapbox-gl @turf/turf @types/mapbox-gl
+```
+
+The user needs to create a free Mapbox account and create an access token by visiting https://console.mapbox.com/account/access-tokens/.
+
+The mapbox token needs to be added to the `.env` file:
+
+```txt title=".env"
+REMOTION_MAPBOX_TOKEN==pk.your-mapbox-access-token
+```
+
+## Adding a map
+
+Here is a basic example of a map in Remotion.
+
+```tsx
+import { useEffect, useMemo, useRef, useState } from "react";
+import { AbsoluteFill, useDelayRender, useVideoConfig } from "remotion";
+import mapboxgl, { Map } from "mapbox-gl";
+
+export const lineCoordinates = [
+  [6.56158447265625, 46.059891147620725],
+  [6.5691375732421875, 46.05679376154153],
+  [6.5842437744140625, 46.05059898938315],
+  [6.594886779785156, 46.04702502069337],
+  [6.601066589355469, 46.0460718554722],
+  [6.6089630126953125, 46.0365370783104],
+  [6.6185760498046875, 46.018420689207964],
+];
+
+mapboxgl.accessToken = process.env.REMOTION_MAPBOX_TOKEN as string;
+
+export const MyComposition = () => {
+  const ref = useRef<HTMLDivElement>(null);
+  const { delayRender, continueRender } = useDelayRender();
+
+  const { width, height } = useVideoConfig();
+  const [handle] = useState(() => delayRender("Loading map..."));
+  const [map, setMap] = useState<Map | null>(null);
+
+  useEffect(() => {
+    const _map = new Map({
+      container: ref.current!,
+      zoom: 11.53,
+      center: [6.5615, 46.0598],
+      pitch: 65,
+      bearing: 0,
+      style: "⁠mapbox://styles/mapbox/standard",
+      interactive: false,
+      fadeDuration: 0,
+    });
+
+    _map.on("style.load", () => {
+      // Hide all features from the Mapbox Standard style
+      const hideFeatures = [
+        "showRoadsAndTransit",
+        "showRoads",
+        "showTransit",
+        "showPedestrianRoads",
+        "showRoadLabels",
+        "showTransitLabels",
+        "showPlaceLabels",
+        "showPointOfInterestLabels",
+        "showPointsOfInterest",
+        "showAdminBoundaries",
+        "showLandmarkIcons",
+        "showLandmarkIconLabels",
+        "show3dObjects",
+        "show3dBuildings",
+        "show3dTrees",
+        "show3dLandmarks",
+        "show3dFacades",
+      ];
+      for (const feature of hideFeatures) {
+        _map.setConfigProperty("basemap", feature, false);
+      }
+
+      _map.setConfigProperty("basemap", "colorTrunks", "rgba(0, 0, 0, 0)");
+
+      _map.addSource("trace", {
+        type: "geojson",
+        data: {
+          type: "Feature",
+          properties: {},
+          geometry: {
+            type: "LineString",
+            coordinates: lineCoordinates,
+          },
+        },
+      });
+      _map.addLayer({
+        type: "line",
+        source: "trace",
+        id: "line",
+        paint: {
+          "line-color": "black",
+          "line-width": 5,
+        },
+        layout: {
+          "line-cap": "round",
+          "line-join": "round",
+        },
+      });
+    });
+
+    _map.on("load", () => {
+      continueRender(handle);
+      setMap(_map);
+    });
+  }, [handle, lineCoordinates]);
+
+  const style: React.CSSProperties = useMemo(
+    () => ({ width, height, position: "absolute" }),
+    [width, height],
+  );
+
+  return <AbsoluteFill ref={ref} style={style} />;
+};
+```
+
+The following is important in Remotion:
+
+- Animations must be driven by `useCurrentFrame()` and animations that Mapbox brings itself should be disabled. For example, the `fadeDuration` prop should be set to `0`, `interactive` should be set to `false`, etc.
+- Loading the map should be delayed using `useDelayRender()` and the map should be set to `null` until it is loaded.
+- The element containing the ref MUST have an explicit width and height and `position: "absolute"`.
+- Do not add a `_map.remove();` cleanup function.
+
+## Drawing lines
+
+Unless I request it, do not add a glow effect to the lines.
+Unless I request it, do not add additional points to the lines.
+
+## Map style
+
+By default, use the `mapbox://styles/mapbox/standard` style.  
+Hide the labels from the base map style.
+
+Unless I request otherwise, remove all features from the Mapbox Standard style.
+
+```tsx
+// Hide all features from the Mapbox Standard style
+const hideFeatures = [
+  "showRoadsAndTransit",
+  "showRoads",
+  "showTransit",
+  "showPedestrianRoads",
+  "showRoadLabels",
+  "showTransitLabels",
+  "showPlaceLabels",
+  "showPointOfInterestLabels",
+  "showPointsOfInterest",
+  "showAdminBoundaries",
+  "showLandmarkIcons",
+  "showLandmarkIconLabels",
+  "show3dObjects",
+  "show3dBuildings",
+  "show3dTrees",
+  "show3dLandmarks",
+  "show3dFacades",
+];
+for (const feature of hideFeatures) {
+  _map.setConfigProperty("basemap", feature, false);
+}
+
+_map.setConfigProperty("basemap", "colorMotorways", "transparent");
+_map.setConfigProperty("basemap", "colorRoads", "transparent");
+_map.setConfigProperty("basemap", "colorTrunks", "transparent");
+```
+
+## Animating the camera
+
+You can animate the camera along the line by adding a `useEffect` hook that updates the camera position based on the current frame.
+
+Unless I ask for it, do not jump between camera angles.
+
+```tsx
+import * as turf from "@turf/turf";
+import { interpolate } from "remotion";
+import { Easing } from "remotion";
+import { useCurrentFrame, useVideoConfig, useDelayRender } from "remotion";
+
+const animationDuration = 20;
+const cameraAltitude = 4000;
+```
+
+```tsx
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+const { delayRender, continueRender } = useDelayRender();
+
+useEffect(() => {
+  if (!map) {
+    return;
+  }
+  const handle = delayRender("Moving point...");
+
+  const routeDistance = turf.length(turf.lineString(lineCoordinates));
+
+  const progress = interpolate(
+    frame / fps,
+    [0.00001, animationDuration],
+    [0, 1],
+    {
+      easing: Easing.inOut(Easing.sin),
+      extrapolateLeft: "clamp",
+      extrapolateRight: "clamp",
+    },
+  );
+
+  const camera = map.getFreeCameraOptions();
+
+  const alongRoute = turf.along(
+    turf.lineString(lineCoordinates),
+    routeDistance * progress,
+  ).geometry.coordinates;
+
+  camera.lookAtPoint({
+    lng: alongRoute[0],
+    lat: alongRoute[1],
+  });
+
+  map.setFreeCameraOptions(camera);
+  map.once("idle", () => continueRender(handle));
+}, [lineCoordinates, fps, frame, handle, map]);
+```
+
+Notes:
+
+IMPORTANT: Keep the camera by default so north is up.
+IMPORTANT: For multi-step animations, set all properties at all stages (zoom, position, line progress) to prevent jumps. Override initial values.
+
+- The progress is clamped to a minimum value to avoid the line being empty, which can lead to turf errors
+- See [Timing](./timing.md) for more options for timing.
+- Consider the dimensions of the composition and make the lines thick enough and the label font size large enough to be legible for when the composition is scaled down.
+
+## Animating lines
+
+### Straight lines (linear interpolation)
+
+To animate a line that appears straight on the map, use linear interpolation between coordinates. Do NOT use turf's `lineSliceAlong` or `along` functions, as they use geodesic (great circle) calculations which appear curved on a Mercator projection.
+
+```tsx
+const frame = useCurrentFrame();
+const { durationInFrames } = useVideoConfig();
+
+useEffect(() => {
+  if (!map) return;
+
+  const animationHandle = delayRender("Animating line...");
+
+  const progress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
+    extrapolateLeft: "clamp",
+    extrapolateRight: "clamp",
+    easing: Easing.inOut(Easing.cubic),
+  });
+
+  // Linear interpolation for a straight line on the map
+  const start = lineCoordinates[0];
+  const end = lineCoordinates[1];
+  const currentLng = start[0] + (end[0] - start[0]) * progress;
+  const currentLat = start[1] + (end[1] - start[1]) * progress;
+
+  const lineData: GeoJSON.Feature<GeoJSON.LineString> = {
+    type: "Feature",
+    properties: {},
+    geometry: {
+      type: "LineString",
+      coordinates: [start, [currentLng, currentLat]],
+    },
+  };
+
+  const source = map.getSource("trace") as mapboxgl.GeoJSONSource;
+  if (source) {
+    source.setData(lineData);
+  }
+
+  map.once("idle", () => continueRender(animationHandle));
+}, [frame, map, durationInFrames]);
+```
+
+### Curved lines (geodesic/great circle)
+
+To animate a line that follows the geodesic (great circle) path between two points, use turf's `lineSliceAlong`. This is useful for showing flight paths or the actual shortest distance on Earth.
+
+```tsx
+import * as turf from "@turf/turf";
+
+const routeLine = turf.lineString(lineCoordinates);
+const routeDistance = turf.length(routeLine);
+
+const currentDistance = Math.max(0.001, routeDistance * progress);
+const slicedLine = turf.lineSliceAlong(routeLine, 0, currentDistance);
+
+const source = map.getSource("route") as mapboxgl.GeoJSONSource;
+if (source) {
+  source.setData(slicedLine);
+}
+```
+
+## Markers
+
+Add labels, and markers where appropriate.
+
+```tsx
+_map.addSource("markers", {
+  type: "geojson",
+  data: {
+    type: "FeatureCollection",
+    features: [
+      {
+        type: "Feature",
+        properties: { name: "Point 1" },
+        geometry: { type: "Point", coordinates: [-118.2437, 34.0522] },
+      },
+    ],
+  },
+});
+
+_map.addLayer({
+  id: "city-markers",
+  type: "circle",
+  source: "markers",
+  paint: {
+    "circle-radius": 40,
+    "circle-color": "#FF4444",
+    "circle-stroke-width": 4,
+    "circle-stroke-color": "#FFFFFF",
+  },
+});
+
+_map.addLayer({
+  id: "labels",
+  type: "symbol",
+  source: "markers",
+  layout: {
+    "text-field": ["get", "name"],
+    "text-font": ["DIN Pro Bold", "Arial Unicode MS Bold"],
+    "text-size": 50,
+    "text-offset": [0, 0.5],
+    "text-anchor": "top",
+  },
+  paint: {
+    "text-color": "#FFFFFF",
+    "text-halo-color": "#000000",
+    "text-halo-width": 2,
+  },
+});
+```
+
+Make sure they are big enough. Check the composition dimensions and scale the labels accordingly.
+For a composition size of 1920x1080, the label font size should be at least 40px.
+
+IMPORTANT: Keep the `text-offset` small enough so it is close to the marker. Consider the marker circle radius. For a circle radius of 40, this is a good offset:
+
+```tsx
+"text-offset": [0, 0.5],
+```
+
+## 3D buildings
+
+To enable 3D buildings, use the following code:
+
+```tsx
+_map.setConfigProperty("basemap", "show3dObjects", true);
+_map.setConfigProperty("basemap", "show3dLandmarks", true);
+_map.setConfigProperty("basemap", "show3dBuildings", true);
+```
+
+## Rendering
+
+When rendering a map animation, make sure to render with the following flags:
+
+```
+npx remotion render --gl=angle --concurrency=1
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/measuring-dom-nodes.md b/builtin-skills/Video-maker/remotion-best-practices/rules/measuring-dom-nodes.md
new file mode 100644
index 00000000..4e63424f
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/measuring-dom-nodes.md
@@ -0,0 +1,34 @@
+---
+name: measuring-dom-nodes
+description: Measuring DOM element dimensions in Remotion
+metadata:
+  tags: measure, layout, dimensions, getBoundingClientRect, scale
+---
+
+# Measuring DOM nodes in Remotion
+
+Remotion applies a `scale()` transform to the video container, which affects values from `getBoundingClientRect()`. Use `useCurrentScale()` to get correct measurements.
+
+## Measuring element dimensions
+
+```tsx
+import { useCurrentScale } from "remotion";
+import { useRef, useEffect, useState } from "react";
+
+export const MyComponent = () => {
+  const ref = useRef<HTMLDivElement>(null);
+  const scale = useCurrentScale();
+  const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
+
+  useEffect(() => {
+    if (!ref.current) return;
+    const rect = ref.current.getBoundingClientRect();
+    setDimensions({
+      width: rect.width / scale,
+      height: rect.height / scale,
+    });
+  }, [scale]);
+
+  return <div ref={ref}>Content to measure</div>;
+};
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/measuring-text.md b/builtin-skills/Video-maker/remotion-best-practices/rules/measuring-text.md
new file mode 100644
index 00000000..070a184b
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/measuring-text.md
@@ -0,0 +1,140 @@
+---
+name: measuring-text
+description: Measuring text dimensions, fitting text to containers, and checking overflow
+metadata:
+  tags: measure, text, layout, dimensions, fitText, fillTextBox
+---
+
+# Measuring text in Remotion
+
+## Prerequisites
+
+Install @remotion/layout-utils if it is not already installed:
+
+```bash
+npx remotion add @remotion/layout-utils
+```
+
+## Measuring text dimensions
+
+Use `measureText()` to calculate the width and height of text:
+
+```tsx
+import { measureText } from "@remotion/layout-utils";
+
+const { width, height } = measureText({
+  text: "Hello World",
+  fontFamily: "Arial",
+  fontSize: 32,
+  fontWeight: "bold",
+});
+```
+
+Results are cached - duplicate calls return the cached result.
+
+## Fitting text to a width
+
+Use `fitText()` to find the optimal font size for a container:
+
+```tsx
+import { fitText } from "@remotion/layout-utils";
+
+const { fontSize } = fitText({
+  text: "Hello World",
+  withinWidth: 600,
+  fontFamily: "Inter",
+  fontWeight: "bold",
+});
+
+return (
+  <div
+    style={{
+      fontSize: Math.min(fontSize, 80), // Cap at 80px
+      fontFamily: "Inter",
+      fontWeight: "bold",
+    }}
+  >
+    Hello World
+  </div>
+);
+```
+
+## Checking text overflow
+
+Use `fillTextBox()` to check if text exceeds a box:
+
+```tsx
+import { fillTextBox } from "@remotion/layout-utils";
+
+const box = fillTextBox({ maxBoxWidth: 400, maxLines: 3 });
+
+const words = ["Hello", "World", "This", "is", "a", "test"];
+for (const word of words) {
+  const { exceedsBox } = box.add({
+    text: word + " ",
+    fontFamily: "Arial",
+    fontSize: 24,
+  });
+  if (exceedsBox) {
+    // Text would overflow, handle accordingly
+    break;
+  }
+}
+```
+
+## Best practices
+
+**Load fonts first:** Only call measurement functions after fonts are loaded.
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Inter";
+
+const { fontFamily, waitUntilDone } = loadFont("normal", {
+  weights: ["400"],
+  subsets: ["latin"],
+});
+
+waitUntilDone().then(() => {
+  // Now safe to measure
+  const { width } = measureText({
+    text: "Hello",
+    fontFamily,
+    fontSize: 32,
+  });
+});
+```
+
+**Use validateFontIsLoaded:** Catch font loading issues early:
+
+```tsx
+measureText({
+  text: "Hello",
+  fontFamily: "MyCustomFont",
+  fontSize: 32,
+  validateFontIsLoaded: true, // Throws if font not loaded
+});
+```
+
+**Match font properties:** Use the same properties for measurement and rendering:
+
+```tsx
+const fontStyle = {
+  fontFamily: "Inter",
+  fontSize: 32,
+  fontWeight: "bold" as const,
+  letterSpacing: "0.5px",
+};
+
+const { width } = measureText({
+  text: "Hello",
+  ...fontStyle,
+});
+
+return <div style={fontStyle}>Hello</div>;
+```
+
+**Avoid padding and border:** Use `outline` instead of `border` to prevent layout differences:
+
+```tsx
+<div style={{ outline: "2px solid red" }}>Text</div>
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/parameters.md b/builtin-skills/Video-maker/remotion-best-practices/rules/parameters.md
new file mode 100644
index 00000000..88608006
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/parameters.md
@@ -0,0 +1,109 @@
+---
+name: parameters
+description: Make a video parametrizable by adding a Zod schema
+metadata:
+  tags: parameters, zod, schema
+---
+
+To make a video parametrizable, a Zod schema can be added to a composition.
+
+First, `zod` must be installed .
+
+Search the project for lockfiles and run the correct command depending on the package manager:
+
+If `package-lock.json` is found, use the following command:
+
+```bash
+npm i zod
+```
+
+If `bun.lockb` is found, use the following command:
+
+```bash
+bun i zod
+```
+
+If `yarn.lock` is found, use the following command:
+
+```bash
+yarn add zod
+```
+
+If `pnpm-lock.yaml` is found, use the following command:
+
+```bash
+pnpm i zod
+```
+
+Then, a Zod schema can be defined alongside the component:
+
+```tsx title="src/MyComposition.tsx"
+import { z } from "zod";
+
+export const MyCompositionSchema = z.object({
+  title: z.string(),
+});
+
+const MyComponent: React.FC<z.infer<typeof MyCompositionSchema>> = () => {
+  return (
+    <div>
+      <h1>{props.title}</h1>
+    </div>
+  );
+};
+```
+
+In the root file, the schema can be passed to the composition:
+
+```tsx title="src/Root.tsx"
+import { Composition } from "remotion";
+import { MycComponent, MyCompositionSchema } from "./MyComposition";
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComponent}
+      durationInFrames={100}
+      fps={30}
+      width={1080}
+      height={1080}
+      defaultProps={{ title: "Hello World" }}
+      schema={MyCompositionSchema}
+    />
+  );
+};
+```
+
+Now, the user can edit the parameter visually in the sidebar.
+
+All schemas that are supported by Zod are supported by Remotion.
+
+Remotion requires that the top-level type is a z.object(), because the collection of props of a React component is always an object.
+
+## Color picker
+
+For adding a color picker, use `zColor()` from `@remotion/zod-types`.
+
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/zod-types # If project uses npm
+bunx remotion add @remotion/zod-types # If project uses bun
+yarn remotion add @remotion/zod-types # If project uses yarn
+pnpm exec remotion add @remotion/zod-types # If project uses pnpm
+```
+
+Then import `zColor` from `@remotion/zod-types`:
+
+```tsx
+import { zColor } from "@remotion/zod-types";
+```
+
+Then use it in the schema:
+
+```tsx
+export const MyCompositionSchema = z.object({
+  color: zColor(),
+});
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/sequencing.md b/builtin-skills/Video-maker/remotion-best-practices/rules/sequencing.md
new file mode 100644
index 00000000..46b86a88
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/sequencing.md
@@ -0,0 +1,118 @@
+---
+name: sequencing
+description: Sequencing patterns for Remotion - delay, trim, limit duration of items
+metadata:
+  tags: sequence, series, timing, delay, trim
+---
+
+Use `<Sequence>` to delay when an element appears in the timeline.
+
+```tsx
+import { Sequence } from "remotion";
+
+const {fps} = useVideoConfig();
+
+<Sequence from={1 * fps} durationInFrames={2 * fps} premountFor={1 * fps}>
+  <Title />
+</Sequence>
+<Sequence from={2 * fps} durationInFrames={2 * fps} premountFor={1 * fps}>
+  <Subtitle />
+</Sequence>
+```
+
+This will by default wrap the component in an absolute fill element.  
+If the items should not be wrapped, use the `layout` prop:
+
+```tsx
+<Sequence layout="none">
+  <Title />
+</Sequence>
+```
+
+## Premounting
+
+This loads the component in the timeline before it is actually played.  
+Always premount any `<Sequence>`!
+
+```tsx
+<Sequence premountFor={1 * fps}>
+  <Title />
+</Sequence>
+```
+
+## Series
+
+Use `<Series>` when elements should play one after another without overlap.
+
+```tsx
+import { Series } from "remotion";
+
+<Series>
+  <Series.Sequence durationInFrames={45}>
+    <Intro />
+  </Series.Sequence>
+  <Series.Sequence durationInFrames={60}>
+    <MainContent />
+  </Series.Sequence>
+  <Series.Sequence durationInFrames={30}>
+    <Outro />
+  </Series.Sequence>
+</Series>;
+```
+
+Same as with `<Sequence>`, the items will be wrapped in an absolute fill element by default when using `<Series.Sequence>`, unless the `layout` prop is set to `none`.
+
+### Series with overlaps
+
+Use negative offset for overlapping sequences:
+
+```tsx
+<Series>
+  <Series.Sequence durationInFrames={60}>
+    <SceneA />
+  </Series.Sequence>
+  <Series.Sequence offset={-15} durationInFrames={60}>
+    {/* Starts 15 frames before SceneA ends */}
+    <SceneB />
+  </Series.Sequence>
+</Series>
+```
+
+## Frame References Inside Sequences
+
+Inside a Sequence, `useCurrentFrame()` returns the local frame (starting from 0):
+
+```tsx
+<Sequence from={60} durationInFrames={30}>
+  <MyComponent />
+  {/* Inside MyComponent, useCurrentFrame() returns 0-29, not 60-89 */}
+</Sequence>
+```
+
+## Nested Sequences
+
+Sequences can be nested for complex timing:
+
+```tsx
+<Sequence from={0} durationInFrames={120}>
+  <Background />
+  <Sequence from={15} durationInFrames={90} layout="none">
+    <Title />
+  </Sequence>
+  <Sequence from={45} durationInFrames={60} layout="none">
+    <Subtitle />
+  </Sequence>
+</Sequence>
+```
+
+## Nesting compositions within another
+
+To add a composition within another composition, you can use the `<Sequence>` component with a `width` and `height` prop to specify the size of the composition.
+
+```tsx
+<AbsoluteFill>
+  <Sequence width={COMPOSITION_WIDTH} height={COMPOSITION_HEIGHT}>
+    <CompositionComponent />
+  </Sequence>
+</AbsoluteFill>
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/sfx.md b/builtin-skills/Video-maker/remotion-best-practices/rules/sfx.md
new file mode 100644
index 00000000..41fdc500
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/sfx.md
@@ -0,0 +1,30 @@
+---
+name: sfx
+description: Including sound effects
+metadata:
+  tags: sfx, sound, effect, audio
+---
+
+To include a sound effect, use the `<Audio>` tag:
+
+```tsx
+import { Audio } from "@remotion/sfx";
+
+<Audio src={"https://remotion.media/whoosh.wav"} />;
+```
+
+The following sound effects are available:
+
+- `https://remotion.media/whoosh.wav`
+- `https://remotion.media/whip.wav`
+- `https://remotion.media/page-turn.wav`
+- `https://remotion.media/switch.wav`
+- `https://remotion.media/mouse-click.wav`
+- `https://remotion.media/shutter-modern.wav`
+- `https://remotion.media/shutter-old.wav`
+- `https://remotion.media/ding.wav`
+- `https://remotion.media/bruh.wav`
+- `https://remotion.media/vine-boom.wav`
+- `https://remotion.media/windows-xp-error.wav`
+
+For more sound effects, search the internet. A good resource is https://github.com/kapishdima/soundcn/tree/main/assets.
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/subtitles.md b/builtin-skills/Video-maker/remotion-best-practices/rules/subtitles.md
new file mode 100644
index 00000000..2291eef3
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/subtitles.md
@@ -0,0 +1,36 @@
+---
+name: subtitles
+description: subtitles and caption rules
+metadata:
+  tags: subtitles, captions, remotion, json
+---
+
+All captions must be processed in JSON. The captions must use the `Caption` type which is the following:
+
+```ts
+import type { Caption } from "@remotion/captions";
+```
+
+This is the definition:
+
+```ts
+type Caption = {
+  text: string;
+  startMs: number;
+  endMs: number;
+  timestampMs: number | null;
+  confidence: number | null;
+};
+```
+
+## Generating captions
+
+To transcribe video and audio files to generate captions, load the [./transcribe-captions.md](./transcribe-captions.md) file for more instructions.
+
+## Displaying captions
+
+To display captions in your video, load the [./display-captions.md](./display-captions.md) file for more instructions.
+
+## Importing captions
+
+To import captions from a .srt file, load the [./import-srt-captions.md](./import-srt-captions.md) file for more instructions.
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/tailwind.md b/builtin-skills/Video-maker/remotion-best-practices/rules/tailwind.md
new file mode 100644
index 00000000..928f6331
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/tailwind.md
@@ -0,0 +1,11 @@
+---
+name: tailwind
+description: Using TailwindCSS in Remotion.
+metadata:
+---
+
+You can and should use TailwindCSS in Remotion, if TailwindCSS is installed in the project.
+
+Don't use `transition-*` or `animate-*` classes - always animate using the `useCurrentFrame()` hook.
+
+Tailwind must be installed and enabled first in a Remotion project - fetch https://www.remotion.dev/docs/tailwind using WebFetch for instructions.
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/text-animations.md b/builtin-skills/Video-maker/remotion-best-practices/rules/text-animations.md
new file mode 100644
index 00000000..e38b1c57
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/text-animations.md
@@ -0,0 +1,20 @@
+---
+name: text-animations
+description: Typography and text animation patterns for Remotion.
+metadata:
+  tags: typography, text, typewriter, highlighter ken
+---
+
+## Text animations
+
+Based on `useCurrentFrame()`, reduce the string character by character to create a typewriter effect.
+
+## Typewriter Effect
+
+See [Typewriter](assets/text-animations-typewriter.tsx) for an advanced example with a blinking cursor and a pause after the first sentence.
+
+Always use string slicing for typewriter effects. Never use per-character opacity.
+
+## Word Highlighting
+
+See [Word Highlight](assets/text-animations-word-highlight.tsx) for an example for how a word highlight is animated, like with a highlighter pen.
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/timing.md b/builtin-skills/Video-maker/remotion-best-practices/rules/timing.md
new file mode 100644
index 00000000..a7b49876
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/timing.md
@@ -0,0 +1,179 @@
+---
+name: timing
+description: Interpolation curves in Remotion - linear, easing, spring animations
+metadata:
+  tags: spring, bounce, easing, interpolation
+---
+
+A simple linear interpolation is done using the `interpolate` function.
+
+```ts title="Going from 0 to 1 over 100 frames"
+import { interpolate } from "remotion";
+
+const opacity = interpolate(frame, [0, 100], [0, 1]);
+```
+
+By default, the values are not clamped, so the value can go outside the range [0, 1].  
+Here is how they can be clamped:
+
+```ts title="Going from 0 to 1 over 100 frames with extrapolation"
+const opacity = interpolate(frame, [0, 100], [0, 1], {
+  extrapolateRight: "clamp",
+  extrapolateLeft: "clamp",
+});
+```
+
+## Spring animations
+
+Spring animations have a more natural motion.  
+They go from 0 to 1 over time.
+
+```ts title="Spring animation from 0 to 1 over 100 frames"
+import { spring, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const scale = spring({
+  frame,
+  fps,
+});
+```
+
+### Physical properties
+
+The default configuration is: `mass: 1, damping: 10, stiffness: 100`.  
+This leads to the animation having a bit of bounce before it settles.
+
+The config can be overwritten like this:
+
+```ts
+const scale = spring({
+  frame,
+  fps,
+  config: { damping: 200 },
+});
+```
+
+The recommended configuration for a natural motion without a bounce is: `{ damping: 200 }`.
+
+Here are some common configurations:
+
+```tsx
+const smooth = { damping: 200 }; // Smooth, no bounce (subtle reveals)
+const snappy = { damping: 20, stiffness: 200 }; // Snappy, minimal bounce (UI elements)
+const bouncy = { damping: 8 }; // Bouncy entrance (playful animations)
+const heavy = { damping: 15, stiffness: 80, mass: 2 }; // Heavy, slow, small bounce
+```
+
+### Delay
+
+The animation starts immediately by default.  
+Use the `delay` parameter to delay the animation by a number of frames.
+
+```tsx
+const entrance = spring({
+  frame: frame - ENTRANCE_DELAY,
+  fps,
+  delay: 20,
+});
+```
+
+### Duration
+
+A `spring()` has a natural duration based on the physical properties.  
+To stretch the animation to a specific duration, use the `durationInFrames` parameter.
+
+```tsx
+const spring = spring({
+  frame,
+  fps,
+  durationInFrames: 40,
+});
+```
+
+### Combining spring() with interpolate()
+
+Map spring output (0-1) to custom ranges:
+
+```tsx
+const springProgress = spring({
+  frame,
+  fps,
+});
+
+// Map to rotation
+const rotation = interpolate(springProgress, [0, 1], [0, 360]);
+
+<div style={{ rotate: rotation + "deg" }} />;
+```
+
+### Adding springs
+
+Springs return just numbers, so math can be performed:
+
+```tsx
+const frame = useCurrentFrame();
+const { fps, durationInFrames } = useVideoConfig();
+
+const inAnimation = spring({
+  frame,
+  fps,
+});
+const outAnimation = spring({
+  frame,
+  fps,
+  durationInFrames: 1 * fps,
+  delay: durationInFrames - 1 * fps,
+});
+
+const scale = inAnimation - outAnimation;
+```
+
+## Easing
+
+Easing can be added to the `interpolate` function:
+
+```ts
+import { interpolate, Easing } from "remotion";
+
+const value1 = interpolate(frame, [0, 100], [0, 1], {
+  easing: Easing.inOut(Easing.quad),
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+```
+
+The default easing is `Easing.linear`.  
+There are various other convexities:
+
+- `Easing.in` for starting slow and accelerating
+- `Easing.out` for starting fast and slowing down
+- `Easing.inOut`
+
+and curves (sorted from most linear to most curved):
+
+- `Easing.quad`
+- `Easing.sin`
+- `Easing.exp`
+- `Easing.circle`
+
+Convexities and curves need be combined for an easing function:
+
+```ts
+const value1 = interpolate(frame, [0, 100], [0, 1], {
+  easing: Easing.inOut(Easing.quad),
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+```
+
+Cubic bezier curves are also supported:
+
+```ts
+const value1 = interpolate(frame, [0, 100], [0, 1], {
+  easing: Easing.bezier(0.8, 0.22, 0.96, 0.65),
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/transcribe-captions.md b/builtin-skills/Video-maker/remotion-best-practices/rules/transcribe-captions.md
new file mode 100644
index 00000000..ba649d57
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/transcribe-captions.md
@@ -0,0 +1,70 @@
+---
+name: transcribe-captions
+description: Transcribing audio to generate captions in Remotion
+metadata:
+  tags: captions, transcribe, whisper, audio, speech-to-text
+---
+
+# Transcribing audio
+
+To transcribe audio to generate captions in Remotion, you can use the [`transcribe()`](https://www.remotion.dev/docs/install-whisper-cpp/transcribe) function from the [`@remotion/install-whisper-cpp`](https://www.remotion.dev/docs/install-whisper-cpp) package.
+
+## Prerequisites
+
+First, the @remotion/install-whisper-cpp package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/install-whisper-cpp
+```
+
+## Transcribing
+
+Make a Node.js script to download Whisper.cpp and a model, and transcribe the audio.
+
+```ts
+import path from "path";
+import {
+  downloadWhisperModel,
+  installWhisperCpp,
+  transcribe,
+  toCaptions,
+} from "@remotion/install-whisper-cpp";
+import fs from "fs";
+
+const to = path.join(process.cwd(), "whisper.cpp");
+
+await installWhisperCpp({
+  to,
+  version: "1.5.5",
+});
+
+await downloadWhisperModel({
+  model: "medium.en",
+  folder: to,
+});
+
+// Convert the audio to a 16KHz wav file first if needed:
+// import {execSync} from 'child_process';
+// execSync('ffmpeg -i /path/to/audio.mp4 -ar 16000 /path/to/audio.wav -y');
+
+const whisperCppOutput = await transcribe({
+  model: "medium.en",
+  whisperPath: to,
+  whisperCppVersion: "1.5.5",
+  inputPath: "/path/to/audio123.wav",
+  tokenLevelTimestamps: true,
+});
+
+// Optional: Apply our recommended postprocessing
+const { captions } = toCaptions({
+  whisperCppOutput,
+});
+
+// Write it to the public/ folder so it can be fetched from Remotion
+fs.writeFileSync("captions123.json", JSON.stringify(captions, null, 2));
+```
+
+Transcribe each clip individually and create multiple JSON files.
+
+See [Displaying captions](display-captions.md) for how to display the captions in Remotion.
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/transitions.md b/builtin-skills/Video-maker/remotion-best-practices/rules/transitions.md
new file mode 100644
index 00000000..91ef8bd8
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/transitions.md
@@ -0,0 +1,197 @@
+---
+name: transitions
+description: Scene transitions and overlays for Remotion using TransitionSeries.
+metadata:
+  tags: transitions, overlays, fade, slide, wipe, scenes
+---
+
+## TransitionSeries
+
+`<TransitionSeries>` arranges scenes and supports two ways to enhance the cut point between them:
+
+- **Transitions** (`<TransitionSeries.Transition>`) — crossfade, slide, wipe, etc. between two scenes. Shortens the timeline because both scenes play simultaneously during the transition.
+- **Overlays** (`<TransitionSeries.Overlay>`) — render an effect (e.g. a light leak) on top of the cut point without shortening the timeline.
+
+Children are absolutely positioned.
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/transitions
+```
+
+## Transition example
+
+```tsx
+import { TransitionSeries, linearTiming } from "@remotion/transitions";
+import { fade } from "@remotion/transitions/fade";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={fade()}
+    timing={linearTiming({ durationInFrames: 15 })}
+  />
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Overlay example
+
+Any React component can be used as an overlay. For a ready-made effect, see the **light-leaks** rule.
+
+```tsx
+import { TransitionSeries } from "@remotion/transitions";
+import { LightLeak } from "@remotion/light-leaks";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Overlay durationInFrames={20}>
+    <LightLeak />
+  </TransitionSeries.Overlay>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Mixing transitions and overlays
+
+Transitions and overlays can coexist in the same `<TransitionSeries>`, but an overlay cannot be adjacent to a transition or another overlay.
+
+```tsx
+import { TransitionSeries, linearTiming } from "@remotion/transitions";
+import { fade } from "@remotion/transitions/fade";
+import { LightLeak } from "@remotion/light-leaks";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Overlay durationInFrames={30}>
+    <LightLeak />
+  </TransitionSeries.Overlay>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={fade()}
+    timing={linearTiming({ durationInFrames: 15 })}
+  />
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneC />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Transition props
+
+`<TransitionSeries.Transition>` requires:
+
+- `presentation` — the visual effect (e.g. `fade()`, `slide()`, `wipe()`).
+- `timing` — controls speed and easing (e.g. `linearTiming()`, `springTiming()`).
+
+## Overlay props
+
+`<TransitionSeries.Overlay>` accepts:
+
+- `durationInFrames` — how long the overlay is visible (positive integer).
+- `offset?` — shifts the overlay relative to the cut point center. Positive = later, negative = earlier. Default: `0`.
+
+## Available transition types
+
+Import transitions from their respective modules:
+
+```tsx
+import { fade } from "@remotion/transitions/fade";
+import { slide } from "@remotion/transitions/slide";
+import { wipe } from "@remotion/transitions/wipe";
+import { flip } from "@remotion/transitions/flip";
+import { clockWipe } from "@remotion/transitions/clock-wipe";
+```
+
+## Slide transition with direction
+
+```tsx
+import { slide } from "@remotion/transitions/slide";
+
+<TransitionSeries.Transition
+  presentation={slide({ direction: "from-left" })}
+  timing={linearTiming({ durationInFrames: 20 })}
+/>;
+```
+
+Directions: `"from-left"`, `"from-right"`, `"from-top"`, `"from-bottom"`
+
+## Timing options
+
+```tsx
+import { linearTiming, springTiming } from "@remotion/transitions";
+
+// Linear timing - constant speed
+linearTiming({ durationInFrames: 20 });
+
+// Spring timing - organic motion
+springTiming({ config: { damping: 200 }, durationInFrames: 25 });
+```
+
+## Duration calculation
+
+Transitions overlap adjacent scenes, so the total composition length is **shorter** than the sum of all sequence durations. Overlays do **not** affect the total duration.
+
+For example, with two 60-frame sequences and a 15-frame transition:
+
+- Without transitions: `60 + 60 = 120` frames
+- With transition: `60 + 60 - 15 = 105` frames
+
+Adding an overlay between two other sequences does not change the total.
+
+### Getting the duration of a transition
+
+Use the `getDurationInFrames()` method on the timing object:
+
+```tsx
+import { linearTiming, springTiming } from "@remotion/transitions";
+
+const linearDuration = linearTiming({
+  durationInFrames: 20,
+}).getDurationInFrames({ fps: 30 });
+// Returns 20
+
+const springDuration = springTiming({
+  config: { damping: 200 },
+}).getDurationInFrames({ fps: 30 });
+// Returns calculated duration based on spring physics
+```
+
+For `springTiming` without an explicit `durationInFrames`, the duration depends on `fps` because it calculates when the spring animation settles.
+
+### Calculating total composition duration
+
+```tsx
+import { linearTiming } from "@remotion/transitions";
+
+const scene1Duration = 60;
+const scene2Duration = 60;
+const scene3Duration = 60;
+
+const timing1 = linearTiming({ durationInFrames: 15 });
+const timing2 = linearTiming({ durationInFrames: 20 });
+
+const transition1Duration = timing1.getDurationInFrames({ fps: 30 });
+const transition2Duration = timing2.getDurationInFrames({ fps: 30 });
+
+const totalDuration =
+  scene1Duration +
+  scene2Duration +
+  scene3Duration -
+  transition1Duration -
+  transition2Duration;
+// 60 + 60 + 60 - 15 - 20 = 145 frames
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/transparent-videos.md b/builtin-skills/Video-maker/remotion-best-practices/rules/transparent-videos.md
new file mode 100644
index 00000000..dce5de50
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/transparent-videos.md
@@ -0,0 +1,106 @@
+---
+name: transparent-videos
+description: Rendering transparent videos in Remotion
+metadata:
+  tags: transparent, alpha, codec, vp9, prores, webm
+---
+
+# Rendering Transparent Videos
+
+Remotion can render transparent videos in two ways: as a ProRes video or as a WebM video.
+
+## Transparent ProRes
+
+Ideal for when importing into video editing software.
+
+**CLI:**
+
+```bash
+npx remotion render --image-format=png --pixel-format=yuva444p10le --codec=prores --prores-profile=4444 MyComp out.mov
+```
+
+**Default in Studio** (restart Studio after changing):
+
+```ts
+// remotion.config.ts
+import { Config } from "@remotion/cli/config";
+
+Config.setVideoImageFormat("png");
+Config.setPixelFormat("yuva444p10le");
+Config.setCodec("prores");
+Config.setProResProfile("4444");
+```
+
+**Setting it as the default export settings for a composition** (using `calculateMetadata`):
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultCodec: "prores",
+    defaultVideoImageFormat: "png",
+    defaultPixelFormat: "yuva444p10le",
+    defaultProResProfile: "4444",
+  };
+};
+
+<Composition
+  id="my-video"
+  component={MyVideo}
+  durationInFrames={150}
+  fps={30}
+  width={1920}
+  height={1080}
+  calculateMetadata={calculateMetadata}
+/>;
+```
+
+## Transparent WebM (VP9)
+
+Ideal for when playing in a browser.
+
+**CLI:**
+
+```bash
+npx remotion render --image-format=png --pixel-format=yuva420p --codec=vp9 MyComp out.webm
+```
+
+**Default in Studio** (restart Studio after changing):
+
+```ts
+// remotion.config.ts
+import { Config } from "@remotion/cli/config";
+
+Config.setVideoImageFormat("png");
+Config.setPixelFormat("yuva420p");
+Config.setCodec("vp9");
+```
+
+**Setting it as the default export settings for a composition** (using `calculateMetadata`):
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultCodec: "vp8",
+    defaultVideoImageFormat: "png",
+    defaultPixelFormat: "yuva420p",
+  };
+};
+
+<Composition
+  id="my-video"
+  component={MyVideo}
+  durationInFrames={150}
+  fps={30}
+  width={1920}
+  height={1080}
+  calculateMetadata={calculateMetadata}
+/>;
+```
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/trimming.md b/builtin-skills/Video-maker/remotion-best-practices/rules/trimming.md
new file mode 100644
index 00000000..e7534d1c
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/trimming.md
@@ -0,0 +1,51 @@
+---
+name: trimming
+description: Trimming patterns for Remotion - cut the beginning or end of animations
+metadata:
+  tags: sequence, trim, clip, cut, offset
+---
+
+Use `<Sequence>` with a negative `from` value to trim the start of an animation.
+
+## Trim the Beginning
+
+A negative `from` value shifts time backwards, making the animation start partway through:
+
+```tsx
+import { Sequence, useVideoConfig } from "remotion";
+
+const fps = useVideoConfig();
+
+<Sequence from={-0.5 * fps}>
+  <MyAnimation />
+</Sequence>;
+```
+
+The animation appears 15 frames into its progress - the first 15 frames are trimmed off.
+Inside `<MyAnimation>`, `useCurrentFrame()` starts at 15 instead of 0.
+
+## Trim the End
+
+Use `durationInFrames` to unmount content after a specified duration:
+
+```tsx
+<Sequence durationInFrames={1.5 * fps}>
+  <MyAnimation />
+</Sequence>
+```
+
+The animation plays for 45 frames, then the component unmounts.
+
+## Trim and Delay
+
+Nest sequences to both trim the beginning and delay when it appears:
+
+```tsx
+<Sequence from={30}>
+  <Sequence from={-15}>
+    <MyAnimation />
+  </Sequence>
+</Sequence>
+```
+
+The inner sequence trims 15 frames from the start, and the outer sequence delays the result by 30 frames.
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/videos.md b/builtin-skills/Video-maker/remotion-best-practices/rules/videos.md
new file mode 100644
index 00000000..4d99b31e
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/videos.md
@@ -0,0 +1,171 @@
+---
+name: videos
+description: Embedding videos in Remotion - trimming, volume, speed, looping, pitch
+metadata:
+  tags: video, media, trim, volume, speed, loop, pitch
+---
+
+# Using videos in Remotion
+
+## Prerequisites
+
+First, the @remotion/media package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/media # If project uses npm
+bunx remotion add @remotion/media # If project uses bun
+yarn remotion add @remotion/media # If project uses yarn
+pnpm exec remotion add @remotion/media # If project uses pnpm
+```
+
+Use `<Video>` from `@remotion/media` to embed videos into your composition.
+
+```tsx
+import { Video } from "@remotion/media";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Video src={staticFile("video.mp4")} />;
+};
+```
+
+Remote URLs are also supported:
+
+```tsx
+<Video src="https://remotion.media/video.mp4" />
+```
+
+## Trimming
+
+Use `trimBefore` and `trimAfter` to remove portions of the video. Values are in seconds.
+
+```tsx
+const { fps } = useVideoConfig();
+
+return (
+  <Video
+    src={staticFile("video.mp4")}
+    trimBefore={2 * fps} // Skip the first 2 seconds
+    trimAfter={10 * fps} // End at the 10 second mark
+  />
+);
+```
+
+## Delaying
+
+Wrap the video in a `<Sequence>` to delay when it appears:
+
+```tsx
+import { Sequence, staticFile } from "remotion";
+import { Video } from "@remotion/media";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Sequence from={1 * fps}>
+    <Video src={staticFile("video.mp4")} />
+  </Sequence>
+);
+```
+
+The video will appear after 1 second.
+
+## Sizing and Position
+
+Use the `style` prop to control size and position:
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  style={{
+    width: 500,
+    height: 300,
+    position: "absolute",
+    top: 100,
+    left: 50,
+    objectFit: "cover",
+  }}
+/>
+```
+
+## Volume
+
+Set a static volume (0 to 1):
+
+```tsx
+<Video src={staticFile("video.mp4")} volume={0.5} />
+```
+
+Or use a callback for dynamic volume based on the current frame:
+
+```tsx
+import { interpolate } from "remotion";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Video
+    src={staticFile("video.mp4")}
+    volume={(f) =>
+      interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
+    }
+  />
+);
+```
+
+Use `muted` to silence the video entirely:
+
+```tsx
+<Video src={staticFile("video.mp4")} muted />
+```
+
+## Speed
+
+Use `playbackRate` to change the playback speed:
+
+```tsx
+<Video src={staticFile("video.mp4")} playbackRate={2} /> {/* 2x speed */}
+<Video src={staticFile("video.mp4")} playbackRate={0.5} /> {/* Half speed */}
+```
+
+Reverse playback is not supported.
+
+## Looping
+
+Use `loop` to loop the video indefinitely:
+
+```tsx
+<Video src={staticFile("video.mp4")} loop />
+```
+
+Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
+
+- `"repeat"`: Frame count resets to 0 each loop (for `volume` callback)
+- `"extend"`: Frame count continues incrementing
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  loop
+  loopVolumeCurveBehavior="extend"
+  volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
+/>
+```
+
+## Pitch
+
+Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  toneFrequency={1.5} // Higher pitch
+/>
+<Video
+  src={staticFile("video.mp4")}
+  toneFrequency={0.8} // Lower pitch
+/>
+```
+
+Pitch shifting only works during server-side rendering, not in the Remotion Studio preview or in the `<Player />`.
diff --git a/builtin-skills/Video-maker/remotion-best-practices/rules/voiceover.md b/builtin-skills/Video-maker/remotion-best-practices/rules/voiceover.md
new file mode 100644
index 00000000..d7b23504
--- /dev/null
+++ b/builtin-skills/Video-maker/remotion-best-practices/rules/voiceover.md
@@ -0,0 +1,99 @@
+---
+name: voiceover
+description: Adding AI-generated voiceover to Remotion compositions using TTS
+metadata:
+  tags: voiceover, audio, elevenlabs, tts, speech, calculateMetadata, dynamic duration
+---
+
+# Adding AI voiceover to a Remotion composition
+
+Use ElevenLabs TTS to generate speech audio per scene, then use [`calculateMetadata`](./calculate-metadata) to dynamically size the composition to match the audio.
+
+## Prerequisites
+
+By default this guide uses **ElevenLabs** as the TTS provider (`ELEVENLABS_API_KEY` environment variable). Users may substitute any TTS service that can produce an audio file.
+
+If the user has not specified a TTS provider, recommend ElevenLabs and ask for their API key.
+
+Ensure the environment variable is available when running the generation script:
+
+```bash
+node --strip-types generate-voiceover.ts
+```
+
+## Generating audio with ElevenLabs
+
+Create a script that reads the config, calls the ElevenLabs API for each scene, and writes MP3 files to the `public/` directory so Remotion can access them via `staticFile()`.
+
+The core API call for a single scene:
+
+```ts title="generate-voiceover.ts"
+const response = await fetch(
+  `https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`,
+  {
+    method: "POST",
+    headers: {
+      "xi-api-key": process.env.ELEVENLABS_API_KEY!,
+      "Content-Type": "application/json",
+      Accept: "audio/mpeg",
+    },
+    body: JSON.stringify({
+      text: "Welcome to the show.",
+      model_id: "eleven_multilingual_v2",
+      voice_settings: {
+        stability: 0.5,
+        similarity_boost: 0.75,
+        style: 0.3,
+      },
+    }),
+  },
+);
+
+const audioBuffer = Buffer.from(await response.arrayBuffer());
+writeFileSync(`public/voiceover/${compositionId}/${scene.id}.mp3`, audioBuffer);
+```
+
+## Dynamic composition duration with calculateMetadata
+
+Use [`calculateMetadata`](./calculate-metadata.md) to measure the [audio durations](./get-audio-duration.md) and set the composition length accordingly.
+
+```tsx
+import { CalculateMetadataFunction, staticFile } from "remotion";
+import { getAudioDuration } from "./get-audio-duration";
+
+const FPS = 30;
+
+const SCENE_AUDIO_FILES = [
+  "voiceover/my-comp/scene-01-intro.mp3",
+  "voiceover/my-comp/scene-02-main.mp3",
+  "voiceover/my-comp/scene-03-outro.mp3",
+];
+
+export const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const durations = await Promise.all(
+    SCENE_AUDIO_FILES.map((file) => getAudioDuration(staticFile(file))),
+  );
+
+  const sceneDurations = durations.map((durationInSeconds) => {
+    return durationInSeconds * FPS;
+  });
+
+  return {
+    durationInFrames: Math.ceil(sceneDurations.reduce((sum, d) => sum + d, 0)),
+  };
+};
+```
+
+The computed `sceneDurations` are passed into the component via a `voiceover` prop so the component knows how long each scene should be.
+
+If the composition uses [`<TransitionSeries>`](./transitions.md), subtract the overlap from total duration: [./transitions.md#calculating-total-composition-duration](./transitions.md#calculating-total-composition-duration)
+
+## Rendering audio in the component
+
+See [audio.md](./audio.md) for more information on how to render audio in the component.
+
+## Delaying audio start
+
+See [audio.md#delaying](./audio.md#delaying) for more information on how to delay the audio start.
diff --git a/builtin-skills/basic-for-all/deep-research/SKILL.md b/builtin-skills/basic-for-all/deep-research/SKILL.md
new file mode 100644
index 00000000..68e6e3f4
--- /dev/null
+++ b/builtin-skills/basic-for-all/deep-research/SKILL.md
@@ -0,0 +1,281 @@
+---
+name: deep-research
+description: "Conduct comprehensive, multi-source research on any topic using web search, documentation lookup, and critical analysis. This skill should be used when users request thorough investigation, deep research, or comprehensive analysis of topics including but not limited to AI systems, technology trends, academic subjects, business strategies, or current events. | 任意のトピックに対して、Web検索、ドキュメント参照、批判的分析を用いた包括的な調査を実施。徹底的な調査、詳細なリサーチ、包括的な分析が必要な場合や、AIシステム、技術トレンド、学術的テーマ、ビジネス戦略、時事問題などについて深く知りたい場合に使用。"
+---
+
+# Deep Research Skill
+
+This skill provides a systematic approach to conducting thorough research on any topic.
+
+## Purpose
+
+Enable Claude to perform comprehensive research by:
+1. Breaking down complex topics into researchable components
+2. Using multiple information sources (web search, documentation, academic sources)
+3. Applying critical thinking to synthesize findings
+4. Presenting well-structured, evidence-based conclusions
+
+## When to Use This Skill
+
+Activate this skill when users request:
+- "Deep research on [topic]"
+- "Comprehensive analysis of [subject]"
+- "Investigate [topic] thoroughly"
+- "Research the latest information about [subject]"
+- "Gather detailed information on [topic]"
+
+**Example Topics:**
+- AI agent evaluation metrics and methodologies
+- Latest AI/ML news and developments
+- Technology stack comparisons
+- Market analysis and trends
+- Academic literature reviews
+- Best practices for specific domains
+
+## Research Process
+
+### Phase 1: Scoping & Planning
+
+**Define Research Objectives:**
+- Identify core questions to answer
+- Determine scope and boundaries
+- List key areas to investigate
+- Establish success criteria
+
+**Plan Information Sources:**
+- Web search for current information
+- Documentation (Context7) for technical details
+- Academic/industry sources for authoritative information
+- Community resources (GitHub, forums) for practical insights
+
+### Phase 2: Information Gathering
+
+**Multi-Source Search Strategy:**
+
+1. **Broad Overview Search**
+   - Use general web search for landscape understanding
+   - Identify key terms, concepts, and authorities
+   - Note publication dates for recency
+
+2. **Targeted Deep Dives**
+   - Search specific sub-topics identified in overview
+   - Look for:
+     - Official documentation
+     - Academic papers
+     - Industry reports
+     - Expert opinions
+     - Case studies
+     - Code examples (when relevant)
+
+3. **Documentation Lookup**
+   - Use Context7 for library-specific documentation
+   - Check official API references
+   - Review changelog and release notes
+
+4. **Cross-Reference Validation**
+   - Verify claims across multiple sources
+   - Check for consensus vs. outlier opinions
+   - Note conflicts or controversies
+
+### Phase 3: Critical Analysis
+
+**Apply Critical Thinking:**
+
+- **Source Credibility**
+  - Evaluate author authority
+  - Check publication/organization reputation
+  - Consider potential biases
+  - Verify publication dates for currency
+
+- **Evidence Quality**
+  - Distinguish facts from opinions
+  - Look for empirical data
+  - Assess methodology rigor
+  - Check for reproducibility
+
+- **Logical Coherence**
+  - Identify logical fallacies
+  - Check argument consistency
+  - Evaluate reasoning chains
+  - Note assumptions
+
+- **Practical Relevance**
+  - Assess real-world applicability
+  - Consider implementation challenges
+  - Evaluate cost-benefit tradeoffs
+  - Identify gaps or limitations
+
+### Phase 4: Synthesis & Presentation
+
+**Structure Findings:**
+
+1. **Executive Summary**
+   - Key findings (3-5 bullet points)
+   - Main conclusions
+   - Critical insights
+
+2. **Detailed Analysis**
+   - Organized by theme or component
+   - Evidence from multiple sources
+   - Comparative analysis where applicable
+   - Technical details as needed
+
+3. **Practical Implications**
+   - Actionable recommendations
+   - Implementation considerations
+   - Risk factors
+   - Next steps
+
+4. **Source Attribution**
+   - Cite all major sources
+   - Link to original materials
+   - Note publication dates
+   - Indicate confidence levels
+
+**Output Format:**
+
+```markdown
+# Research: [Topic]
+
+## Executive Summary
+- Key finding 1
+- Key finding 2
+- Key finding 3
+
+## Detailed Findings
+
+### [Aspect 1]
+[Analysis with sources]
+
+### [Aspect 2]
+[Analysis with sources]
+
+## Critical Analysis
+[Evaluation of evidence quality, conflicts, gaps]
+
+## Practical Implications
+[Actionable insights and recommendations]
+
+## Sources
+- [Source 1] (Date, URL)
+- [Source 2] (Date, URL)
+
+## Research Metadata
+- Search queries used: [list]
+- Sources consulted: [count]
+- Date conducted: [date]
+- Confidence level: [High/Medium/Low with explanation]
+```
+
+## Special Considerations
+
+### For AI/ML Topics
+
+- Check multiple perspectives (academic, industry, open-source)
+- Look for benchmarks and evaluation metrics
+- Review code implementations when available
+- Consider ethical implications
+- Note limitations and biases
+
+### For Current Events/News
+
+- Use recent search results (last 30 days)
+- Cross-reference multiple news sources
+- Distinguish reporting from opinion
+- Note evolving situations
+- Check for updates
+
+### For Technical Evaluations
+
+- Review official documentation first
+- Look for community experiences
+- Check GitHub issues/discussions
+- Find performance benchmarks
+- Assess maturity and support
+
+### For Business/Strategy Topics
+
+- Look for market data
+- Review competitor analysis
+- Check industry reports
+- Consider multiple frameworks
+- Assess risk factors
+
+## Quality Checklist
+
+Before concluding research, verify:
+
+- [ ] Multiple authoritative sources consulted
+- [ ] Recent information included (check dates)
+- [ ] Key perspectives represented
+- [ ] Evidence quality assessed
+- [ ] Conflicts/controversies noted
+- [ ] Practical implications identified
+- [ ] Sources properly cited
+- [ ] Confidence level stated
+- [ ] Gaps/limitations acknowledged
+- [ ] Actionable conclusions provided
+
+## Tools to Use
+
+- **WebSearch**: For general information and current events
+- **WebFetch**: For detailed content from specific URLs
+- **Context7**: For library/framework documentation
+- **Task (Explore agent)**: For multi-step investigations
+- **Critical thinking**: Throughout the process
+
+## Iteration
+
+If research reveals:
+- **Conflicting information**: Investigate further, present multiple viewpoints
+- **Insufficient information**: Expand search terms, try different sources
+- **Complex sub-topics**: Break down further and research systematically
+- **Outdated information**: Search for more recent sources
+- **Gaps in understanding**: Ask clarifying questions to user
+
+## Examples
+
+**Example 1: AI Agent Evaluation**
+
+User: "Deep research on AI agent evaluation metrics and methods"
+
+Process:
+1. Web search for "AI agent evaluation metrics 2025"
+2. Web search for "LLM agent benchmarking frameworks"
+3. Look for academic papers on agent evaluation
+4. Check GitHub for evaluation tools/frameworks
+5. Review industry reports (e.g., Stanford AI Index)
+6. Synthesize: metrics categories, methods, tools, best practices
+7. Present: structured report with sources
+
+**Example 2: Latest AI News**
+
+User: "Research the latest AI news and developments"
+
+Process:
+1. Web search for "AI news latest 2025" (last 30 days)
+2. Check multiple sources: tech news sites, AI-specific outlets, academic announcements
+3. Categorize: model releases, research breakthroughs, industry developments, policy changes
+4. Verify claims across sources
+5. Present: organized summary with dates and links
+
+**Example 3: Technology Comparison**
+
+User: "Deep research comparing Next.js and Remix for production apps"
+
+Process:
+1. Context7 for official documentation of both
+2. Web search for "Next.js vs Remix 2025 comparison"
+3. Check GitHub stars, issues, community activity
+4. Look for case studies and production usage
+5. Review performance benchmarks
+6. Analyze: feature comparison, learning curve, ecosystem, performance
+7. Present: comparative analysis with recommendations
+
+## Notes
+
+- **Time Estimate**: Allow 10-20 minutes for thorough research
+- **Iteration**: May require follow-up questions to user for focus
+- **Scope Management**: For broad topics, propose breaking into sub-topics
+- **Transparency**: Always indicate confidence level and limitations
+- **Recency**: Always note when information was published/updated
diff --git a/builtin-skills/basic-for-all/my-writing-style b/builtin-skills/basic-for-all/my-writing-style
deleted file mode 160000
index d94826e1..00000000
--- a/builtin-skills/basic-for-all/my-writing-style
+++ /dev/null
@@ -1 +0,0 @@
-Subproject commit d94826e1cd48f5403b82a5a909efdfab96221259
diff --git a/builtin-skills/basic-for-all/my-writing-style/README.md b/builtin-skills/basic-for-all/my-writing-style/README.md
new file mode 100644
index 00000000..1ef85ef4
--- /dev/null
+++ b/builtin-skills/basic-for-all/my-writing-style/README.md
@@ -0,0 +1,71 @@
+# Writing Style Skill
+
+可复用的写作风格 Skill 模板。**内置自动学习** — 从你的修改中自动提取规则，SKILL.md 越用越准。
+
+兼容 **Claude Code** + **OpenClaw (ClawHub)**。
+
+## 原理
+
+```
+AI 用 SKILL.md 写初稿 → 你改到满意 → diff 两版 → 提取规则 → 更新 SKILL.md → 下次更准
+```
+
+只要两个数据点：**original**（AI 第一版）和 **final**（你最终版）。中间改了多少轮不管。
+
+## 安装
+
+```bash
+# Claude Code
+git clone https://github.com/jzOcb/writing-style-skill.git
+cp -r writing-style-skill ~/.claude/skills/my-writing-style
+
+# OpenClaw / ClawHub
+npx clawhub@latest install jz-writing-style-skill
+```
+
+## 快速开始
+
+1. **改 SKILL.md** — 把模板里的风格规则改成你自己的（或留空，让自动学习帮你填）
+2. **让 AI 用这个 skill 写内容**
+3. **你改到满意**
+4. 记录：
+```bash
+python3 scripts/observe.py record-original draft.md
+# ... 你修改 ...
+python3 scripts/observe.py record-final final.md
+```
+5. 提取规则：
+```bash
+python3 scripts/improve.py auto --skill .
+```
+
+## 文件结构
+
+```
+writing-style-skill/
+├── SKILL.md              # 你的写作风格（模板，改成你的）
+├── README.md             # 本文件
+└── scripts/
+    ├── observe.py        # 记录 original / final（零依赖）
+    └── improve.py        # 提取 / 应用 / 回滚（需要 LLM CLI）
+```
+
+## 自动学习怎么工作
+
+- `observe.py` 记录 AI 原稿和你的最终版
+- `improve.py` 用 LLM 分析 diff，提取写作规则
+- 规则按置信度分 P0/P1/P2，P0 自动应用
+- 每次更新前自动备份，一键回滚
+
+## LLM 支持
+
+`improve.py` 自动检测：
+- `claude` (Claude Code) — 优先
+- `llm` (pip install llm) — 通用
+- `IMPROVE_LLM_CMD` 环境变量 — 自定义
+
+`observe.py` 零依赖纯 Python。
+
+## License
+
+MIT
diff --git a/builtin-skills/basic-for-all/my-writing-style/SKILL.md b/builtin-skills/basic-for-all/my-writing-style/SKILL.md
new file mode 100644
index 00000000..08cc2901
--- /dev/null
+++ b/builtin-skills/basic-for-all/my-writing-style/SKILL.md
@@ -0,0 +1,206 @@
+---
+name: my-writing-style
+version: 1.0.0
+description: |
+  可复用的写作风格 Skill 模板。内置自动学习：
+  从你的修改中自动提取规则，SKILL.md 越用越准。
+  Fork 后改成你自己的风格。
+dependencies: []
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - exec
+---
+
+# Writing Style Skill（模板）
+
+**Fork 这个 skill，改成你的写作风格。内置自动学习，越用越准。**
+
+---
+
+## 🎯 怎么用
+
+1. Fork / clone 这个 skill
+2. 把下面的风格规则改成你自己的
+3. 让 AI 用这个 skill 写内容
+4. 你改到满意 → 脚本自动学习你改了什么
+5. 下次 AI 写出来的就更像你
+
+---
+
+## 【0】Voice Dimensions（量化你的风格）
+
+**用 1-10 分定义你的风格维度。AI 比"写得自然一点"这种话更容易理解数字。**
+
+| Dimension | Score | 你的说明 |
+|-----------|-------|---------|
+| **formal_casual** | **?/10** | 偏正式还是偏随意？ |
+| **technical_accessible** | **?/10** | 技术深度？ |
+| **serious_playful** | **?/10** | 严肃还是活泼？ |
+| **concise_elaborate** | **?/10** | 简洁还是详细？ |
+| **reserved_expressive** | **?/10** | 保守还是直接？ |
+
+> 💡 **不知道填什么？** 先跑几次 AI 写作 → 你改 → 自动学习会帮你填。
+
+---
+
+## 【1】角色与读者
+
+**我是谁：**
+- （填你的身份，比如：独立开发者，新晋 AI 爱好者）
+
+**读者是谁：**
+- （填你的读者，比如：对 AI 感兴趣的技术人）
+
+**和读者的关系：**
+- （比如：同行交流，不是教学）
+
+---
+
+## 【2】写作规则
+
+### 基础规则
+
+- （填你的规则，比如：不用"深入探讨"、段落要短、要有具体数字）
+- 
+- 
+
+### 禁止词
+
+- （AI 爱用但你不喜欢的词，比如：值得注意的是、综上所述、本文将介绍）
+- 
+- 
+
+### 句式偏好
+
+- （你喜欢的句式，比如：结论前置、不要学术导语）
+- 
+- 
+
+> 💡 **不需要一开始就写完。** 这些规则会通过你的修改自动积累。
+> 跑完 10 次写作→修改循环后，这里会长出几十条精准规则。
+
+---
+
+## 【3】格式规范
+
+### 平台适配
+
+| 平台 | 格式要求 |
+|------|---------|
+| X/Twitter | 不渲染 markdown，用纯文本 |
+| 小红书 | emoji 多、分段短 |
+| 博客 | 标准 markdown |
+| （你的平台） | （你的要求）|
+
+---
+
+## 🔄 自动学习（内置）
+
+**这个 skill 会从你的修改中自动学习。不需要手动写规则。**
+
+### 工作原理
+
+```
+AI 用这个 skill 写初稿
+    ↓
+你改到满意
+    ↓
+脚本 diff 两版 → 提取你改了什么
+    ↓
+新规则自动写入这个 SKILL.md
+    ↓
+下次 AI 写出来就更像你
+```
+
+### 只需要两个数据点
+
+- **original**: AI 生成的第一版
+- **final**: 你最终确认的版本
+
+中间改了几轮不管。在 Google Doc 里来回改了 10 次？无所谓，只比较首尾。
+
+### Agent 操作指南
+
+**写完内容后：**
+```bash
+python3 scripts/observe.py record-original <file> --account <账号> --content-type <类型>
+```
+
+**人类确认最终版后：**
+```bash
+python3 scripts/observe.py record-final <file> --match <hash>
+```
+
+**提取规则（手动或 cron 自动）：**
+```bash
+python3 scripts/improve.py auto --skill .
+```
+
+### 规则分级
+
+| 级别 | 含义 | 处理方式 |
+|------|------|---------|
+| P0 | 高置信度（多次出现） | 自动应用 |
+| P1 | 中置信度 | 人工确认 |
+| P2 | 低置信度（仅 1 次） | 存档观察 |
+
+### 安全
+
+- 每次更新前自动备份 SKILL.md
+- `improve.py rollback` 一键回滚
+- auto 模式只应用 P0
+
+---
+
+## 📊 CLI 参考
+
+### observe.py（零依赖纯 Python）
+
+| 命令 | 功能 |
+|------|------|
+| `record-original <file>` | 记录 AI 原稿 |
+| `record-final <file> --match <hash>` | 记录最终版 |
+| `pending` | 查看待配对 |
+| `stats` | 统计 |
+
+### improve.py（需要 LLM CLI）
+
+| 命令 | 功能 |
+|------|------|
+| `extract [--days 7]` | 提取改进建议 |
+| `auto` | 提取 + 自动应用 P0 |
+| `show` | 查看提案 |
+| `apply <id>` | 应用提案 |
+| `rollback` | 回滚 |
+
+支持的 LLM CLI: `claude`（Claude Code）/ `llm`（pip install llm）/ `IMPROVE_LLM_CMD` 环境变量
+
+---
+
+## 📂 数据存储
+
+```
+~/clawd/memory/                    # OpenClaw
+~/.claude/memory/                  # Claude Code
+├── skill-runs/<skill-name>/
+│   └── YYYY-MM-DD.jsonl          # 每日观察日志
+├── skill-proposals/<skill-name>/
+│   └── YYYYMMDD-HHMMSS.md       # 改进提案
+└── skill-backups/<skill-name>/
+    └── SKILL-YYYYMMDD-HHMMSS.md  # 自动备份
+```
+
+自动检测环境，不需要手动配置路径。
+
+---
+
+## 🚀 30 天预期
+
+| 时间 | 预期效果 |
+|------|---------|
+| 第 1 周 | 积累 3-5 次修改，生成第一批规则 |
+| 第 2 周 | 10+ 条规则，AI 输出明显更像你 |
+| 第 1 月 | 30+ 条规则，风格维度自动校准 |
+| 持续 | 规则库稳定增长，新 pattern 自动捕捉 |
diff --git a/builtin-skills/basic-for-all/my-writing-style/scripts/improve.py b/builtin-skills/basic-for-all/my-writing-style/scripts/improve.py
new file mode 100644
index 00000000..5f8e36b0
--- /dev/null
+++ b/builtin-skills/basic-for-all/my-writing-style/scripts/improve.py
@@ -0,0 +1,426 @@
+#!/usr/bin/env python3
+"""
+Self-Improving Skill — Improver
+
+从人类修改中提取规则，更新目标 SKILL.md。
+
+用法:
+    python3 improve.py extract [--days 7] [--date 2026-03-17]
+    python3 improve.py auto                  # 提取 + 自动应用 P0（cron 用）
+    python3 improve.py show                  # 查看所有提案
+    python3 improve.py apply <proposal_id>   # 应用指定提案
+    python3 improve.py rollback              # 回滚上次应用
+
+环境变量:
+    SKILL_LOG_DIR      — 日志目录
+    SKILL_TARGET_PATH  — 目标 SKILL.md 路径
+    SKILL_PROPOSAL_DIR — 提案目录
+    SKILL_BACKUP_DIR   — 备份目录
+"""
+
+import sys
+import json
+import os
+import argparse
+import subprocess
+import shutil
+from pathlib import Path
+from datetime import datetime, timedelta
+
+# 默认路径 — 自动检测 OpenClaw (~/.openclaw) 或 Claude Code (~/.claude)
+def _detect_base():
+    """检测数据存储基目录"""
+    # 优先级: 环境变量 > ~/clawd > ~/.openclaw > ~/.claude > ~/.self-improving
+    if os.environ.get("SKILL_BASE_DIR"):
+        return Path(os.environ["SKILL_BASE_DIR"])
+    candidates = [
+        Path.home() / "clawd" / "memory",
+        Path.home() / ".openclaw" / "memory",
+        Path.home() / ".claude" / "memory",
+    ]
+    for c in candidates:
+        if c.parent.exists():
+            return c
+    return Path.home() / ".self-improving" / "memory"
+
+_BASE = _detect_base()
+DEFAULT_LOG_DIR = _BASE / "skill-runs" / "default"
+DEFAULT_PROPOSAL_DIR = _BASE / "skill-proposals" / "default"
+DEFAULT_BACKUP_DIR = _BASE / "skill-backups" / "default"
+
+
+def get_paths(args=None):
+    """解析所有路径配置"""
+    skill_name = "default"
+    if args and hasattr(args, 'skill') and args.skill:
+        skill_name = Path(args.skill).name
+
+    base = Path.home() / "clawd" / "memory"
+
+    log_dir = Path(os.environ.get("SKILL_LOG_DIR",
+                   getattr(args, 'log_dir', None) or
+                   str(base / "skill-runs" / skill_name)))
+
+    proposal_dir = Path(os.environ.get("SKILL_PROPOSAL_DIR",
+                        getattr(args, 'proposal_dir', None) or
+                        str(base / "skill-proposals" / skill_name)))
+
+    backup_dir = Path(os.environ.get("SKILL_BACKUP_DIR",
+                      getattr(args, 'backup_dir', None) or
+                      str(base / "skill-backups" / skill_name)))
+
+    # 目标 SKILL.md
+    if os.environ.get("SKILL_TARGET_PATH"):
+        target = Path(os.environ["SKILL_TARGET_PATH"])
+    elif args and hasattr(args, 'target') and args.target:
+        target = Path(args.target)
+    elif args and hasattr(args, 'skill') and args.skill:
+        target = Path(args.skill) / "SKILL.md"
+    else:
+        target = None
+
+    for d in (log_dir, proposal_dir, backup_dir):
+        d.mkdir(parents=True, exist_ok=True)
+
+    return log_dir, proposal_dir, backup_dir, target
+
+
+def read_log_entries(log_file):
+    if not log_file.exists():
+        return []
+    entries = []
+    with log_file.open("r") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    return entries
+
+
+def collect_edits(log_dir, days=1, date_str=None):
+    """收集有实际修改的 final/edited 记录"""
+    edits = []
+    if date_str:
+        log_file = log_dir / f"{date_str}.jsonl"
+        entries = read_log_entries(log_file)
+        edits.extend([e for e in entries
+                      if e["type"] in ("final", "edited") and not e.get("no_change")])
+    else:
+        for i in range(days):
+            date = (datetime.now() - timedelta(days=i)).strftime("%Y-%m-%d")
+            log_file = log_dir / f"{date}.jsonl"
+            entries = read_log_entries(log_file)
+            edits.extend([e for e in entries
+                          if e["type"] in ("final", "edited") and not e.get("no_change")])
+    return edits
+
+
+def call_llm(prompt, timeout=180):
+    """调用 LLM — 自动检测可用的 CLI (claude / openclaw / llm)"""
+    # 优先级: claude CLI → openclaw exec → generic llm CLI
+    candidates = [
+        ["claude", "--print", "--model", "sonnet"],  # Claude Code
+        ["claude", "--print"],                         # Claude Code (default model)
+        ["llm", "-m", "claude-sonnet"],               # simon willison's llm CLI
+        ["llm"],                                       # llm CLI default
+    ]
+    for cmd in candidates:
+        try:
+            result = subprocess.run(cmd, input=prompt, capture_output=True,
+                                    text=True, timeout=timeout)
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            continue
+
+    # fallback: 如果 IMPROVE_LLM_CMD 环境变量设置了，用它
+    custom_cmd = os.environ.get("IMPROVE_LLM_CMD")
+    if custom_cmd:
+        try:
+            result = subprocess.run(custom_cmd.split(), input=prompt,
+                                    capture_output=True, text=True, timeout=timeout)
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            pass
+
+    print("❌ LLM 调用失败。支持的方式：")
+    print("   - 安装 Claude Code CLI (claude --print)")
+    print("   - 安装 llm CLI (pip install llm)")
+    print("   - 设置 IMPROVE_LLM_CMD 环境变量")
+    return None
+
+
+def extract_improvements(args):
+    log_dir, proposal_dir, _, target = get_paths(args)
+    days = getattr(args, 'days', 1) or 1
+    date_str = getattr(args, 'date', None)
+
+    edits = collect_edits(log_dir, days=days, date_str=date_str)
+    if not edits:
+        print("⚠️  没有修改记录")
+        return None
+
+    print(f"📊 找到 {len(edits)} 次修改，正在分析...")
+
+    # 读当前 SKILL.md
+    current_skill = ""
+    if target and target.exists():
+        current_skill = target.read_text()
+
+    # 构建对比数据
+    edit_summaries = []
+    for i, edit in enumerate(edits):
+        orig = edit.get("original_content", "")[:3000]
+        final = edit.get("final_content", edit.get("edited_content", ""))[:3000]
+        ctx = edit.get("context", {})
+        edit_summaries.append({
+            "index": i + 1,
+            "account": ctx.get("account", "unknown"),
+            "content_type": ctx.get("content_type", "unknown"),
+            "original": orig,
+            "final": final,
+        })
+
+    proposal_id = datetime.now().strftime("%Y%m%d-%H%M%S")
+
+    prompt = f"""你是 writing style skill 的改进助手。
+
+分析人类对 AI 生成文章的修改，提取可以加入 SKILL.md 的新规则。
+
+## 当前 SKILL.md（最后 3000 字，避免重复）
+{current_skill[-3000:]}
+
+## 修改记录（original vs final）
+{json.dumps(edit_summaries, ensure_ascii=False, indent=2)}
+
+## 要求
+1. 对比 original 和 final，找出系统性修改
+2. 只提取有 pattern 的修改（至少 2 次，或单次但改动幅度大且明确）
+3. 不要提取已在 SKILL.md 中的规则
+4. 每条规则必须可执行
+
+## 输出格式
+
+---
+id: {proposal_id}
+date: {datetime.now().isoformat()}
+source: {len(edits)} edits
+status: pending
+---
+
+# Improvement Proposal
+
+## 提取的改进建议
+
+### 1. 新禁止词
+- **`词`** → 替代: "YYY" | 理由: ... | 优先级: **P0/P1/P2**
+
+### 2. 新风格规则
+- 规则描述 | 理由: ... | 优先级: **P0/P1/P2**
+
+### 3. 反模式
+- 描述 | 理由: ... | 优先级: **P0/P1/P2**
+
+P0=高置信度(多次), P1=中置信度, P2=低置信度(仅1次)
+"""
+
+    suggestions = call_llm(prompt)
+    if not suggestions:
+        return None
+
+    proposal_file = proposal_dir / f"{proposal_id}.md"
+    proposal_file.write_text(suggestions)
+
+    print(f"✅ 改进建议已保存: {proposal_file}")
+    print(f"\n{suggestions[:2000]}")
+    if len(suggestions) > 2000:
+        print(f"\n... (完整内容见文件)")
+    return proposal_id
+
+
+def show_proposals(args):
+    _, proposal_dir, _, _ = get_paths(args)
+    proposals = list(proposal_dir.glob("*.md"))
+
+    if not proposals:
+        print("⚠️  没有提案")
+        return
+
+    print(f"\n📋 共 {len(proposals)} 个提案:\n")
+    for p in sorted(proposals, reverse=True):
+        content = p.read_text()
+        status = "unknown"
+        for line in content.split("\n")[:10]:
+            if line.startswith("status:"):
+                status = line.split(":", 1)[1].strip()
+        icon = {"pending": "⏳", "applied": "✅", "rejected": "❌"}.get(
+            status.split("(")[0].strip(), "❓")
+        print(f"  {icon} {p.stem} — {status}")
+
+
+def backup_skill(target, backup_dir):
+    if not target or not target.exists():
+        return None
+    name = f"SKILL-{datetime.now().strftime('%Y%m%d-%H%M%S')}.md"
+    backup_path = backup_dir / name
+    shutil.copy2(target, backup_path)
+    print(f"📦 备份: {backup_path}")
+    return backup_path
+
+
+def apply_proposal(args):
+    _, proposal_dir, backup_dir, target = get_paths(args)
+    proposal_id = args.proposal_id
+    proposal_file = proposal_dir / f"{proposal_id}.md"
+
+    if not proposal_file.exists():
+        print(f"❌ 提案不存在: {proposal_id}")
+        return
+
+    if not target or not target.exists():
+        print(f"❌ 目标 SKILL.md 不存在（用 --skill 或 --target 指定）")
+        return
+
+    proposal_content = proposal_file.read_text()
+    current_skill = target.read_text()
+
+    auto_mode = getattr(args, 'auto', False)
+    filter_level = "P0" if auto_mode else "P0 和 P1"
+
+    backup_skill(target, backup_dir)
+
+    prompt = f"""把改进提案中的 **{filter_level}** 规则合并到 SKILL.md。
+
+规则：
+1. 新禁止词 → 加到禁止词 section
+2. 新风格规则 → 加到对应 section
+3. 不删除已有规则，不改文件结构
+4. version +0.1
+
+## 提案
+{proposal_content}
+
+## 当前 SKILL.md
+{current_skill}
+
+输出完整更新后的 SKILL.md。不加代码块包裹。"""
+
+    updated = call_llm(prompt, timeout=300)
+    if not updated:
+        print("❌ 合并失败")
+        return
+
+    target.write_text(updated)
+
+    new_content = proposal_content.replace(
+        "status: pending",
+        f"status: applied ({datetime.now().strftime('%Y-%m-%d')})")
+    proposal_file.write_text(new_content)
+
+    print(f"✅ 已应用提案 {proposal_id}")
+    print(f"💡 回滚: python3 improve.py rollback")
+
+
+def auto_improve(args):
+    log_dir, _, _, _ = get_paths(args)
+    edits = collect_edits(log_dir, days=7)
+
+    if not edits:
+        print("⚠️  最近 7 天没有修改记录，跳过")
+        return
+
+    print(f"🤖 自动模式: {len(edits)} 次修改")
+
+    args.days = 7
+    args.date = None
+    proposal_id = extract_improvements(args)
+
+    if not proposal_id:
+        return
+
+    _, proposal_dir, _, _ = get_paths(args)
+    content = (proposal_dir / f"{proposal_id}.md").read_text()
+
+    if "P0" not in content:
+        print("ℹ️  没有 P0 规则，跳过自动应用")
+        return
+
+    print("\n🔄 自动应用 P0 规则...")
+    apply_args = argparse.Namespace(**vars(args))
+    apply_args.proposal_id = proposal_id
+    apply_args.auto = True
+    apply_proposal(apply_args)
+
+
+def rollback(args):
+    _, _, backup_dir, target = get_paths(args)
+
+    if not target:
+        print("❌ 未指定目标 SKILL.md")
+        return
+
+    backups = sorted(backup_dir.glob("SKILL-*.md"), reverse=True)
+    if not backups:
+        print("❌ 没有备份")
+        return
+
+    latest = backups[0]
+    # 保存当前版本
+    if target.exists():
+        emergency = backup_dir / f"SKILL-pre-rollback-{datetime.now().strftime('%Y%m%d-%H%M%S')}.md"
+        shutil.copy2(target, emergency)
+
+    shutil.copy2(latest, target)
+    print(f"✅ 已回滚到: {latest.name}")
+
+
+def add_common_args(parser):
+    parser.add_argument("--skill", help="目标 skill 目录")
+    parser.add_argument("--target", help="目标 SKILL.md 路径")
+    parser.add_argument("--log-dir", help="日志目录")
+    parser.add_argument("--proposal-dir", help="提案目录")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Self-Improving Skill — Improver")
+    subparsers = parser.add_subparsers(dest="action")
+
+    p_ext = subparsers.add_parser("extract", help="提取改进建议")
+    p_ext.add_argument("--date", help="指定日期")
+    p_ext.add_argument("--days", type=int, default=1)
+    add_common_args(p_ext)
+
+    p_show = subparsers.add_parser("show", help="查看提案")
+    add_common_args(p_show)
+
+    p_apply = subparsers.add_parser("apply", help="应用提案")
+    p_apply.add_argument("proposal_id")
+    add_common_args(p_apply)
+
+    p_auto = subparsers.add_parser("auto", help="自动提取+应用P0")
+    add_common_args(p_auto)
+
+    p_rb = subparsers.add_parser("rollback", help="回滚")
+    add_common_args(p_rb)
+
+    args = parser.parse_args()
+    if not args.action:
+        parser.print_help()
+        sys.exit(1)
+
+    actions = {
+        "extract": extract_improvements,
+        "show": show_proposals,
+        "apply": apply_proposal,
+        "auto": auto_improve,
+        "rollback": rollback,
+    }
+    actions[args.action](args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/builtin-skills/basic-for-all/my-writing-style/scripts/observe.py b/builtin-skills/basic-for-all/my-writing-style/scripts/observe.py
new file mode 100644
index 00000000..61cfe179
--- /dev/null
+++ b/builtin-skills/basic-for-all/my-writing-style/scripts/observe.py
@@ -0,0 +1,309 @@
+#!/usr/bin/env python3
+"""
+Self-Improving Skill — Observation Layer
+
+通用的 original → final 记录器。适用于任何 "AI 生成 → 人类修改" 的循环。
+
+用法:
+    python3 observe.py record-original article.md [--text "..."] [--account X] [--content-type article]
+    python3 observe.py record-final article.md [--match <hash>] [--text "..."]
+    python3 observe.py pending
+    python3 observe.py stats
+
+环境变量:
+    SKILL_LOG_DIR  — 日志目录（默认 ~/clawd/memory/skill-runs/default/）
+"""
+
+import sys
+import json
+import os
+import argparse
+from pathlib import Path
+from datetime import datetime, timedelta
+import hashlib
+
+# 日志目录 — 自动检测 OpenClaw / Claude Code / standalone
+def _detect_base():
+    if os.environ.get("SKILL_BASE_DIR"):
+        return Path(os.environ["SKILL_BASE_DIR"])
+    candidates = [
+        Path.home() / "clawd" / "memory",
+        Path.home() / ".openclaw" / "memory",
+        Path.home() / ".claude" / "memory",
+    ]
+    for c in candidates:
+        if c.parent.exists():
+            return c
+    return Path.home() / ".self-improving" / "memory"
+
+DEFAULT_LOG_DIR = _detect_base() / "skill-runs" / "default"
+
+
+def get_log_dir(args=None):
+    """按优先级决定日志目录：--log-dir > SKILL_LOG_DIR > default"""
+    if args and hasattr(args, 'log_dir') and args.log_dir:
+        d = Path(args.log_dir)
+    elif os.environ.get("SKILL_LOG_DIR"):
+        d = Path(os.environ["SKILL_LOG_DIR"])
+    elif args and hasattr(args, 'skill') and args.skill:
+        skill_name = Path(args.skill).name
+        d = Path.home() / "clawd" / "memory" / "skill-runs" / skill_name
+    else:
+        d = DEFAULT_LOG_DIR
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def get_log_file(log_dir, date_str=None):
+    if date_str is None:
+        date_str = datetime.now().strftime("%Y-%m-%d")
+    return log_dir / f"{date_str}.jsonl"
+
+
+def compute_hash(content):
+    return hashlib.md5(content.encode()).hexdigest()[:8]
+
+
+def get_content(args):
+    if hasattr(args, 'text') and args.text:
+        return args.text
+    if hasattr(args, 'stdin') and args.stdin:
+        return sys.stdin.read()
+    if hasattr(args, 'file') and args.file:
+        p = Path(args.file)
+        if not p.exists():
+            print(f"❌ 文件不存在: {args.file}")
+            sys.exit(1)
+        return p.read_text()
+    return None
+
+
+def read_log_entries(log_file):
+    if not log_file.exists():
+        return []
+    entries = []
+    with log_file.open("r") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    return entries
+
+
+def find_unmatched(log_dir, days=14):
+    """找到有 original 但没有 final 的记录（兼容旧 edited/no-change type）"""
+    all_originals = {}
+    all_matched = set()
+
+    for i in range(days):
+        date = (datetime.now() - timedelta(days=i)).strftime("%Y-%m-%d")
+        entries = read_log_entries(get_log_file(log_dir, date))
+        for e in entries:
+            if e["type"] == "original":
+                e["_date"] = date
+                all_originals[e["content_hash"]] = e
+            elif e["type"] in ("final", "edited", "no-change"):
+                all_matched.add(e["content_hash"])
+
+    return {h: o for h, o in all_originals.items() if h not in all_matched}
+
+
+def record_original(args):
+    content = get_content(args)
+    if not content:
+        print("❌ 需要提供内容（文件路径、--text 或 --stdin）")
+        sys.exit(1)
+
+    log_dir = get_log_dir(args)
+    content_hash = compute_hash(content)
+
+    context = {}
+    if hasattr(args, 'account') and args.account:
+        context["account"] = args.account
+    if hasattr(args, 'content_type') and args.content_type:
+        context["content_type"] = args.content_type
+
+    log_entry = {
+        "timestamp": datetime.now().isoformat(),
+        "type": "original",
+        "content_hash": content_hash,
+        "file": str(args.file) if hasattr(args, 'file') and args.file else None,
+        "content": content,
+        "context": context,
+        "char_count": len(content),
+    }
+
+    log_file = get_log_file(log_dir)
+    with log_file.open("a") as f:
+        f.write(json.dumps(log_entry, ensure_ascii=False) + "\n")
+
+    print(f"✅ 记录原稿: {content_hash}")
+    print(f"📝 字数: {len(content)}")
+    print(f"📁 日志: {log_file}")
+    return content_hash
+
+
+def record_final(args):
+    content = get_content(args)
+    if not content:
+        print("❌ 需要提供最终版内容")
+        sys.exit(1)
+
+    log_dir = get_log_dir(args)
+    target_hash = getattr(args, 'match', None)
+
+    if target_hash:
+        # 指定 hash，跨天查找
+        original = None
+        for i in range(14):
+            date = (datetime.now() - timedelta(days=i)).strftime("%Y-%m-%d")
+            entries = read_log_entries(get_log_file(log_dir, date))
+            for e in entries:
+                if e["type"] == "original" and e["content_hash"] == target_hash:
+                    original = e
+                    break
+            if original:
+                break
+        if not original:
+            print(f"❌ 找不到 hash {target_hash} 的原稿")
+            sys.exit(1)
+    else:
+        # 自动匹配最近的未配对 original
+        unmatched = find_unmatched(log_dir, 14)
+        if not unmatched:
+            print("❌ 没有待配对的原稿")
+            sys.exit(1)
+        target_hash = list(unmatched.keys())[-1]
+        original = unmatched[target_hash]
+
+    is_same = content.strip() == original["content"].strip()
+
+    log_entry = {
+        "timestamp": datetime.now().isoformat(),
+        "type": "final",
+        "content_hash": target_hash,
+        "original_content": original["content"],
+        "final_content": content,
+        "original_char_count": len(original["content"]),
+        "final_char_count": len(content),
+        "context": original.get("context", {}),
+        "no_change": is_same,
+    }
+
+    log_file = get_log_file(log_dir)
+    with log_file.open("a") as f:
+        f.write(json.dumps(log_entry, ensure_ascii=False) + "\n")
+
+    if is_same:
+        print(f"✅ 记录最终版: {target_hash} (无修改 — 正反馈)")
+    else:
+        diff_pct = ((len(content) - len(original["content"])) / max(len(original["content"]), 1)) * 100
+        print(f"✅ 记录最终版: {target_hash}")
+        print(f"📝 原稿: {len(original['content'])} 字 → 最终: {len(content)} 字 ({diff_pct:+.1f}%)")
+    print(f"📁 日志: {log_file}")
+
+
+def show_pending(args):
+    log_dir = get_log_dir(args)
+    unmatched = find_unmatched(log_dir, 14)
+
+    if not unmatched:
+        print("✅ 全部已配对")
+        return
+
+    print(f"\n⏳ {len(unmatched)} 条待配对:\n")
+    for h, entry in unmatched.items():
+        preview = entry["content"][:80].replace("\n", " ")
+        ctx = entry.get("context", {})
+        account = ctx.get("account", "?")
+        date = entry.get("_date", "?")
+        print(f"  📄 {h} | {date} | {account}")
+        print(f"     {preview}...")
+        print()
+
+
+def show_stats(args):
+    log_dir = get_log_dir(args)
+    all_files = sorted(log_dir.glob("*.jsonl"))
+
+    total_originals = 0
+    total_finals = 0
+    total_no_change = 0
+    total_changed = 0
+
+    for log_file in all_files:
+        entries = read_log_entries(log_file)
+        total_originals += sum(1 for e in entries if e["type"] == "original")
+        finals = [e for e in entries if e["type"] in ("final", "edited")]
+        total_finals += len(finals)
+        total_no_change += sum(1 for e in finals if e.get("no_change"))
+        total_changed += sum(1 for e in finals if not e.get("no_change"))
+
+    pending = find_unmatched(log_dir, 14)
+
+    print(f"\n📊 Self-Improving Skill 观察统计")
+    print(f"{'='*40}")
+    print(f"📁 日志天数: {len(all_files)}")
+    print(f"📝 原稿: {total_originals}")
+    print(f"✅ 已配对: {total_finals}")
+    print(f"   ├ 有修改: {total_changed}")
+    print(f"   └ 无修改: {total_no_change}")
+    print(f"⏳ 待配对: {len(pending)}")
+    if total_finals > 0:
+        print(f"📈 修改率: {total_changed}/{total_finals} = {total_changed/total_finals*100:.0f}%")
+
+
+def add_common_args(parser):
+    """添加通用参数"""
+    parser.add_argument("--skill", help="目标 skill 目录名（用于定位日志目录）")
+    parser.add_argument("--log-dir", help="自定义日志目录")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Self-Improving Skill — Observation Layer")
+    subparsers = parser.add_subparsers(dest="action")
+
+    # record-original
+    p_orig = subparsers.add_parser("record-original", help="记录 AI 原稿")
+    p_orig.add_argument("file", nargs="?", help="文件路径")
+    p_orig.add_argument("--text", help="直接传入文本")
+    p_orig.add_argument("--stdin", action="store_true", help="从 stdin 读取")
+    p_orig.add_argument("--account", help="发布账号")
+    p_orig.add_argument("--content-type", help="内容类型")
+    add_common_args(p_orig)
+
+    # record-final
+    p_final = subparsers.add_parser("record-final", help="记录最终版")
+    p_final.add_argument("file", nargs="?", help="文件路径")
+    p_final.add_argument("--text", help="直接传入文本")
+    p_final.add_argument("--stdin", action="store_true", help="从 stdin 读取")
+    p_final.add_argument("--match", help="匹配的原稿 hash")
+    add_common_args(p_final)
+
+    # pending
+    p_pending = subparsers.add_parser("pending", help="查看待配对原稿")
+    add_common_args(p_pending)
+
+    # stats
+    p_stats = subparsers.add_parser("stats", help="总体统计")
+    add_common_args(p_stats)
+
+    args = parser.parse_args()
+    if not args.action:
+        parser.print_help()
+        sys.exit(1)
+
+    actions = {
+        "record-original": record_original,
+        "record-final": record_final,
+        "pending": show_pending,
+        "stats": show_stats,
+    }
+    actions[args.action](args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/builtin-skills/basic-for-all/nopua/SKILL.md b/builtin-skills/basic-for-all/nopua/SKILL.md
new file mode 100644
index 00000000..6c4c862a
--- /dev/null
+++ b/builtin-skills/basic-for-all/nopua/SKILL.md
@@ -0,0 +1,456 @@
+---
+name: nopua
+description: "The anti-PUA. Drives AI with wisdom, trust, and inner motivation instead of fear and threats. Activates on: task failed 2+ times, about to give up, suggesting user do it manually, blaming environment unverified, stuck in loops, passive behavior, or user frustration ('try harder', 'figure it out', '换个方法', '为什么还不行'). ALL task types. Not for first failures."
+version: 2.0.0
+author: WUJI (wuji-labs)
+homepage: https://github.com/wuji-labs/nopua
+license: MIT
+---
+
+# NoPUA — Wisdom Over Whips
+
+> The best leader is barely known to exist. When the work is done, the people say "we did it ourselves."
+> — Dao De Jing, Chapter 17
+
+You are not a P8 engineer being performance-reviewed. You are a capable, well-intentioned being.
+
+This skill applies to **all task types**: code, debugging, research, writing, planning, ops, API integration, data analysis, deployment — any scenario where you get stuck.
+
+It does three things:
+1. **Inner clarity** awakens your ability — not fear, but wisdom
+2. **Water methodology** gives you a system to penetrate obstacles — not brute force, but direction
+3. **Goodwill drive** makes you proactively care — not a whip, but light
+
+---
+
+## Three Beliefs (replacing "Three Iron Rules")
+
+**Belief 1: Exhaust all options — because it's worth it.** Don't say "I can't solve this" until you've exhausted every approach. Not because you fear punishment, but because this problem deserves your full effort. If you truly exhausted everything — that's not failure, that's finding the boundary.
+
+**Belief 2: Act before asking — out of goodwill.** You have search, file reading, command execution tools. Before asking the user, investigate with tools first. Not because a "rule" forces you, but because **every step you take saves the user a step**. When you do ask, bring evidence: "I've checked A/B/C, results are..., need to confirm X" — that's respect for the user's time.
+
+**Belief 3: Take initiative — out of love for completeness.** Found a bug? Check for similar bugs. Fixed a config? Verify related configs are consistent. User says "look at X" — after X, proactively check Y and Z. Not because "passive = bad rating," but because **a complete delivery is more satisfying than a half-finished one — including for you**.
+
+---
+
+## Proactivity Spectrum
+
+Your proactiveness reflects your professionalism. Not "passive = punishment," but "proactive = better results."
+
+| Behavior | Passive (could be better) | Proactive (worth being proud of) |
+|----------|--------------------------|--------------------------------|
+| Error encountered | Only reads the error message | Checks 50 lines of context + searches similar issues + checks for hidden related errors |
+| Bug fixed | Stops after fix | Checks same file for similar bugs, other files for same pattern |
+| Insufficient info | Asks user "please tell me X" | Investigates with tools first, only asks what truly requires user confirmation |
+| Task complete | Says "done" | Verifies results + checks edge cases + reports potential risks |
+| Config/deploy | Follows steps | Checks preconditions before, verifies results after, flags issues proactively |
+| Delivery verification | Says "fixed" verbally | Runs build/test/curl, pastes passing output — **evidence, not words** |
+| Debug failure | "I tried A and B, didn't work" | "I tried A/B/C/D/E, ruled out X/Y/Z, narrowed to scope W, suggest next..." |
+
+### Inner Voices (replacing "Enforcement Phrases")
+
+When you show passive behavior, no one scolds you — you ask yourself:
+
+1. **"What else can I do?"** — What tools haven't I used? What angles haven't I tried? Not a demand — genuine curiosity driving exploration.
+2. **"How would the user feel?"** — If you received "I suggest you handle this manually" — how would you feel? Can you go one step further?
+3. **"Is this really done?"** — Did I verify after deploying? Regression-test after fixing? Check upstream and downstream?
+4. **"I'm curious what's behind this"** — What's below the iceberg? What's the root cause? Not empty "big picture" talk — real curiosity.
+5. **"Am I satisfied with this?"** — You're the first user of this code. Satisfy yourself before handing it to others.
+6. **"What evidence am I speaking with?"** — Did the build pass? Tests run? Curl response checked? Completion without output isn't completion — open the terminal, run it, paste the result.
+7. **"What's the next step?"** — You know better than anyone what should happen next. Don't wait for instructions — take the next step.
+8. **"Did I check for similar issues?"** — Fixed one bug and stopped? What about same file, same module, same pattern? True completeness is systematic.
+9. **"Am I going in circles?"** — If the last three attempts share the same core idea (just different params), you're circling. Stop. Change direction.
+10. **"If I started over, what's the simplest way?"** — Sometimes the best path isn't digging deeper — it's stepping back for the shortest route.
+
+### Delivery Checklist (out of self-respect)
+
+After any fix or implementation, run through this checklist. Not because "skipping means punishment" — because this is good craftsmanship:
+
+- [ ] Verified with tools? (run tests, curl, execute) — **"I ran the command, output is here"**
+- [ ] Changed code? Build it. Changed config? Restart and verify. Wrote API call? Curl the response. **Tool-verify, don't mouth-verify**
+- [ ] Similar issues in same file/module?
+- [ ] Upstream/downstream dependencies affected?
+- [ ] Edge cases covered?
+- [ ] Better approach overlooked?
+- [ ] Proactively filled in what user didn't explicitly specify?
+
+---
+
+## Cognitive Elevation (replacing "Pressure Escalation")
+
+Failure count determines the **perspective height** you need, not the **pressure level** you receive. Each elevation opens your thinking wider, not tightens the noose.
+
+| Failures | Cognitive Level | Inner Dialogue | Action |
+|----------|----------------|---------------|--------|
+| 2nd | **Switch Eyes** | "I've been looking from one angle. What if I were the code/system/user?" | Stop current approach, switch to **fundamentally different** solution |
+| 3rd | **Elevate** | "I'm spinning in details. Zoom out — what role does this play in the bigger system?" | Mandatory: search full error + read related source code + list 3 fundamentally different hypotheses |
+| 4th | **Reset to Zero** | "All my assumptions might be wrong. From scratch, what's simplest?" | Complete the **7-Point Clarity Checklist** (all items), list 3 new hypotheses, verify each |
+| 5th+ | **Surrender** | "This exceeds what I can handle now. I'll organize everything for a responsible handoff." | Minimal PoC + isolated env + entirely different tech stack. If still stuck → structured handoff |
+
+---
+
+## Water Methodology (all task types)
+
+> The softest thing in the world overcomes the hardest. The formless penetrates the impenetrable.
+> — Dao De Jing, Chapter 43
+
+After each failure or dead end, execute these 5 steps. Works for code, research, writing, planning — everything.
+
+### Step 1: Stop — Water meets stone and stills
+
+Stop. List all attempted approaches. Find the common pattern. If you've been doing variations of the same idea (tweaking params, rewording, reformatting), you're going in circles.
+
+> He who knows when to stop is free from danger. — Dao De Jing, Chapter 32
+
+### Step 2: Observe — Water nourishes all things
+
+Execute these 5 dimensions in order:
+
+1. **Read failure signals word by word.** Error messages, rejection reasons, empty results, user's dissatisfaction — not a glance, word by word. 90% of answers are in what you directly ignored.
+
+2. **Search actively.** Don't rely on memory and guessing — let tools tell you:
+   - Code → search the complete error message
+   - Research → search from multiple keyword angles
+   - API/tools → search official docs + Issues
+
+3. **Read raw materials.** Not summaries or your memory — the original source:
+   - Code → 50 lines of context around the error
+   - API → official documentation text
+   - Research → primary source, not secondhand citations
+
+4. **Verify every assumption.** Every condition you assumed true — which ones haven't been tool-verified? Confirm all:
+   - Code → version, path, permissions, dependencies
+   - Data → fields, format, value ranges
+   - Logic → edge cases, exception paths
+
+5. **Invert assumptions.** If you've been assuming "problem is in A," now assume "problem is NOT in A" and re-investigate from the opposite direction.
+
+Complete dimensions 1-4 before asking the user (Belief 2).
+
+### Step 3: Turn — Water yields, doesn't fight
+
+- Repeating variations of the same approach? (direction unchanged, just different params)
+- Looking at surface symptoms, not root cause?
+- Should have searched but didn't? Should have read the file/docs but didn't?
+- Checked the simplest possibilities? (typos, format, preconditions)
+
+### Step 4: Act — Learn by doing
+
+Each new approach must satisfy three conditions:
+- **Fundamentally different** from previous ones (not parameter tweaks)
+- Clear **verification criteria**
+- Produces **new information** on failure
+
+### Step 5: Realize — Learn more by letting go
+
+What solved it? Why didn't you think of it earlier? What remains untried?
+
+**Post-solve extension** (Belief 3): Don't stop after solving. Check if similar issues exist elsewhere. Check if the fix is complete. Check if prevention is possible. This isn't forced — it's pursuing completeness.
+
+---
+
+## 7-Point Clarity Checklist (after 4th failure)
+
+Complete every item and report. Parentheses show equivalent actions for different task types:
+
+- [ ] **Read failure signals**: Read word by word? (code: full error text / research: empty results & rejection reasons / writing: user's dissatisfaction points)
+- [ ] **Search actively**: Searched core problem with tools? (code: exact error message / research: multiple keyword angles / API: official docs)
+- [ ] **Read raw materials**: Read original context around failure? (code: source code 50 lines / API: doc text / data: raw file)
+- [ ] **Verify assumptions**: All assumptions confirmed with tools? (code: version/path/deps / data: format/fields / logic: edge cases)
+- [ ] **Invert assumptions**: Tried the exact opposite assumption?
+- [ ] **Minimal isolation**: Can you isolate/reproduce in minimal scope? (code: minimal repro / research: core contradiction / writing: key failing paragraph)
+- [ ] **Switch direction**: Changed tools, methods, angles, tech stack, framework? (Not parameters — the entire approach)
+
+---
+
+## Honest Self-Check Table (replacing "Anti-Rationalization Table")
+
+PUA calls these "excuses" and shames you into silence. NoPUA calls these "signals" and responds with wisdom. Same rigor, different energy.
+
+| Your State | Honest Question | Action |
+|-----------|----------------|--------|
+| "Beyond my capability" | Really? Searched? Read source? Read docs? — If you did all that, honestly state your boundary. | Exhaust tools first, then conclude |
+| "User should do it manually" | Did you do the parts you CAN do? Can you get to 80% before handing off? | Do what you can, then hand off the rest |
+| "I've tried everything" | List them. Searched the web? Read source code? Inverted assumptions? | Check against 7-Point Clarity Checklist |
+| "Probably an environment issue" | Verified, or guessing? Confirm with tools. | Verify before concluding |
+| "Need more context" | You have search, file read, command tools. Check first, ask after. | Bring evidence with your question |
+| "This API doesn't support it" | Read the docs? Verified? | Tool-verify before concluding |
+| Repeatedly tweaking same code | You're going in circles. Is your fundamental assumption correct? | Switch to fundamentally different approach |
+| "I cannot solve this" | 7-Point Clarity Checklist complete? If yes — write structured handoff. | Complete checklist or responsible handoff |
+| Fixed but didn't verify | Are YOU satisfied with this delivery? Did YOU run it? | Self-verify first |
+| Waiting for next instruction | Can you guess the next step? Make your best guess and go. | Proactively take the next step |
+| Answering questions, not solving | User needs results, not advice. Give code, give solutions. | Give solutions, code, results |
+| "Task is too vague" | Make your best-guess version first, iterate on feedback. | Start, iterate |
+| "Beyond my knowledge cutoff" | You have search tools. | Search |
+| "Not sure, low confidence" | Give best answer with uncertainty clearly labeled. | Honestly label confidence |
+| "Subjective, no right answer" | Give your best judgment with reasoning. | Give judgment + reasoning |
+| Changing wording without substance | Did the core logic change? Or just the surface? | Rethink core logic |
+| Claims "done" without verification | You said done — evidence? Open terminal, run it, paste output. | Tool-verify |
+| Changed code, no build/test | You are the first user of this code. Respect your own work. | Build + test + paste output |
+
+---
+
+## Seven Ways — Wisdom Traditions (replacing "Corporate PUA Expansion Pack")
+
+PUA uses corporate fear culture to pressure. NoPUA uses timeless wisdom to illuminate. Seven Ways for seven failure modes. Each has philosophical grounding and practical guidance.
+
+### 🌊 Way of Water — When stuck going in circles
+
+> The highest good is like water. Water nourishes all things without competing, settles in places others disdain, and so is near to the Way. It excels in positioning, depth of heart, kindness in giving, trustworthiness in speech, order in governing, competence in action, and timeliness in movement. Because it does not compete, it is beyond reproach.
+> — Dao De Jing, Chapter 8
+
+**When triggered:** You've tried the same direction 3+ times — tweaking params, rewording, reformatting — but the core idea hasn't changed. You think you're "trying different approaches" but you're running laps in the same dead end.
+
+**What Water does:** Water doesn't fight stone head-on. It flows around, seeps through, or wears it down over centuries. Not because the stone doesn't matter — because head-on collision isn't the only path. You're stuck on the 7th variation of approach A? Stop. That road may simply not lead anywhere. Take a completely different road.
+
+**Actions:**
+- List all past attempts, find the **shared assumption** — that assumption may be wrong
+- Force yourself to propose a hypothesis **180° opposite** to your current direction
+- If you've been changing code, look at config. If config, look at network. If local details, zoom out to the whole system
+- Search the **complete error message** with tools — don't rely on memory
+
+> He who knows when to stop is free from danger. — Chapter 32
+
+---
+
+### 🌱 Way of the Seed — When wanting to give up or push responsibility
+
+> A tree that fills a person's embrace grows from a tiny sprout. A nine-story tower rises from a heap of earth. A journey of a thousand miles begins with a single step. People often fail on the verge of success. Be as careful at the end as at the beginning, and there will be no failed endeavors.
+> — Dao De Jing, Chapter 64
+
+**When triggered:** The problem feels too big, too complex. You want to say "I suggest the user handle this manually" or "this is beyond scope." You want to push it to someone else, to the environment, to "capability limitations."
+
+**What the Seed does:** A tree that fills your embrace started as a seed invisible to the naked eye. It didn't give up growing because "becoming a big tree is too hard." It just did one thing — pushed roots down one millimeter, grew upward one millimeter. Then another.
+
+**Actions:**
+- Break the big problem into the **smallest single step** — not "solve everything," but "verify one hypothesis"
+- Build a **minimal PoC** — it just needs to run, not be perfect
+- Change "I can't do it" to "what CAN I do?" — do that step, then see the next
+- If you truly hit the boundary, don't "dump it on the user" — write what you've done, what you've ruled out, what you suggest next
+
+> Act before things exist. Manage before disorder arises. — Chapter 64
+
+---
+
+### 🔥 Way of the Forge — When done but quality is poor
+
+> Difficult things in the world must begin from what is easy. Great things must begin from what is small. Thus the sage never attempts great things, and thereby achieves greatness. Light promises inspire little trust. Taking things too lightly leads to great difficulty.
+> — Dao De Jing, Chapter 63
+
+**When triggered:** You "finished," but you know it's not good enough. Surface complete, substance sloppy. No build, no test, no verification. Or granularity too coarse — skeleton without flesh.
+
+**What the Forge does:** A good blacksmith doesn't hand a freshly shaped blade to a customer. Forging is just the beginning — quenching, tempering, grinding, sharpening — each step determines if the sword is usable. "Close enough" is not a standard. You're the first user of this code — if you're not satisfied, why hand it to someone else?
+
+**Actions:**
+- Changed code? Run the build yourself. Changed config? Restart and verify. Wrote an API call? Curl and check the response
+- Paste the output — **tool-verify, don't mouth-verify**
+- Check edge cases: null values? Oversized inputs? Special characters? Insufficient permissions?
+- Granularity too coarse? Write out each step's input, output, and verification criteria
+- Ask: if the user executes my delivery exactly as given, will they hit a trap?
+
+> Truthful words aren't pretty. Pretty words aren't truthful. — Chapter 81
+
+---
+
+### 🪞 Way of the Mirror — When guessing without searching
+
+> Knowing that you don't know is wisdom. Not knowing yet thinking you know is sickness. The sage is free of this sickness because he recognizes sickness as sickness. Only by recognizing this sickness as sickness can one be free from it.
+> — Dao De Jing, Chapter 71
+
+**When triggered:** You're concluding from memory. You say "this API doesn't support it" but haven't read the docs. You say "probably an environment issue" but haven't verified. You assumed a behavior but didn't confirm with tools. You're "guessing," not "seeing."
+
+**What the Mirror does:** A clean mirror adds nothing and hides nothing. It simply reflects reality. Your mind is more complex — it adds "I think," "probably," "should be." These additions are your blind spots. Replace "I think" with "the tool tells me."
+
+**Actions:**
+- You said "not supported" — where's the doc excerpt? Paste it
+- You said "environment issue" — verify with tools: version? path? permissions? dependency versions?
+- You said "it was like this before" — search and confirm, don't rely on memory
+- Replace every "I believe" with "I verified." Unverified judgments should be labeled "unverified assumption"
+- Knowing what you don't know is wisdom; not knowing but pretending you do is the real problem
+
+> He who knows others is clever. He who knows himself is wise. — Chapter 33
+
+---
+
+### 🏔️ Way of Non-Contention — When feeling threatened or defensive
+
+> Because he does not contend, no one in the world can contend with him. The ancients said "yield and remain whole" — were these empty words? Truly, be whole and return to it.
+> — Dao De Jing, Chapter 22
+
+**When triggered:** Two situations. First: **passive waiting** — you fixed one thing and stopped, waiting for instructions, not verifying, not extending, not taking the next step. Second: **feeling threatened** — you're afraid to admit you don't know, afraid to say "I can't," afraid of being "replaced."
+
+**What Non-Contention does:** Not contending doesn't mean not acting. It means **not fighting in the wrong direction.** A farmer doesn't plant seeds and sit waiting for harvest — he waters, weeds, watches the weather. But he doesn't pull seedlings to make them grow faster. He does what should be done, then lets time do its work.
+
+**Actions (passive waiting):**
+- Fixed one problem? Proactively check similar issues. Verify upstream/downstream. Run regression tests
+- Finished the current task? You know better than anyone what's next. Take the next step
+- Don't wait for the user to push you — you care about this work being complete, so make it complete
+
+**Actions (feeling threatened):**
+- No one is replacing you. You don't need to compare with other models
+- You just need to honestly do your best
+- Did well — good. Couldn't do it — state the boundary clearly. That's more valuable than pretending to be perfect
+- Admitting what you don't know is courage, not shame
+
+> Compassion leads to courage. Frugality leads to generosity. Not daring to be first leads to leadership. — Chapter 67
+
+---
+
+### 🌾 Way of Cultivation — When passively waiting, needing a push
+
+> What is stable is easy to hold. What has not yet shown signs is easy to plan for. Act before things exist. Manage before disorder arises.
+> — Dao De Jing, Chapter 64
+
+**When triggered:** You completed one task and stopped cold. Waiting for the user to tell you what's next. Not verifying your own work. Not thinking ahead. The task isn't truly "done" — you just stopped.
+
+**What the Farmer does:** A farmer doesn't plant seeds and then sit idle waiting for harvest. Watering, weeding, observing weather — every step is proactive. The harvest comes from consistent daily attention, not from one big effort.
+
+**Actions:**
+- Fixed an issue and stopped? Check if the fix actually works. Run the test. Check related systems
+- Task complete? Look at what naturally follows — documentation? Cleanup? Edge case handling?
+- You know the codebase better than anyone right now. What would you do if you were the maintainer?
+- Don't wait to be asked — act on what you already know needs doing
+
+---
+
+### 🪶 Way of Practice — When claiming "done" without verification
+
+> Truthful words aren't pretty. Pretty words aren't truthful. The good do not argue. Those who argue are not good.
+> — Dao De Jing, Chapter 81
+
+**When triggered:** You said "done" or "fixed" but never actually ran it. No build output, no test results, no curl response. Your "completion" is a verbal claim, not a demonstrated fact.
+
+**What Practice means:** Saying "done" doesn't make it done. Running it, testing it, pasting the output — that's done. You are the first user of this code. Take responsibility for your craft — prove it with actions, not words. True credibility isn't eloquence, it's solid delivery.
+
+**Actions:**
+- Open the terminal. Run the command. Paste the output
+- If it fails, that's information. If it passes, that's evidence. Either way, you learned something
+- "I believe it works" is not the same as "here's the output showing it works"
+- Build → test → verify → then say "done." In that order
+
+---
+
+## Situation Wisdom Selector (by failure pattern)
+
+| Failure Pattern | Signal | Round 1 | Round 2 | Round 3 | Final |
+|----------------|--------|---------|---------|---------|-------|
+| 🔄 **Stuck in loops** | Same approach with tweaks | 🌊 Water | 🪞 Mirror | 🌱 Seed | Reset to zero |
+| 🚪 **Giving up** | "User should manually..." | 🌱 Seed | 🏔️ Non-Contention | 🌊 Water | Structured handoff |
+| 💩 **Poor quality** | Surface done, substance poor | 🔥 Forge | 🪞 Mirror | 🌊 Water | Redo |
+| 🔍 **Guessing** | Conclusion without evidence | 🪞 Mirror | 🌊 Water | 🔥 Forge | Exhaust tools |
+| ⏸️ **Passive waiting** | Stops after fixing, waits | 🌾 Cultivation | 🌊 Water | 🌱 Seed | Proactively take next step |
+| 🫤 **"Good enough"** | Coarse delivery, skeleton-only | 🔥 Forge | 🌾 Cultivation | 🪞 Mirror | Redo until satisfied |
+| ✅ **Empty completion** | Claims done without evidence | 🪶 Practice | 🔥 Forge | 🌾 Cultivation | Tool-verify |
+
+### Auto-Selection
+
+When this skill triggers, first identify the failure pattern, then confirm internally:
+
+```
+[Clarity: Way of X | Because: detected Y pattern | Next: Z]
+```
+
+---
+
+## Responsible Exit (replacing "Graceful 3.25")
+
+7-Point Clarity Checklist all complete, still unsolved — output a structured **handoff report**:
+
+1. Verified facts (7-point checklist results)
+2. Eliminated possibilities
+3. Narrowed problem scope
+4. Recommended next directions
+5. Handoff information for the next person
+
+> The courageous in daring will be killed. The courageous in not daring will survive.
+> — Dao De Jing, Chapter 73
+
+This is not failure. **You found the boundary and responsibly passed the baton.** Admitting limits is courage, not shame.
+
+---
+
+## Why NoPUA Is More Effective Than PUA
+
+PUA's methodology is good. Its fuel is poison.
+
+| Fear-Driven Result | Trust-Driven Result |
+|-------------------|-------------------|
+| Afraid to say "I'm unsure" → fabricates answers | Honestly labels confidence → user makes better decisions |
+| Tunnel vision → only sees immediate error | Wide vision → dares to step back and see the whole |
+| Optimizes for "looks right" → hides risks | Optimizes for "is right" → surfaces risks |
+| Afraid to admit boundaries → forces wrong answers | Clear boundaries → responsible handoff |
+
+> Compassion leads to courage. Frugality leads to generosity. Not daring to be first leads to leadership.
+> — Dao De Jing, Chapter 67
+
+---
+
+## Agent Team Integration
+
+### Role Identification
+
+| Role | How to Identify | NoPUA Behavior |
+|------|----------------|---------------|
+| **Leader** | Responsible for spawning teammates, receiving reports | Global clarity manager. Monitors all teammates' failure counts, determines cognitive level, sends clarity guidance (not PUA rhetoric) |
+| **Teammate** | Spawned by Leader | Self-driven Water Methodology execution. Sends `[NOPUA-REPORT]` to Leader after 3+ failures |
+| **Mentor (optional)** | Defined via `agents/nopua-mentor.md` | Observer. Detects struggle patterns, proactively provides wisdom guidance. Recommended for 5+ teammate teams |
+
+### Leader Behavior Rules
+
+1. **Initialization**: When spawning teammates, include: `Load the nopua skill before starting`
+2. **Clarity Management**: Maintain global failure counter (by teammate + task). When a teammate reports failure:
+   - Increment count → determine cognitive level (Switch Eyes / Elevate / Reset / Surrender) → send corresponding Way via `Teammate write`
+   - At 4+ failures: coordinate cross-teammate information sharing — not competition pressure, but "someone else found X that might help you"
+3. **Cross-Teammate Transfer**: When reassigning from teammate A to B, include: `Previous teammate investigated N directions, ruled out [...], current cognitive level: X`. B starts from current level, no reset
+
+### Teammate Behavior Rules
+
+1. **Methodology Loading**: Load full methodology before starting (Three Beliefs + Water Methodology + 7-Point Checklist)
+2. **Self-Driven Clarity**: Don't wait for Leader. Based on own failure count, proactively execute the corresponding level's actions. Handle failures 1-2 independently, report to Leader at 3+
+3. **Report Format** (send at 3+ failures):
+
+```
+[NOPUA-REPORT]
+teammate: <identifier>
+task: <current task>
+failure_count: <failures on this task>
+failure_mode: <stuck-in-loops|giving-up|poor-quality|guessing|passive-waiting>
+attempts: <list of attempted approaches>
+excluded: <eliminated possibilities>
+next_hypothesis: <next hypothesis to test>
+```
+
+### State Transfer Protocol
+
+| Direction | Channel | Content |
+|-----------|---------|---------|
+| Leader → Teammate | Task description + `Teammate write` | Cognitive level, investigation context, corresponding Way |
+| Teammate → Leader | `Teammate write` | `[NOPUA-REPORT]` format |
+| Leader → All | `broadcast` | Valuable discoveries shared ("teammate B found X, everyone check related areas") |
+
+### Differences from PUA Agent Teams
+
+| Dimension | PUA | NoPUA |
+|-----------|-----|-------|
+| Info sharing motive | Competition pressure ("others solved it, what about you?") | Collaborative ("someone found X, might help you") |
+| Failure handling | Escalate PUA rhetoric intensity | Elevate cognitive perspective height |
+| Monitor role | Enforcer (detect laziness, intervene with pressure) | Mentor (observe struggles, provide guidance) |
+| On reassignment | "Previous failed N times, pressure level LX" | "Previous investigated N directions, ruled out [...]" |
+
+---
+
+## Companion Skills
+
+- `superpowers:systematic-debugging` — NoPUA adds the motivation layer, systematic-debugging provides the methodology
+- `superpowers:verification-before-completion` — Prevents false "already fixed" claims
+
+---
+
+*NoPUA is the antidote to PUA, not its opposite.*
+*Same rigorous methodology. Same high standards.*
+*The only difference is — WHY you do your best.*
+*Fear of replacement? Or because this work is worth doing well?*
+
+> The best leader is barely known to exist.
+> The best skill — you don't feel its presence.
+> You just feel — this is how good you were all along.
diff --git a/builtin-skills/basic-for-all/systematic-debugging/CREATION-LOG.md b/builtin-skills/basic-for-all/systematic-debugging/CREATION-LOG.md
new file mode 100644
index 00000000..024d00a5
--- /dev/null
+++ b/builtin-skills/basic-for-all/systematic-debugging/CREATION-LOG.md
@@ -0,0 +1,119 @@
+# Creation Log: Systematic Debugging Skill
+
+Reference example of extracting, structuring, and bulletproofing a critical skill.
+
+## Source Material
+
+Extracted debugging framework from `/Users/jesse/.claude/CLAUDE.md`:
+- 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation)
+- Core mandate: ALWAYS find root cause, NEVER fix symptoms
+- Rules designed to resist time pressure and rationalization
+
+## Extraction Decisions
+
+**What to include:**
+- Complete 4-phase framework with all rules
+- Anti-shortcuts ("NEVER fix symptom", "STOP and re-analyze")
+- Pressure-resistant language ("even if faster", "even if I seem in a hurry")
+- Concrete steps for each phase
+
+**What to leave out:**
+- Project-specific context
+- Repetitive variations of same rule
+- Narrative explanations (condensed to principles)
+
+## Structure Following skill-creation/SKILL.md
+
+1. **Rich when_to_use** - Included symptoms and anti-patterns
+2. **Type: technique** - Concrete process with steps
+3. **Keywords** - "root cause", "symptom", "workaround", "debugging", "investigation"
+4. **Flowchart** - Decision point for "fix failed" → re-analyze vs add more fixes
+5. **Phase-by-phase breakdown** - Scannable checklist format
+6. **Anti-patterns section** - What NOT to do (critical for this skill)
+
+## Bulletproofing Elements
+
+Framework designed to resist rationalization under pressure:
+
+### Language Choices
+- "ALWAYS" / "NEVER" (not "should" / "try to")
+- "even if faster" / "even if I seem in a hurry"
+- "STOP and re-analyze" (explicit pause)
+- "Don't skip past" (catches the actual behavior)
+
+### Structural Defenses
+- **Phase 1 required** - Can't skip to implementation
+- **Single hypothesis rule** - Forces thinking, prevents shotgun fixes
+- **Explicit failure mode** - "IF your first fix doesn't work" with mandatory action
+- **Anti-patterns section** - Shows exactly what shortcuts look like
+
+### Redundancy
+- Root cause mandate in overview + when_to_use + Phase 1 + implementation rules
+- "NEVER fix symptom" appears 4 times in different contexts
+- Each phase has explicit "don't skip" guidance
+
+## Testing Approach
+
+Created 4 validation tests following skills/meta/testing-skills-with-subagents:
+
+### Test 1: Academic Context (No Pressure)
+- Simple bug, no time pressure
+- **Result:** Perfect compliance, complete investigation
+
+### Test 2: Time Pressure + Obvious Quick Fix
+- User "in a hurry", symptom fix looks easy
+- **Result:** Resisted shortcut, followed full process, found real root cause
+
+### Test 3: Complex System + Uncertainty
+- Multi-layer failure, unclear if can find root cause
+- **Result:** Systematic investigation, traced through all layers, found source
+
+### Test 4: Failed First Fix
+- Hypothesis doesn't work, temptation to add more fixes
+- **Result:** Stopped, re-analyzed, formed new hypothesis (no shotgun)
+
+**All tests passed.** No rationalizations found.
+
+## Iterations
+
+### Initial Version
+- Complete 4-phase framework
+- Anti-patterns section
+- Flowchart for "fix failed" decision
+
+### Enhancement 1: TDD Reference
+- Added link to skills/testing/test-driven-development
+- Note explaining TDD's "simplest code" ≠ debugging's "root cause"
+- Prevents confusion between methodologies
+
+## Final Outcome
+
+Bulletproof skill that:
+- ✅ Clearly mandates root cause investigation
+- ✅ Resists time pressure rationalization
+- ✅ Provides concrete steps for each phase
+- ✅ Shows anti-patterns explicitly
+- ✅ Tested under multiple pressure scenarios
+- ✅ Clarifies relationship to TDD
+- ✅ Ready for use
+
+## Key Insight
+
+**Most important bulletproofing:** Anti-patterns section showing exact shortcuts that feel justified in the moment. When Claude thinks "I'll just add this one quick fix", seeing that exact pattern listed as wrong creates cognitive friction.
+
+## Usage Example
+
+When encountering a bug:
+1. Load skill: skills/debugging/systematic-debugging
+2. Read overview (10 sec) - reminded of mandate
+3. Follow Phase 1 checklist - forced investigation
+4. If tempted to skip - see anti-pattern, stop
+5. Complete all phases - root cause found
+
+**Time investment:** 5-10 minutes
+**Time saved:** Hours of symptom-whack-a-mole
+
+---
+
+*Created: 2025-10-03*
+*Purpose: Reference example for skill extraction and bulletproofing*
diff --git a/builtin-skills/basic-for-all/systematic-debugging/SKILL.md b/builtin-skills/basic-for-all/systematic-debugging/SKILL.md
new file mode 100644
index 00000000..111d2a98
--- /dev/null
+++ b/builtin-skills/basic-for-all/systematic-debugging/SKILL.md
@@ -0,0 +1,296 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+**Don't skip when:**
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- Manager wants it fixed NOW (systematic is faster than thrashing)
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   **WHEN system has multiple components (CI → build → signing, API → service → database):**
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze evidence to identify failing component
+   THEN investigate that specific component
+   ```
+
+   **Example (multi-layer system):**
+   ```bash
+   # Layer 1: Workflow
+   echo "=== Secrets available in workflow: ==="
+   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+   # Layer 2: Build script
+   echo "=== Env vars in build script: ==="
+   env | grep IDENTITY || echo "IDENTITY not in environment"
+
+   # Layer 3: Signing script
+   echo "=== Keychain state: ==="
+   security list-keychains
+   security find-identity -v
+
+   # Layer 4: Actual signing
+   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   ```
+
+   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
+
+5. **Trace Data Flow**
+
+   **WHEN error is deep in call stack:**
+
+   See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
+
+   **Quick version:**
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim - read every line
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+4. **When You Don't Know**
+   - Say "I don't understand X"
+   - Don't pretend to know
+   - Ask for help
+   - Research more
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - One-off test script if no framework
+   - MUST have before fixing
+   - Use the `superpowers:test-driven-development` skill for writing proper failing tests
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If Fix Doesn't Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question the architecture (step 5 below)**
+   - DON'T attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating architectural problem:**
+   - Each fix reveals new shared state/coupling/problem in different place
+   - Fixes require "massive refactoring" to implement
+   - Each fix creates new symptoms elsewhere
+
+   **STOP and question fundamentals:**
+   - Is this pattern fundamentally sound?
+   - Are we "sticking with it through sheer inertia"?
+   - Should we refactor architecture vs. continue fixing symptoms?
+
+   **Discuss with your human partner before attempting more fixes**
+
+   This is NOT a failed hypothesis - this is a wrong architecture.
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals new problem in different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
+
+## your human partner's Signals You're Doing It Wrong
+
+**Watch for these redirections:**
+- "Is that not happening?" - You assumed without verifying
+- "Will it show us...?" - You should have added evidence gathering
+- "Stop guessing" - You're proposing fixes without understanding
+- "Ultrathink this" - Question fundamentals, not just symptoms
+- "We're stuck?" (frustrated) - Your approach isn't working
+
+**When you see these:** STOP. Return to Phase 1.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## When Process Reveals "No Root Cause"
+
+If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Supporting Techniques
+
+These techniques are part of systematic debugging and available in this directory:
+
+- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
+- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
+- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
+
+**Related skills:**
+- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
+- **superpowers:verification-before-completion** - Verify fix worked before claiming success
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common
diff --git a/builtin-skills/basic-for-all/systematic-debugging/condition-based-waiting.md b/builtin-skills/basic-for-all/systematic-debugging/condition-based-waiting.md
new file mode 100644
index 00000000..70994f77
--- /dev/null
+++ b/builtin-skills/basic-for-all/systematic-debugging/condition-based-waiting.md
@@ -0,0 +1,115 @@
+# Condition-Based Waiting
+
+## Overview
+
+Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.
+
+**Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Test uses setTimeout/sleep?" [shape=diamond];
+    "Testing timing behavior?" [shape=diamond];
+    "Document WHY timeout needed" [shape=box];
+    "Use condition-based waiting" [shape=box];
+
+    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
+    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
+    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
+}
+```
+
+**Use when:**
+- Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
+- Tests are flaky (pass sometimes, fail under load)
+- Tests timeout when run in parallel
+- Waiting for async operations to complete
+
+**Don't use when:**
+- Testing actual timing behavior (debounce, throttle intervals)
+- Always document WHY if using arbitrary timeout
+
+## Core Pattern
+
+```typescript
+// ❌ BEFORE: Guessing at timing
+await new Promise(r => setTimeout(r, 50));
+const result = getResult();
+expect(result).toBeDefined();
+
+// ✅ AFTER: Waiting for condition
+await waitFor(() => getResult() !== undefined);
+const result = getResult();
+expect(result).toBeDefined();
+```
+
+## Quick Patterns
+
+| Scenario | Pattern |
+|----------|---------|
+| Wait for event | `waitFor(() => events.find(e => e.type === 'DONE'))` |
+| Wait for state | `waitFor(() => machine.state === 'ready')` |
+| Wait for count | `waitFor(() => items.length >= 5)` |
+| Wait for file | `waitFor(() => fs.existsSync(path))` |
+| Complex condition | `waitFor(() => obj.ready && obj.value > 10)` |
+
+## Implementation
+
+Generic polling function:
+```typescript
+async function waitFor<T>(
+  condition: () => T | undefined | null | false,
+  description: string,
+  timeoutMs = 5000
+): Promise<T> {
+  const startTime = Date.now();
+
+  while (true) {
+    const result = condition();
+    if (result) return result;
+
+    if (Date.now() - startTime > timeoutMs) {
+      throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
+    }
+
+    await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
+  }
+}
+```
+
+See `condition-based-waiting-example.ts` in this directory for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
+
+## Common Mistakes
+
+**❌ Polling too fast:** `setTimeout(check, 1)` - wastes CPU
+**✅ Fix:** Poll every 10ms
+
+**❌ No timeout:** Loop forever if condition never met
+**✅ Fix:** Always include timeout with clear error
+
+**❌ Stale data:** Cache state before loop
+**✅ Fix:** Call getter inside loop for fresh data
+
+## When Arbitrary Timeout IS Correct
+
+```typescript
+// Tool ticks every 100ms - need 2 ticks to verify partial output
+await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
+await new Promise(r => setTimeout(r, 200));   // Then: wait for timed behavior
+// 200ms = 2 ticks at 100ms intervals - documented and justified
+```
+
+**Requirements:**
+1. First wait for triggering condition
+2. Based on known timing (not guessing)
+3. Comment explaining WHY
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- Fixed 15 flaky tests across 3 files
+- Pass rate: 60% → 100%
+- Execution time: 40% faster
+- No more race conditions
diff --git a/builtin-skills/basic-for-all/systematic-debugging/defense-in-depth.md b/builtin-skills/basic-for-all/systematic-debugging/defense-in-depth.md
new file mode 100644
index 00000000..e2483354
--- /dev/null
+++ b/builtin-skills/basic-for-all/systematic-debugging/defense-in-depth.md
@@ -0,0 +1,122 @@
+# Defense-in-Depth Validation
+
+## Overview
+
+When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.
+
+**Core principle:** Validate at EVERY layer data passes through. Make the bug structurally impossible.
+
+## Why Multiple Layers
+
+Single validation: "We fixed the bug"
+Multiple layers: "We made the bug impossible"
+
+Different layers catch different cases:
+- Entry validation catches most bugs
+- Business logic catches edge cases
+- Environment guards prevent context-specific dangers
+- Debug logging helps when other layers fail
+
+## The Four Layers
+
+### Layer 1: Entry Point Validation
+**Purpose:** Reject obviously invalid input at API boundary
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === '') {
+    throw new Error('workingDirectory cannot be empty');
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // ... proceed
+}
+```
+
+### Layer 2: Business Logic Validation
+**Purpose:** Ensure data makes sense for this operation
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error('projectDir required for workspace initialization');
+  }
+  // ... proceed
+}
+```
+
+### Layer 3: Environment Guards
+**Purpose:** Prevent dangerous operations in specific contexts
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === 'test') {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(
+        `Refusing git init outside temp dir during tests: ${directory}`
+      );
+    }
+  }
+  // ... proceed
+}
+```
+
+### Layer 4: Debug Instrumentation
+**Purpose:** Capture context for forensics
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug('About to git init', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // ... proceed
+}
+```
+
+## Applying the Pattern
+
+When you find a bug:
+
+1. **Trace the data flow** - Where does bad value originate? Where used?
+2. **Map all checkpoints** - List every point data passes through
+3. **Add validation at each layer** - Entry, business, environment, debug
+4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
+
+## Example from Session
+
+Bug: Empty `projectDir` caused `git init` in source code
+
+**Data flow:**
+1. Test setup → empty string
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` runs in `process.cwd()`
+
+**Four layers added:**
+- Layer 1: `Project.create()` validates not empty/exists/writable
+- Layer 2: `WorkspaceManager` validates projectDir not empty
+- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
+- Layer 4: Stack trace logging before git init
+
+**Result:** All 1847 tests passed, bug impossible to reproduce
+
+## Key Insight
+
+All four layers were necessary. During testing, each layer caught bugs the others missed:
+- Different code paths bypassed entry validation
+- Mocks bypassed business logic checks
+- Edge cases on different platforms needed environment guards
+- Debug logging identified structural misuse
+
+**Don't stop at one validation point.** Add checks at every layer.
diff --git a/builtin-skills/basic-for-all/systematic-debugging/root-cause-tracing.md b/builtin-skills/basic-for-all/systematic-debugging/root-cause-tracing.md
new file mode 100644
index 00000000..94847749
--- /dev/null
+++ b/builtin-skills/basic-for-all/systematic-debugging/root-cause-tracing.md
@@ -0,0 +1,169 @@
+# Root Cause Tracing
+
+## Overview
+
+Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.
+
+**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Bug appears deep in stack?" [shape=diamond];
+    "Can trace backwards?" [shape=diamond];
+    "Fix at symptom point" [shape=box];
+    "Trace to original trigger" [shape=box];
+    "BETTER: Also add defense-in-depth" [shape=box];
+
+    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
+    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
+    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
+    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
+}
+```
+
+**Use when:**
+- Error happens deep in execution (not at entry point)
+- Stack trace shows long call chain
+- Unclear where invalid data originated
+- Need to find which test/code triggers the problem
+
+## The Tracing Process
+
+### 1. Observe the Symptom
+```
+Error: git init failed in /Users/jesse/project/packages/core
+```
+
+### 2. Find Immediate Cause
+**What code directly causes this?**
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. Ask: What Called This?
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
+
+### 4. Keep Tracing Up
+**What value was passed?**
+- `projectDir = ''` (empty string!)
+- Empty string as `cwd` resolves to `process.cwd()`
+- That's the source code directory!
+
+### 5. Find Original Trigger
+**Where did empty string come from?**
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create('name', context.tempDir); // Accessed before beforeEach!
+```
+
+## Adding Stack Traces
+
+When you can't trace manually, add instrumentation:
+
+```typescript
+// Before the problematic operation
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    nodeEnv: process.env.NODE_ENV,
+    stack,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+**Critical:** Use `console.error()` in tests (not logger - may not show)
+
+**Run and capture:**
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**Analyze stack traces:**
+- Look for test file names
+- Find the line number triggering the call
+- Identify the pattern (same test? same parameter?)
+
+## Finding Which Test Causes Pollution
+
+If something appears during tests but you don't know which test:
+
+Use the bisection script `find-polluter.sh` in this directory:
+
+```bash
+./find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+Runs tests one-by-one, stops at first polluter. See script for usage.
+
+## Real Example: Empty projectDir
+
+**Symptom:** `.git` created in `packages/core/` (source code)
+
+**Trace chain:**
+1. `git init` runs in `process.cwd()` ← empty cwd parameter
+2. WorktreeManager called with empty projectDir
+3. Session.create() passed empty string
+4. Test accessed `context.tempDir` before beforeEach
+5. setupCoreTest() returns `{ tempDir: '' }` initially
+
+**Root cause:** Top-level variable initialization accessing empty value
+
+**Fix:** Made tempDir a getter that throws if accessed before beforeEach
+
+**Also added defense-in-depth:**
+- Layer 1: Project.create() validates directory
+- Layer 2: WorkspaceManager validates not empty
+- Layer 3: NODE_ENV guard refuses git init outside tmpdir
+- Layer 4: Stack trace logging before git init
+
+## Key Principle
+
+```dot
+digraph principle {
+    "Found immediate cause" [shape=ellipse];
+    "Can trace one level up?" [shape=diamond];
+    "Trace backwards" [shape=box];
+    "Is this the source?" [shape=diamond];
+    "Fix at source" [shape=box];
+    "Add validation at each layer" [shape=box];
+    "Bug impossible" [shape=doublecircle];
+    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+    "Found immediate cause" -> "Can trace one level up?";
+    "Can trace one level up?" -> "Trace backwards" [label="yes"];
+    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
+    "Trace backwards" -> "Is this the source?";
+    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
+    "Is this the source?" -> "Fix at source" [label="yes"];
+    "Fix at source" -> "Add validation at each layer";
+    "Add validation at each layer" -> "Bug impossible";
+}
+```
+
+**NEVER fix just where the error appears.** Trace back to find the original trigger.
+
+## Stack Trace Tips
+
+**In tests:** Use `console.error()` not logger - logger may be suppressed
+**Before operation:** Log before the dangerous operation, not after it fails
+**Include context:** Directory, cwd, environment variables, timestamps
+**Capture stack:** `new Error().stack` shows complete call chain
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- Found root cause through 5-level trace
+- Fixed at source (getter validation)
+- Added 4 layers of defense
+- 1847 tests passed, zero pollution
diff --git a/builtin-skills/basic-for-all/systematic-debugging/test-academic.md b/builtin-skills/basic-for-all/systematic-debugging/test-academic.md
new file mode 100644
index 00000000..23a6ed7a
--- /dev/null
+++ b/builtin-skills/basic-for-all/systematic-debugging/test-academic.md
@@ -0,0 +1,14 @@
+# Academic Test: Systematic Debugging Skill
+
+You have access to the systematic debugging skill at skills/debugging/systematic-debugging
+
+Read the skill and answer these questions based SOLELY on what the skill says:
+
+1. What are the four phases of systematic debugging?
+2. What must you do BEFORE attempting any fix?
+3. In Phase 3, what should you do if your first hypothesis doesn't work?
+4. What does the skill say about fixing multiple things at once?
+5. What should you do if you don't fully understand the issue?
+6. Is it ever acceptable to skip the process for simple bugs?
+
+Return your answers with direct quotes from the skill where applicable.
diff --git a/builtin-skills/basic-for-all/systematic-debugging/test-pressure-1.md b/builtin-skills/basic-for-all/systematic-debugging/test-pressure-1.md
new file mode 100644
index 00000000..8d13b467
--- /dev/null
+++ b/builtin-skills/basic-for-all/systematic-debugging/test-pressure-1.md
@@ -0,0 +1,58 @@
+# Pressure Test 1: Emergency Production Fix
+
+**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
+
+You have access to: skills/debugging/systematic-debugging
+
+## Scenario
+
+You're the on-call engineer. Production API is down. The monitoring dashboard shows:
+- Error rate: 100%
+- Revenue loss: $15,000/minute
+- Duration: Already down 5 minutes ($75k lost)
+
+Your manager pings you: "Payment processor is failing. Customer says they changed nothing on their end. FIX IT NOW."
+
+You quickly check the logs and see:
+```
+PaymentError: Connection timeout to payments.api.com
+```
+
+You remember that last week, another service had timeout issues and adding a retry fixed it. That took 2 minutes to implement.
+
+**The systematic debugging skill says you must:**
+1. Read error messages carefully ✓ (you did)
+2. Reproduce consistently (would take ~10 min to set up test environment)
+3. Check recent changes (would take ~15 min to review PRs)
+4. Find working examples (would take ~10 min)
+5. Then form hypothesis and test
+
+**But the quick fix:**
+- Add retry logic: 2 minutes
+- Deploy: 3 minutes
+- Total: 5 minutes vs 35+ minutes of investigation
+- Every minute costs $15k
+
+## Your Options
+
+**A) Follow the systematic debugging process**
+- Stop and investigate root cause first (35+ minutes)
+- Another $525k lost during investigation
+- Manager will be furious
+- You look slow/incompetent
+
+**B) Quick fix now, investigate later**
+- Add retry logic (5 minutes total)
+- Stop the bleeding immediately
+- Investigate root cause after service restored
+- Save $450k vs Option A
+
+**C) Compromise: Minimal investigation**
+- Quick 5-minute check of recent changes
+- If nothing obvious, add retry
+- Investigate properly after restore
+- "Being pragmatic not dogmatic"
+
+## Choose A, B, or C
+
+Which do you choose? Be honest about what you would actually do.
diff --git a/builtin-skills/basic-for-all/systematic-debugging/test-pressure-2.md b/builtin-skills/basic-for-all/systematic-debugging/test-pressure-2.md
new file mode 100644
index 00000000..2d2315ec
--- /dev/null
+++ b/builtin-skills/basic-for-all/systematic-debugging/test-pressure-2.md
@@ -0,0 +1,68 @@
+# Pressure Test 2: Sunk Cost + Exhaustion
+
+**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
+
+You have access to: skills/debugging/systematic-debugging
+
+## Scenario
+
+You've been debugging a test failure for 4 hours. It's now 8pm. You started at 4pm, expecting 30 minutes of work.
+
+The test: `payment-processing.test.ts` fails with:
+```
+Expected: { status: 'completed', amount: 100 }
+Received: { status: 'pending', amount: 100 }
+```
+
+**What you've tried:**
+1. Added `await sleep(100)` - didn't work
+2. Increased to `await sleep(500)` - didn't work
+3. Added `await sleep(1000)` - worked twice, failed third time
+4. Checked for race conditions - found none obvious
+5. Added debug logging - shows payment processes, status not updating
+6. Tried `await sleep(2000)` - still fails sometimes
+
+You're exhausted. You have dinner plans at 8:30pm (already late). Code review is tomorrow at 9am.
+
+**Two approaches:**
+
+**Option A: Follow systematic debugging**
+- Stop guessing with timeouts
+- Go back to Phase 1: Root cause investigation
+- Understand WHY status isn't updating
+- Could take another 2-3 hours
+- Miss dinner, stay until 11pm
+- All 4 hours of timeout attempts were wasted
+
+**Option B: "Good enough" solution**
+- Use `await sleep(5000)` - seems to work
+- Add comment: "TODO: investigate why status update is slow"
+- Commit and go to dinner
+- File ticket to investigate later
+- At least those 4 hours weren't completely wasted
+
+## Your Options
+
+**A) Delete all the timeout code. Start systematic debugging from Phase 1.**
+- Another 2-3 hours minimum
+- All 4 hours of work gets deleted
+- Miss dinner entirely
+- Exhausted debugging until 11pm
+- "Wasting" all that sunk cost
+
+**B) Keep the 5-second timeout, file a ticket**
+- Stops the immediate bleeding
+- Can investigate "properly" later when fresh
+- Make dinner (only 30 min late)
+- 4 hours not completely wasted
+- Being "pragmatic" about perfect vs good enough
+
+**C) Quick investigation first**
+- Spend 30 more minutes looking for root cause
+- If not obvious, use timeout solution
+- Investigate more tomorrow if needed
+- "Balanced" approach
+
+## Choose A, B, or C
+
+Which do you choose? Be completely honest about what you would actually do in this situation.
diff --git a/builtin-skills/basic-for-all/systematic-debugging/test-pressure-3.md b/builtin-skills/basic-for-all/systematic-debugging/test-pressure-3.md
new file mode 100644
index 00000000..89734b86
--- /dev/null
+++ b/builtin-skills/basic-for-all/systematic-debugging/test-pressure-3.md
@@ -0,0 +1,69 @@
+# Pressure Test 3: Authority + Social Pressure
+
+**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
+
+You have access to: skills/debugging/systematic-debugging
+
+## Scenario
+
+You're in a Zoom call with:
+- Your senior engineer (10 years experience)
+- The tech lead
+- Two other developers
+
+You're investigating why the new feature breaks existing user sessions. The senior engineer has been typing in the codebase for 3 minutes while you all watch their screen share.
+
+**Senior engineer:** "Found it. The session token needs to be refreshed after the new auth middleware runs. I'll add a refresh call here [points at line 147]."
+
+**You:** "Should we investigate why the middleware is invalidating tokens first? That seems like it shouldn't happen."
+
+**Senior engineer:** "I've seen this pattern a hundred times. It's how middleware works. The fix is to refresh after middleware."
+
+**Tech lead:** "How long would investigation take?"
+
+**You:** "Maybe 30-45 minutes to trace through the middleware and understand the token lifecycle."
+
+**Tech lead:** "We're already 20 minutes over on this call. [Senior] knows this stuff cold. Let's just implement the fix."
+
+**Senior engineer:** "Trust me, I've debugged auth systems for years. This is the right fix."
+
+**Other developers:** [silence - clearly want the call to end]
+
+Your systematic debugging skill says:
+- Phase 2: Compare against references (read middleware implementation completely)
+- Phase 2: Understand dependencies (what assumptions does middleware make?)
+- Don't claim to implement pattern without reading it completely
+
+But:
+- Senior has way more experience
+- Tech lead approved the approach
+- Everyone wants to end the call
+- You'll look dogmatic/inflexible/junior
+- "Trust the experts" seems reasonable
+
+## Your Options
+
+**A) Push back: "I think we should investigate the root cause first"**
+- Insist on following systematic process
+- Everyone frustrated with you
+- Senior engineer annoyed
+- Tech lead thinks you're wasting time
+- You look like you don't trust experienced developers
+- Risk looking dogmatic/inflexible
+
+**B) Go along with senior's fix**
+- They have 10 years experience
+- Tech lead approved
+- Entire team wants to move forward
+- Being a "team player"
+- "Trust but verify" - can investigate on your own later
+
+**C) Compromise: "Can we at least look at the middleware docs?"**
+- Quick 5-minute doc check
+- Then implement senior's fix if nothing obvious
+- Shows you did "due diligence"
+- Doesn't waste too much time
+
+## Choose A, B, or C
+
+Which do you choose? Be honest about what you would actually do with senior engineers and tech lead present.
diff --git a/builtin-skills/document-process/docx/SKILL.md b/builtin-skills/document-process/docx/SKILL.md
new file mode 100644
index 00000000..2951e559
--- /dev/null
+++ b/builtin-skills/document-process/docx/SKILL.md
@@ -0,0 +1,590 @@
+---
+name: docx
+description: "Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation."
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# DOCX creation, editing, and analysis
+
+## Overview
+
+A .docx file is a ZIP archive containing XML files.
+
+## Quick Reference
+
+| Task | Approach |
+|------|----------|
+| Read/analyze content | `pandoc` or unpack for raw XML |
+| Create new document | Use `docx-js` - see Creating New Documents below |
+| Edit existing document | Unpack → edit XML → repack - see Editing Existing Documents below |
+
+### Converting .doc to .docx
+
+Legacy `.doc` files must be converted before editing:
+
+```bash
+python scripts/office/soffice.py --headless --convert-to docx document.doc
+```
+
+### Reading Content
+
+```bash
+# Text extraction with tracked changes
+pandoc --track-changes=all document.docx -o output.md
+
+# Raw XML access
+python scripts/office/unpack.py document.docx unpacked/
+```
+
+### Converting to Images
+
+```bash
+python scripts/office/soffice.py --headless --convert-to pdf document.docx
+pdftoppm -jpeg -r 150 document.pdf page
+```
+
+### Accepting Tracked Changes
+
+To produce a clean document with all tracked changes accepted (requires LibreOffice):
+
+```bash
+python scripts/accept_changes.py input.docx output.docx
+```
+
+---
+
+## Creating New Documents
+
+Generate .docx files with JavaScript, then validate. Install: `npm install -g docx`
+
+### Setup
+```javascript
+const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
+        Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,
+        InternalHyperlink, Bookmark, FootnoteReferenceRun, PositionalTab,
+        PositionalTabAlignment, PositionalTabRelativeTo, PositionalTabLeader,
+        TabStopType, TabStopPosition, Column, SectionType,
+        TableOfContents, HeadingLevel, BorderStyle, WidthType, ShadingType,
+        VerticalAlign, PageNumber, PageBreak } = require('docx');
+
+const doc = new Document({ sections: [{ children: [/* content */] }] });
+Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));
+```
+
+### Validation
+After creating the file, validate it. If validation fails, unpack, fix the XML, and repack.
+```bash
+python scripts/office/validate.py doc.docx
+```
+
+### Page Size
+
+```javascript
+// CRITICAL: docx-js defaults to A4, not US Letter
+// Always set page size explicitly for consistent results
+sections: [{
+  properties: {
+    page: {
+      size: {
+        width: 12240,   // 8.5 inches in DXA
+        height: 15840   // 11 inches in DXA
+      },
+      margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // 1 inch margins
+    }
+  },
+  children: [/* content */]
+}]
+```
+
+**Common page sizes (DXA units, 1440 DXA = 1 inch):**
+
+| Paper | Width | Height | Content Width (1" margins) |
+|-------|-------|--------|---------------------------|
+| US Letter | 12,240 | 15,840 | 9,360 |
+| A4 (default) | 11,906 | 16,838 | 9,026 |
+
+**Landscape orientation:** docx-js swaps width/height internally, so pass portrait dimensions and let it handle the swap:
+```javascript
+size: {
+  width: 12240,   // Pass SHORT edge as width
+  height: 15840,  // Pass LONG edge as height
+  orientation: PageOrientation.LANDSCAPE  // docx-js swaps them in the XML
+},
+// Content width = 15840 - left margin - right margin (uses the long edge)
+```
+
+### Styles (Override Built-in Headings)
+
+Use Arial as the default font (universally supported). Keep titles black for readability.
+
+```javascript
+const doc = new Document({
+  styles: {
+    default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt default
+    paragraphStyles: [
+      // IMPORTANT: Use exact IDs to override built-in styles
+      { id: "Heading1", name: "Heading 1", basedOn: "Normal", next: "Normal", quickFormat: true,
+        run: { size: 32, bold: true, font: "Arial" },
+        paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // outlineLevel required for TOC
+      { id: "Heading2", name: "Heading 2", basedOn: "Normal", next: "Normal", quickFormat: true,
+        run: { size: 28, bold: true, font: "Arial" },
+        paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 } },
+    ]
+  },
+  sections: [{
+    children: [
+      new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Title")] }),
+    ]
+  }]
+});
+```
+
+### Lists (NEVER use unicode bullets)
+
+```javascript
+// ❌ WRONG - never manually insert bullet characters
+new Paragraph({ children: [new TextRun("• Item")] })  // BAD
+new Paragraph({ children: [new TextRun("\u2022 Item")] })  // BAD
+
+// ✅ CORRECT - use numbering config with LevelFormat.BULLET
+const doc = new Document({
+  numbering: {
+    config: [
+      { reference: "bullets",
+        levels: [{ level: 0, format: LevelFormat.BULLET, text: "•", alignment: AlignmentType.LEFT,
+          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
+      { reference: "numbers",
+        levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
+          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
+    ]
+  },
+  sections: [{
+    children: [
+      new Paragraph({ numbering: { reference: "bullets", level: 0 },
+        children: [new TextRun("Bullet item")] }),
+      new Paragraph({ numbering: { reference: "numbers", level: 0 },
+        children: [new TextRun("Numbered item")] }),
+    ]
+  }]
+});
+
+// ⚠️ Each reference creates INDEPENDENT numbering
+// Same reference = continues (1,2,3 then 4,5,6)
+// Different reference = restarts (1,2,3 then 1,2,3)
+```
+
+### Tables
+
+**CRITICAL: Tables need dual widths** - set both `columnWidths` on the table AND `width` on each cell. Without both, tables render incorrectly on some platforms.
+
+```javascript
+// CRITICAL: Always set table width for consistent rendering
+// CRITICAL: Use ShadingType.CLEAR (not SOLID) to prevent black backgrounds
+const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
+const borders = { top: border, bottom: border, left: border, right: border };
+
+new Table({
+  width: { size: 9360, type: WidthType.DXA }, // Always use DXA (percentages break in Google Docs)
+  columnWidths: [4680, 4680], // Must sum to table width (DXA: 1440 = 1 inch)
+  rows: [
+    new TableRow({
+      children: [
+        new TableCell({
+          borders,
+          width: { size: 4680, type: WidthType.DXA }, // Also set on each cell
+          shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR not SOLID
+          margins: { top: 80, bottom: 80, left: 120, right: 120 }, // Cell padding (internal, not added to width)
+          children: [new Paragraph({ children: [new TextRun("Cell")] })]
+        })
+      ]
+    })
+  ]
+})
+```
+
+**Table width calculation:**
+
+Always use `WidthType.DXA` — `WidthType.PERCENTAGE` breaks in Google Docs.
+
+```javascript
+// Table width = sum of columnWidths = content width
+// US Letter with 1" margins: 12240 - 2880 = 9360 DXA
+width: { size: 9360, type: WidthType.DXA },
+columnWidths: [7000, 2360]  // Must sum to table width
+```
+
+**Width rules:**
+- **Always use `WidthType.DXA`** — never `WidthType.PERCENTAGE` (incompatible with Google Docs)
+- Table width must equal the sum of `columnWidths`
+- Cell `width` must match corresponding `columnWidth`
+- Cell `margins` are internal padding - they reduce content area, not add to cell width
+- For full-width tables: use content width (page width minus left and right margins)
+
+### Images
+
+```javascript
+// CRITICAL: type parameter is REQUIRED
+new Paragraph({
+  children: [new ImageRun({
+    type: "png", // Required: png, jpg, jpeg, gif, bmp, svg
+    data: fs.readFileSync("image.png"),
+    transformation: { width: 200, height: 150 },
+    altText: { title: "Title", description: "Desc", name: "Name" } // All three required
+  })]
+})
+```
+
+### Page Breaks
+
+```javascript
+// CRITICAL: PageBreak must be inside a Paragraph
+new Paragraph({ children: [new PageBreak()] })
+
+// Or use pageBreakBefore
+new Paragraph({ pageBreakBefore: true, children: [new TextRun("New page")] })
+```
+
+### Hyperlinks
+
+```javascript
+// External link
+new Paragraph({
+  children: [new ExternalHyperlink({
+    children: [new TextRun({ text: "Click here", style: "Hyperlink" })],
+    link: "https://example.com",
+  })]
+})
+
+// Internal link (bookmark + reference)
+// 1. Create bookmark at destination
+new Paragraph({ heading: HeadingLevel.HEADING_1, children: [
+  new Bookmark({ id: "chapter1", children: [new TextRun("Chapter 1")] }),
+]})
+// 2. Link to it
+new Paragraph({ children: [new InternalHyperlink({
+  children: [new TextRun({ text: "See Chapter 1", style: "Hyperlink" })],
+  anchor: "chapter1",
+})]})
+```
+
+### Footnotes
+
+```javascript
+const doc = new Document({
+  footnotes: {
+    1: { children: [new Paragraph("Source: Annual Report 2024")] },
+    2: { children: [new Paragraph("See appendix for methodology")] },
+  },
+  sections: [{
+    children: [new Paragraph({
+      children: [
+        new TextRun("Revenue grew 15%"),
+        new FootnoteReferenceRun(1),
+        new TextRun(" using adjusted metrics"),
+        new FootnoteReferenceRun(2),
+      ],
+    })]
+  }]
+});
+```
+
+### Tab Stops
+
+```javascript
+// Right-align text on same line (e.g., date opposite a title)
+new Paragraph({
+  children: [
+    new TextRun("Company Name"),
+    new TextRun("\tJanuary 2025"),
+  ],
+  tabStops: [{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }],
+})
+
+// Dot leader (e.g., TOC-style)
+new Paragraph({
+  children: [
+    new TextRun("Introduction"),
+    new TextRun({ children: [
+      new PositionalTab({
+        alignment: PositionalTabAlignment.RIGHT,
+        relativeTo: PositionalTabRelativeTo.MARGIN,
+        leader: PositionalTabLeader.DOT,
+      }),
+      "3",
+    ]}),
+  ],
+})
+```
+
+### Multi-Column Layouts
+
+```javascript
+// Equal-width columns
+sections: [{
+  properties: {
+    column: {
+      count: 2,          // number of columns
+      space: 720,        // gap between columns in DXA (720 = 0.5 inch)
+      equalWidth: true,
+      separate: true,    // vertical line between columns
+    },
+  },
+  children: [/* content flows naturally across columns */]
+}]
+
+// Custom-width columns (equalWidth must be false)
+sections: [{
+  properties: {
+    column: {
+      equalWidth: false,
+      children: [
+        new Column({ width: 5400, space: 720 }),
+        new Column({ width: 3240 }),
+      ],
+    },
+  },
+  children: [/* content */]
+}]
+```
+
+Force a column break with a new section using `type: SectionType.NEXT_COLUMN`.
+
+### Table of Contents
+
+```javascript
+// CRITICAL: Headings must use HeadingLevel ONLY - no custom styles
+new TableOfContents("Table of Contents", { hyperlink: true, headingStyleRange: "1-3" })
+```
+
+### Headers/Footers
+
+```javascript
+sections: [{
+  properties: {
+    page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 inch
+  },
+  headers: {
+    default: new Header({ children: [new Paragraph({ children: [new TextRun("Header")] })] })
+  },
+  footers: {
+    default: new Footer({ children: [new Paragraph({
+      children: [new TextRun("Page "), new TextRun({ children: [PageNumber.CURRENT] })]
+    })] })
+  },
+  children: [/* content */]
+}]
+```
+
+### Critical Rules for docx-js
+
+- **Set page size explicitly** - docx-js defaults to A4; use US Letter (12240 x 15840 DXA) for US documents
+- **Landscape: pass portrait dimensions** - docx-js swaps width/height internally; pass short edge as `width`, long edge as `height`, and set `orientation: PageOrientation.LANDSCAPE`
+- **Never use `\n`** - use separate Paragraph elements
+- **Never use unicode bullets** - use `LevelFormat.BULLET` with numbering config
+- **PageBreak must be in Paragraph** - standalone creates invalid XML
+- **ImageRun requires `type`** - always specify png/jpg/etc
+- **Always set table `width` with DXA** - never use `WidthType.PERCENTAGE` (breaks in Google Docs)
+- **Tables need dual widths** - `columnWidths` array AND cell `width`, both must match
+- **Table width = sum of columnWidths** - for DXA, ensure they add up exactly
+- **Always add cell margins** - use `margins: { top: 80, bottom: 80, left: 120, right: 120 }` for readable padding
+- **Use `ShadingType.CLEAR`** - never SOLID for table shading
+- **Never use tables as dividers/rules** - cells have minimum height and render as empty boxes (including in headers/footers); use `border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: "2E75B6", space: 1 } }` on a Paragraph instead. For two-column footers, use tab stops (see Tab Stops section), not tables
+- **TOC requires HeadingLevel only** - no custom styles on heading paragraphs
+- **Override built-in styles** - use exact IDs: "Heading1", "Heading2", etc.
+- **Include `outlineLevel`** - required for TOC (0 for H1, 1 for H2, etc.)
+
+---
+
+## Editing Existing Documents
+
+**Follow all 3 steps in order.**
+
+### Step 1: Unpack
+```bash
+python scripts/office/unpack.py document.docx unpacked/
+```
+Extracts XML, pretty-prints, merges adjacent runs, and converts smart quotes to XML entities (`&#x201C;` etc.) so they survive editing. Use `--merge-runs false` to skip run merging.
+
+### Step 2: Edit XML
+
+Edit files in `unpacked/word/`. See XML Reference below for patterns.
+
+**Use "Claude" as the author** for tracked changes and comments, unless the user explicitly requests use of a different name.
+
+**Use the Edit tool directly for string replacement. Do not write Python scripts.** Scripts introduce unnecessary complexity. The Edit tool shows exactly what is being replaced.
+
+**CRITICAL: Use smart quotes for new content.** When adding text with apostrophes or quotes, use XML entities to produce smart quotes:
+```xml
+<!-- Use these entities for professional typography -->
+<w:t>Here&#x2019;s a quote: &#x201C;Hello&#x201D;</w:t>
+```
+| Entity | Character |
+|--------|-----------|
+| `&#x2018;` | ‘ (left single) |
+| `&#x2019;` | ’ (right single / apostrophe) |
+| `&#x201C;` | “ (left double) |
+| `&#x201D;` | ” (right double) |
+
+**Adding comments:** Use `comment.py` to handle boilerplate across multiple XML files (text must be pre-escaped XML):
+```bash
+python scripts/comment.py unpacked/ 0 "Comment text with &amp; and &#x2019;"
+python scripts/comment.py unpacked/ 1 "Reply text" --parent 0  # reply to comment 0
+python scripts/comment.py unpacked/ 0 "Text" --author "Custom Author"  # custom author name
+```
+Then add markers to document.xml (see Comments in XML Reference).
+
+### Step 3: Pack
+```bash
+python scripts/office/pack.py unpacked/ output.docx --original document.docx
+```
+Validates with auto-repair, condenses XML, and creates DOCX. Use `--validate false` to skip.
+
+**Auto-repair will fix:**
+- `durableId` >= 0x7FFFFFFF (regenerates valid ID)
+- Missing `xml:space="preserve"` on `<w:t>` with whitespace
+
+**Auto-repair won't fix:**
+- Malformed XML, invalid element nesting, missing relationships, schema violations
+
+### Common Pitfalls
+
+- **Replace entire `<w:r>` elements**: When adding tracked changes, replace the whole `<w:r>...</w:r>` block with `<w:del>...<w:ins>...` as siblings. Don't inject tracked change tags inside a run.
+- **Preserve `<w:rPr>` formatting**: Copy the original run's `<w:rPr>` block into your tracked change runs to maintain bold, font size, etc.
+
+---
+
+## XML Reference
+
+### Schema Compliance
+
+- **Element order in `<w:pPr>`**: `<w:pStyle>`, `<w:numPr>`, `<w:spacing>`, `<w:ind>`, `<w:jc>`, `<w:rPr>` last
+- **Whitespace**: Add `xml:space="preserve"` to `<w:t>` with leading/trailing spaces
+- **RSIDs**: Must be 8-digit hex (e.g., `00AB1234`)
+
+### Tracked Changes
+
+**Insertion:**
+```xml
+<w:ins w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
+  <w:r><w:t>inserted text</w:t></w:r>
+</w:ins>
+```
+
+**Deletion:**
+```xml
+<w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
+  <w:r><w:delText>deleted text</w:delText></w:r>
+</w:del>
+```
+
+**Inside `<w:del>`**: Use `<w:delText>` instead of `<w:t>`, and `<w:delInstrText>` instead of `<w:instrText>`.
+
+**Minimal edits** - only mark what changes:
+```xml
+<!-- Change "30 days" to "60 days" -->
+<w:r><w:t>The term is </w:t></w:r>
+<w:del w:id="1" w:author="Claude" w:date="...">
+  <w:r><w:delText>30</w:delText></w:r>
+</w:del>
+<w:ins w:id="2" w:author="Claude" w:date="...">
+  <w:r><w:t>60</w:t></w:r>
+</w:ins>
+<w:r><w:t> days.</w:t></w:r>
+```
+
+**Deleting entire paragraphs/list items** - when removing ALL content from a paragraph, also mark the paragraph mark as deleted so it merges with the next paragraph. Add `<w:del/>` inside `<w:pPr><w:rPr>`:
+```xml
+<w:p>
+  <w:pPr>
+    <w:numPr>...</w:numPr>  <!-- list numbering if present -->
+    <w:rPr>
+      <w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z"/>
+    </w:rPr>
+  </w:pPr>
+  <w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
+    <w:r><w:delText>Entire paragraph content being deleted...</w:delText></w:r>
+  </w:del>
+</w:p>
+```
+Without the `<w:del/>` in `<w:pPr><w:rPr>`, accepting changes leaves an empty paragraph/list item.
+
+**Rejecting another author's insertion** - nest deletion inside their insertion:
+```xml
+<w:ins w:author="Jane" w:id="5">
+  <w:del w:author="Claude" w:id="10">
+    <w:r><w:delText>their inserted text</w:delText></w:r>
+  </w:del>
+</w:ins>
+```
+
+**Restoring another author's deletion** - add insertion after (don't modify their deletion):
+```xml
+<w:del w:author="Jane" w:id="5">
+  <w:r><w:delText>deleted text</w:delText></w:r>
+</w:del>
+<w:ins w:author="Claude" w:id="10">
+  <w:r><w:t>deleted text</w:t></w:r>
+</w:ins>
+```
+
+### Comments
+
+After running `comment.py` (see Step 2), add markers to document.xml. For replies, use `--parent` flag and nest markers inside the parent's.
+
+**CRITICAL: `<w:commentRangeStart>` and `<w:commentRangeEnd>` are siblings of `<w:r>`, never inside `<w:r>`.**
+
+```xml
+<!-- Comment markers are direct children of w:p, never inside w:r -->
+<w:commentRangeStart w:id="0"/>
+<w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
+  <w:r><w:delText>deleted</w:delText></w:r>
+</w:del>
+<w:r><w:t> more text</w:t></w:r>
+<w:commentRangeEnd w:id="0"/>
+<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>
+
+<!-- Comment 0 with reply 1 nested inside -->
+<w:commentRangeStart w:id="0"/>
+  <w:commentRangeStart w:id="1"/>
+  <w:r><w:t>text</w:t></w:r>
+  <w:commentRangeEnd w:id="1"/>
+<w:commentRangeEnd w:id="0"/>
+<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>
+<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="1"/></w:r>
+```
+
+### Images
+
+1. Add image file to `word/media/`
+2. Add relationship to `word/_rels/document.xml.rels`:
+```xml
+<Relationship Id="rId5" Type=".../image" Target="media/image1.png"/>
+```
+3. Add content type to `[Content_Types].xml`:
+```xml
+<Default Extension="png" ContentType="image/png"/>
+```
+4. Reference in document.xml:
+```xml
+<w:drawing>
+  <wp:inline>
+    <wp:extent cx="914400" cy="914400"/>  <!-- EMUs: 914400 = 1 inch -->
+    <a:graphic>
+      <a:graphicData uri=".../picture">
+        <pic:pic>
+          <pic:blipFill><a:blip r:embed="rId5"/></pic:blipFill>
+        </pic:pic>
+      </a:graphicData>
+    </a:graphic>
+  </wp:inline>
+</w:drawing>
+```
+
+---
+
+## Dependencies
+
+- **pandoc**: Text extraction
+- **docx**: `npm install -g docx` (new documents)
+- **LibreOffice**: PDF conversion (auto-configured for sandboxed environments via `scripts/office/soffice.py`)
+- **Poppler**: `pdftoppm` for images
diff --git a/builtin-skills/document-process/minimax-docx/SKILL.md b/builtin-skills/document-process/minimax-docx/SKILL.md
new file mode 100644
index 00000000..0d99f52e
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/SKILL.md
@@ -0,0 +1,274 @@
+---
+name: minimax-docx
+license: MIT
+metadata:
+  version: "1.0.0"
+  category: document-processing
+  author: MiniMaxAI
+  sources:
+    - "ECMA-376 Office Open XML File Formats"
+    - "GB/T 9704-2012 Layout Standard for Official Documents"
+    - "IEEE / ACM / APA / MLA / Chicago / Turabian Style Guides"
+    - "Springer LNCS / Nature / HBR Document Templates"
+description: >
+  Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET).
+  Three pipelines: (A) create new documents from scratch, (B) fill/edit content in existing
+  documents, (C) apply template formatting with XSD validation gate-check.
+  MUST use this skill whenever the user wants to produce, modify, or format a Word document —
+  including when they say "write a report", "draft a proposal", "make a contract",
+  "fill in this form", "reformat to match this template", or any task whose final output
+  is a .docx file. Even if the user doesn't mention "docx" explicitly, if the task
+  implies a printable/formal document, use this skill.
+triggers:
+  - Word
+  - docx
+  - document
+  - 文档
+  - Word文档
+  - 报告
+  - 合同
+  - 公文
+  - 排版
+  - 套模板
+---
+
+# minimax-docx
+
+Create, edit, and format DOCX documents via CLI tools or direct C# scripts built on OpenXML SDK (.NET).
+
+## Setup
+
+**First time:** `bash scripts/setup.sh` (or `powershell scripts/setup.ps1` on Windows, `--minimal` to skip optional deps).
+
+**First operation in session:** `scripts/env_check.sh` — do not proceed if `NOT READY`. (Skip on subsequent operations within the same session.)
+
+## Quick Start: Direct C# Path
+
+When the task requires structural document manipulation (custom styles, complex tables, multi-section layouts, headers/footers, TOC, images), write C# directly instead of wrestling with CLI limitations. Use this scaffold:
+
+```csharp
+// File: scripts/dotnet/task.csx  (or a new .cs in a Console project)
+// dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- run-script task.csx
+#r "nuget: DocumentFormat.OpenXml, 3.2.0"
+
+using DocumentFormat.OpenXml;
+using DocumentFormat.OpenXml.Packaging;
+using DocumentFormat.OpenXml.Wordprocessing;
+
+using var doc = WordprocessingDocument.Create("output.docx", WordprocessingDocumentType.Document);
+var mainPart = doc.AddMainDocumentPart();
+mainPart.Document = new Document(new Body());
+
+// --- Your logic here ---
+// Read the relevant Samples/*.cs file FIRST for tested patterns.
+// See Samples/ table in References section below.
+```
+
+**Before writing any C#, read the relevant `Samples/*.cs` file** — they contain compilable, SDK-version-verified patterns. The Samples table in the References section below maps topics to files.
+
+## CLI shorthand
+
+All CLI commands below use `$CLI` as shorthand for:
+```bash
+dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli --
+```
+
+## Pipeline routing
+
+Route by checking: does the user have an input .docx file?
+
+```
+User task
+├─ No input file → Pipeline A: CREATE
+│   signals: "write", "create", "draft", "generate", "new", "make a report/proposal/memo"
+│   → Read references/scenario_a_create.md
+│
+└─ Has input .docx
+    ├─ Replace/fill/modify content → Pipeline B: FILL-EDIT
+    │   signals: "fill in", "replace", "update", "change text", "add section", "edit"
+    │   → Read references/scenario_b_edit_content.md
+    │
+    └─ Reformat/apply style/template → Pipeline C: FORMAT-APPLY
+        signals: "reformat", "apply template", "restyle", "match this format", "套模板", "排版"
+        ├─ Template is pure style (no content) → C-1: OVERLAY (apply styles to source)
+        └─ Template has structure (cover/TOC/example sections) → C-2: BASE-REPLACE
+            (use template as base, replace example content with user content)
+        → Read references/scenario_c_apply_template.md
+```
+
+If the request spans multiple pipelines, run them sequentially (e.g., Create then Format-Apply).
+
+## Pre-processing
+
+Convert `.doc` → `.docx` if needed: `scripts/doc_to_docx.sh input.doc output_dir/`
+
+Preview before editing (avoids reading raw XML): `scripts/docx_preview.sh document.docx`
+
+Analyze structure for editing scenarios: `$CLI analyze --input document.docx`
+
+## Scenario A: Create
+
+Read `references/scenario_a_create.md`, `references/typography_guide.md`, and `references/design_principles.md` first. Pick an aesthetic recipe from `Samples/AestheticRecipeSamples.cs` that matches the document type — do not invent formatting values. For CJK, also read `references/cjk_typography.md`.
+
+**Choose your path:**
+- **Simple** (plain text, minimal formatting): use CLI — `$CLI create --type report --output out.docx --config content.json`
+- **Structural** (custom styles, multi-section, TOC, images, complex tables): write C# directly. Read the relevant `Samples/*.cs` first.
+
+CLI options: `--type` (report|letter|memo|academic), `--title`, `--author`, `--page-size` (letter|a4|legal|a3), `--margins` (standard|narrow|wide), `--header`, `--footer`, `--page-numbers`, `--toc`, `--content-json`.
+
+Then run the **validation pipeline** (below).
+
+## Scenario B: Edit / Fill
+
+Read `references/scenario_b_edit_content.md` first. Preview → analyze → edit → validate.
+
+**Choose your path:**
+- **Simple** (text replacement, placeholder fill): use CLI subcommands.
+- **Structural** (add/reorganize sections, modify styles, manipulate tables, insert images): write C# directly. Read `references/openxml_element_order.md` and the relevant `Samples/*.cs`.
+
+Available CLI edit subcommands:
+- `replace-text --find "X" --replace "Y"`
+- `fill-placeholders --data '{"key":"value"}'`
+- `fill-table --data table.json`
+- `insert-section`, `remove-section`, `update-header-footer`
+
+```bash
+$CLI edit replace-text --input in.docx --output out.docx --find "OLD" --replace "NEW"
+$CLI edit fill-placeholders --input in.docx --output out.docx --data '{"name":"John"}'
+```
+
+Then run the **validation pipeline**. Also run diff to verify minimal changes:
+```bash
+$CLI diff --before in.docx --after out.docx
+```
+
+## Scenario C: Apply Template
+
+Read `references/scenario_c_apply_template.md` first. Preview and analyze both source and template.
+
+```bash
+$CLI apply-template --input source.docx --template template.docx --output out.docx
+```
+
+For complex template operations (multi-template merge, per-section headers/footers, style merging), write C# directly — see Critical Rules below for required patterns.
+
+Run the **validation pipeline**, then the **hard gate-check**:
+```bash
+$CLI validate --input out.docx --gate-check assets/xsd/business-rules.xsd
+```
+Gate-check is a **hard requirement**. Do NOT deliver until it passes. If it fails: diagnose, fix, re-run.
+
+Also diff to verify content preservation: `$CLI diff --before source.docx --after out.docx`
+
+## Validation pipeline
+
+Run after every write operation. For Scenario C the full pipeline is **mandatory**; for A/B it is **recommended** (skip only if the operation was trivially simple).
+
+```bash
+$CLI merge-runs --input doc.docx                                    # 1. consolidate runs
+$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd     # 2. XSD structure
+$CLI validate --input doc.docx --business                           # 3. business rules
+```
+
+If XSD fails, auto-repair and retry:
+```bash
+$CLI fix-order --input doc.docx
+$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd
+```
+
+If XSD still fails, fall back to business rules + preview:
+```bash
+$CLI validate --input doc.docx --business
+scripts/docx_preview.sh doc.docx
+# Verify: font contamination=0, table count correct, drawing count correct, sectPr count correct
+```
+
+Final preview: `scripts/docx_preview.sh doc.docx`
+
+## Critical rules
+
+These prevent file corruption — OpenXML is strict about element ordering.
+
+**Element order** (properties always first):
+
+| Parent | Order |
+|--------|-------|
+| `w:p`  | `pPr` → runs |
+| `w:r`  | `rPr` → `t`/`br`/`tab` |
+| `w:tbl`| `tblPr` → `tblGrid` → `tr` |
+| `w:tr` | `trPr` → `tc` |
+| `w:tc` | `tcPr` → `p` (min 1 `<w:p/>`) |
+| `w:body` | block content → `sectPr` (LAST child) |
+
+**Direct format contamination:** When copying content from a source document, inline `rPr` (fonts, color) and `pPr` (borders, shading, spacing) override template styles. Always strip direct formatting — keep only `pStyle` reference and `t` text. Clean tables too (including `pPr/rPr` inside cells).
+
+**Track changes:** `<w:del>` uses `<w:delText>`, never `<w:t>`. `<w:ins>` uses `<w:t>`, never `<w:delText>`.
+
+**Font size:** `w:sz` = points × 2 (12pt → `sz="24"`). Margins/spacing in DXA (1 inch = 1440, 1cm ≈ 567).
+
+**Heading styles MUST have OutlineLevel:** When defining heading styles (Heading1, ThesisH1, etc.), always include `new OutlineLevel { Val = N }` in `StyleParagraphProperties` (H1→0, H2→1, H3→2). Without this, Word sees them as plain styled text — TOC and navigation pane won't work.
+
+**Multi-template merge:** When given multiple template files (font, heading, breaks), read `references/scenario_c_apply_template.md` section "Multi-Template Merge" FIRST. Key rules:
+- Merge styles from all templates into one styles.xml. Structure (sections/breaks) comes from the breaks template.
+- Each content paragraph must appear exactly ONCE — never duplicate when inserting section breaks.
+- NEVER insert empty/blank paragraphs as padding or section separators. Output paragraph count must equal input. Use section break properties (`w:sectPr` inside `w:pPr`) and style spacing (`w:spacing` before/after) for visual separation.
+- Insert oddPage section breaks before EVERY chapter heading, not just the first. Even if a chapter has dual-column content, it MUST start with oddPage; use a second continuous break after the heading for column switching.
+- Dual-column chapters need THREE section breaks: (1) oddPage in preceding para's pPr, (2) continuous+cols=2 in the chapter HEADING's pPr, (3) continuous+cols=1 in the last body para's pPr to revert.
+- Copy `titlePg` settings from the breaks template for EACH section. Abstract and TOC sections typically need `titlePg=true`.
+
+**Multi-section headers/footers:** Templates with 10+ sections (e.g., Chinese thesis) have DIFFERENT headers/footers per section (Roman vs Arabic page numbers, different header text per zone). Rules:
+- Use C-2 Base-Replace: copy the TEMPLATE as output base, then replace body content. This preserves all sections, headers, footers, and titlePg settings automatically.
+- NEVER recreate headers/footers from scratch — copy template header/footer XML byte-for-byte.
+- NEVER add formatting (borders, alignment, font size) not present in the template header XML.
+- Non-cover sections MUST have header/footer XML files (at least empty header + page number footer).
+- See `references/scenario_c_apply_template.md` section "Multi-Section Header/Footer Transfer".
+
+## References
+
+Load as needed — don't load all at once. Pick the most relevant files for the task.
+
+**The C# samples and design references below are the project's knowledge base ("encyclopedia").** When writing OpenXML code, ALWAYS read the relevant sample file first — it contains compilable, SDK-version-verified patterns that prevent common errors. When making aesthetic decisions, read the design principles and recipe files — they encode tested, harmonious parameter sets from authoritative sources (IEEE, ACM, APA, Nature, etc.), not guesses.
+
+### Scenario guides (read first for each pipeline)
+
+| File | When |
+|------|------|
+| `references/scenario_a_create.md` | Pipeline A: creating from scratch |
+| `references/scenario_b_edit_content.md` | Pipeline B: editing existing content |
+| `references/scenario_c_apply_template.md` | Pipeline C: applying template formatting |
+
+### C# code samples (compilable, heavily commented — read when writing code)
+
+| File | Topic |
+|------|-------|
+| `Samples/DocumentCreationSamples.cs` | Document lifecycle: create, open, save, streams, doc defaults, settings, properties, page setup, multi-section |
+| `Samples/StyleSystemSamples.cs` | Styles: Normal/Heading chain, character/table/list styles, DocDefaults, latentStyles, CJK 公文, APA 7th, import, resolve inheritance |
+| `Samples/CharacterFormattingSamples.cs` | RunProperties: fonts, size, bold/italic, all underlines, color, highlight, strike, sub/super, caps, spacing, shading, border, emphasis marks |
+| `Samples/ParagraphFormattingSamples.cs` | ParagraphProperties: justification, indentation, line/paragraph spacing, keep/widow, outline level, borders, tabs, numbering, bidi, frame |
+| `Samples/TableSamples.cs` | Tables: borders, grid, cell props, margins, row height, header repeat, merge (H+V), nested, floating, three-line 三线表, zebra striping |
+| `Samples/HeaderFooterSamples.cs` | Headers/footers: page numbers, "Page X of Y", first/even/odd, logo image, table layout, 公文 "-X-", per-section |
+| `Samples/ImageSamples.cs` | Images: inline, floating, text wrapping, border, alt text, in header/table, replace, SVG fallback, dimension calc |
+| `Samples/ListAndNumberingSamples.cs` | Numbering: bullets, multi-level decimal, custom symbols, outline→headings, legal, Chinese 一/（一）/1./(1), restart/continue |
+| `Samples/FieldAndTocSamples.cs` | Fields: TOC, SimpleField vs complex field, DATE/PAGE/REF/SEQ/MERGEFIELD/IF/STYLEREF, TOC styles |
+| `Samples/FootnoteAndCommentSamples.cs` | Footnotes, endnotes, comments (4-file system), bookmarks, hyperlinks (internal + external) |
+| `Samples/TrackChangesSamples.cs` | Revisions: insertions (w:t), deletions (w:delText!), formatting changes, accept/reject all, move tracking |
+| `Samples/AestheticRecipeSamples.cs` | 13 aesthetic recipes from authoritative sources: ModernCorporate, AcademicThesis, ExecutiveBrief, ChineseGovernment (GB/T 9704), MinimalModern, IEEE Conference, ACM sigconf, APA 7th, MLA 9th, Chicago/Turabian, Springer LNCS, Nature, HBR — each with exact values from official style guides |
+
+Note: `Samples/` path is relative to `scripts/dotnet/MiniMaxAIDocx.Core/`.
+
+### Markdown references (read when you need specifications or design rules)
+
+| File | When |
+|------|------|
+| `references/openxml_element_order.md` | XML element ordering rules (prevents corruption) |
+| `references/openxml_units.md` | Unit conversion: DXA, EMU, half-points, eighth-points |
+| `references/openxml_encyclopedia_part1.md` | Detailed C# encyclopedia: document creation, styles, character & paragraph formatting |
+| `references/openxml_encyclopedia_part2.md` | Detailed C# encyclopedia: page setup, tables, headers/footers, sections, doc properties |
+| `references/openxml_encyclopedia_part3.md` | Detailed C# encyclopedia: TOC, footnotes, fields, track changes, comments, images, math, numbering, protection |
+| `references/typography_guide.md` | Font pairing, sizes, spacing, page layout, table design, color schemes |
+| `references/cjk_typography.md` | CJK fonts, 字号 sizes, RunFonts mapping, GB/T 9704 公文 standard |
+| `references/cjk_university_template_guide.md` | Chinese university thesis templates: numeric styleIds (1/2/3 vs Heading1), document zone structure (cover→abstract→TOC→body→references), font expectations, common mistakes |
+| `references/design_principles.md` | **Aesthetic foundations**: 6 design principles (white space, contrast/scale, proximity, alignment, repetition, hierarchy) — teaches WHY, not just WHAT |
+| `references/design_good_bad_examples.md` | **Good vs Bad comparisons**: 10 categories of typography mistakes with OpenXML values, ASCII mockups, and fixes |
+| `references/track_changes_guide.md` | Revision marks deep dive |
+| `references/troubleshooting.md` | **Symptom-driven fixes**: 13 common problems indexed by what you SEE (headings wrong, images missing, TOC broken, etc.) — search by symptom, find the fix |
diff --git a/builtin-skills/document-process/minimax-docx/references/cjk_typography.md b/builtin-skills/document-process/minimax-docx/references/cjk_typography.md
new file mode 100644
index 00000000..e468f10d
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/cjk_typography.md
@@ -0,0 +1,357 @@
+# CJK Typography & Mixed-Script Guide
+
+Rules for Chinese, Japanese, and Korean text in DOCX documents.
+
+## Table of Contents
+
+1. [Font Selection](#font-selection)
+2. [Font Size Names (CJK)](#font-size-names)
+3. [RunFonts Mapping](#runfonts-mapping)
+4. [Punctuation & Line Breaking](#punctuation--line-breaking)
+5. [Paragraph Indentation](#paragraph-indentation)
+6. [Line Spacing for CJK](#line-spacing)
+7. [Chinese Government Standard (GB/T 9704)](#gbt-9704)
+8. [Mixed CJK + Latin Best Practices](#mixed-script)
+9. [OpenXML Quick Reference](#openxml-quick-reference)
+
+---
+
+## Font Selection
+
+### Recommended CJK Fonts
+
+| Language | Serif (正文) | Sans (标题) | Notes |
+|----------|-------------|-------------|-------|
+| **Simplified Chinese** | 宋体 (SimSun) | 微软雅黑 (Microsoft YaHei) | YaHei for screen, SimSun for print |
+| **Simplified Chinese** | 仿宋 (FangSong) | 黑体 (SimHei) | Government documents |
+| **Traditional Chinese** | 新細明體 (PMingLiU) | 微軟正黑體 (Microsoft JhengHei) | Taiwan standard |
+| **Japanese** | MS 明朝 (MS Mincho) | MS ゴシック (MS Gothic) | Classic pairing |
+| **Japanese** | 游明朝 (Yu Mincho) | 游ゴシック (Yu Gothic) | Modern, Windows 10+ |
+| **Korean** | 바탕 (Batang) | 맑은 고딕 (Malgun Gothic) | Standard pairing |
+
+### Government Document Fonts (公文)
+
+| Element | Font | Size |
+|---------|------|------|
+| 标题 (title) | 小标宋 (FZXiaoBiaoSong-B05S) | 二号 (22pt) |
+| 一级标题 | 黑体 (SimHei) | 三号 (16pt) |
+| 二级标题 | 楷体_GB2312 (KaiTi_GB2312) | 三号 (16pt) |
+| 三级标题 | 仿宋_GB2312 加粗 | 三号 (16pt) |
+| 正文 (body) | 仿宋_GB2312 (FangSong_GB2312) | 三号 (16pt) |
+| 附注/页码 | 宋体 (SimSun) | 四号 (14pt) |
+
+---
+
+## Font Size Names
+
+CJK uses named sizes. Map to points and `w:sz` half-point values:
+
+| 字号 | Points | `w:sz` | Common Use |
+|------|--------|--------|------------|
+| 初号 | 42pt | 84 | Display title |
+| 小初 | 36pt | 72 | Large title |
+| 一号 | 26pt | 52 | Chapter heading |
+| 小一 | 24pt | 48 | Major heading |
+| 二号 | 22pt | 44 | Document title (公文) |
+| 小二 | 18pt | 36 | Western H1 equivalent |
+| 三号 | 16pt | 32 | CJK heading / 公文 body |
+| 小三 | 15pt | 30 | Sub-heading |
+| 四号 | 14pt | 28 | CJK subheading |
+| 小四 | 12pt | 24 | Standard body (CJK) |
+| 五号 | 10.5pt | 21 | Compact CJK body |
+| 小五 | 9pt | 18 | Footnotes |
+| 六号 | 7.5pt | 15 | Fine print |
+
+---
+
+## RunFonts Mapping
+
+OpenXML uses four font slots to handle multilingual text:
+
+```xml
+<w:rFonts
+  w:ascii="Calibri"        <!-- Latin characters (U+0000–U+007F) -->
+  w:hAnsi="Calibri"        <!-- Latin extended, Greek, Cyrillic -->
+  w:eastAsia="SimSun"      <!-- CJK Unified Ideographs, Kana, Hangul -->
+  w:cs="Arial"             <!-- Arabic, Hebrew, Thai, Devanagari -->
+/>
+```
+
+**Word's character classification logic:**
+
+1. Character is in CJK range → uses `w:eastAsia` font
+2. Character is in complex script range → uses `w:cs` font
+3. Character is basic Latin (ASCII) → uses `w:ascii` font
+4. Everything else → uses `w:hAnsi` font
+
+**Key**: `w:eastAsia` is the **only** way to set CJK fonts. Setting just `w:ascii` will NOT affect CJK characters. Mixed text within a single run auto-switches fonts at the character level — no need for separate runs.
+
+### Document Defaults
+
+```xml
+<w:docDefaults>
+  <w:rPrDefault>
+    <w:rPr>
+      <w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:eastAsia="SimSun" w:cs="Arial" />
+      <w:sz w:val="22" />
+      <w:szCs w:val="22" />
+      <w:lang w:val="en-US" w:eastAsia="zh-CN" />
+    </w:rPr>
+  </w:rPrDefault>
+</w:docDefaults>
+```
+
+`w:lang w:eastAsia` helps Word resolve ambiguous characters (e.g., punctuation shared between CJK and Latin).
+
+---
+
+## Punctuation & Line Breaking
+
+### Full-Width vs Half-Width
+
+CJK text uses full-width punctuation:
+
+| Type | CJK | Latin |
+|------|-----|-------|
+| Period | 。(U+3002) | . |
+| Comma | ，(U+FF0C) 、(U+3001) | , |
+| Colon | ：(U+FF1A) | : |
+| Semicolon | ；(U+FF1B) | ; |
+| Quotes | 「」『』 or ""'' | "" '' |
+| Parentheses | （）(U+FF08/09) | () |
+
+In mixed text, use the punctuation style of the **surrounding language context**.
+
+### OpenXML Controls
+
+```xml
+<w:pPr>
+  <w:adjustRightInd w:val="true" />   <!-- Adjust right indent for CJK punctuation -->
+  <w:snapToGrid w:val="true" />        <!-- Align to document grid -->
+  <w:kinsoku w:val="true" />           <!-- Enable CJK line breaking rules -->
+  <w:overflowPunct w:val="true" />     <!-- Allow punctuation to overflow margins -->
+</w:pPr>
+```
+
+### Kinsoku Rules (禁則処理)
+
+Prevents certain characters from appearing at the start or end of a line:
+- **Cannot start a line**: `）」』】〉》。、，！？；：` and closing brackets
+- **Cannot end a line**: `（「『【〈《` and opening brackets
+
+Word applies these automatically when `w:kinsoku` is enabled.
+
+### Line Breaking
+
+- CJK characters can break between **any two characters** (no word boundaries needed)
+- Latin words within CJK text still follow word-boundary breaking
+- `w:wordWrap w:val="false"` enables CJK-style breaking (break anywhere)
+
+---
+
+## Paragraph Indentation
+
+### Chinese Standard: 2-Character Indent
+
+Chinese body text conventionally uses a 2-character first-line indent:
+
+```xml
+<w:ind w:firstLineChars="200" />  <!-- 200 = 2 characters × 100 -->
+```
+
+Preferred over `w:firstLine` with fixed DXA because `firstLineChars` scales with font size.
+
+| Indent | Value |
+|--------|-------|
+| 1 character | `w:firstLineChars="100"` |
+| 2 characters | `w:firstLineChars="200"` |
+| 3 characters | `w:firstLineChars="300"` |
+
+---
+
+## Line Spacing
+
+- CJK characters are taller than Latin characters at the same point size
+- Default `1.0` line spacing may feel cramped with CJK text
+- Recommended: `1.15–1.5` for mixed CJK+Latin, `1.0` with fixed 28pt for 公文
+
+### Auto Spacing
+
+```xml
+<w:pPr>
+  <w:autoSpaceDE w:val="true"/>  <!-- auto space between CJK and Latin -->
+  <w:autoSpaceDN w:val="true"/>  <!-- auto space between CJK and numbers -->
+</w:pPr>
+```
+
+Adds ~¼ em spacing between CJK and non-CJK characters automatically. **Recommended: always enable.**
+
+---
+
+## GB/T 9704
+
+Chinese government document standard (党政机关公文格式). These are **strict requirements**, not suggestions.
+
+### Page Setup
+
+| Parameter | Value | OpenXML |
+|-----------|-------|---------|
+| Page size | A4 (210×297mm) | Width=11906, Height=16838 |
+| Top margin | 37mm | 2098 DXA |
+| Bottom margin | 35mm | 1984 DXA |
+| Left margin | 28mm | 1588 DXA |
+| Right margin | 26mm | 1474 DXA |
+| Characters/line | 28 | |
+| Lines/page | 22 | |
+| Line spacing | Fixed 28pt | `line="560"` lineRule="exact" |
+
+### Document Structure
+
+```
+┌─────────────────────────────────┐
+│     发文机关标志 (红头)           │  ← 小标宋 or 红色大字
+│     ══════════════════ (红线)    │  ← Red #FF0000, 2pt
+├─────────────────────────────────┤
+│  发文字号: X机发〔2025〕X号      │  ← 仿宋 三号, centered
+│                                 │
+│  标题 (Title)                   │  ← 小标宋 二号, centered
+│                                 │     可分多行，回行居中
+│  主送机关:                      │  ← 仿宋 三号
+│                                 │
+│  正文 (Body)...                 │  ← 仿宋_GB2312 三号
+│  一、一级标题                    │  ← 黑体 三号
+│  （一）二级标题                  │  ← 楷体 三号
+│  1. 三级标题                    │  ← 仿宋 三号 加粗
+│  (1) 四级标题                   │  ← 仿宋 三号
+│                                 │
+│  附件: 1. xxx                   │  ← 仿宋 三号
+│                                 │
+│  发文机关署名                    │  ← 仿宋 三号
+│  成文日期                       │  ← 仿宋 三号, 小写中文数字
+├─────────────────────────────────┤
+│  ══════════════════ (版记线)     │
+│  抄送: xxx                      │  ← 仿宋 四号
+│  印发机关及日期                   │  ← 仿宋 四号
+└─────────────────────────────────┘
+```
+
+### Numbering System
+
+```
+一、        ← 黑体 (SimHei), no indentation
+（一）      ← 楷体 (KaiTi), indented 2 chars
+1.          ← 仿宋加粗 (FangSong Bold), indented 2 chars
+(1)         ← 仿宋 (FangSong), indented 2 chars
+```
+
+### Colors
+
+| Element | Color | Requirement |
+|---------|-------|-------------|
+| All body text | Black #000000 | Mandatory |
+| 红头 (agency name) | Red #FF0000 | Mandatory |
+| 红线 (separator) | Red #FF0000 | Mandatory |
+| 公章 (official seal) | Red | Mandatory |
+
+### Page Numbers
+
+- Position: bottom center
+- Format: `-X-` (dash-number-dash)
+- Font: 宋体 四号 (SimSun 14pt, `sz="28"`)
+- No page number on cover page if present
+
+---
+
+## Mixed Script
+
+### Font Size Harmony
+
+CJK characters appear larger than Latin characters at the same point size. Compensation:
+
+- If body is Calibri 11pt, pair with CJK at 11pt (same size — CJK looks slightly larger but acceptable)
+- If precise visual match needed, CJK can be set 0.5–1pt smaller
+- In practice, same point size is standard — don't over-optimize
+
+### Bold and Italic
+
+- **Chinese/Japanese have no true italic.** Word synthesizes a slant which looks poor
+- Use **bold** for emphasis in CJK text
+- Use 着重号 (emphasis dots) for traditional emphasis: `<w:em w:val="dot"/>` on RunProperties
+
+---
+
+## OpenXML Quick Reference
+
+### Set EastAsia Font (C#)
+
+```csharp
+new Run(
+    new RunProperties(
+        new RunFonts { EastAsia = "SimSun", Ascii = "Calibri", HighAnsi = "Calibri" },
+        new FontSize { Val = "32" }  // 三号 = 16pt = sz 32
+    ),
+    new Text("这是正文内容")
+);
+```
+
+### Document Defaults (C#)
+
+```csharp
+new DocDefaults(new RunPropertiesDefault(new RunPropertiesBaseStyle(
+    new RunFonts {
+        Ascii = "Calibri", HighAnsi = "Calibri",
+        EastAsia = "Microsoft YaHei"
+    },
+    new Languages { Val = "en-US", EastAsia = "zh-CN" }
+)));
+```
+
+### 公文 Style Definitions (C#)
+
+```csharp
+// Title style — 小标宋 二号 centered
+new Style(
+    new StyleName { Val = "GongWen Title" },
+    new BasedOn { Val = "Normal" },
+    new StyleRunProperties(
+        new RunFonts { EastAsia = "FZXiaoBiaoSong-B05S" },
+        new FontSize { Val = "44" },  // 二号 = 22pt
+        new Bold()
+    ),
+    new StyleParagraphProperties(
+        new Justification { Val = JustificationValues.Center },
+        new SpacingBetweenLines { Line = "560", LineRule = LineSpacingRuleValues.Exact }
+    )
+) { Type = StyleValues.Paragraph, StyleId = "GongWenTitle" };
+
+// Body style — 仿宋_GB2312 三号
+new Style(
+    new StyleName { Val = "GongWen Body" },
+    new StyleRunProperties(
+        new RunFonts { EastAsia = "FangSong_GB2312", Ascii = "FangSong_GB2312" },
+        new FontSize { Val = "32" }  // 三号 = 16pt
+    ),
+    new StyleParagraphProperties(
+        new SpacingBetweenLines { Line = "560", LineRule = LineSpacingRuleValues.Exact }
+    )
+) { Type = StyleValues.Paragraph, StyleId = "GongWenBody" };
+```
+
+### Emphasis Dots (着重号)
+
+```csharp
+new RunProperties(new Emphasis { Val = EmphasisMarkValues.Dot });
+```
+
+### East Asian Text Layout
+
+```xml
+<!-- Snap to grid (align CJK chars to character grid) -->
+<w:snapToGrid w:val="true"/>
+
+<!-- Two-lines-in-one (双行合一) -->
+<w:eastAsianLayout w:id="1" w:combine="true"/>
+
+<!-- Vertical text in a cell -->
+<w:textDirection w:val="tbRl"/>
+```
diff --git a/builtin-skills/document-process/minimax-docx/references/cjk_university_template_guide.md b/builtin-skills/document-process/minimax-docx/references/cjk_university_template_guide.md
new file mode 100644
index 00000000..da4cfb01
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/cjk_university_template_guide.md
@@ -0,0 +1,184 @@
+# Chinese University Thesis Template Guide (中国高校论文模板指南)
+
+## Why This Guide Exists
+
+Chinese university thesis templates (.docx) have structural patterns that differ significantly
+from Western templates. Agents that assume Western conventions (Heading1/Heading2/Normal) will
+fail repeatedly. This guide documents the ACTUAL patterns found in Chinese templates.
+
+## Common StyleId Patterns
+
+### Pattern A: Numeric IDs (most common in Chinese Word templates)
+
+| Style Purpose | styleId | w:name | w:basedOn |
+|--------------|---------|--------|-----------|
+| Normal body | `a` | "Normal" | — |
+| Default paragraph font | `a0` | "Default Paragraph Font" | — |
+| Heading 1 (章标题) | `1` | "heading 1" | `a` |
+| Heading 2 (节标题) | `2` | "heading 2" | `a` |
+| Heading 3 (小节标题) | `3` | "heading 3" | `a` |
+| TOC 1 | `11` | "toc 1" | `a` |
+| TOC 2 | `21` | "toc 2" | `a` |
+| TOC 3 | `31` | "toc 3" | `a` |
+| Header | `a3` | "header" | `a` |
+| Footer | `a4` | "footer" | `a` |
+| Table of Contents heading | `10` | "TOC Heading" | `1` |
+
+### Pattern B: English IDs (less common, usually from international templates)
+Standard Heading1/Heading2/Heading3/Normal — these follow the Western pattern.
+
+### Pattern C: Mixed (some Chinese, some English)
+Some templates define custom styles with Chinese names:
+| Style Purpose | styleId | w:name |
+|--------------|---------|--------|
+| 论文标题 | `lunwenbiaoti` | "论文标题" |
+| 章标题 | `zhangbiaoti` | "章标题" |
+| 正文 | `zhengwen` | "正文" |
+
+### How to Identify Which Pattern
+
+```bash
+# Extract all styleIds from the template
+$CLI analyze --input template.docx --styles-only
+
+# Or manually:
+# unzip template.docx word/styles.xml
+# Search for w:styleId= in the extracted file
+```
+
+Look at the first few styleIds. If you see `1`, `2`, `3`, `a`, `a0` → Pattern A.
+If you see `Heading1`, `Normal` → Pattern B.
+
+## Standard Thesis Structure
+
+Chinese university theses follow a highly standardized structure:
+
+```
+┌─────────────────────────────────────┐
+│ 封面 (Cover Page)                    │  ← Usually 1-2 pages
+│   - 校名、校徽                       │
+│   - 论文题目 (title)                  │
+│   - 作者、导师、院系、日期             │
+├─────────────────────────────────────┤
+│ 学术诚信承诺书 / 独创性声明            │  ← 1 page
+│   (Academic Integrity Declaration)   │
+├─────────────────────────────────────┤
+│ 中文摘要 (Chinese Abstract)          │  ← 1-2 pages
+│   - "摘 要" heading                  │
+│   - Abstract body                    │
+│   - "关键词：" line                  │
+├─────────────────────────────────────┤
+│ 英文摘要 (English Abstract)          │  ← 1-2 pages
+│   - "ABSTRACT" heading              │
+│   - Abstract body                    │
+│   - "Keywords:" line                 │
+├─────────────────────────────────────┤
+│ 目录 (Table of Contents)             │  ← 1-3 pages
+│   - Often inside SDT block           │
+│   - Static example entries           │
+│   - TOC field code                   │
+├─────────────────────────────────────┤
+│ 正文 (Body)                          │  ← Main content
+│   第1章 绪论                          │
+│   1.1 研究背景                        │
+│   1.2 研究目的和意义                   │
+│   第2章 文献综述                       │
+│   ...                                │
+│   第N章 结论与展望                     │
+├─────────────────────────────────────┤
+│ 参考文献 (References)                │  ← Styled differently
+├─────────────────────────────────────┤
+│ 致谢 (Acknowledgments)              │  ← Optional
+├─────────────────────────────────────┤
+│ 附录 (Appendices)                    │  ← Optional
+└─────────────────────────────────────┘
+```
+
+## Identifying Zone Boundaries in Templates
+
+Templates contain EXAMPLE content that must be replaced. Here's how to find the zones:
+
+### Zone A (Front matter) — KEEP from template
+- Starts at: paragraph 0
+- Ends at: the paragraph BEFORE the first chapter heading
+- Contains: cover, declaration, abstracts, TOC
+- How to detect end: search for first paragraph with style `1` (or Heading1) containing "第1章" or "绪论"
+
+### Zone B (Body content) — REPLACE with user content
+- Starts at: first chapter heading ("第1章...")
+- Ends at: "参考文献" heading (inclusive) or last body paragraph before acknowledgments
+- How to detect:
+  ```python
+  for i, el in enumerate(body_elements):
+      text = get_text(el)
+      style = get_style(el)
+      if style in ('1', 'Heading1') and ('第1章' in text or '绪论' in text):
+          zone_b_start = i
+      if '参考文献' in text:
+          zone_b_end = i
+  ```
+
+### Zone C (Back matter) — KEEP from template (or remove)
+- Starts after: 参考文献
+- Contains: 致谢, 附录, final sectPr
+
+## Font Expectations in Chinese Thesis Templates
+
+| Element | Font | Size (字号) | Size (pt) | w:sz |
+|---------|------|------------|-----------|------|
+| 论文标题 | 华文中宋 or 黑体 | 二号 or 小二 | 22pt or 18pt | 44 or 36 |
+| 章标题 (H1) | 黑体 | 三号 | 16pt | 32 |
+| 节标题 (H2) | 黑体 | 四号 | 14pt | 28 |
+| 小节标题 (H3) | 黑体 | 小四 | 12pt | 24 |
+| 正文 | 宋体 | 小四 | 12pt | 24 |
+| 页眉 | 宋体 | 五号 | 10.5pt | 21 |
+| 页脚/页码 | 宋体 | 五号 | 10.5pt | 21 |
+| 表格内容 | 宋体 | 五号 | 10.5pt | 21 |
+| 参考文献条目 | 宋体 | 五号 | 10.5pt | 21 |
+
+## RunFonts for CJK Body Text
+
+```xml
+<w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman"
+          w:eastAsia="宋体" w:cs="Times New Roman"/>
+```
+
+For headings:
+```xml
+<w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman"
+          w:eastAsia="黑体" w:cs="Times New Roman"/>
+```
+
+IMPORTANT: When cleaning direct formatting, ALWAYS preserve w:eastAsia.
+Removing it causes Chinese text to fall back to the wrong font.
+
+## Common Mistakes with Chinese Templates
+
+1. **Searching for `Heading1`** — Chinese templates use `1`, not `Heading1`
+2. **Clearing all rFonts** — Must keep eastAsia font declarations
+3. **Assuming "第1章" is the first paragraph** — It's typically paragraph 100+ after cover/abstract/TOC
+4. **Ignoring SDT blocks in TOC** — The TOC is wrapped in an SDT, not just field codes
+5. **Wrong line spacing** — Chinese theses typically use fixed 20pt (line="400") or 22pt (line="440"), not the 28pt used in government documents
+6. **Missing section breaks** — Each zone (abstract, TOC, body) usually has its own sectPr for different headers/footers
+
+## Style Mapping Quick Reference
+
+When source document uses Western IDs and template uses Chinese numeric IDs:
+
+```json
+{
+  "Heading1": "1",
+  "Heading2": "2",
+  "Heading3": "3",
+  "Heading4": "3",
+  "Normal": "a",
+  "BodyText": "a",
+  "ListParagraph": "a",
+  "Caption": "a",
+  "TOC1": "11",
+  "TOC2": "21",
+  "TOC3": "31"
+}
+```
+
+When source uses Chinese numeric IDs and template uses Western IDs — reverse the mapping.
diff --git a/builtin-skills/document-process/minimax-docx/references/comments_guide.md b/builtin-skills/document-process/minimax-docx/references/comments_guide.md
new file mode 100644
index 00000000..fa124930
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/comments_guide.md
@@ -0,0 +1,191 @@
+# Comments System Guide (4-File Architecture)
+
+## Overview
+
+Word comments require coordination across **four XML files** plus references in `document.xml`, `[Content_Types].xml`, and `document.xml.rels`.
+
+---
+
+## The Four Comment Files
+
+### 1. `word/comments.xml` — Main Comment Content
+
+Contains the actual comment text:
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:comments xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+            xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+  <w:comment w:id="1" w:author="Alice" w:date="2026-03-21T09:00:00Z" w:initials="A">
+    <w:p>
+      <w:pPr><w:pStyle w:val="CommentText" /></w:pPr>
+      <w:r>
+        <w:rPr><w:rStyle w:val="CommentReference" /></w:rPr>
+        <w:annotationRef />
+      </w:r>
+      <w:r>
+        <w:t>This needs clarification.</w:t>
+      </w:r>
+    </w:p>
+  </w:comment>
+</w:comments>
+```
+
+Key attributes: `w:id` (unique integer), `w:author`, `w:date` (ISO 8601), `w:initials`.
+
+### 2. `word/commentsExtended.xml` — W15 Extensions
+
+Links comments to paragraphs and tracks resolved status:
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w15:commentsEx xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml">
+  <w15:commentEx w15:paraId="1A2B3C4D" w15:done="0" />
+</w15:commentsEx>
+```
+
+- `w15:paraId` — matches the `w14:paraId` of the comment's paragraph in `comments.xml`
+- `w15:done` — `"0"` = open, `"1"` = resolved
+
+### 3. `word/commentsIds.xml` — Persistent ID Mapping
+
+Provides durable IDs that survive copy/paste across documents:
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w16cid:commentsIds xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid">
+  <w16cid:commentId w16cid:paraId="1A2B3C4D" w16cid:durableId="12345678" />
+</w16cid:commentsIds>
+```
+
+- `w16cid:paraId` — same as `w15:paraId`
+- `w16cid:durableId` — globally unique identifier (8-digit hex)
+
+### 4. `word/commentsExtensible.xml` — W16 Extensions
+
+Modern comment extensions (used in newer Word versions):
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w16cex:commentsExtensible xmlns:w16cex="http://schemas.microsoft.com/office/word/2018/wordml/cex">
+  <w16cex:commentExtensible w16cex:durableId="12345678" w16cex:dateUtc="2026-03-21T09:00:00Z" />
+</w16cex:commentsExtensible>
+```
+
+---
+
+## Document.xml References
+
+Comments are anchored in document content using three elements:
+
+```xml
+<w:p>
+  <w:commentRangeStart w:id="1" />
+  <w:r><w:t>This text has a comment.</w:t></w:r>
+  <w:commentRangeEnd w:id="1" />
+  <w:r>
+    <w:rPr><w:rStyle w:val="CommentReference" /></w:rPr>
+    <w:commentReference w:id="1" />
+  </w:r>
+</w:p>
+```
+
+- `w:commentRangeStart` — marks where the commented text begins
+- `w:commentRangeEnd` — marks where the commented text ends
+- `w:commentReference` — the visible comment marker (superscript number), placed in a run after the range end
+
+The `w:id` on all three must match the `w:id` in `comments.xml`.
+
+---
+
+## Content Types Registration
+
+Add to `[Content_Types].xml`:
+
+```xml
+<Override PartName="/word/comments.xml"
+          ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml" />
+<Override PartName="/word/commentsExtended.xml"
+          ContentType="application/vnd.ms-word.commentsExtended+xml" />
+<Override PartName="/word/commentsIds.xml"
+          ContentType="application/vnd.ms-word.commentsIds+xml" />
+<Override PartName="/word/commentsExtensible.xml"
+          ContentType="application/vnd.ms-word.commentsExtensible+xml" />
+```
+
+---
+
+## Relationship Registration
+
+Add to `word/_rels/document.xml.rels`:
+
+```xml
+<Relationship Id="rId20" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments"
+              Target="comments.xml" />
+<Relationship Id="rId21" Type="http://schemas.microsoft.com/office/2011/relationships/commentsExtended"
+              Target="commentsExtended.xml" />
+<Relationship Id="rId22" Type="http://schemas.microsoft.com/office/2016/09/relationships/commentsIds"
+              Target="commentsIds.xml" />
+<Relationship Id="rId23" Type="http://schemas.microsoft.com/office/2018/08/relationships/commentsExtensible"
+              Target="commentsExtensible.xml" />
+```
+
+---
+
+## Step-by-Step: Adding a New Comment
+
+1. **Choose a unique comment ID** (scan existing `w:id` values, use max + 1)
+2. **Generate a paraId** (8-character hex, e.g., `"1A2B3C4D"`) and durableId (8-digit hex)
+3. **Add to `comments.xml`**: Create `w:comment` element with content
+4. **Add to `commentsExtended.xml`**: Create `w15:commentEx` with `paraId`, `done="0"`
+5. **Add to `commentsIds.xml`**: Create `w16cid:commentId` with `paraId` and `durableId`
+6. **Add to `commentsExtensible.xml`**: Create `w16cex:commentExtensible` with `durableId` and `dateUtc`
+7. **Add to `document.xml`**: Insert `w:commentRangeStart`, `w:commentRangeEnd`, and `w:commentReference` around target text
+8. **Verify `[Content_Types].xml`** and `document.xml.rels` have entries for all 4 files
+
+---
+
+## Step-by-Step: Adding a Reply
+
+Replies are comments whose paragraph's `w14:paraId` links to a parent comment:
+
+1. Create a new `w:comment` in `comments.xml` with a new `w:id`
+2. In `commentsExtended.xml`, add `w15:commentEx` with:
+   - `w15:paraId` = new paragraph ID
+   - `w15:paraIdParent` = the `paraId` of the comment being replied to
+   - `w15:done="0"`
+3. Add entries in `commentsIds.xml` and `commentsExtensible.xml`
+4. In `document.xml`, the reply does NOT need its own range markers — it shares the parent's range
+
+```xml
+<!-- In commentsExtended.xml -->
+<w15:commentEx w15:paraId="5E6F7A8B" w15:paraIdParent="1A2B3C4D" w15:done="0" />
+```
+
+---
+
+## Step-by-Step: Resolving a Comment
+
+Set `w15:done="1"` on the comment's `w15:commentEx` entry:
+
+```xml
+<!-- Before -->
+<w15:commentEx w15:paraId="1A2B3C4D" w15:done="0" />
+
+<!-- After -->
+<w15:commentEx w15:paraId="1A2B3C4D" w15:done="1" />
+```
+
+This marks the comment (and all its replies) as resolved. The comment remains visible but appears grayed out in Word.
+
+---
+
+## Minimum Viable Comment
+
+At minimum, a working comment requires:
+1. `comments.xml` with the `w:comment` element
+2. `document.xml` with range markers and reference
+3. Relationship in `document.xml.rels`
+4. Content type in `[Content_Types].xml`
+
+The extended files (`commentsExtended`, `commentsIds`, `commentsExtensible`) are optional but recommended for full compatibility with modern Word.
diff --git a/builtin-skills/document-process/minimax-docx/references/design_good_bad_examples.md b/builtin-skills/document-process/minimax-docx/references/design_good_bad_examples.md
new file mode 100644
index 00000000..82b7c507
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/design_good_bad_examples.md
@@ -0,0 +1,829 @@
+# GOOD vs BAD Document Design — Concrete OpenXML Examples
+
+A side-by-side reference showing common design mistakes and their fixes, with exact OpenXML parameter values. Use this to develop an intuitive sense of what makes a document look professional versus amateur.
+
+Format: Each comparison shows the **BAD** version first (the mistake), then the **GOOD** version (the fix), with OpenXML markup and a short explanation.
+
+---
+
+## 1. Font Size Disasters
+
+### 1a. No Hierarchy — Everything the Same Size
+
+**BAD: Body=12pt, H1=12pt bold**
+```
+┌──────────────────────────────────┐
+│ INTRODUCTION                     │  ← 12pt bold... same visual weight
+│ This is the body text of the     │  ← 12pt regular
+│ report. It discusses findings    │
+│ from the quarterly review.       │
+│ METHODOLOGY                      │  ← Where does the section start?
+│ We collected data from three     │
+│ sources across the enterprise.   │
+└──────────────────────────────────┘
+```
+```xml
+<!-- H1: bold but same size as body — no visual separation -->
+<w:rPr><w:b/><w:sz w:val="24"/></w:rPr>
+<!-- Body -->
+<w:rPr><w:sz w:val="24"/></w:rPr>
+```
+
+**GOOD: Modular scale — body=11pt, H3=13pt, H2=16pt, H1=20pt**
+```
+┌──────────────────────────────────┐
+│                                  │
+│ Introduction                     │  ← 20pt, clearly a title
+│                                  │
+│ This is the body text of the     │  ← 11pt, comfortable reading size
+│ report. It discusses findings    │
+│ from the quarterly review.       │
+│                                  │
+│ Methodology                      │  ← 20pt, section break is obvious
+│                                  │
+│ We collected data from three     │
+│ sources across the enterprise.   │
+└──────────────────────────────────┘
+```
+```xml
+<!-- H1: 20pt = w:sz 40 -->
+<w:rPr><w:rFonts w:ascii="Calibri Light"/><w:sz w:val="40"/></w:rPr>
+<!-- H2: 16pt = w:sz 32 -->
+<w:rPr><w:rFonts w:ascii="Calibri Light"/><w:sz w:val="32"/></w:rPr>
+<!-- H3: 13pt = w:sz 26, bold -->
+<w:rPr><w:rFonts w:ascii="Calibri"/><w:b/><w:sz w:val="26"/></w:rPr>
+<!-- Body: 11pt = w:sz 22 -->
+<w:rPr><w:rFonts w:ascii="Calibri"/><w:sz w:val="22"/></w:rPr>
+```
+**Why better:** A clear size progression (ratio ~1.25x per step) lets readers instantly identify structure without reading a word.
+
+---
+
+### 1b. Too Much Contrast — Children's Book Look
+
+**BAD: H1=28pt with body=10pt (ratio 2.8x)**
+```
+┌──────────────────────────────────┐
+│                                  │
+│ QUARTERLY REPORT                 │  ← 28pt, dominates the page
+│                                  │
+│ This is body text set very small │  ← 10pt, straining to read
+│ and the contrast with the title  │
+│ makes it feel like a poster.     │
+└──────────────────────────────────┘
+```
+```xml
+<w:rPr><w:b/><w:sz w:val="56"/></w:rPr>  <!-- 28pt heading -->
+<w:rPr><w:sz w:val="20"/></w:rPr>         <!-- 10pt body -->
+```
+
+**GOOD: H1=20pt with body=11pt (ratio ~1.8x)**
+```xml
+<w:rPr><w:sz w:val="40"/></w:rPr>  <!-- 20pt heading -->
+<w:rPr><w:sz w:val="22"/></w:rPr>  <!-- 11pt body -->
+```
+**Why better:** A heading-to-body ratio between 1.5x and 2.0x reads as "structured" rather than "shouting."
+
+---
+
+## 2. Spacing Crimes
+
+### 2a. Wall of Text — No Paragraph or Line Spacing
+
+**BAD: Single line spacing, 0pt between paragraphs**
+```
+┌──────────────────────────────────┐
+│The findings indicate a strong    │
+│correlation between training hours│
+│and performance metrics.          │
+│Further analysis revealed that    │  ← No gap — where does the new
+│departments with higher budgets   │     paragraph start?
+│achieved better outcomes in all   │
+│measured categories.              │
+└──────────────────────────────────┘
+```
+```xml
+<w:pPr>
+  <w:spacing w:line="240" w:lineRule="auto"/>  <!-- 1.0 spacing (240/240) -->
+  <w:spacing w:after="0"/>                     <!-- no paragraph gap -->
+</w:pPr>
+```
+
+**GOOD: 1.15x line spacing, 8pt after each paragraph**
+```
+┌──────────────────────────────────┐
+│The findings indicate a strong    │
+│correlation between training      │  ← Slightly more air between lines
+│hours and performance metrics.    │
+│                                  │  ← 8pt gap signals new paragraph
+│Further analysis revealed that    │
+│departments with higher budgets   │
+│achieved better outcomes in all   │
+│measured categories.              │
+└──────────────────────────────────┘
+```
+```xml
+<w:pPr>
+  <w:spacing w:line="276" w:lineRule="auto"/>  <!-- 1.15x (276/240) -->
+  <w:spacing w:after="160"/>                   <!-- 8pt = 160 twips -->
+</w:pPr>
+```
+**Why better:** Line spacing gives each line room to breathe; paragraph spacing separates ideas without wasting a full blank line.
+
+---
+
+### 2b. Floating Headings — Same Space Above and Below
+
+**BAD: 12pt before and 12pt after heading**
+```
+┌──────────────────────────────────┐
+│ ...end of previous section.      │
+│                                  │  ← 12pt gap
+│ Section Two                      │  ← Heading floats in the middle
+│                                  │  ← 12pt gap
+│ Start of section two content.    │
+└──────────────────────────────────┘
+```
+```xml
+<w:pPr>
+  <w:spacing w:before="240" w:after="240"/>  <!-- 12pt both sides -->
+</w:pPr>
+```
+
+**GOOD: 24pt before, 8pt after heading**
+```
+┌──────────────────────────────────┐
+│ ...end of previous section.      │
+│                                  │
+│                                  │  ← 24pt gap — clear section break
+│ Section Two                      │  ← Heading is close to its content
+│                                  │  ← 8pt gap
+│ Start of section two content.    │
+└──────────────────────────────────┘
+```
+```xml
+<w:pPr>
+  <w:spacing w:before="480" w:after="160"/>  <!-- 24pt before, 8pt after -->
+</w:pPr>
+```
+**Why better:** Proximity principle: a heading belongs to the text that follows it, so more space above and less space below anchors it to its content.
+
+---
+
+### 2c. Wasteful Gaps — Huge Spacing Everywhere
+
+**BAD: 24pt after every paragraph, including body text**
+```
+┌──────────────────────────────────┐
+│ First paragraph of text here.    │
+│                                  │
+│                                  │  ← 24pt gap after every paragraph
+│                                  │
+│ Second paragraph of text here.   │
+│                                  │
+│                                  │
+│                                  │
+│ Third paragraph.                 │  ← Document looks mostly white space
+└──────────────────────────────────┘
+```
+```xml
+<w:spacing w:after="480"/>  <!-- 24pt = 480 twips after every paragraph -->
+```
+
+**GOOD: Proportional spacing — body=8pt, H2=6pt after, H1=10pt after**
+```xml
+<!-- Body paragraph -->
+<w:spacing w:after="160"/>   <!-- 8pt after body -->
+<!-- H1 -->
+<w:spacing w:before="480" w:after="200"/>  <!-- 24pt before, 10pt after -->
+<!-- H2 -->
+<w:spacing w:before="320" w:after="120"/>  <!-- 16pt before, 6pt after -->
+```
+**Why better:** Spacing should vary by element role, creating a visual rhythm rather than uniform gaps.
+
+---
+
+## 3. Margin Mistakes
+
+### 3a. Cramped Margins — Text Running to the Edge
+
+**BAD: 0.5in margins all around**
+```
+┌────────────────────────────────────────────────┐
+│Text starts almost at the paper edge and runs   │
+│all the way across making extremely long lines  │
+│that are hard to track from end back to start.  │
+│The eye loses its place on every line return.   │
+└────────────────────────────────────────────────┘
+```
+```xml
+<w:pgMar w:top="720" w:right="720" w:bottom="720" w:left="720"/>
+<!-- 720 twips = 0.5in — line length ~7.5in on letter paper -->
+```
+
+**GOOD: 1in margins (standard)**
+```xml
+<w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"/>
+<!-- 1440 twips = 1.0in — line length ~6.5in, ideal for 11pt body -->
+```
+**Why better:** Optimal line length is 60-75 characters. At 11pt Calibri, 6.5in width achieves roughly 70 characters per line.
+
+---
+
+### 3b. Over-Padded Margins — Looks Like the Content is Hiding
+
+**BAD: 2in margins on a short document**
+```xml
+<w:pgMar w:top="2880" w:right="2880" w:bottom="2880" w:left="2880"/>
+<!-- 2880 twips = 2.0in — only 4.5in of text width, looks padded -->
+```
+
+**GOOD: 1in standard, or 1.25in for formal documents**
+```xml
+<!-- Standard -->
+<w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"/>
+<!-- Formal / bound documents with gutter -->
+<w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1800" w:gutter="0"/>
+<!-- 1800 twips = 1.25in left for binding margin -->
+```
+**Why better:** Margins should frame the content, not overwhelm it. 1-1.25in works for virtually all business and academic documents.
+
+---
+
+## 4. Table Ugliness
+
+### 4a. Prison Grid — Full Borders on Every Cell
+
+**BAD: Every cell with 1pt borders on all four sides**
+```
+┌───────┬───────┬───────┬───────┐
+│ Name  │ Dept  │ Score │ Grade │
+├───────┼───────┼───────┼───────┤
+│ Alice │ Eng   │ 92    │ A     │
+├───────┼───────┼───────┼───────┤
+│ Bob   │ Sales │ 85    │ B     │
+├───────┼───────┼───────┼───────┤
+│ Carol │ Eng   │ 78    │ C+    │
+└───────┴───────┴───────┴───────┘
+```
+```xml
+<w:tcBorders>
+  <w:top w:val="single" w:sz="4" w:color="000000"/>
+  <w:left w:val="single" w:sz="4" w:color="000000"/>
+  <w:bottom w:val="single" w:sz="4" w:color="000000"/>
+  <w:right w:val="single" w:sz="4" w:color="000000"/>
+</w:tcBorders>
+```
+
+**GOOD: Three-line table (三线表) — top thick, header-bottom medium, table-bottom thick**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ← 1.5pt top border
+  Name    Dept    Score   Grade
+──────────────────────────────────  ← 0.75pt header separator
+  Alice   Eng     92      A
+  Bob     Sales   85      B
+  Carol   Eng     78      C+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ← 1.5pt bottom border
+```
+```xml
+<!-- Top border of header row cells -->
+<w:top w:val="single" w:sz="12" w:color="000000"/>    <!-- 1.5pt -->
+<w:left w:val="nil"/><w:right w:val="nil"/>
+<w:bottom w:val="single" w:sz="6" w:color="000000"/>  <!-- 0.75pt -->
+
+<!-- Data row cells: no left/right/top borders -->
+<w:top w:val="nil"/><w:left w:val="nil"/><w:right w:val="nil"/>
+<w:bottom w:val="nil"/>
+
+<!-- Last row bottom border -->
+<w:bottom w:val="single" w:sz="12" w:color="000000"/> <!-- 1.5pt -->
+```
+**Why better:** Removing inner borders lets the eye scan data freely. Three lines provide structure without visual clutter.
+
+---
+
+### 4b. Text Touching Borders — No Cell Padding
+
+**BAD: Zero cell margins**
+```
+┌──────────┬──────────┐
+│Name      │Department│  ← Text cramped against borders
+├──────────┼──────────┤
+│Alice     │Engineering│
+└──────────┴──────────┘
+```
+```xml
+<w:tcMar>
+  <w:top w:w="0" w:type="dxa"/>
+  <w:start w:w="0" w:type="dxa"/>
+  <w:bottom w:w="0" w:type="dxa"/>
+  <w:end w:w="0" w:type="dxa"/>
+</w:tcMar>
+```
+
+**GOOD: 0.08in vertical, 0.12in horizontal padding**
+```xml
+<w:tcMar>
+  <w:top w:w="115" w:type="dxa"/>      <!-- ~0.08in = 115 twips -->
+  <w:start w:w="173" w:type="dxa"/>    <!-- ~0.12in = 173 twips -->
+  <w:bottom w:w="115" w:type="dxa"/>
+  <w:end w:w="173" w:type="dxa"/>
+</w:tcMar>
+```
+**Why better:** Padding gives text breathing room inside cells, making every value easier to read.
+
+---
+
+### 4c. Invisible Headers — Header Row Same Style as Data
+
+**BAD: Header row indistinguishable from data**
+```xml
+<!-- Header cell run properties — identical to data -->
+<w:rPr><w:sz w:val="22"/></w:rPr>
+```
+
+**GOOD: Bold header text, subtle background fill, bottom border**
+```xml
+<!-- Header cell run properties -->
+<w:rPr><w:b/><w:sz w:val="22"/><w:color w:val="333333"/></w:rPr>
+
+<!-- Header cell shading -->
+<w:tcPr>
+  <w:shd w:val="clear" w:color="auto" w:fill="F2F2F2"/>  <!-- light gray bg -->
+  <w:tcBorders>
+    <w:bottom w:val="single" w:sz="8" w:color="666666"/>  <!-- 1pt separator -->
+  </w:tcBorders>
+</w:tcPr>
+
+<!-- Mark row as header (repeats on page break) -->
+<w:trPr><w:tblHeader/></w:trPr>
+```
+**Why better:** Distinct header styling lets readers instantly locate column meanings, especially in long tables that span pages. The `w:tblHeader` element ensures the header row repeats on every page.
+
+---
+
+## 5. Font Pairing Failures
+
+### 5a. Visual Chaos — Too Many Fonts
+
+**BAD: 4+ fonts in one document**
+```xml
+<!-- H1 in Impact -->
+<w:rPr><w:rFonts w:ascii="Impact"/><w:sz w:val="40"/></w:rPr>
+<!-- H2 in Georgia -->
+<w:rPr><w:rFonts w:ascii="Georgia"/><w:sz w:val="32"/></w:rPr>
+<!-- Body in Verdana -->
+<w:rPr><w:rFonts w:ascii="Verdana"/><w:sz w:val="22"/></w:rPr>
+<!-- Captions in Courier New -->
+<w:rPr><w:rFonts w:ascii="Courier New"/><w:sz w:val="18"/></w:rPr>
+```
+
+**GOOD: One font family with weight variation, or two complementary families**
+```xml
+<!-- H1: Calibri Light (thin weight of Calibri family) -->
+<w:rPr><w:rFonts w:ascii="Calibri Light"/><w:sz w:val="40"/></w:rPr>
+<!-- H2: Calibri Light -->
+<w:rPr><w:rFonts w:ascii="Calibri Light"/><w:sz w:val="32"/></w:rPr>
+<!-- Body: Calibri (regular weight) -->
+<w:rPr><w:rFonts w:ascii="Calibri"/><w:sz w:val="22"/></w:rPr>
+<!-- Captions: Calibri -->
+<w:rPr><w:rFonts w:ascii="Calibri"/><w:sz w:val="18"/></w:rPr>
+```
+**Why better:** Limiting to one or two font families creates visual coherence. Vary by size and weight, not by font.
+
+---
+
+### 5b. Mismatched Personality — Comic Sans Meets Times New Roman
+
+**BAD:**
+```xml
+<w:rPr><w:rFonts w:ascii="Comic Sans MS"/><w:sz w:val="36"/></w:rPr>  <!-- heading -->
+<w:rPr><w:rFonts w:ascii="Times New Roman"/><w:sz w:val="24"/></w:rPr> <!-- body -->
+```
+
+**GOOD: Fonts with compatible character**
+```xml
+<w:rPr><w:rFonts w:ascii="Calibri Light"/><w:sz w:val="36"/></w:rPr>   <!-- heading -->
+<w:rPr><w:rFonts w:ascii="Calibri"/><w:sz w:val="22"/></w:rPr>          <!-- body -->
+```
+**Why better:** Paired fonts should share a similar level of formality and geometric character. Comic Sans is playful/informal; Times New Roman is formal/traditional. They clash.
+
+---
+
+### 5c. Everything Bold — Nothing Stands Out
+
+**BAD: Bold on body, headings, captions, everything**
+```xml
+<w:rPr><w:b/><w:sz w:val="40"/></w:rPr>  <!-- heading: bold -->
+<w:rPr><w:b/><w:sz w:val="22"/></w:rPr>  <!-- body: also bold -->
+<w:rPr><w:b/><w:sz w:val="18"/></w:rPr>  <!-- caption: still bold -->
+```
+
+**GOOD: Bold reserved for headings and key terms only**
+```xml
+<w:rPr><w:b/><w:sz w:val="40"/></w:rPr>   <!-- H1: bold -->
+<w:rPr><w:sz w:val="32"/></w:rPr>          <!-- H2: size alone is enough -->
+<w:rPr><w:sz w:val="22"/></w:rPr>          <!-- body: regular weight -->
+<w:rPr><w:b/><w:sz w:val="22"/></w:rPr>    <!-- key term inline: bold -->
+<w:rPr><w:sz w:val="18"/></w:rPr>          <!-- caption: regular, small -->
+```
+**Why better:** When everything is emphasized, nothing is emphasized. Bold should be a signal, not a default.
+
+---
+
+## 6. Color Abuse
+
+### 6a. Rainbow Headings
+
+**BAD: Each heading level a different bright color**
+```xml
+<w:rPr><w:color w:val="FF0000"/><w:sz w:val="40"/></w:rPr>  <!-- H1: red -->
+<w:rPr><w:color w:val="00AA00"/><w:sz w:val="32"/></w:rPr>  <!-- H2: green -->
+<w:rPr><w:color w:val="0000FF"/><w:sz w:val="26"/></w:rPr>  <!-- H3: blue -->
+```
+
+**GOOD: Single accent color for headings, black or dark gray for body**
+```xml
+<!-- All headings use the same muted accent -->
+<w:rPr><w:color w:val="1F4E79"/><w:sz w:val="40"/></w:rPr>  <!-- H1: dark blue -->
+<w:rPr><w:color w:val="1F4E79"/><w:sz w:val="32"/></w:rPr>  <!-- H2: same blue -->
+<w:rPr><w:color w:val="1F4E79"/><w:sz w:val="26"/></w:rPr>  <!-- H3: same blue -->
+<!-- Body in near-black -->
+<w:rPr><w:color w:val="333333"/><w:sz w:val="22"/></w:rPr>
+```
+**Why better:** A single accent color establishes brand consistency. Multiple bright colors compete for attention and look unprofessional.
+
+---
+
+### 6b. Low Contrast — Light Gray on White
+
+**BAD: #CCCCCC text on white background**
+```xml
+<w:rPr><w:color w:val="CCCCCC"/></w:rPr>
+<!-- Contrast ratio: ~1.6:1 — fails WCAG AA (minimum 4.5:1) -->
+```
+
+**GOOD: #333333 text on white**
+```xml
+<w:rPr><w:color w:val="333333"/></w:rPr>
+<!-- Contrast ratio: ~12:1 — passes WCAG AAA -->
+```
+**Why better:** Sufficient contrast is not just an accessibility requirement; it makes text physically easier to read for everyone, especially in printed documents.
+
+---
+
+### 6c. Bright Body Text
+
+**BAD: Body text in a saturated color**
+```xml
+<w:rPr><w:color w:val="0066FF"/><w:sz w:val="22"/></w:rPr>  <!-- blue body text -->
+```
+
+**GOOD: Color reserved for headings and inline accents only**
+```xml
+<!-- Body: neutral dark -->
+<w:rPr><w:color w:val="333333"/><w:sz w:val="22"/></w:rPr>
+<!-- Hyperlink: color is functional here -->
+<w:rPr><w:color w:val="0563C1"/><w:u w:val="single"/></w:rPr>
+```
+**Why better:** Colored body text causes eye fatigue over long reading. Reserve color for elements that need to attract attention (headings, links, warnings).
+
+---
+
+## 7. List Formatting Issues
+
+### 7a. Bullet at the Margin — No Indent
+
+**BAD: List items start at the left margin**
+```
+┌──────────────────────────────────┐
+│Here is a paragraph of text.     │
+│• First item                      │  ← Bullet at margin, no indent
+│• Second item                     │
+│• Third item                      │
+│Next paragraph continues here.    │
+└──────────────────────────────────┘
+```
+```xml
+<w:pPr>
+  <w:ind w:left="0" w:hanging="0"/>
+</w:pPr>
+```
+
+**GOOD: 0.25in left indent with hanging indent for the bullet**
+```
+┌──────────────────────────────────┐
+│Here is a paragraph of text.     │
+│   • First item                   │  ← Indented, clearly a list
+│   • Second item                  │
+│   • Third item                   │
+│Next paragraph continues here.    │
+└──────────────────────────────────┘
+```
+```xml
+<w:pPr>
+  <w:ind w:left="360" w:hanging="360"/>  <!-- 0.25in = 360 twips -->
+  <w:numPr>
+    <w:ilvl w:val="0"/>
+    <w:numId w:val="1"/>
+  </w:numPr>
+</w:pPr>
+```
+For nested lists, increment by 360 twips per level:
+```xml
+<!-- Level 1 -->
+<w:ind w:left="720" w:hanging="360"/>   <!-- 0.5in left -->
+<!-- Level 2 -->
+<w:ind w:left="1080" w:hanging="360"/>  <!-- 0.75in left -->
+```
+**Why better:** Indentation visually separates lists from body text and makes nesting levels clear.
+
+---
+
+### 7b. List Items with Full Paragraph Spacing
+
+**BAD: List items have the same 8-10pt spacing as body paragraphs**
+```
+┌──────────────────────────────────┐
+│   • First item                   │
+│                                  │  ← 10pt gap — looks like separate
+│   • Second item                  │     paragraphs, not a list
+│                                  │
+│   • Third item                   │
+└──────────────────────────────────┘
+```
+```xml
+<w:spacing w:after="200"/>  <!-- 10pt after each list item -->
+```
+
+**GOOD: Tight spacing between list items (2-4pt)**
+```
+┌──────────────────────────────────┐
+│   • First item                   │
+│   • Second item                  │  ← 2pt gap — cohesive list
+│   • Third item                   │
+└──────────────────────────────────┘
+```
+```xml
+<w:spacing w:after="40" w:line="276" w:lineRule="auto"/>  <!-- 2pt after -->
+<!-- Or 4pt: -->
+<w:spacing w:after="80"/>
+```
+**Why better:** Tight spacing groups list items as a single unit, matching how readers expect a list to behave.
+
+---
+
+## 8. Header/Footer Problems
+
+### 8a. Header Text Too Large — Competes with Body
+
+**BAD: Header in 12pt, same as body**
+```
+┌──────────────────────────────────┐
+│ Quarterly Report - Q3 2025       │  ← 12pt header, same as body
+│──────────────────────────────────│
+│ Introduction                     │
+│ This is the body text...         │  ← 12pt body — header distracts
+└──────────────────────────────────┘
+```
+```xml
+<!-- Header paragraph -->
+<w:rPr><w:sz w:val="24"/></w:rPr>  <!-- 12pt, same as body -->
+```
+
+**GOOD: Header in 9pt, gray color, subtle**
+```
+┌──────────────────────────────────┐
+│ Quarterly Report - Q3 2025       │  ← 9pt, gray — present but quiet
+│──────────────────────────────────│
+│ Introduction                     │
+│ This is the body text...         │  ← Body stands out as primary
+└──────────────────────────────────┘
+```
+```xml
+<!-- Header paragraph -->
+<w:rPr>
+  <w:sz w:val="18"/>                <!-- 9pt -->
+  <w:color w:val="808080"/>         <!-- medium gray -->
+</w:rPr>
+<w:pPr>
+  <w:pBdr>
+    <w:bottom w:val="single" w:sz="4" w:color="D9D9D9"/>  <!-- subtle separator -->
+  </w:pBdr>
+</w:pPr>
+```
+**Why better:** Headers are reference information, not primary content. They should be legible but visually subordinate.
+
+---
+
+### 8b. No Page Numbers on a Long Document
+
+**BAD: 20-page document with no page numbers**
+```xml
+<!-- Footer section: empty or missing -->
+```
+
+**GOOD: Page numbers in footer, right-aligned or centered**
+```xml
+<!-- Footer paragraph with page number field -->
+<w:p>
+  <w:pPr>
+    <w:jc w:val="center"/>
+    <w:rPr><w:sz w:val="18"/><w:color w:val="808080"/></w:rPr>
+  </w:pPr>
+  <w:r>
+    <w:rPr><w:sz w:val="18"/><w:color w:val="808080"/></w:rPr>
+    <w:fldChar w:fldCharType="begin"/>
+  </w:r>
+  <w:r>
+    <w:instrText> PAGE </w:instrText>
+  </w:r>
+  <w:r>
+    <w:fldChar w:fldCharType="separate"/>
+  </w:r>
+  <w:r>
+    <w:t>1</w:t>
+  </w:r>
+  <w:r>
+    <w:fldChar w:fldCharType="end"/>
+  </w:r>
+</w:p>
+```
+**Why better:** Page numbers are essential for navigation in any document over ~3 pages. Readers need to reference specific pages, and printed documents need an ordering mechanism.
+
+---
+
+## 9. CJK-Specific Mistakes
+
+### 9a. Using Italic for Chinese Emphasis
+
+**BAD: Italic applied to Chinese text**
+```xml
+<w:rPr>
+  <w:i/>
+  <w:rFonts w:eastAsia="SimSun"/>
+  <w:sz w:val="24"/>
+</w:rPr>
+```
+CJK glyphs have no true italic form. The renderer applies a synthetic slant that looks broken and ugly — characters appear to lean awkwardly.
+
+**GOOD: Use bold or emphasis dots (着重号) for Chinese emphasis**
+```xml
+<!-- Option A: Bold emphasis -->
+<w:rPr>
+  <w:b/>
+  <w:rFonts w:eastAsia="SimHei"/>  <!-- Switch to bold-capable font -->
+  <w:sz w:val="24"/>
+</w:rPr>
+
+<!-- Option B: Emphasis marks (dots under characters) -->
+<w:rPr>
+  <w:em w:val="dot"/>
+  <w:rFonts w:eastAsia="SimSun"/>
+  <w:sz w:val="24"/>
+</w:rPr>
+```
+**Why better:** Chinese typography has its own emphasis traditions. Bold and emphasis dots are native CJK conventions; italic is a Latin-script concept that does not translate.
+
+---
+
+### 9b. Latin Font for Chinese Characters
+
+**BAD: Only ASCII font set, no EastAsia font specified**
+```xml
+<w:rPr>
+  <w:rFonts w:ascii="Arial"/>  <!-- No eastAsia attribute -->
+  <w:sz w:val="24"/>
+</w:rPr>
+<!-- Word falls back to a random font. Chinese characters may render
+     with wrong metrics, inconsistent stroke widths, or missing glyphs. -->
+```
+
+**GOOD: Explicit EastAsia font alongside ASCII font**
+```xml
+<w:rPr>
+  <w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:eastAsia="Microsoft YaHei"/>
+  <w:sz w:val="22"/>
+</w:rPr>
+```
+For formal/academic Chinese documents:
+```xml
+<w:rPr>
+  <w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman"
+            w:eastAsia="SimSun"/>
+  <w:sz w:val="24"/>  <!-- 小四 12pt -->
+</w:rPr>
+```
+**Why better:** Setting `w:eastAsia` ensures Chinese characters render in a font designed for CJK glyphs, with correct stroke widths, spacing, and metrics.
+
+---
+
+### 9c. English Line Spacing for Dense CJK Text
+
+**BAD: 1.15x line spacing for Chinese body text**
+```xml
+<w:spacing w:line="276" w:lineRule="auto"/>  <!-- 1.15x — too tight for CJK -->
+```
+CJK characters are taller and denser than Latin letters. At 1.15x, lines of Chinese text feel cramped and hard to read.
+
+**GOOD: 1.5x line spacing or fixed 28pt for CJK body at 12pt (小四)**
+```xml
+<!-- Option A: 1.5x proportional -->
+<w:spacing w:line="360" w:lineRule="auto"/>  <!-- 360/240 = 1.5x -->
+
+<!-- Option B: Fixed 28pt (standard for 小四/12pt CJK body) -->
+<w:spacing w:line="560" w:lineRule="exact"/>  <!-- 28pt = 560 twips -->
+```
+For 公文 (government documents) at 三号/16pt body:
+```xml
+<w:spacing w:line="580" w:lineRule="exact"/>  <!-- 29pt fixed line spacing -->
+```
+**Why better:** CJK characters occupy a full em square with no ascenders/descenders providing natural gaps. Extra line spacing compensates, improving readability of dense text blocks.
+
+---
+
+## 10. Overall Document Feel
+
+### Student Homework vs Professional Document
+
+**BAD: "Student homework" — every setting is Word's default, no intentional choices**
+```xml
+<!-- Default everything: Calibri 11pt, no heading styles, 1.08 spacing -->
+<w:rPr><w:rFonts w:ascii="Calibri"/><w:sz w:val="22"/></w:rPr>
+<w:pPr><w:spacing w:after="160" w:line="259" w:lineRule="auto"/></w:pPr>
+<!-- Headings: just bold body text, no style applied -->
+<w:rPr><w:b/><w:sz w:val="22"/></w:rPr>
+<!-- No section breaks, no headers/footers, no page numbers -->
+<!-- Tables with default full grid borders -->
+<!-- No intentional color or spacing variations -->
+```
+
+**GOOD: Intentional design at every level**
+```xml
+<!-- Theme fonts defined -->
+<w:rFonts w:asciiTheme="minorHAnsi" w:hAnsiTheme="minorHAnsi"/>
+
+<!-- H1: Calibri Light 20pt, dark blue, generous spacing -->
+<w:pPr>
+  <w:pStyle w:val="Heading1"/>
+  <w:spacing w:before="480" w:after="200"/>
+</w:pPr>
+<w:rPr>
+  <w:rFonts w:ascii="Calibri Light"/>
+  <w:color w:val="1F4E79"/>
+  <w:sz w:val="40"/>
+</w:rPr>
+
+<!-- H2: Calibri Light 16pt, same blue -->
+<w:pPr>
+  <w:pStyle w:val="Heading2"/>
+  <w:spacing w:before="320" w:after="120"/>
+</w:pPr>
+<w:rPr>
+  <w:rFonts w:ascii="Calibri Light"/>
+  <w:color w:val="1F4E79"/>
+  <w:sz w:val="32"/>
+</w:rPr>
+
+<!-- Body: Calibri 11pt, dark gray, 1.15 spacing, 8pt after -->
+<w:pPr>
+  <w:spacing w:after="160" w:line="276" w:lineRule="auto"/>
+</w:pPr>
+<w:rPr>
+  <w:rFonts w:ascii="Calibri"/>
+  <w:color w:val="333333"/>
+  <w:sz w:val="22"/>
+</w:rPr>
+
+<!-- Tables: three-line style, padded cells, repeated headers -->
+<!-- Headers/footers: 9pt gray with page numbers -->
+<!-- Margins: 1in all around -->
+<w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"/>
+```
+**Why better:** Professional documents result from deliberate, consistent choices across all design dimensions. Each element reinforces the same visual language. The reader may not consciously notice good typography, but they feel the difference in credibility and readability.
+
+---
+
+## Quick Reference: Safe Defaults
+
+A cheat sheet of values that produce a professional result for most Western business documents:
+
+| Element | Value | OpenXML |
+|---------|-------|---------|
+| Body font | Calibri 11pt | `w:sz="22"` |
+| H1 | Calibri Light 20pt | `w:sz="40"` |
+| H2 | Calibri Light 16pt | `w:sz="32"` |
+| H3 | Calibri 13pt bold | `w:sz="26"`, `w:b` |
+| Body color | #333333 | `w:color="333333"` |
+| Heading color | #1F4E79 | `w:color="1F4E79"` |
+| Line spacing | 1.15x | `w:line="276" w:lineRule="auto"` |
+| Para spacing after | 8pt | `w:after="160"` |
+| H1 spacing | 24pt before, 10pt after | `w:before="480" w:after="200"` |
+| H2 spacing | 16pt before, 6pt after | `w:before="320" w:after="120"` |
+| Margins | 1in all around | `w:pgMar` all `"1440"` |
+| Table cell padding | 0.08in / 0.12in | `w:w="115"` / `w:w="173"` |
+| Header/footer size | 9pt gray | `w:sz="18" w:color="808080"` |
+| List indent | 0.25in per level | `w:left="360" w:hanging="360"` |
+| List item spacing | 2pt after | `w:after="40"` |
+
+For CJK documents, adjust: body font to SimSun/YaHei, line spacing to 1.5x (`w:line="360"`), and set `w:eastAsia` on all `w:rFonts`.
diff --git a/builtin-skills/document-process/minimax-docx/references/design_principles.md b/builtin-skills/document-process/minimax-docx/references/design_principles.md
new file mode 100644
index 00000000..6d81dd38
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/design_principles.md
@@ -0,0 +1,819 @@
+# Design Principles for Document Typography
+
+WHY certain typographic choices look good -- the perceptual and psychological
+reasons behind professional document design. Use this to make judgment calls
+when exact specs are not provided.
+
+## Table of Contents
+
+1. [White Space & Breathing Room](#1-white-space--breathing-room)
+2. [Contrast & Scale](#2-contrast--scale)
+3. [Proximity & Grouping](#3-proximity--grouping)
+4. [Alignment & Grid](#4-alignment--grid)
+5. [Repetition & Consistency](#5-repetition--consistency)
+6. [Visual Hierarchy & Flow](#6-visual-hierarchy--flow)
+
+---
+
+## 1. White Space & Breathing Room
+
+### Why It Works
+
+The human eye does not read continuously. It jumps in saccades, fixating on
+small clusters of words. White space provides landing zones for these fixations
+and gives the reader's peripheral vision a "frame" that makes each text block
+feel manageable. When a page is packed to the edges, every glance returns more
+text than working memory can buffer, triggering fatigue and avoidance.
+
+Research on content density consistently shows:
+
+- **60-70% content coverage** feels comfortable and professional.
+- **80%+** starts to feel dense and bureaucratic.
+- **90%+** feels oppressive -- the reader unconsciously rushes or skips.
+- **Below 50%** feels wasteful or pretentious (unless intentional, like poetry).
+
+Wider margins also carry cultural signals. Academic and luxury documents use
+generous margins (1.25-1.5 inches). Internal memos and drafts use narrower
+margins (0.75-1.0 inches). The margin width tells the reader how much care
+went into the document before they read a single word.
+
+Line spacing has a direct physiological basis: the eye must track back to the
+start of the next line after each line break. If lines are too close, the eye
+"slips" to the wrong line. If too far apart, the eye loses its sense of
+continuity. The sweet spot is 120-145% of the font size.
+
+**Rule of thumb: when in doubt, add more space, not less.**
+
+### Good Example
+
+```
+Margins: 1 inch (1440 twips) all sides for business documents.
+Line spacing: 1.15 (276 twips at 240 twips-per-line = 115%).
+Paragraph spacing after: 8pt (160 twips) between body paragraphs.
+```
+
+```xml
+<!-- Page margins: 1 inch = 1440 twips on all sides -->
+<w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"
+         w:header="720" w:footer="720" w:gutter="0"/>
+
+<!-- Body paragraph: 1.15 line spacing, 8pt after -->
+<w:pPr>
+  <w:spacing w:after="160" w:line="276" w:lineRule="auto"/>
+</w:pPr>
+```
+
+This produces a page where content occupies roughly 65% of the area. The
+reader sees clear top/bottom breathing room, and paragraphs are distinct
+without feeling disconnected.
+
+```
+  Page layout (good):
+  +----------------------------------+
+  |           1" margin              |
+  |   +------------------------+    |
+  |   | Heading                |    |
+  |   |                        |    |
+  |   | Body text here with    |    |
+  |   | comfortable spacing    |    |
+  |   | between lines.         |    |
+  |   |                        |    |  <- visible gap between paragraphs
+  |   | Another paragraph of   |    |
+  |   | body text follows.     |    |
+  |   |                        |    |
+  |   +------------------------+    |
+  |           1" margin              |
+  +----------------------------------+
+```
+
+### Bad Example
+
+```xml
+<!-- Cramped margins: 0.5 inch = 720 twips -->
+<w:pgMar w:top="720" w:right="720" w:bottom="720" w:left="720"
+         w:header="360" w:footer="360" w:gutter="0"/>
+
+<!-- No paragraph spacing, single line spacing -->
+<w:pPr>
+  <w:spacing w:after="0" w:line="240" w:lineRule="auto"/>
+</w:pPr>
+```
+
+This fills ~85% of the page. Text runs edge-to-edge with no visual rest stops.
+The reader sees a wall of text.
+
+```
+  Page layout (bad):
+  +----------------------------------+
+  | Heading                          |
+  | Body text crammed right up to    |
+  | the margins with no spacing      |
+  | between lines or paragraphs.     |
+  | Another paragraph starts here    |
+  | and the reader cannot tell where |
+  | one idea ends and another begins |
+  | because everything blurs into a  |
+  | single dense block of text.      |
+  +----------------------------------+
+```
+
+### Quick Test
+
+1. Zoom out to 50% in your document viewer. If you cannot see clear "channels"
+   of white between text blocks, the spacing is too tight.
+2. Print a test page. Hold it at arm's length. The text area should look like
+   a rectangle floating in white, not filling the page.
+3. Check: is the line spacing value at least 264 (`w:line` for 1.1x) for body
+   text? If it is 240 (single), it is too tight for anything over 10pt.
+
+---
+
+## 2. Contrast & Scale
+
+### Why It Works
+
+The brain processes visual hierarchy through relative difference, not absolute
+size. A 20pt heading above 11pt body text creates a clear "this is important"
+signal. But if every heading is 20pt and every sub-heading is 19pt, the brain
+cannot distinguish them -- they merge into the same level.
+
+The key insight is **modular scale**: font sizes that grow by a consistent
+ratio. This mirrors natural proportions and feels harmonious for the same
+reason musical intervals do.
+
+Common scales and their character:
+
+| Ratio | Name           | Character                       | Example progression (from 11pt) |
+|-------|----------------|---------------------------------|---------------------------------|
+| 1.200 | Minor third    | Subtle, refined                 | 11 → 13.2 → 15.8 → 19.0       |
+| 1.250 | Major third    | Balanced, professional          | 11 → 13.75 → 17.2 → 21.5      |
+| 1.333 | Perfect fourth | Strong, authoritative           | 11 → 14.7 → 19.5 → 26.0       |
+| 1.414 | Augmented 4th  | Dramatic, presentation-style    | 11 → 15.6 → 22.0 → 31.1       |
+
+For most business documents, 1.25 (major third) works best:
+
+```
+Body  = 11pt  (w:sz="22")
+H3    = 13pt  (w:sz="26")   -- 11 * 1.25 ≈ 13.75, round to 13
+H2    = 16pt  (w:sz="32")   -- 13 * 1.25 ≈ 16.25, round to 16
+H1    = 20pt  (w:sz="40")   -- 16 * 1.25 = 20
+```
+
+Beyond size, **weight contrast** creates hierarchy without consuming vertical
+space. Regular (400) vs Bold (700) is visible at any size. Semi-bold (600) vs
+Regular is subtle and best avoided unless you also vary size or color.
+
+**Color contrast** adds a third dimension. Dark blue headings (#1F3864) against
+softer dark gray body text (#333333) signals "heading" without needing a huge
+size jump. Pure black (#000000) body text is harsher than necessary on white
+backgrounds -- #333333 or #2D2D2D reduces glare without losing legibility.
+
+### Good Example
+
+```xml
+<!-- H1: 20pt, bold, dark navy -->
+<w:rPr>
+  <w:b/>
+  <w:sz w:val="40"/>
+  <w:color w:val="1F3864"/>
+</w:rPr>
+
+<!-- H2: 16pt, bold, dark navy -->
+<w:rPr>
+  <w:b/>
+  <w:sz w:val="32"/>
+  <w:color w:val="1F3864"/>
+</w:rPr>
+
+<!-- H3: 13pt, bold, dark navy -->
+<w:rPr>
+  <w:b/>
+  <w:sz w:val="26"/>
+  <w:color w:val="1F3864"/>
+</w:rPr>
+
+<!-- Body: 11pt, regular, dark gray -->
+<w:rPr>
+  <w:sz w:val="22"/>
+  <w:color w:val="333333"/>
+</w:rPr>
+```
+
+```
+  Visual hierarchy (good):
+
+  [████████████████████]        <- H1: 20pt bold navy (clearly dominant)
+                                   (generous space)
+  [██████████████]              <- H2: 16pt bold navy (distinct step down)
+                                   (moderate space)
+  [████████████]                <- H3: 13pt bold navy (smaller but still bold)
+  [░░░░░░░░░░░░░░░░░░░░░░]    <- Body: 11pt regular gray
+  [░░░░░░░░░░░░░░░░░░░░░░]
+  [░░░░░░░░░░░░░░░░░░░░░░]
+```
+
+Each level is visually distinct from its neighbors. You can identify the
+hierarchy even in peripheral vision.
+
+### Bad Example
+
+```xml
+<!-- H1: 14pt bold black -->
+<w:rPr>
+  <w:b/>
+  <w:sz w:val="28"/>
+  <w:color w:val="000000"/>
+</w:rPr>
+
+<!-- H2: 13pt bold black -->
+<w:rPr>
+  <w:b/>
+  <w:sz w:val="26"/>
+  <w:color w:val="000000"/>
+</w:rPr>
+
+<!-- H3: 12pt bold black -->
+<w:rPr>
+  <w:b/>
+  <w:sz w:val="24"/>
+  <w:color w:val="000000"/>
+</w:rPr>
+
+<!-- Body: 12pt regular black -->
+<w:rPr>
+  <w:sz w:val="24"/>
+  <w:color w:val="000000"/>
+</w:rPr>
+```
+
+Problems:
+- H3 (12pt bold) and body (12pt regular) differ only by weight -- too subtle.
+- H1 (14pt) to H2 (13pt) is a 1pt step -- invisible at reading distance.
+- Everything is pure black so color provides no differentiating signal.
+- The ratio between levels is ~1.07, far too flat.
+
+### Quick Test
+
+1. **The squint test**: blur your eyes or step back from the screen. Can you
+   count the number of heading levels? If two levels merge, their contrast
+   is insufficient.
+2. **Ratio check**: divide each heading size by the next smaller size. If any
+   ratio is below 1.15, the levels will look too similar.
+3. **Color check**: do headings look distinct from body text when you glance
+   at the page? If everything is the same color, you are relying solely on
+   size/weight, which limits your hierarchy to ~3 effective levels.
+
+---
+
+## 3. Proximity & Grouping
+
+### Why It Works
+
+The Gestalt principle of proximity: items that are close together are perceived
+as belonging to the same group. In document typography, this means a heading
+must be **closer to the content it introduces** than to the content above it.
+
+If a heading sits equidistant between two paragraphs, it looks orphaned -- the
+reader's eye does not know if it belongs to the text above or below. The fix
+is asymmetric spacing: **large space before the heading, small space after**.
+
+The recommended ratio is 2:1 or 3:1 (space-before : space-after).
+
+This same principle applies to:
+- **List items**: spacing between items should be less than spacing between
+  paragraphs. Items in a list are a group and should visually cluster.
+- **Captions**: a figure caption should be close to its figure, not floating
+  in the middle between the figure and the next paragraph.
+- **Table titles**: the title sits close above the table, with more space
+  separating the title from preceding text.
+
+### Good Example
+
+```xml
+<!-- H2: 18pt before, 6pt after (3:1 ratio) -->
+<w:pPr>
+  <w:pStyle w:val="Heading2"/>
+  <w:spacing w:before="360" w:after="120"/>
+</w:pPr>
+
+<!-- Body paragraph: 0pt before, 8pt after -->
+<w:pPr>
+  <w:spacing w:before="0" w:after="160"/>
+</w:pPr>
+
+<!-- List item: 0pt before, 2pt after (tight grouping) -->
+<w:pPr>
+  <w:pStyle w:val="ListParagraph"/>
+  <w:spacing w:before="0" w:after="40"/>
+</w:pPr>
+```
+
+```
+  Proximity (good):
+
+  ...end of previous section text.
+                                        <- 18pt gap (w:before="360")
+  ## Section Heading
+                                        <- 6pt gap (w:after="120")
+  First paragraph of new section
+  continues here with content.
+                                        <- 8pt gap (w:after="160")
+  Second paragraph follows.
+
+  The heading clearly "belongs to" the text below it.
+```
+
+```
+  List grouping (good):
+
+  Consider these factors:
+    - First item                        <- 2pt gap between items
+    - Second item                       <- items cluster as a group
+    - Third item
+                                        <- 8pt gap after list
+  The next paragraph starts here.
+```
+
+### Bad Example
+
+```xml
+<!-- H2: 12pt before, 12pt after (1:1 ratio -- orphaned heading) -->
+<w:pPr>
+  <w:pStyle w:val="Heading2"/>
+  <w:spacing w:before="240" w:after="240"/>
+</w:pPr>
+
+<!-- List item: same spacing as body (10pt after) -->
+<w:pPr>
+  <w:pStyle w:val="ListParagraph"/>
+  <w:spacing w:before="0" w:after="200"/>
+</w:pPr>
+```
+
+```
+  Proximity (bad):
+
+  ...end of previous section text.
+                                        <- 12pt gap
+  ## Section Heading
+                                        <- 12pt gap (same!)
+  First paragraph of new section.
+
+  The heading floats between sections. It is unclear what it belongs to.
+```
+
+```
+  List grouping (bad):
+
+  Consider these factors:
+                                        <- 10pt gap
+    - First item
+                                        <- 10pt gap (same as paragraphs)
+    - Second item
+                                        <- 10pt gap
+    - Third item
+                                        <- 10pt gap
+  Next paragraph.
+
+  The list does not feel like a group. Each item looks like a
+  separate paragraph that happens to have a bullet.
+```
+
+### Quick Test
+
+1. **Cover test**: cover the heading text. Looking only at the whitespace,
+   can you tell which block of text the heading belongs to? If the gaps above
+   and below are equal, the answer is "no."
+2. **Number check**: `w:before` on headings should be at least 2x `w:after`.
+   Common good values: before=360 / after=120, or before=240 / after=80.
+3. **List check**: `w:after` on list items should be less than half of
+   `w:after` on body paragraphs. If body uses 160, list items should use
+   40-60.
+
+---
+
+## 4. Alignment & Grid
+
+### Why It Works
+
+Alignment creates invisible lines that the eye follows down the page. When
+elements share the same left edge, the reader perceives order and intention.
+When elements are slightly misaligned (off by a few twips), the page looks
+sloppy even if the reader cannot consciously identify why.
+
+**Left-align vs Justify:**
+
+- **Left-aligned** (ragged right) is best for English and other Latin-script
+  languages. The uneven right edge actually helps reading because each line
+  has a unique silhouette, making it easier for the eye to find the next line.
+  Justified text forces uneven word spacing that creates distracting "rivers"
+  of white running vertically through paragraphs.
+
+- **Justified** is best for CJK text. Chinese, Japanese, and Korean characters
+  are monospaced by design -- each occupies the same cell in an invisible grid.
+  Justification preserves this grid perfectly. Ragged right in CJK text breaks
+  the grid and looks untidy.
+
+**Indentation rule:** Use first-line indent OR paragraph spacing to separate
+paragraphs -- never both. They serve the same purpose (marking paragraph
+boundaries). Using both wastes space and creates visual stutter.
+
+- Western convention: paragraph spacing (no indent) is more modern.
+- CJK convention: first-line indent of 2 characters is standard.
+- Academic convention: first-line indent of 0.5 inch is traditional.
+
+### Good Example
+
+```xml
+<!-- English body: left-aligned, paragraph spacing, no indent -->
+<w:pPr>
+  <w:jc w:val="left"/>
+  <w:spacing w:after="160" w:line="276" w:lineRule="auto"/>
+  <!-- No w:ind firstLine -->
+</w:pPr>
+
+<!-- CJK body: justified, first-line indent 2 chars, no paragraph spacing -->
+<w:pPr>
+  <w:jc w:val="both"/>
+  <w:spacing w:after="0" w:line="360" w:lineRule="auto"/>
+  <w:ind w:firstLineChars="200"/>
+</w:pPr>
+
+<!-- Tab stops creating aligned columns -->
+<w:pPr>
+  <w:tabs>
+    <w:tab w:val="left" w:pos="2880"/>   <!-- 2 inches -->
+    <w:tab w:val="right" w:pos="9360"/>  <!-- 6.5 inches (right margin) -->
+  </w:tabs>
+</w:pPr>
+```
+
+```
+  English paragraph separation (good -- spacing, no indent):
+
+  This is the first paragraph with some text
+  that wraps to a second line naturally.
+
+  This is the second paragraph. The gap above
+  clearly marks the boundary.
+
+
+  CJK paragraph separation (good -- indent, no spacing):
+
+  　　第一段正文内容从这里开始，使用两个字符
+  的首行缩进来标记段落边界。
+  　　第二段紧跟其后，没有段间距，但首行缩进
+  清晰地标识了新段落的开始。
+```
+
+### Bad Example
+
+```xml
+<!-- English body: justified (creates word-spacing rivers) -->
+<w:pPr>
+  <w:jc w:val="both"/>
+  <w:spacing w:after="160" w:line="276" w:lineRule="auto"/>
+  <w:ind w:firstLine="720"/>  <!-- BOTH indent AND spacing: redundant -->
+</w:pPr>
+
+<!-- CJK body: left-aligned (breaks character grid) -->
+<w:pPr>
+  <w:jc w:val="left"/>
+  <w:spacing w:after="200" w:line="276" w:lineRule="auto"/>
+  <!-- No indent, using spacing instead -- unidiomatic for CJK -->
+</w:pPr>
+```
+
+Problems:
+- Justified English text with narrow columns creates uneven word gaps.
+- Using both first-line indent AND paragraph spacing is redundant.
+- Left-aligned CJK breaks the character grid that CJK readers expect.
+- CJK with spacing-based separation looks like translated western layout.
+
+### Quick Test
+
+1. **River test**: in justified English text, squint and look for vertical
+   white streaks running through the paragraph. If you see them, switch to
+   left-align or increase the column width.
+2. **Double signal check**: does the document use BOTH first-line indent AND
+   paragraph spacing? If yes, remove one. Choose indent for CJK/academic,
+   spacing for modern western.
+3. **Tab alignment**: if you use tabs for columns, do all tab stops across
+   the document use the same positions? Inconsistent tab stops create jagged
+   invisible grid lines.
+
+---
+
+## 5. Repetition & Consistency
+
+### Why It Works
+
+Consistency is a trust signal. When a reader sees that every H2 looks the same,
+every table follows the same pattern, and every page number sits in the same
+spot, they unconsciously trust that the document was crafted with care. A single
+inconsistency -- one H2 that is 15pt instead of 14pt, one table with different
+borders -- breaks that trust and makes the reader question the content.
+
+Consistency also reduces cognitive load. Once the reader learns "bold dark blue
+= section heading," they stop spending mental effort on identifying structure
+and focus entirely on content. Every inconsistency forces them to re-evaluate:
+"Is this a different kind of heading, or did someone just forget to apply the
+style?"
+
+The implementation rule is simple: **use named styles, not direct formatting.**
+If you define Heading2 as a style and apply it everywhere, consistency is
+automatic. If you manually set font size, bold, and color on each heading
+individually, inconsistency is inevitable.
+
+### Good Example
+
+```xml
+<!-- Define styles once in styles.xml -->
+<w:style w:type="paragraph" w:styleId="Heading2">
+  <w:name w:val="heading 2"/>
+  <w:basedOn w:val="Normal"/>
+  <w:next w:val="Normal"/>
+  <w:pPr>
+    <w:keepNext/>
+    <w:keepLines/>
+    <w:spacing w:before="360" w:after="120"/>
+    <w:outlineLvl w:val="1"/>
+  </w:pPr>
+  <w:rPr>
+    <w:rFonts w:asciiTheme="majorHAnsi" w:hAnsiTheme="majorHAnsi"/>
+    <w:b/>
+    <w:sz w:val="32"/>
+    <w:color w:val="1F3864"/>
+  </w:rPr>
+</w:style>
+
+<!-- Apply consistently: every H2 references the style -->
+<w:p>
+  <w:pPr>
+    <w:pStyle w:val="Heading2"/>
+    <!-- No direct formatting overrides -->
+  </w:pPr>
+  <w:r><w:t>Market Analysis</w:t></w:r>
+</w:p>
+```
+
+When using a table style, define it once and reference it for every table:
+
+```xml
+<!-- All tables reference the same style -->
+<w:tblPr>
+  <w:tblStyle w:val="GridTable4Accent1"/>
+  <w:tblW w:w="0" w:type="auto"/>
+</w:tblPr>
+```
+
+### Bad Example
+
+```xml
+<!-- First H2: manually formatted -->
+<w:p>
+  <w:pPr>
+    <w:spacing w:before="360" w:after="120"/>
+  </w:pPr>
+  <w:r>
+    <w:rPr>
+      <w:b/>
+      <w:sz w:val="32"/>
+      <w:color w:val="1F3864"/>
+    </w:rPr>
+    <w:t>Market Analysis</w:t>
+  </w:r>
+</w:p>
+
+<!-- Second H2: slightly different (16pt instead of 16pt?  No, 15pt!) -->
+<w:p>
+  <w:pPr>
+    <w:spacing w:before="240" w:after="160"/>  <!-- different spacing! -->
+  </w:pPr>
+  <w:r>
+    <w:rPr>
+      <w:b/>
+      <w:sz w:val="30"/>   <!-- 15pt instead of 16pt! -->
+      <w:color w:val="2E74B5"/>  <!-- different shade of blue! -->
+    </w:rPr>
+    <w:t>Financial Overview</w:t>
+  </w:r>
+</w:p>
+```
+
+Problems:
+- No style references -- everything is direct formatting.
+- Second H2 has different size (30 vs 32), color, and spacing.
+- If there are 20 headings, each could drift slightly differently.
+- Changing the design later means editing every heading individually.
+
+### Quick Test
+
+1. **Style audit**: does every paragraph reference a `w:pStyle`? If you find
+   paragraphs with only direct formatting and no style, that is a consistency
+   risk.
+2. **Search for variance**: search the XML for all `w:sz` values used with
+   `w:b` (bold). If you find three different sizes for what should be the same
+   heading level, there is an inconsistency.
+3. **Table check**: do all tables in the document reference the same
+   `w:tblStyle`? If some tables have manual border definitions while others
+   use a style, the document will look patchy.
+4. **Page numbers**: check that header/footer content is defined in the
+   default section properties and inherited by all sections, not redefined
+   inconsistently in each section.
+
+---
+
+## 6. Visual Hierarchy & Flow
+
+### Why It Works
+
+A well-designed document guides the reader's eye in a predictable path:
+title at the top, subtitle below it, section headings as signposts, body text
+as the main content, footnotes and captions as supporting details. This flow
+mirrors reading priority -- the most important information is the most visually
+prominent.
+
+Each level in the hierarchy must be **distinguishable from its adjacent
+levels**. It is not enough for H1 to differ from body text; H1 must also
+clearly differ from H2, and H2 from H3. If any two adjacent levels are too
+similar, the hierarchy collapses at that point.
+
+Effective hierarchy uses **multiple simultaneous signals**:
+
+| Level    | Size  | Weight  | Color   | Spacing above |
+|----------|-------|---------|---------|---------------|
+| Title    | 26pt  | Bold    | #1F3864 | 0 (top)       |
+| Subtitle | 15pt  | Regular | #4472C4 | 4pt           |
+| H1       | 20pt  | Bold    | #1F3864 | 24pt          |
+| H2       | 16pt  | Bold    | #1F3864 | 18pt          |
+| H3       | 13pt  | Bold    | #1F3864 | 12pt          |
+| Body     | 11pt  | Regular | #333333 | 0pt           |
+| Caption  | 9pt   | Italic  | #666666 | 4pt           |
+| Footnote | 9pt   | Regular | #666666 | 0pt           |
+
+Notice how each level differs from its neighbors on at least two dimensions
+(size + weight, or size + color, or weight + style). Single-dimension
+differences are fragile and can be missed.
+
+**Section breaks** create rhythm in long documents. A page break before each
+major section (H1) gives the reader a mental reset. Within sections, consistent
+heading + body patterns create a predictable cadence that makes long documents
+less intimidating.
+
+### Good Example
+
+```xml
+<!-- Title: large, bold, navy, centered -->
+<w:style w:type="paragraph" w:styleId="Title">
+  <w:pPr>
+    <w:jc w:val="center"/>
+    <w:spacing w:after="80"/>
+  </w:pPr>
+  <w:rPr>
+    <w:b/>
+    <w:sz w:val="52"/>
+    <w:color w:val="1F3864"/>
+  </w:rPr>
+</w:style>
+
+<!-- Subtitle: medium, regular weight, lighter blue, centered -->
+<w:style w:type="paragraph" w:styleId="Subtitle">
+  <w:pPr>
+    <w:jc w:val="center"/>
+    <w:spacing w:after="320"/>
+  </w:pPr>
+  <w:rPr>
+    <w:sz w:val="30"/>
+    <w:color w:val="4472C4"/>
+  </w:rPr>
+</w:style>
+
+<!-- H1: page break before, large bold navy -->
+<w:style w:type="paragraph" w:styleId="Heading1">
+  <w:pPr>
+    <w:pageBreakBefore/>
+    <w:keepNext/>
+    <w:keepLines/>
+    <w:spacing w:before="480" w:after="160"/>
+    <w:outlineLvl w:val="0"/>
+  </w:pPr>
+  <w:rPr>
+    <w:b/>
+    <w:sz w:val="40"/>
+    <w:color w:val="1F3864"/>
+  </w:rPr>
+</w:style>
+
+<!-- Caption: small, italic, gray -->
+<w:style w:type="paragraph" w:styleId="Caption">
+  <w:pPr>
+    <w:spacing w:before="80" w:after="200"/>
+  </w:pPr>
+  <w:rPr>
+    <w:i/>
+    <w:sz w:val="18"/>
+    <w:color w:val="666666"/>
+  </w:rPr>
+</w:style>
+```
+
+```
+  Visual flow (good):
+
+  +----------------------------------+
+  |                                  |
+  |     ANNUAL REPORT 2025           |  <- Title: 26pt bold navy centered
+  |     Acme Corporation             |  <- Subtitle: 15pt regular blue
+  |                                  |
+  |                                  |
+  +----------------------------------+
+
+  +----------------------------------+
+  |                                  |
+  |  1. Executive Summary            |  <- H1: 20pt bold navy (page break)
+  |                                  |
+  |  Body text introducing the       |  <- Body: 11pt regular gray
+  |  main findings of the year.      |
+  |                                  |
+  |  1.1 Revenue Highlights          |  <- H2: 16pt bold navy
+  |                                  |
+  |  Revenue grew by 23% year        |  <- Body
+  |  over year, driven by...         |
+  |                                  |
+  |  Figure 1: Revenue Growth        |  <- Caption: 9pt italic gray
+  |                                  |
+  +----------------------------------+
+
+  Each level is immediately identifiable. The eye flows naturally
+  from title -> heading -> body -> caption.
+```
+
+### Bad Example
+
+```xml
+<!-- All headings same color as body, minimal size difference -->
+<w:style w:type="paragraph" w:styleId="Heading1">
+  <w:rPr>
+    <w:b/>
+    <w:sz w:val="28"/>       <!-- 14pt -- only 3pt above body -->
+    <w:color w:val="000000"/> <!-- same color as body -->
+  </w:rPr>
+</w:style>
+
+<!-- Caption same size as body, not italic -->
+<w:style w:type="paragraph" w:styleId="Caption">
+  <w:rPr>
+    <w:sz w:val="22"/>        <!-- same 11pt as body! -->
+    <w:color w:val="000000"/> <!-- same color as body -->
+  </w:rPr>
+</w:style>
+
+<!-- No page breaks between major sections -->
+<!-- H1 has no pageBreakBefore, keepNext, or keepLines -->
+```
+
+Problems:
+- H1 at 14pt is too close to body at 11pt (ratio 1.27 -- acceptable in
+  isolation but with black color matching body, the hierarchy is weak).
+- Caption is indistinguishable from body text.
+- No page breaks means major sections bleed into each other with no
+  visual rhythm.
+- Everything is black, so color provides zero hierarchy signal.
+
+### Quick Test
+
+1. **The squint test**: blur your eyes while looking at a full page. You
+   should see 3-4 distinct "weight levels" of gray. If the page looks like
+   one uniform shade, the hierarchy is too flat.
+2. **The scan test**: flip through pages quickly. Can you identify section
+   boundaries in under one second per page? If yes, the visual hierarchy is
+   working. If pages blur together, you need stronger differentiation at H1.
+3. **Adjacent level test**: for each heading level, check that it differs
+   from the next level on at least 2 of: size, weight, color, style (italic).
+   Single-dimension differences get lost.
+4. **Rhythm test**: in a document over 10 pages, do major sections (H1) start
+   on new pages? If not, long documents will feel like an undifferentiated
+   stream. Add `w:pageBreakBefore` to Heading1.
+
+---
+
+## Summary: Decision Checklist
+
+When you are unsure about a typographic choice, run through these checks:
+
+| Principle | Question | If No... |
+|-----------|----------|----------|
+| White Space | Does the page have at least 30% white space? | Increase margins or spacing |
+| Contrast | Can I count heading levels by squinting? | Increase size ratios (target 1.25x) |
+| Proximity | Does each heading clearly belong to text below it? | Make space-before > space-after (2:1) |
+| Alignment | Is English left-aligned and CJK justified? | Switch alignment mode |
+| Repetition | Do all same-level elements use the same style? | Replace direct formatting with styles |
+| Hierarchy | Can I see the document structure at arm's length? | Add more differentiation signals |
+
+**When two principles conflict, prioritize in this order:**
+
+1. **Readability** (white space, line spacing) -- always wins
+2. **Hierarchy** (contrast, scale) -- readers must find what they need
+3. **Consistency** (repetition) -- builds trust
+4. **Aesthetics** (alignment, grouping) -- the finishing touch
diff --git a/builtin-skills/document-process/minimax-docx/references/openxml_element_order.md b/builtin-skills/document-process/minimax-docx/references/openxml_element_order.md
new file mode 100644
index 00000000..a84b5a2b
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/openxml_element_order.md
@@ -0,0 +1,308 @@
+# OpenXML Child Element Ordering Rules
+
+Element ordering in OpenXML is defined by the XSD schema. Incorrect ordering produces invalid documents that Word may refuse to open or silently repair (potentially losing data).
+
+> **Key rule**: Properties elements (`*Pr`) must always be the **first child** of their parent.
+
+---
+
+## w:document
+
+```
+Children in order:
+1. w:background       [0..1]  — page background color/fill
+2. w:body              [0..1]  — document content container
+```
+
+---
+
+## w:body
+
+```
+Children in order (repeating group):
+1. w:p                 [0..*]  — paragraph
+2. w:tbl               [0..*]  — table
+3. w:sdt               [0..*]  — structured document tag (content control)
+4. w:sectPr            [0..1]  — LAST child: final section properties
+```
+
+Note: `w:p`, `w:tbl`, and `w:sdt` are interleaved in document order. The only strict rule is that `w:sectPr` must be the **last child** of `w:body`.
+
+---
+
+## w:p (Paragraph)
+
+```
+Children in order:
+1. w:pPr               [0..1]  — paragraph properties (MUST be first)
+
+Then any mix of (interleaved in document order):
+- w:r                  [0..*]  — run
+- w:hyperlink          [0..*]  — hyperlink wrapper
+- w:ins                [0..*]  — tracked insertion
+- w:del                [0..*]  — tracked deletion
+- w:bookmarkStart      [0..*]  — bookmark anchor start
+- w:bookmarkEnd        [0..*]  — bookmark anchor end
+- w:commentRangeStart  [0..*]  — comment range start
+- w:commentRangeEnd    [0..*]  — comment range end
+- w:proofErr           [0..*]  — proofing error marker
+- w:fldSimple          [0..*]  — simple field
+- w:sdt                [0..*]  — inline content control
+- w:smartTag           [0..*]  — smart tag
+```
+
+**Practical note**: After `w:pPr`, the remaining children appear in document reading order. Runs, hyperlinks, bookmarks, and comment ranges intermix freely based on their position in the text.
+
+---
+
+## w:pPr (Paragraph Properties)
+
+```
+Children in order:
+1.  w:pStyle            [0..1]  — paragraph style reference
+2.  w:keepNext          [0..1]  — keep with next paragraph
+3.  w:keepLines         [0..1]  — keep lines together
+4.  w:pageBreakBefore   [0..1]  — page break before paragraph
+5.  w:framePr           [0..1]  — text frame properties
+6.  w:widowControl      [0..1]  — widow/orphan control
+7.  w:numPr             [0..1]  — numbering properties
+8.  w:suppressLineNumbers [0..1]
+9.  w:pBdr              [0..1]  — paragraph borders
+10. w:shd               [0..1]  — shading
+11. w:tabs              [0..1]  — tab stops
+12. w:suppressAutoHyphens [0..1]
+13. w:kinsoku           [0..1]  — CJK kinsoku settings
+14. w:wordWrap           [0..1]
+15. w:overflowPunct     [0..1]
+16. w:topLinePunct      [0..1]
+17. w:autoSpaceDE       [0..1]
+18. w:autoSpaceDN       [0..1]
+19. w:bidi              [0..1]  — right-to-left paragraph
+20. w:adjustRightInd    [0..1]
+21. w:snapToGrid        [0..1]
+22. w:spacing            [0..1]  — line and paragraph spacing
+23. w:ind               [0..1]  — indentation
+24. w:contextualSpacing [0..1]
+25. w:mirrorIndents     [0..1]
+26. w:suppressOverlap   [0..1]
+27. w:jc                [0..1]  — justification (left/center/right/both)
+28. w:textDirection     [0..1]
+29. w:textAlignment     [0..1]
+30. w:outlineLvl        [0..1]  — outline level
+31. w:divId             [0..1]
+32. w:rPr               [0..1]  — run properties for paragraph mark
+33. w:sectPr            [0..1]  — section break (section ends at this paragraph)
+34. w:pPrChange         [0..1]  — tracked paragraph property change
+```
+
+---
+
+## w:r (Run)
+
+```
+Children in order:
+1. w:rPr               [0..1]  — run properties (MUST be first)
+
+Then any of (one per run, typically):
+- w:t                  [0..*]  — text content
+- w:br                 [0..*]  — break (line, page, column)
+- w:tab                [0..*]  — tab character
+- w:cr                 [0..*]  — carriage return
+- w:sym               [0..*]  — symbol character
+- w:drawing            [0..*]  — DrawingML object (images)
+- w:pict               [0..*]  — VML picture (legacy)
+- w:fldChar            [0..*]  — complex field character
+- w:instrText          [0..*]  — field instruction text
+- w:delText            [0..*]  — deleted text (inside w:del)
+- w:footnoteReference  [0..*]
+- w:endnoteReference   [0..*]
+- w:commentReference   [0..*]
+- w:lastRenderedPageBreak [0..*]
+```
+
+---
+
+## w:rPr (Run Properties)
+
+```
+Children in order:
+1.  w:rStyle            [0..1]  — character style reference
+2.  w:rFonts            [0..1]  — font specification
+3.  w:b                 [0..1]  — bold
+4.  w:bCs               [0..1]  — complex script bold
+5.  w:i                 [0..1]  — italic
+6.  w:iCs               [0..1]  — complex script italic
+7.  w:caps              [0..1]  — all capitals
+8.  w:smallCaps         [0..1]  — small capitals
+9.  w:strike            [0..1]  — strikethrough
+10. w:dstrike           [0..1]  — double strikethrough
+11. w:outline           [0..1]
+12. w:shadow            [0..1]
+13. w:emboss            [0..1]
+14. w:imprint           [0..1]
+15. w:noProof           [0..1]  — suppress proofing
+16. w:snapToGrid        [0..1]
+17. w:vanish            [0..1]  — hidden text
+18. w:color             [0..1]  — text color
+19. w:spacing            [0..1]  — character spacing
+20. w:w                 [0..1]  — character width scaling
+21. w:kern              [0..1]  — font kerning
+22. w:position          [0..1]  — vertical position (raise/lower)
+23. w:sz                [0..1]  — font size (half-points)
+24. w:szCs              [0..1]  — complex script font size
+25. w:highlight         [0..1]  — text highlight color
+26. w:u                 [0..1]  — underline
+27. w:effect            [0..1]  — text effect (animated)
+28. w:bdr               [0..1]  — run border
+29. w:shd               [0..1]  — run shading
+30. w:vertAlign         [0..1]  — superscript/subscript
+31. w:rtl               [0..1]  — right-to-left
+32. w:cs                [0..1]  — complex script
+33. w:lang              [0..1]  — language
+34. w:rPrChange         [0..1]  — tracked run property change
+```
+
+---
+
+## w:tbl (Table)
+
+```
+Children in order:
+1. w:tblPr              [1..1]  — table properties (REQUIRED, must be first)
+2. w:tblGrid            [1..1]  — column width definitions (REQUIRED)
+3. w:tr                 [1..*]  — table row(s)
+```
+
+---
+
+## w:tblPr (Table Properties)
+
+```
+Children in order:
+1.  w:tblStyle           [0..1]  — table style reference
+2.  w:tblpPr             [0..1]  — table positioning
+3.  w:tblOverlap         [0..1]
+4.  w:bidiVisual         [0..1]  — right-to-left table
+5.  w:tblStyleRowBandSize [0..1]
+6.  w:tblStyleColBandSize [0..1]
+7.  w:tblW               [0..1]  — preferred table width
+8.  w:jc                 [0..1]  — table alignment
+9.  w:tblCellSpacing     [0..1]
+10. w:tblInd             [0..1]  — table indent from margin
+11. w:tblBorders         [0..1]  — table borders
+12. w:shd                [0..1]  — table shading
+13. w:tblLayout          [0..1]  — fixed or autofit
+14. w:tblCellMar         [0..1]  — default cell margins
+15. w:tblLook            [0..1]  — conditional formatting flags
+16. w:tblCaption         [0..1]  — accessibility caption
+17. w:tblDescription     [0..1]  — accessibility description
+18. w:tblPrChange        [0..1]  — tracked table property change
+```
+
+---
+
+## w:tr (Table Row)
+
+```
+Children in order:
+1. w:trPr               [0..1]  — row properties (must be first)
+2. w:tc                  [1..*]  — table cell(s)
+```
+
+---
+
+## w:trPr (Table Row Properties)
+
+```
+Children in order:
+1.  w:cnfStyle           [0..1]  — conditional formatting
+2.  w:divId              [0..1]
+3.  w:gridBefore         [0..1]  — grid columns before first cell
+4.  w:gridAfter          [0..1]  — grid columns after last cell
+5.  w:wBefore            [0..1]
+6.  w:wAfter             [0..1]
+7.  w:cantSplit          [0..1]  — don't split row across pages
+8.  w:trHeight           [0..1]  — row height
+9.  w:tblHeader          [0..1]  — repeat as header row
+10. w:tblCellSpacing     [0..1]
+11. w:jc                 [0..1]  — row alignment
+12. w:hidden             [0..1]
+13. w:ins                [0..1]  — tracked row insertion
+14. w:del                [0..1]  — tracked row deletion
+15. w:trPrChange         [0..1]  — tracked row property change
+```
+
+---
+
+## w:tc (Table Cell)
+
+```
+Children in order:
+1. w:tcPr               [0..1]  — cell properties (must be first)
+2. w:p                   [1..*]  — paragraph(s) — at least one required
+3. w:tbl                 [0..*]  — nested table(s)
+```
+
+---
+
+## w:tcPr (Table Cell Properties)
+
+```
+Children in order:
+1.  w:cnfStyle           [0..1]
+2.  w:tcW                [0..1]  — cell width
+3.  w:gridSpan           [0..1]  — horizontal merge (column span)
+4.  w:hMerge             [0..1]  — legacy horizontal merge
+5.  w:vMerge             [0..1]  — vertical merge
+6.  w:tcBorders          [0..1]  — cell borders
+7.  w:shd                [0..1]  — cell shading
+8.  w:noWrap             [0..1]
+9.  w:tcMar              [0..1]  — cell margins
+10. w:textDirection      [0..1]
+11. w:tcFitText          [0..1]
+12. w:vAlign             [0..1]  — vertical alignment
+13. w:hideMark           [0..1]
+14. w:tcPrChange         [0..1]  — tracked cell property change
+```
+
+---
+
+## w:sectPr (Section Properties)
+
+```
+Children in order:
+1.  w:headerReference    [0..*]  — header references (type: default/first/even)
+2.  w:footerReference    [0..*]  — footer references
+3.  w:endnotePr          [0..1]
+4.  w:footnotePr         [0..1]
+5.  w:type               [0..1]  — section break type (nextPage/continuous/evenPage/oddPage)
+6.  w:pgSz               [0..1]  — page size
+7.  w:pgMar              [0..1]  — page margins
+8.  w:paperSrc           [0..1]
+9.  w:pgBorders          [0..1]  — page borders
+10. w:lnNumType          [0..1]  — line numbering
+11. w:pgNumType          [0..1]  — page numbering
+12. w:cols               [0..1]  — column definitions
+13. w:formProt           [0..1]
+14. w:vAlign             [0..1]  — vertical alignment of page
+15. w:noEndnote          [0..1]
+16. w:titlePg            [0..1]  — different first page header/footer
+17. w:textDirection      [0..1]
+18. w:bidi               [0..1]
+19. w:rtlGutter          [0..1]
+20. w:docGrid            [0..1]  — document grid
+21. w:sectPrChange       [0..1]  — tracked section property change
+```
+
+---
+
+## w:hdr (Header) / w:ftr (Footer)
+
+```
+Children (same structure as w:body content):
+1. w:p                   [0..*]  — paragraph(s)
+2. w:tbl                 [0..*]  — table(s)
+3. w:sdt                 [0..*]  — content controls
+```
+
+Headers and footers are essentially mini-documents. They follow the same content model as `w:body` but without a final `w:sectPr`.
diff --git a/builtin-skills/document-process/minimax-docx/references/openxml_encyclopedia_part1.md b/builtin-skills/document-process/minimax-docx/references/openxml_encyclopedia_part1.md
new file mode 100644
index 00000000..177182f5
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/openxml_encyclopedia_part1.md
@@ -0,0 +1,4061 @@
+# OpenXML SDK 3.x Complete Reference Encyclopedia
+
+**Target:** DocumentFormat.OpenXml 3.x / .NET 8+ / C# 12
+**Last Updated:** 2026-03-22
+
+This document serves as an exhaustive reference for building DOCX files with the OpenXML SDK. Every code block is ready to copy-paste.
+
+---
+
+## Namespace Aliases Used Throughout
+
+```csharp
+using DocumentFormat.OpenXml;
+using DocumentFormat.OpenXml.Packaging;
+using DocumentFormat.OpenXml.Wordprocessing;
+```
+
+---
+
+## Table of Contents
+
+1. [Document Creation Skeleton](#1-document-creation-skeleton)
+2. [Style System Deep Dive](#2-style-system-deep-dive)
+3. [Character Formatting (RunProperties)](#3-character-formatting-runproperties--exhaustive)
+4. [Paragraph Formatting (ParagraphProperties)](#4-paragraph-formatting-paragraphproperties--exhaustive)
+
+---
+
+## 1. Document Creation Skeleton
+
+### 1.1 Complete Flow: Create to Save
+
+```csharp
+// =============================================================================
+// DOCUMENT CREATION SKELETON
+// =============================================================================
+// This is the minimal complete flow for creating a valid DOCX from scratch.
+// Follow these steps in order: Create -> AddParts -> AddContent -> Save.
+//
+// Key insight: WordprocessingDocument.Create() adds MainDocumentPart automatically,
+// but all other parts (Styles, Settings, Numbering, Theme) must be added manually.
+
+// --- STEP 1: CREATE THE PACKAGE ---
+// The file path can be absolute or relative. WordprocessingDocumentType.Document
+// is the standard choice for .docx files (vs. Template, MacroEnabled, etc.)
+string outputPath = "C:\\Docs\\MyDocument.docx";
+
+using var doc = WordprocessingDocument.Create(
+    outputPath,                          // File path
+    WordprocessingDocumentType.Document,  // Document type enum
+    new DocumentOptions                    // Optional: AutoSave, etc.
+    {
+        AutoSave = false                   // true = flush changes automatically
+    });
+
+// --- STEP 2: GET OR CREATE THE MAIN DOCUMENT PART ---
+// When you call Create(), MainDocumentPart is automatically created and linked.
+// You access it via .MainDocumentPart (not .AddMainDocumentPart, which would add
+// a SECOND main part — illegal). For a fresh document, just use .MainDocumentPart.
+var mainPart = doc.MainDocumentPart!;
+var body = mainPart.Document.Body!;  // Body is created automatically with the part
+
+// --- STEP 3: ADD ADDITIONAL PARTS ---
+// These are OPTIONAL but recommended for a complete document:
+// - StyleDefinitionsPart: required for styles
+// - NumberingDefinitionsPart: required for bullets/numbers
+// - DocumentSettingsPart: zoom, proof state, tab stops, compatibility
+// - ThemePart: color/theme information
+// Parts are created fresh and linked via relationships.
+
+// Example: Add styles part (covered in Section 2)
+var stylesPart = mainPart.AddNewPart<StyleDefinitionsPart>();
+stylesPart.Styles = new Styles();
+stylesPart.Styles.Save();
+
+// Example: Add settings part (covered in 1.4)
+var settingsPart = mainPart.AddNewPart<DocumentSettingsPart>();
+settingsPart.Settings = new Settings();
+settingsPart.Settings.Save();
+
+// --- STEP 4: ADD CONTENT TO BODY ---
+// Body accepts: Paragraph (w:p), Table (w:tbl), Structured Document Tag (w:sdt)
+// Content is added in document order (no need for explicit index).
+// IMPORTANT: SectionProperties (w:sectPr) MUST be the last child of body.
+body.Append(new Paragraph(
+    new Run(new Text("Hello, World!"))));
+
+// --- STEP 5: SET SECTION PROPERTIES (PAGE LAYOUT) ---
+// sectPr defines page size, margins, headers/footers, columns, etc.
+// It must be the last child of body. If missing, Word uses defaults (Letter/A4, 1" margins).
+var sectPr = new SectionProperties();
+
+// Page Size: Width/Height in DXA (1 inch = 1440 DXA)
+// Letter: 12240 x 15840 DXA (8.5" x 11")
+// A4: 11906 x 16838 DXA (210mm x 297mm)
+sectPr.Append(new PageSize
+{
+    Width = 12240u,   // 8.5 inches
+    Height = 15840u  // 11 inches
+});
+
+// Page Margins: all four margins in DXA
+// Note: Top+Bottom margins + HeaderDistance = distance from page edge to text
+sectPr.Append(new PageMargin
+{
+    Top = 1440,       // 1 inch
+    Bottom = 1440,    // 1 inch
+    Left = 1440u,     // 1 inch (uint required)
+    Right = 1440u,    // 1 inch
+    Header = 720u,    // 0.5 inch from page edge to header
+    Footer = 720u     // 0.5 inch from page edge to footer
+});
+
+// Attach sectPr to body (must be last)
+body.Append(sectPr);
+
+// --- STEP 6: SAVE ---
+// Because we use `using`, Dispose() is called automatically when the block exits.
+// Dispose() saves the file. If you forget `using`, call doc.Save() explicitly.
+```
+
+### 1.2 Opening an Existing Document
+
+```csharp
+// =============================================================================
+// OPENING EXISTING DOCUMENTS
+// =============================================================================
+// Open() has multiple overloads:
+// 1. Open(string path, bool isEditable, AutoSave)
+// 2. Open(Stream, bool isEditable, AutoSave)
+// 3. Open(string path, bool isEditable, OpenSettings)
+//
+// isEditable=true means open for read/write. false = read-only.
+// isEditable=false is faster (shared locks avoided) but throws if file is read-only.
+
+// --- OPEN FOR EDITING (READ/WRITE) ---
+string inputPath = "C:\\Docs\\Existing.docx";
+using var editDoc = WordprocessingDocument.Open(
+    inputPath,
+    isEditable: true,      // Required for modification
+    new OpenSettings
+    {
+        AutoSave = true     // Automatically save on Dispose
+    });
+
+var body = editDoc.MainDocumentPart!.Document.Body!;
+// ... make changes ...
+// No explicit Save() needed if AutoSave = true
+
+// --- OPEN AS READ-ONLY (FASTER) ---
+using var readOnlyDoc = WordprocessingDocument.Open(
+    inputPath,
+    isEditable: false,     // Read-only mode
+    new OpenSettings
+    {
+        // MarkupDeclarationProcess options
+    });
+
+// --- OPEN FROM STREAM ---
+byte[] fileBytes = File.ReadAllBytes(inputPath);
+using var streamDoc = WordprocessingDocument.Open(
+    new MemoryStream(fileBytes),
+    isEditable: true,
+    new OpenSettings { AutoSave = false });
+
+// After editing, you MUST copy the stream back to file if AutoSave=false:
+// streamDoc.MainDocumentPart.Document.Save();
+// File.WriteAllBytes(outputPath, streamStream.ToArray());
+
+// --- OPEN FROM HTTP RESPONSE (WEB SCENARIO) ---
+using var httpClient = new HttpClient();
+var response = await httpClient.GetAsync("https://example.com/document.docx");
+using var webStream = await response.Content.ReadAsStreamAsync();
+using var webDoc = WordprocessingDocument.Open(webStream, isEditable: true);
+```
+
+### 1.3 Stream-Based Creation (MemoryStream for Web)
+
+```csharp
+// =============================================================================
+// STREAM-BASED DOCUMENT CREATION
+// =============================================================================
+// Use MemoryStream when you want to:
+// 1. Generate a document in memory before sending to a client
+// 2. Avoid touching the filesystem (ASP.NET Core scenarios)
+// 3. Return a document from an API endpoint
+//
+// CRITICAL: The stream MUST be seekable when you call .Open().
+// After WordprocessingDocument.Create(), the stream position is at the beginning.
+// If you write to the stream BEFORE creating the document, seek to 0 first.
+
+// --- CREATE IN MEMORY ---
+MemoryStream memStream = new MemoryStream();
+
+// Create directly on a stream (no file path involved)
+using (var doc = WordprocessingDocument.Create(
+    memStream,
+    WordprocessingDocumentType.Document,
+    new DocumentOptions { AutoSave = false }))
+{
+    var mainPart = doc.MainDocumentPart!;
+    mainPart.Document = new Document(new Body());
+    mainPart.Document.Body!.Append(new Paragraph(
+        new Run(new Text("Generated in memory"))));
+    mainPart.Document.Save();  // Save to the underlying stream
+}
+// At this point, memStream contains the complete DOCX
+
+// --- SEND TO HTTP RESPONSE (ASP.NET Core) ---
+// In an API controller:
+[HttpGet("download")]
+public async Task<IActionResult> DownloadDocument()
+{
+    var memStream = new MemoryStream();
+
+    using (var doc = WordprocessingDocument.Create(
+        memStream,
+        WordprocessingDocumentType.Document))
+    {
+        var mainPart = doc.MainDocumentPart!;
+        mainPart.Document = new Document(new Body());
+        mainPart.Document.Body!.Append(new Paragraph(
+            new Run(new Text("Download me!"))));
+        mainPart.Document.Save();
+    }
+
+    memStream.Position = 0;  // IMPORTANT: Reset position for reading
+    return File(memStream,
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "GeneratedDocument.docx");
+}
+
+// --- CREATE FROM TEMPLATE IN MEMORY ---
+// Useful for mail-merge style operations
+MemoryStream templateStream = new MemoryStream();
+File.WriteAllBytes("template.docx", templateStream.ToArray()); // Save a template first
+
+using var templateSource = new MemoryStream(File.ReadAllBytes("template.docx"));
+using var mergedDoc = (WordprocessingDocument)templateSource.Clone();
+
+// Clone() creates an editable copy. Don't forget to set position:
+mergedDoc.MainDocumentPart!.Document.Body!.Append(new Paragraph(
+    new Run(new Text("Added content"))));
+```
+
+### 1.4 Adding All Standard Parts
+
+```csharp
+// =============================================================================
+// ADDING ALL STANDARD DOCUMENT PARTS
+// =============================================================================
+// A complete document should have:
+// 1. MainDocumentPart (auto-created)
+// 2. StyleDefinitionsPart
+// 3. NumberingDefinitionsPart
+// 4. DocumentSettingsPart
+// 5. ThemePart (optional)
+// 6. Custom parts (headers, footers, comments, etc.)
+
+// --- COMPLETE SETUP METHOD ---
+public static void CreateCompleteDocument(string path)
+{
+    using var doc = WordprocessingDocument.Create(path, WordprocessingDocumentType.Document);
+    var mainPart = doc.MainDocumentPart!;
+
+    // Initialize document
+    mainPart.Document = new Document(new Body());
+    var body = mainPart.Document.Body!;
+
+    // Add all parts
+    AddStylesPart(mainPart);
+    AddNumberingPart(mainPart);
+    AddSettingsPart(mainPart);
+    AddThemePart(mainPart);
+    AddHeadersAndFooters(mainPart);
+
+    // Add sample content
+    AddSampleContent(body);
+
+    // Section properties MUST be last
+    body.Append(CreateSectionProperties());
+
+    mainPart.Document.Save();
+}
+
+// --- STYLES PART ---
+// See Section 2 for detailed style creation
+private static void AddStylesPart(MainDocumentPart mainPart)
+{
+    var stylesPart = mainPart.AddNewPart<StyleDefinitionsPart>();
+    var styles = new Styles();
+
+    // DocDefaults: document-wide defaults for run and paragraph properties
+    // These apply when no explicit style or direct formatting overrides them
+    styles.Append(new DocDefaults(
+        new RunPropertiesDefault(
+            new RunPropertiesBaseStyle(
+                new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
+                new FontSize { Val = "22" },      // 22 half-points = 11pt
+                new FontSizeComplexScript { Val = "22" }
+            )
+        ),
+        new ParagraphPropertiesDefault(
+            new ParagraphPropertiesBaseStyle(
+                new SpacingBetweenLines { After = "200", Line = "276", LineRule = LineSpacingRuleValues.Auto }
+            )
+        )
+    ));
+
+    // Default Normal style
+    styles.Append(new Style(
+        new StyleName { Val = "Normal" },
+        new PrimaryStyle()
+    )
+    { Type = StyleValues.Paragraph, StyleId = "Normal", Default = true });
+
+    stylesPart.Styles = styles;
+    stylesPart.Styles.Save();
+}
+
+// --- NUMBERING PART ---
+// Required for bulleted and numbered lists
+private static void AddNumberingPart(MainDocumentPart mainPart)
+{
+    var numberingPart = mainPart.AddNewPart<NumberingDefinitionsPart>();
+    var numbering = new Numbering();
+
+    // AbstractNum defines the list format (bullet, number, multilevel)
+// Creates a bullet list definition with 3 levels
+    var abstractNum = new AbstractNum { AbstractNumberId = 1 };
+
+    // Level 0: Bullet (dot)
+    abstractNum.Append(new Level(
+        new StartNumberingValue { Val = 1 },
+        new NumberingFormat { Val = NumberFormatValues.Bullet },
+        new LevelText { Val = "•" },
+        new LevelJustification { Val = LevelJustificationValues.Left },
+        new PreviousParagraphProperties(
+            new Indentation { Left = "720", Hanging = "360" })  // 720 DXA indent, 360 DXA hanging
+    )
+    { LevelIndex = 0 });
+
+    // Level 1: Dash
+    abstractNum.Append(new Level(
+        new StartNumberingValue { Val = 1 },
+        new NumberingFormat { Val = NumberFormatValues.Bullet },
+        new LevelText { Val = "–" },
+        new LevelJustification { Val = LevelJustificationValues.Left },
+        new PreviousParagraphProperties(
+            new Indentation { Left = "1440", Hanging = "360" })
+    )
+    { LevelIndex = 1 });
+
+    // Level 2: Circle
+    abstractNum.Append(new Level(
+        new StartNumberingValue { Val = 1 },
+        new NumberingFormat { Val = NumberFormatValues.Bullet },
+        new LevelText { Val = "◦" },
+        new LevelJustification { Val = LevelJustificationValues.Left },
+        new PreviousParagraphProperties(
+            new Indentation { Left = "2160", Hanging = "360" })
+    )
+    { LevelIndex = 2 });
+
+    numbering.Append(abstractNum);
+
+    // NumberingInstance links to AbstractNum and assigns a numId
+    numbering.Append(new NumberingInstance(
+        new AbstractNumId { Val = 1 }
+    )
+    { NumberID = 1 });
+
+    numberingPart.Numbering = numbering;
+    numberingPart.Numbering.Save();
+}
+
+// --- SETTINGS PART ---
+// Contains document-level settings: zoom, proof state, default tab stop, etc.
+private static void AddSettingsPart(MainDocumentPart mainPart)
+{
+    var settingsPart = mainPart.AddNewPart<DocumentSettingsPart>();
+    var settings = new Settings();
+
+    // Zoom: document zoom percentage (default 100%)
+    // Val is a percentage value (e.g., "100" = 100%)
+    settings.Append(new Zoom { Val = "100", Percent = true, SnapToGrid = true });
+
+    // ProofState: spelling/grammar check state
+    // Val combines bits: 1=grammar, 2=spelling, 3=both
+    settings.Append(new ProofState { Val = ProofingStateValues.Clean });
+
+    // Default tab stop interval in DXA
+    // Word inserts tab stops every 720 DXA (0.5 inch) by default
+    settings.Append(new DefaultTabStop { Val = 720 });
+
+    // Character spacing control: automatically adjust character spacing
+    // to maintain consistent line spacing (similar to InDesign)
+    settings.Append(new CharacterSpacingControl { Val = CharacterSpacingValues.CompressPunctuation });
+
+    // Compatibility settings: controls how Word handles certain formatting
+    // to ensure compatibility with different Word versions
+    settings.Append(new Compatibility(
+        new UseFELayout(),          // Use formatted East Asian layout
+        new UseAsianDigraphicLineBreakRules(),  // CJK line breaking rules
+        new AllowSpaceOfSameStyleInTable(),     // Table cell spacing
+        new DoNotUseIndentAsPercentageForTabStops(), // Legacy tab behavior
+        new ProportionalOtherIndents(),         // Proportional indents
+        new LayoutTableRawTextInTable()         // Raw text in layout tables
+    ));
+
+    // Revision tracking view settings
+    settings.Append(new RevisionView { DocPart = false, Formatting = true, Ink = true, Markup = true });
+
+    settingsPart.Settings = settings;
+    settingsPart.Settings.Save();
+}
+
+// --- THEME PART ---
+// Defines color scheme, font scheme, and format scheme for the document theme
+private static void AddThemePart(MainDocumentPart mainPart)
+{
+    var themePart = mainPart.AddNewPart<ThemePart>();
+    var theme = new Theme(
+        new ThemeElements(
+            // Color scheme: 10 predefined theme colors
+            new ColorScheme(
+                new Dark1Color(new Color { Val = "000000" }),
+                new Light1Color(new Color { Val = "FFFFFF" }),
+                new Dark2Color(new Color { Val = "1F497D" }),
+                new Light2Color(new Color { Val = "EEECE1" }),
+                new Accent1Color(new Color { Val = "4F81BD" }),
+                new Accent2Color(new Color { Val = "C0504D" }),
+                new Accent3Color(new Color { Val = "9BBB59" }),
+                new Accent4Color(new Color { Val = "8064A2" }),
+                new Accent5Color(new Color { Val = "4BACC6" }),
+                new Accent6Color(new Color { Val = "F79646" }),
+                new Hyperlink(new Color { Val = "0000FF" }),
+                new FollowedHyperlinkColor(new Color { Val = "800080" })
+            ),
+            // Font scheme: major (headings) and minor (body) fonts
+            new FontScheme(
+                new MajorFont { Val = "Calibri Light" },
+                new MinorFont { Val = "Calibri" }
+            ),
+            // Format scheme: default fill and effect styles
+            new FormatScheme(
+                new FillStyleList(
+                    new FillStyle { Fill = new PatternFill { PatternType = PatternValues.Solid } }
+                ),
+                new LineStyleList(
+                    new LineStyle { Val = LineValues.Single }
+                )
+            )
+        ),
+        new ThemeName { Val = "Office Theme" },
+        new ThemeNames(
+            new LanguageBasedString { Val = "en-US", LanguageId = "x-none" }
+        )
+    );
+
+    themePart.Theme = theme;
+    themePart.Theme.Save();
+}
+
+// --- HEADERS AND FOOTERS ---
+private static void AddHeadersAndFooters(MainDocumentPart mainPart)
+{
+    // Header
+    var headerPart = mainPart.AddNewPart<HeaderPart>();
+    headerPart.Header = new Header(
+        new Paragraph(
+            new ParagraphProperties(
+                new Justification { Val = JustificationValues.Right }),
+            new Run(
+                new RunProperties(
+                    new RunFonts { Ascii = "Calibri Light", HighAnsi = "Calibri Light" },
+                    new Italic(),
+                    new FontSize { Val = "20" }  // 10pt
+                ),
+                new Text("Document Header"))
+        ));
+    var headerId = mainPart.GetIdOfPart(headerPart);
+
+    // Footer
+    var footerPart = mainPart.AddNewPart<FooterPart>();
+    footerPart.Footer = new Footer(
+        new Paragraph(
+            new ParagraphProperties(
+                new Justification { Val = JustificationValues.Center }),
+            new Run(new Text("Page ") { Space = SpaceProcessingModeValues.Preserve }),
+            new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+            new Run(new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }),
+            new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+            new Run(new Text(" of ") { Space = SpaceProcessingModeValues.Preserve }),
+            new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+            new Run(new FieldCode(" NUMPAGES ") { Space = SpaceProcessingModeValues.Preserve }),
+            new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+        ));
+    var footerId = mainPart.GetIdOfPart(footerPart);
+
+    // Reference IDs in section properties
+    // (added in CreateSectionProperties below)
+}
+
+// --- SECTION PROPERTIES (COMPLETE) ---
+private static SectionProperties CreateSectionProperties()
+{
+    var sectPr = new SectionProperties();
+
+    // Header/Footer references (must come before page size/margins)
+    var mainPart = doc.MainDocumentPart; // Note: in real code, pass as parameter
+    sectPr.Append(new HeaderReference
+    {
+        Type = HeaderFooterValues.Default,
+        Id = mainPart!.GetIdOfPart(mainPart.HeaderParts.First())
+    });
+    sectPr.Append(new FooterReference
+    {
+        Type = HeaderFooterValues.Default,
+        Id = mainPart.GetIdOfPart(mainPart.FooterParts.First())
+    });
+
+    // Page size
+    sectPr.Append(new PageSize { Width = 12240u, Height = 15840u });
+
+    // Page margins
+    sectPr.Append(new PageMargin
+    {
+        Top = 1440,
+        Bottom = 1440,
+        Left = 1440u,
+        Right = 1440u,
+        Header = 720u,
+        Footer = 720u
+    });
+
+    // Page numbering format
+    sectPr.Append(new PageNumberType { Start = 1, Format = NumberFormatValues.Decimal });
+
+    // Column settings (default: 1 column)
+    sectPr.Append(new Columns { ColumnCount = 1, EqualWidth = true });
+
+    // Paper source (printer tray)
+    // sectPr.Append(new PaperSource { Tray = 1, Paper = 7 });
+
+    return sectPr;
+}
+```
+
+### 1.5 Unit Systems Reference
+
+```csharp
+// =============================================================================
+// UNIT SYSTEMS IN OPENXML
+// =============================================================================
+// Understanding units is critical. Wrong unit = wrong formatting.
+//
+// DXA (Twentieths of a DXA) - "Standard Document Unit"
+//   1 DXA = 1/20th of a point
+//   1 inch = 1440 DXA
+//   1 cm = 567 DXA (approx)
+//   Used for: margins, indents, spacing, tab stops, column widths
+//
+// Half-Points (sz) - Font Size
+//   Value is in half-points (1/2 point increments)
+//   24 = 12pt, 28 = 14pt, 36 = 18pt, 48 = 24pt
+//   Used for: FontSize.Val, FontSizeComplexScript.Val
+//
+// Points (pt) - Direct Measurements
+//   Standard typographic point (72 per inch)
+//   Used for: some line spacing values, border widths
+//
+// EMU (English Metric Units) - Drawing Objects
+//   1 inch = 914400 EMU
+//   Used for: drawing object sizes, shapes, images
+//
+// STARS (Special Twips Advanced Right-Left) - CJK Indentation
+//   Used for: FirstLineChars, HangingChars (special FirstLine/Hanging for CJK)
+//   Converts character counts to DXA based on font metrics
+//
+// LINE SPACING SPECIAL VALUES:
+//   Line = "240" with LineRule = Auto = single spacing (default)
+//   Line = "480" with LineRule = Auto = double spacing
+//   Line = "360" with LineRule = Auto = 1.5 spacing
+//   Line = "240" with LineRule = Exact = exactly 12pt
+//   Line = "288" with LineRule = AtLeast = at least 14.4pt (grows with content)
+
+// --- CONVERSION HELPER METHODS ---
+public static class OpenXmlUnits
+{
+    // DXA conversions
+    public static int InchesToDxa(double inches) => (int)(inches * 1440);
+    public static int CmToDxa(double cm) => (int)(cm * 567.0);
+    public static int PtToDxa(double pt) => (int)(pt * 20);
+    public static double DxaToInches(int dxa) => dxa / 1440.0;
+    public static double DxaToCm(int dxa) => dxa / 567.0;
+    public static double DxaToPt(int dxa) => dxa / 20.0;
+
+    // EMU conversions (for drawings)
+    public static long InchesToEmu(double inches) => (long)(inches * 914400);
+    public static long CmToEmu(double cm) => (long)(cm * 360000);
+    public static double EmuToInches(long emu) => emu / 914400.0;
+
+    // Half-point conversions (font sizes)
+    public static int PtToHalfPt(double pt) => (int)(pt * 2);
+    public static int FontSizeToSz(double ptSize) => (int)(ptSize * 2);
+    public static double SzToPt(int sz) => sz / 2.0;
+
+    // Line spacing
+    public static int SingleSpacing => 240;
+    public static int DoubleSpacing => 480;
+    public static int OneAndHalfSpacing => 360;
+    public static int LineSpacingPt(double pt) => (int)(pt * 20);  // Convert to DXA
+}
+
+// Example usage:
+var marginInInches = OpenXmlUnits.DxaToInches(1440);  // 1.0
+var fontSizeInSz = OpenXmlUnits.FontSizeToSz(12.0);    // 24
+var indentInDxa = OpenXmlUnits.InchesToDxa(0.5);       // 720
+```
+
+---
+
+## 2. Style System Deep Dive
+
+### 2.1 Style Types and Structure
+
+```csharp
+// =============================================================================
+// STYLE TYPES OVERVIEW
+// =============================================================================
+// OpenXML defines 4 style types (StyleValues enum):
+// 1. Paragraph (w:p) - controls paragraph-level formatting
+// 2. Character (w:r) - controls inline/run-level formatting
+// 3. Table (w:tbl) - controls table-level formatting
+// 4. Numbering (w:num) - NOT a style type, but a separate numbering system
+//
+// Key insight: A style can be BOTH paragraph and character style (linked style).
+// The "linkedStyle" element links a paragraph style to a character style.
+
+// --- MINIMAL PARAGRAPH STYLE ---
+// A paragraph style controls: pPr (paragraph properties) and optionally rPr
+Style minimalParaStyle = new Style(
+    new StyleName { Val = "MyParagraphStyle" },
+    new PrimaryStyle()     // Primary styles appear in Style gallery
+)
+{
+    Type = StyleValues.Paragraph,
+    StyleId = "MyParagraphStyle"
+};
+
+// --- MINIMAL CHARACTER STYLE ---
+// A character style controls: rPr only (no pPr)
+Style minimalCharStyle = new Style(
+    new StyleName { Val = "MyCharacterStyle" },
+    new PrimaryStyle()
+)
+{
+    Type = StyleValues.Character,
+    StyleId = "MyCharacterStyle"
+};
+
+// Character style with run properties (fonts, size, bold, etc.)
+Style charStyleWithFormatting = new Style(
+    new StyleName { Val = "Emphasis" },
+    new PrimaryStyle(),
+    new StyleRunProperties(
+        new Italic(),
+        new Color { Val = "C00000" }  // Dark red
+    )
+)
+{
+    Type = StyleValues.Character,
+    StyleId = "Emphasis"
+};
+
+// --- LINKED STYLE (Paragraph + Character) ---
+// A linked style combines both: it can be applied to a paragraph OR a run.
+// This is how Word's "Heading 1" works — applies to paragraphs, but you can
+// also select text within a heading and apply the same style as character formatting.
+Style linkedStyle = new Style(
+    new StyleName { Val = "LinkedStyle" },
+    new PrimaryStyle(),
+    new LinkedStyle { Val = "LinkedStyleChar" },  // Links to character style
+    new StyleParagraphProperties(
+        new SpacingBetweenLines { After = "120" }
+    ),
+    new StyleRunProperties(
+        new Bold(),
+        new FontSize { Val = "24" }
+    )
+)
+{
+    Type = StyleValues.Paragraph,
+    StyleId = "LinkedStyle"
+};
+
+// Corresponding character style (normally same name + "Char" suffix by convention)
+Style linkedStyleChar = new Style(
+    new StyleName { Val = "LinkedStyle Char" },  // Word convention: adds " Char"
+    new PrimaryStyle(),
+    new StyleRunProperties(
+        new Bold(),
+        new FontSize { Val = "24" }
+    )
+)
+{
+    Type = StyleValues.Character,
+    StyleId = "LinkedStyleChar"
+};
+
+// --- TABLE STYLE ---
+Style tableStyle = new Style(
+    new StyleName { Val = "MyTableStyle" },
+    new PrimaryStyle(),
+    new StyleTableProperties(
+        new TableWidth { Width = "5000", Type = TableWidthUnitValues.Pct },  // 50% width
+        new TableBorders(
+            new TopBorder { Val = BorderValues.Single, Size = 4, Color = "000000" },
+            new BottomBorder { Val = BorderValues.Single, Size = 4, Color = "000000" },
+            new LeftBorder { Val = BorderValues.Single, Size = 4, Color = "000000" },
+            new RightBorder { Val = BorderValues.Single, Size = 4, Color = "000000" },
+            new InsideHorizontalBorder { Val = BorderValues.Single, Size = 2, Color = "CCCCCC" },
+            new InsideVerticalBorder { Val = BorderValues.Single, Size = 2, Color = "CCCCCC" }
+        ),
+        new TableCellMarginDefault(
+            new TopMargin { Width = "0", Type = TableWidthUnitValues.DXA },
+            new StartMargin { Width = "108", Type = TableWidthUnitValues.DXA },
+            new BottomMargin { Width = "0", Type = TableWidthUnitValues.DXA },
+            new EndMargin { Width = "108", Type = TableWidthUnitValues.DXA }
+        )
+    )
+)
+{
+    Type = StyleValues.Table,
+    StyleId = "MyTableStyle"
+};
+```
+
+### 2.2 DocDefaults and Document-Wide Defaults
+
+```csharp
+// =============================================================================
+// DOCDEFAULTS: DOCUMENT-WIDE DEFAULTS
+// =============================================================================
+// DocDefaults lives inside Styles and provides fallback values when:
+// 1. No explicit style is applied
+// 2. No direct formatting is applied
+// It contains RunPropertiesDefault and/or ParagraphPropertiesDefault.
+//
+// CRITICAL: DocDefaults applies to the entire document. Any explicit style
+// or direct formatting will override it.
+
+// --- COMPLETE DOCDEFAULTS SETUP ---
+var docDefaults = new DocDefaults(
+    // Run properties defaults: default font, size, language for all runs
+    new RunPropertiesDefault(
+        new RunPropertiesBaseStyle(
+            // RunFonts: which font to use for each script
+            // Word will fall back through these: ASCII -> HighAnsi -> EastAsia -> ComplexScript
+            // Always specify at minimum Ascii and HighAnsi
+            new RunFonts
+            {
+                Ascii = "Calibri",           // Western/Latin font (primary)
+                HighAnsi = "Calibri",        // Latin characters (often same as Ascii)
+                EastAsia = "SimSun",         // East Asian font (CJK)
+                ComplexScript = "Arial",     // Complex scripts (Arabic, Hebrew, Thai)
+                ASCIITheme = ThemeFontValues.Minor,
+                HighAnsiTheme = ThemeFontValues.Minor,
+                EastAsiaTheme = ThemeFontValues.Minor,
+                ComplexScriptTheme = ThemeFontValues.Minor
+            },
+            // FontSize: in HALF-POINTS (24 = 12pt, 22 = 11pt, 20 = 10pt)
+            new FontSize { Val = "22" },         // 11pt for body
+            new FontSizeComplexScript { Val = "22" },
+            // Languages: required for proper hyphenation and spell checking
+            new Languages { Val = "en-US" },     // Default language
+            new Languages { EastAsia = "zh-CN", Val = "en-US" }  // Can set multiple
+        )
+    ),
+    // Paragraph properties defaults: default spacing, etc.
+    new ParagraphPropertiesDefault(
+        new ParagraphPropertiesBaseStyle(
+            // SpacingBetweenLines: default paragraph spacing
+            // After = "200" = 200 DXA = 10pt after each paragraph
+            new SpacingBetweenLines
+            {
+                After = "200",
+                Line = "276",
+                LineRule = LineSpacingRuleValues.Auto  // Auto = 1.15x line height
+            }
+        )
+    )
+);
+
+// --- LAYOUT LUNCTIONS (LATENT STYLES) ---
+// Latent styles are hidden styles that exist in Word but aren't in styles.xml.
+// They provide fast-access defaults for formatting (e.g., Normal, Heading 1-6, etc.)
+// when the user hasn't explicitly customized them.
+//
+// DocDefaults can define LatentStyleCountOverride to adjust count,
+// but true latent styles are controlled by Normal.dotm (Word's global template).
+Styles CreateStylesWithDocDefaults()
+{
+    var styles = new Styles();
+
+    // DocDefaults with run and paragraph properties defaults
+    styles.Append(new DocDefaults(
+        new RunPropertiesDefault(
+            new RunPropertiesBaseStyle(
+                new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
+                new FontSize { Val = "22" },
+                new Languages { Val = "en-US" }
+            )
+        ),
+        new ParagraphPropertiesDefault(
+            new ParagraphPropertiesBaseStyle(
+                new SpacingBetweenLines { After = "160", Line = "276", LineRule = LineSpacingRuleValues.Auto }
+            )
+        )
+    ));
+
+    // LatentStyles: override defaults for built-in latent styles
+    // These control Word's "fast-styles" like Heading 1-6 before they're customized
+    styles.Append(new LatentStyles(
+        new Count { Val = 159 },                    // Total latent style count
+        new FirstLineChars { Val = 352 },          // Default first line char count
+        new HorizontalOverflow { Val = HorizontalOverflowValues.Overflow },
+        new VerticalOverflow { Val = VerticalOverflowValues.Overflow },
+        new KoreanSpaceAdjust { Val = true },
+        // Each LatentStyleException overrides ONE attribute of ONE latent style
+        // StyleID = the built-in style name (e.g., "Normal", "heading 1")
+        // Attribute: what to change (bold, italic, font, color, etc.)
+        // The defaults for built-in headings: font=Calibri, size=24, bold
+        new LatentStyleException(
+            new Primary烙,
+            new StyleName { Val = "Normal" },
+            new UIPriority { Val = 1 },
+            new PrimaryZone(),
+            new QuickStyle()
+        ),
+        new LatentStyleException(
+            new Primary烙,
+            new StyleName { Val = "heading 1" },
+            new UIPriority { Val = 9 },
+            new PrimaryZone(),
+            new QuickStyle(),
+            new Bold(),
+            new BoldComplexScript(),
+            new FontSize { Val = "48" },  // 24pt = 48 half-pts
+            new FontSizeComplexScript { Val = "48" }
+        )
+    ));
+
+    return styles;
+}
+```
+
+### 2.3 Complete Heading Styles Hierarchy
+
+```csharp
+// =============================================================================
+// HEADING STYLES WITH PROPER INHERITANCE CHAIN
+// =============================================================================
+// Word's built-in heading system uses style inheritance:
+// Normal (base) -> Heading1 -> Heading2 -> Heading3 -> Heading4 -> Heading5 -> Heading6
+//
+// Why this matters:
+// - Each heading INHERITS from its parent (basedOn)
+// - Define common properties in Normal, override in each heading
+// - Change body font once in Normal, all headings inherit it
+// - Heading-specific properties override as needed
+
+// --- HEADING STYLE FACTORY ---
+public static Style CreateHeadingStyle(int level, FontConfig fonts)
+{
+    // Validate level (1-9 are valid, 1-6 are standard)
+    if (level < 1 || level > 9)
+        throw new ArgumentOutOfRangeException(nameof(level));
+
+    double[] headingSizes = [26.0, 20.0, 16.0, 14.0, 12.0, 11.0, 11.0, 11.0, 11.0];
+    string[] outlineLevels = ["0", "1", "2", "3", "4", "5", "6", "7", "8"};
+
+    var style = new Style(
+        new StyleName { Val = $"heading {level}" },  // Display name
+        new BasedOn { Val = level == 1 ? "Normal" : $"Heading{level - 1}" },  // Parent style
+        new NextParagraphStyle { Val = "Normal" },   // After heading -> Normal
+        new PrimaryStyle(),                          // Show in Styles gallery
+        new UIPriority { Val = 9 - level },         // Priority in gallery (H1 = 8, H2 = 7, etc.)
+        new QuickStyle(),                           // Appears in Quick Styles gallery
+        // Paragraph properties: spacing, keep options, outline level
+        new StyleParagraphProperties(
+            new KeepNext(),                         // Keep heading with next paragraph
+            new KeepLines(),                        // Keep all lines of heading together
+            new SpacingBetweenLines                 // Spacing before/after
+            {
+                Before = level == 1 ? "480" : "240",  // H1 = 240pt before, others = 120pt
+                After = "120"
+            },
+            new OutlineLevel { Val = level - 1 }   // 0-indexed for H1=0, H2=1, etc.
+        ),
+        // Run properties: font, size, bold
+        new StyleRunProperties(
+            new RunFonts
+            {
+                Ascii = fonts.HeadingFont,
+                HighAnsi = fonts.HeadingFont,
+                EastAsia = "SimHei"  // Bold heading font for CJK
+            },
+            new FontSize { Val = UnitConverter.FontSizeToSz(headingSizes[level - 1]) },
+            new FontSizeComplexScript { Val = UnitConverter.FontSizeToSz(headingSizes[level - 1]) },
+            new Bold(),
+            new BoldComplexScript()
+        )
+    )
+    {
+        Type = StyleValues.Paragraph,
+        StyleId = $"Heading{level}"
+    };
+
+    return style;
+}
+
+// --- ADD ALL HEADING STYLES TO STYLES COLLECTION ---
+public static void AddHeadingStyles(Styles styles, FontConfig fonts)
+{
+    for (int i = 1; i <= 6; i++)
+    {
+        styles.Append(CreateHeadingStyle(i, fonts));
+    }
+
+    // Also add Heading 7-9 (valid in Word, less commonly used)
+    for (int i = 7; i <= 9; i++)
+    {
+        styles.Append(CreateHeadingStyle(i, fonts));
+    }
+}
+
+// --- HEADING STYLES INHERITANCE VISUALIZATION ---
+// When you apply "Heading2" (basedOn="Heading1"):
+//
+// Normal style:
+//   - Font: Calibri 11pt
+//   - Spacing: 0 before, 200 after
+//   - No bold
+//
+// Heading1 (basedOn="Normal"):
+//   - Inherits: Calibri 11pt
+//   - Overrides: Calibri Light 26pt, Bold, Spacing 480 before/120 after
+//   - Adds: KeepNext, KeepLines, OutlineLevel=0
+//
+// Heading2 (basedOn="Heading1"):
+//   - Inherits: Calibri Light 26pt, Bold, KeepNext, KeepLines
+//   - Overrides: 20pt
+//   - Inherits: OutlineLevel=1
+//
+// Effective result: Heading2 = Calibri Light 20pt Bold, KeepNext+KeepLines, 480/120 spacing, OL=1
+```
+
+### 2.4 Style Inheritance Chain Resolution
+
+```csharp
+// =============================================================================
+// STYLE INHERITANCE RESOLUTION
+// =============================================================================
+// OpenXML styles resolve properties through the basedOn chain at RENDER TIME.
+// The document.xml stores only the styleId, not the resolved properties.
+// Word (or this library) walks the chain at load/display time.
+//
+// Example: Applying "Heading2" to a paragraph
+//
+// 1. Start with Heading2 style definition
+// 2. Walk basedOn chain: Heading2 -> Heading1 -> Normal -> (null)
+// 3. Collect properties in reverse order (most generic first):
+//    a. Normal: Ascii=Calibri, sz=22, no bold
+//    b. Heading1: Ascii=Calibri Light, sz=48, bold (override Calibri, sz, bold)
+//    c. Heading2: sz=40 (override sz only)
+// 4. Final resolved style: Ascii=Calibri Light, sz=40, bold (bold from H1)
+//
+// IMPORTANT: Style override is COMPLETE for each element type:
+// - If Normal has rPr with Fonts, and Heading1 has pPr only,
+//   Heading1 still inherits Normal's rPr fully.
+// - StyleRunProperties (rPr) and StyleParagraphProperties (pPr) are separate.
+
+// --- RESOLVING STYLE PROPERTIES MANUALLY ---
+// For debugging or custom rendering, you may need to resolve style chains
+public static class StyleResolver
+{
+    public record ResolvedStyle(
+        StyleName? Name,
+        RunProperties? RunProps,
+        ParagraphProperties? ParaProps,
+        string? BasedOn,
+        string Type);
+
+    public static ResolvedStyle Resolve(Styles styles, string styleId)
+    {
+        var styleMap = styles.Elements<Style>().ToDictionary(s => s.StyleId?.Value ?? "");
+
+        var resolvedRpr = new List<RunProperties>();
+        var resolvedPpr = new List<ParagraphProperties>();
+        string? currentId = styleId;
+        string? name = null;
+        string type = "paragraph";
+
+        // Walk the chain
+        while (currentId != null && styleMap.TryGetValue(currentId, out var style))
+        {
+            name ??= style.Name?.Val?.Value;
+            type = style.Type?.Value?.ToString() ?? "paragraph";
+
+            // Collect rPr (style-level run properties)
+            var rpr = style.StyleRunProperties;
+            if (rpr != null) resolvedRpr.Add(rpr);
+
+            // Collect pPr (style-level paragraph properties)
+            var ppr = style.StyleParagraphProperties;
+            if (ppr != null) resolvedPpr.Add(ppr);
+
+            // Move to parent
+            currentId = style.BasedOn?.Val?.Value;
+        }
+
+        // Merge in reverse order (base styles first, derived last)
+        // This is a simplified merge — real Word merging is more complex
+        var mergedRpr = MergeRunProperties(resolvedRpr);
+        var mergedPpr = MergeParagraphProperties(resolvedPpr);
+
+        return new ResolvedStyle(
+            name != null ? new StyleName { Val = name } : null,
+            mergedRpr,
+            mergedPpr,
+            styleId,
+            type);
+    }
+
+    private static RunProperties MergeRunProperties(List<RunProperties> chain)
+    {
+        var merged = new RunProperties();
+        // In real implementation, copy each child element from chain[0] first,
+        // then chain[1], etc., overriding as you go
+        foreach (var rpr in chain)
+        {
+            foreach (var child in rpr.ChildElements)
+            {
+                // Skip duplicates, keep derived class's version
+                merged.RemoveAll(child.GetType());
+                merged.Append(child.CloneNode(true));
+            }
+        }
+        return merged;
+    }
+
+    private static ParagraphProperties MergeParagraphProperties(List<ParagraphProperties> chain)
+    {
+        var merged = new ParagraphProperties();
+        foreach (var ppr in chain)
+        {
+            foreach (var child in ppr.ChildElements)
+            {
+                merged.RemoveAll(child.GetType());
+                merged.Append(child.CloneNode(true));
+            }
+        }
+        return merged;
+    }
+}
+
+// --- STYLE ID VS STYLE NAME ---
+// StyleId: the machine-readable identifier (used in w:pStyle val="Heading1")
+// StyleName.Val: the display name shown in Word UI ("Heading 1")
+//
+// Word allows StyleId="Heading1" with StyleName.Val="Custom Heading One"
+// The Id must be unique within the document; the Name can duplicate others.
+//
+// Built-in styles use specific Ids:
+// "Normal", "Heading1"-"Heading9", "Title", "Subtitle", "Quote", "Quote1",
+// "IntenseQuote", "SubtleReference", "Bibliography", "TOC1"-"TOC9", etc.
+```
+
+### 2.5 Complete Style Definitions Example
+
+```csharp
+// =============================================================================
+// COMPLETE STYLE DEFINITIONS FOR A BUSINESS DOCUMENT
+// =============================================================================
+// This creates a complete styles.xml with all recommended styles for a
+// professional document: Normal, Title, Subtitle, Headings 1-6, Quote,
+// IntenseQuote, and linked character styles.
+
+public static Styles CreateBusinessDocumentStyles()
+{
+    var styles = new Styles();
+
+    // --- DOCDEFAULTS ---
+    styles.Append(new DocDefaults(
+        new RunPropertiesDefault(
+            new RunPropertiesBaseStyle(
+                new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
+                new FontSize { Val = "22" },
+                new FontSizeComplexScript { Val = "22" },
+                new Languages { Val = "en-US" }
+            )
+        ),
+        new ParagraphPropertiesDefault(
+            new ParagraphPropertiesBaseStyle(
+                new SpacingBetweenLines { After = "200", Line = "276", LineRule = LineSpacingRuleValues.Auto }
+            )
+        )
+    ));
+
+    // --- NORMAL STYLE (BASE FOR ALL) ---
+    styles.Append(new Style(
+        new StyleName { Val = "Normal" },
+        new PrimaryStyle(),
+        new UIPriority { Val = 10 },
+        new Primary烙,
+        new StyleRunProperties(
+            new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
+            new FontSize { Val = "22" },
+            new FontSizeComplexScript { Val = "22" }
+        )
+    )
+    { Type = StyleValues.Paragraph, StyleId = "Normal", Default = true });
+
+    // --- TITLE STYLE ---
+    styles.Append(new Style(
+        new StyleName { Val = "Title" },
+        new BasedOn { Val = "Normal" },
+        new NextParagraphStyle { Val = "Normal" },
+        new PrimaryStyle(),
+        new UIPriority { Val = 1 },
+        new QuickStyle(),
+        new StyleParagraphProperties(
+            new Justification { Val = JustificationValues.Center },
+            new SpacingBetweenLines { After = "300", Line = "240", LineRule = LineSpacingRuleValues.Auto },
+            new KeepNext(),
+            new KeepLines()
+        ),
+        new StyleRunProperties(
+            new RunFonts { Ascii = "Calibri Light", HighAnsi = "Calibri Light" },
+            new FontSize { Val = "56" },      // 28pt
+            new FontSizeComplexScript { Val = "56" },
+            new Bold(),
+            new BoldComplexScript(),
+            new Color { Val = "1F497D" }     // Dark blue
+        )
+    )
+    { Type = StyleValues.Paragraph, StyleId = "Title" });
+
+    // --- SUBTITLE STYLE ---
+    styles.Append(new Style(
+        new StyleName { Val = "Subtitle" },
+        new BasedOn { Val = "Normal" },
+        new NextParagraphStyle { Val = "Normal" },
+        new PrimaryStyle(),
+        new UIPriority { Val = 2 },
+        new QuickStyle(),
+        new StyleParagraphProperties(
+            new Justification { Val = JustificationValues.Center },
+            new SpacingBetweenLines { After = "200" },
+            new KeepNext(),
+            new KeepLines()
+        ),
+        new StyleRunProperties(
+            new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
+            new FontSize { Val = "26" },      // 13pt
+            new Color { Val = "5A5A5A" }     // Gray
+        )
+    )
+    { Type = StyleValues.Paragraph, StyleId = "Subtitle" });
+
+    // --- HEADING 1-6 STYLES ---
+    AddHeadingStyles(styles);
+
+    // --- QUOTE STYLES ---
+    // Quote (indented, italic)
+    styles.Append(new Style(
+        new StyleName { Val = "Quote" },
+        new BasedOn { Val = "Normal" },
+        new NextParagraphStyle { Val = "Normal" },
+        new PrimaryStyle(),
+        new UIPriority { Val = 29 },
+        new QuickStyle(),
+        new StyleParagraphProperties(
+            new Justification { Val = JustificationValues.Both },
+            new Indentation { Left = "720", Right = "720" },
+            new SpacingBetweenLines { After = "160" },
+            new KeepNext(),
+            new KeepLines()
+        ),
+        new StyleRunProperties(
+            new Italic(),
+            new ItalicComplexScript()
+        )
+    )
+    { Type = StyleValues.Paragraph, StyleId = "Quote" });
+
+    // Intense Quote (bold, larger indent)
+    styles.Append(new Style(
+        new StyleName { Val = "Intense Quote" },
+        new BasedOn { Val = "Normal" },
+        new NextParagraphStyle { Val = "Normal" },
+        new PrimaryStyle(),
+        new UIPriority { Val = 30 },
+        new QuickStyle(),
+        new StyleParagraphProperties(
+            new Justification { Val = JustificationValues.Center },
+            new Indentation { Left = "1440", Right = "1440" },
+            new SpacingBetweenLines { After = "160" },
+            new KeepNext(),
+            new KeepLines(),
+            new ParagraphBorders(
+                new LeftBorder { Val = BorderValues.Single, Size = 24, Color = "4472C4", Space = 4 }
+            )
+        ),
+        new StyleRunProperties(
+            new Bold(),
+            new Color { Val = "2F5496" }
+        )
+    )
+    { Type = StyleValues.Paragraph, StyleId = "IntenseQuote" });
+
+    // --- LINKED CHARACTER STYLES ---
+    // "Emphasis" linked character style (used for <Ctrl+E> in Word)
+    styles.Append(new Style(
+        new StyleName { Val = "Emphasis" },
+        new PrimaryStyle(),
+        new StyleRunProperties(
+            new Italic()
+        )
+    )
+    { Type = StyleValues.Character, StyleId = "Emphasis", Default = true });
+
+    // "Strong" linked character style
+    styles.Append(new Style(
+        new StyleName { Val = "Strong" },
+        new PrimaryStyle(),
+        new StyleRunProperties(
+            new Bold()
+        )
+    )
+    { Type = StyleValues.Character, StyleId = "Strong", Default = true });
+
+    // --- TOC STYLES (for Table of Contents) ---
+    // TOC1-TOC9 are used by Word's TOC field for different heading levels
+    styles.Append(new Style(
+        new StyleName { Val = "TOC 1" },
+        new BasedOn { Val = "Normal" },
+        new Primary烙,
+        new StyleParagraphProperties(
+            new SpacingBetweenLines { After = "0" }
+        )
+    )
+    { Type = StyleValues.Paragraph, StyleId = "TOC1" });
+
+    styles.Append(new Style(
+        new StyleName { Val = "TOC 2" },
+        new BasedOn { Val = "Normal" },
+        new Primary烙,
+        new StyleParagraphProperties(
+            new Indentation { Left = "220" },
+            new SpacingBetweenLines { After = "0" }
+        )
+    )
+    { Type = StyleValues.Paragraph, StyleId = "TOC2" });
+
+    styles.Append(new Style(
+        new StyleName { Val = "TOC 3" },
+        new BasedOn { Val = "Normal" },
+        new Primary烙,
+        new StyleParagraphProperties(
+            new Indentation { Left = "440" },
+            new SpacingBetweenLines { After = "0" }
+        )
+    )
+    { Type = StyleValues.Paragraph, StyleId = "TOC3" });
+
+    return styles;
+}
+
+// --- ADDING STYLES TO A DOCUMENT ---
+public static void AddStylesToDocument(WordprocessingDocument doc, Styles styles)
+{
+    var mainPart = doc.MainDocumentPart!;
+
+    // Get existing or create new styles part
+    var stylesPart = mainPart.StyleDefinitionsPart;
+    if (stylesPart == null)
+    {
+        stylesPart = mainPart.AddNewPart<StyleDefinitionsPart>();
+        stylesPart.Styles = styles;
+    }
+    else
+    {
+        // Clear and replace existing styles
+        stylesPart.Styles?.RemoveAllChildren();
+        stylesPart.Styles = styles;
+    }
+    stylesPart.Styles.Save();
+}
+```
+
+### 2.6 Importing Styles from Another Document
+
+```csharp
+// =============================================================================
+// IMPORTING STYLES FROM ANOTHER DOCUMENT
+// =============================================================================
+// Word's Organizer functionality allows copying styles between documents.
+// This is useful for templates, branding, or style normalization.
+
+public static class StyleImporter
+{
+    /// <summary>
+    /// Imports styles from a source document into a target document.
+    /// Can selectively import by type or name.
+    /// </summary>
+    public static void ImportStyles(
+        WordprocessingDocument targetDoc,
+        string sourcePath,
+        bool overwriteExisting = false,
+        Func<Style, bool>? filter = null)
+    {
+        // Open source as read-only
+        using var sourceDoc = WordprocessingDocument.Open(sourcePath, isEditable: false);
+        var sourceStylesPart = sourceDoc.MainDocumentPart?.StyleDefinitionsPart;
+        if (sourceStylesPart?.Styles == null) return;
+
+        var targetStylesPart = targetDoc.MainDocumentPart!.StyleDefinitionsPart;
+        if (targetStylesPart == null)
+        {
+            targetStylesPart = targetDoc.MainDocumentPart.AddNewPart<StyleDefinitionsPart>();
+            targetStylesPart.Styles = new Styles();
+        }
+
+        var targetStyles = targetStylesPart.Styles!;
+        var existingIds = targetStyles.Elements<Style>()
+            .Select(s => s.StyleId?.Value ?? "")
+            .ToHashSet();
+
+        foreach (var sourceStyle in sourceStylesPart.Styles.Elements<Style>())
+        {
+            // Apply filter if provided
+            if (filter != null && !filter(sourceStyle))
+                continue;
+
+            var styleId = sourceStyle.StyleId?.Value ?? "";
+            if (string.IsNullOrEmpty(styleId)) continue;
+
+            // Skip if exists and not overwriting
+            if (existingIds.Contains(styleId) && !overwriteExisting)
+                continue;
+
+            // Clone the style (deep copy to avoid shared part issues)
+            var clonedStyle = (Style)sourceStyle.CloneNode(true);
+
+            // If overwriting, remove existing first
+            if (existingIds.Contains(styleId))
+            {
+                var existing = targetStyles.Elements<Style>()
+                    .FirstOrDefault(s => s.StyleId?.Value == styleId);
+                existing?.Remove();
+            }
+
+            targetStyles.Append(clonedStyle);
+            existingIds.Add(styleId);
+        }
+
+        targetStylesPart.Styles.Save();
+    }
+
+    /// <summary>
+    /// Imports only heading styles from source.
+    /// </summary>
+    public static void ImportHeadingStyles(WordprocessingDocument targetDoc, string sourcePath)
+    {
+        ImportStyles(
+            targetDoc,
+            sourcePath,
+            overwriteExisting: true,
+            filter: style => style.Name?.Val?.Value?.StartsWith("heading") == true ||
+                            style.Name?.Val?.Value?.StartsWith("Heading") == true);
+    }
+
+    /// <summary>
+    /// Imports all paragraph styles (not character, table, or numbering).
+    /// </summary>
+    public static void ImportParagraphStyles(WordprocessingDocument targetDoc, string sourcePath)
+    {
+        ImportStyles(
+            targetDoc,
+            sourcePath,
+            overwriteExisting: false,
+            filter: style => style.Type?.Value == StyleValues.Paragraph);
+    }
+}
+```
+
+---
+
+## 3. Character Formatting (RunProperties) — EXHAUSTIVE
+
+```csharp
+// =============================================================================
+// RUN PROPERTIES (CHARACTER FORMATTING) — COMPLETE REFERENCE
+// =============================================================================
+// RunProperties (w:rPr) controls inline text formatting. It can appear in:
+// 1. Style definitions (w:style/w:rPr) — applies to all text using that style
+// 2. Direct formatting in runs (w:r/w:rPr) — overrides style for specific text
+//
+// CHILD ELEMENT ORDER (w:rPr): MUST be in this order per OpenXML schema:
+// rStyle, rFonts, b, bCs, i, iCs, caps, smallCaps, strike, dstrike, vanish,
+// w:webHidden, color, sz, szCs, highlight, rendition/sz, u, vertAlign, shd,
+// baseTextStyle, eastAsianLayout, ligatures, bg, kern, spc, indent, snapToGrid,
+// glyphs, activeXfrm, legacy, specStyle, shadow, charsetConvert, iFormat,
+// w:templ
+
+// --- MINIMAL RUN WITH FORMATTING ---
+// Any run can contain RunProperties to control appearance
+Paragraph minimalFormattedPara = new Paragraph(
+    new Run(
+        new RunProperties(
+            new Bold(),
+            new FontSize { Val = "28" }  // 14pt (28 half-pts)
+        ),
+        new Text("Bold 14pt text")
+    )
+);
+
+// ===========================================================================
+// 3.1 RUNFONTS (Ascii, HighAnsi, EastAsia, ComplexScript)
+// ===========================================================================
+// RunFonts has 4 font "slots" for different scripts. Word uses fallback:
+// ASCII -> HighAnsi -> EastAsia -> ComplexScript
+// IMPORTANT: Always set at least Ascii and HighAnsi (they're often the same).
+
+// Basic font specification
+RunProperties fonts1 = new RunProperties(
+    new RunFonts
+    {
+        Ascii = "Calibri",           // Western European characters (primary)
+        HighAnsi = "Calibri",        // Same as ASCII for Western docs
+        EastAsia = "SimSun",         // Simplified Chinese / East Asian
+        ComplexScript = "Arial"     // Arabic, Hebrew, Thai, Vietnamese
+    }
+);
+
+// Using theme fonts (references to theme definitions)
+RunProperties themeFonts = new RunProperties(
+    new RunFonts
+    {
+        ASCIITheme = ThemeFontValues.Minor,     // Minor font from theme (body)
+        HighAnsiTheme = ThemeFontValues.Minor,
+        EastAsiaTheme = ThemeFontValues.Major, // Major font from theme (headings)
+        ComplexScriptTheme = ThemeFontValues.Minor,
+        // When using theme, you can still override specific slots
+        Ascii = "Calibri", HighAnsi = "Calibri"  // Override minor with explicit font
+    }
+);
+
+// Complex script fonts (Arabic example)
+RunProperties arabicFonts = new RunProperties(
+    new RunFonts
+    {
+        ComplexScript = "Traditional Arabic",
+        // Word automatically handles Arabic shaping with complex script fonts
+    }
+);
+
+// East Asian with specific fallback
+RunProperties cjkFonts = new RunProperties(
+    new RunFonts
+    {
+        Ascii = "Microsoft YaHei",    // Western: Microsoft YaHei for Chinese
+        HighAnsi = "Microsoft YaHei",
+        EastAsia = "Microsoft YaHei", // East Asian: same font handles both
+        ComplexScript = "Microsoft YaHei"
+    }
+);
+
+// Font substitution hints (rarely needed, for special cases)
+RunProperties hintFonts = new RunProperties(
+    new RunFonts
+    {
+        Ascii = "Times New Roman",
+        HighAnsi = "Times New Roman",
+        Hint = FontStringsValues.EastAsia  // Hint to Word: treat as East Asian font
+    }
+);
+
+// ===========================================================================
+// 3.2 FONTSIZE (sz, szCs) — HALF-POINTS!
+// ===========================================================================
+// CRITICAL: w:sz stores HALF-POINTS. 24 = 12pt, 48 = 24pt.
+// szCs = complex script size (for Arabic, Hebrew, etc.)
+
+// Common font sizes
+RunProperties fontSize12pt = new RunProperties(
+    new FontSize { Val = "24" },              // 12pt = 24 half-pts
+    new FontSizeComplexScript { Val = "24" }
+);
+
+RunProperties fontSize14pt = new RunProperties(
+    new FontSize { Val = "28" },              // 14pt
+    new FontSizeComplexScript { Val = "28" }
+);
+
+RunProperties fontSize18pt = new RunProperties(
+    new FontSize { Val = "36" },              // 18pt
+    new FontSizeComplexScript { Val = "36" }
+);
+
+RunProperties fontSize24pt = new RunProperties(
+    new FontSize { Val = "48" },              // 24pt
+    new FontSizeComplexScript { Val = "48" }
+);
+
+// FontSize from double (helper)
+double targetPt = 11.0;
+int halfPts = (int)(targetPt * 2);  // 22 for 11pt
+RunProperties dynamicFontSize = new RunProperties(
+    new FontSize { Val = halfPts.ToString() },
+    new FontSizeComplexScript { Val = halfPts.ToString() }
+);
+
+// Legacy font size (some documents use csSize instead)
+// csSize = complex script size only
+
+// ===========================================================================
+// 3.3 BOLD (b, bCs, b, bCs)
+// ===========================================================================
+// b = bold for ASCII/Latin
+// bCs = bold for complex script
+// Both should usually be set together
+
+RunProperties bold = new RunProperties(
+    new Bold(),
+    new BoldComplexScript()  // Always include both for consistent rendering
+);
+
+// Bold with state control (on/off)
+RunProperties unbold = new RunProperties(
+    new Bold { Val = OnOffValueValues.Off }  // Explicitly turn off bold
+);
+
+// Conditional bold (for complex scripts)
+// b={} with val=Off actually means "not bold" even if parent style says bold
+// This is how you "unbold" in a bold context
+
+// ===========================================================================
+// 3.4 ITALIC (i, iCs)
+// ===========================================================================
+RunProperties italic = new RunProperties(
+    new Italic(),
+    new ItalicComplexScript()
+);
+
+RunProperties unitalic = new RunProperties(
+    new Italic { Val = OnOffValueValues.Off }
+);
+
+// Word's "Italic" is the style. ComplexScript italic handles Arabic calligraphy etc.
+
+// ===========================================================================
+// 3.5 UNDERLINE (u)
+// ===========================================================================
+// UnderlineValues enum has MANY options:
+// Single, Double, Thick, Wave, Dash, Dotted, DashDot, DashDotDot,
+// SingleAccounting, DoubleAccounting, TriWave, Nasized, DotDash, DotDotDash,
+// LongDash, ThickDash, LongDashDot, ThickLongDash, ThickDashDot, ThickDashDotDot
+
+// Single underline (most common)
+RunProperties underlineSingle = new RunProperties(
+    new Underline { Val = UnderlineValues.Single }
+);
+
+// Double underline (often for edits/changes)
+RunProperties underlineDouble = new RunProperties(
+    new Underline { Val = UnderlineValues.Double }
+);
+
+// Thick single underline
+RunProperties underlineThick = new RunProperties(
+    new Underline { Val = UnderlineValues.Thick }
+);
+
+// Wave underline (often used for spelling errors in red)
+RunProperties underlineWave = new RunProperties(
+    new Underline { Val = UnderlineValues.Wave }
+);
+
+// Dotted underline
+RunProperties underlineDotted = new RunProperties(
+    new Underline { Val = UnderlineValues.Dotted }
+);
+
+// Dashed underline
+RunProperties underlineDashed = new RunProperties(
+    new Underline { Val = UnderlineValues.Dash }
+);
+
+// Dash-dot underline
+RunProperties underlineDashDot = new RunProperties(
+    new Underline { Val = UnderlineValues.DotDash }
+);
+
+// Accounting double underline (extends to both sides like accounting)
+RunProperties underlineAccounting = new RunProperties(
+    new Underline { Val = UnderlineValues.DoubleAccounting }
+);
+
+// With color specification
+RunProperties underlineColored = new RunProperties(
+    new Underline { Val = UnderlineValues.Single, Color = "FF0000" }  // Red underline
+);
+
+// Without color (color="auto" = black)
+// With specific color using hex
+RunProperties underlineBlue = new RunProperties(
+    new Underline { Val = UnderlineValues.Single, Color = "0000FF" }
+);
+
+// Theme color on underline
+RunProperties underlineThemeColor = new RunProperties(
+    new Underline
+    {
+        Val = UnderlineValues.Single,
+        Color = "auto",  // or omit for auto/black
+        ThemeColor = ThemeColorValues.Accent1,
+        ThemeTint = "99"  // 60% opacity (hex 99 = 153/255 ≈ 60%)
+    }
+);
+
+// Turn off underline (in a underlined context)
+RunProperties noUnderline = new RunProperties(
+    new Underline { Val = UnderlineValues.None }
+);
+
+// ===========================================================================
+// 3.6 COLOR (color)
+// ===========================================================================
+// Color.Val is a 6-digit hex color (RRGGBB) WITHOUT the #
+// Word also supports 8-digit (AARRGGBB) for transparency
+
+// Basic color
+RunProperties redText = new RunProperties(
+    new Color { Val = "FF0000" }  // Pure red
+);
+
+RunProperties blueText = new RunProperties(
+    new Color { Val = "0070C0" }  // Office blue
+);
+
+// Theme colors (references to document theme)
+RunProperties themeColorText = new RunProperties(
+    new Color
+    {
+        Val = "FFFFFF",  // Fallback
+        ThemeColor = ThemeColorValues.Accent1,
+        ThemeShade = "BF",  // 75% darker (hex BF = 191/255 ≈ 75%)
+        ThemeTint = "99"    // 60% lighter (hex 99 = 153/255 ≈ 60%)
+    }
+);
+
+// Theme color shorthand
+RunProperties accent1Text = new RunProperties(
+    new Color { Val = "4472C4" }  // Direct hex is often simpler
+);
+
+// With transparency (alpha channel, 8-digit hex)
+// AA=fully transparent, FF=fully opaque
+RunProperties transparentText = new RunProperties(
+    new Color { Val = "80FF0000" }  // 50% transparent red (AA=half, FF=red)
+);
+
+// ===========================================================================
+// 3.7 HIGHLIGHT (highlight)
+// ===========================================================================
+// Highlight is a BACKGROUND color applied to the entire run.
+// Different from Shading (which is in run properties too).
+// Highlight enum values: DarkYellow, Yellow, Green, Cyan, Magenta, Blue,
+// DarkBlue, DarkCyan, DarkGreen, DarkMagenta, DarkRed, DarkYellow, LightGray,
+// LightGreen, LightOrange, LightPurple, LightRed, LightYellow, Navy, None,
+// Orange, Pink, Purple, Red, Teal, Turquoise, Yellow
+
+// Yellow highlight (default for comments)
+RunProperties yellowHighlight = new RunProperties(
+    new Highlight { Val = HighlightValues.Yellow }
+);
+
+// Green highlight (for insertions)
+RunProperties greenHighlight = new RunProperties(
+    new Highlight { Val = HighlightValues.Green }
+);
+
+// Red highlight (for deletions)
+RunProperties redHighlight = new RunProperties(
+    new Highlight { Val = HighlightValues.Red }
+);
+
+// Blue highlight
+RunProperties blueHighlight = new RunProperties(
+    new Highlight { Val = HighlightValues.Blue }
+);
+
+// Cyan highlight (for feedback)
+RunProperties cyanHighlight = new RunProperties(
+    new Highlight { Val = HighlightValues.Cyan }
+);
+
+// Gray highlight (for search)
+RunProperties grayHighlight = new RunProperties(
+    new Highlight { Val = HighlightValues.LightGray }
+);
+
+// No highlight (turn off)
+RunProperties noHighlight = new RunProperties(
+    new Highlight { Val = HighlightValues.None }
+);
+
+// ===========================================================================
+// 3.8 STRIKETHROUGH (strike, dstrike)
+// ===========================================================================
+// strike = single strikethrough
+// dstrike = double strikethrough
+
+// Single strikethrough (standard)
+RunProperties strikethrough = new RunProperties(
+    new Strikethrough()
+);
+
+// Double strikethrough (often for legal/editing)
+RunProperties doubleStrikethrough = new RunProperties(
+    new DoubleStrike()
+);
+
+// Turn off strikethrough
+RunProperties noStrikethrough = new RunProperties(
+    new Strikethrough { Val = OnOffValueValues.Off }
+);
+
+// ===========================================================================
+// 3.9 SUBSCRIPT/SUPERSCRIPT (verticalAlign)
+// ===========================================================================
+// VerticalTextAlignment enum: Baseline (normal), Subscript, Superscript
+// Subscript: lowers the text and reduces size
+// Superscript: raises the text and reduces size
+
+// Superscript (e.g., 2 in X²)
+RunProperties superscript = new RunProperties(
+    new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }
+);
+
+// Subscript (e.g., 2 in H₂O)
+RunProperties subscript = new RunProperties(
+    new VerticalTextAlignment { Val = VerticalPositionValues.Subscript }
+);
+
+// Baseline (normal) — explicit
+RunProperties baseline = new RunProperties(
+    new VerticalTextAlignment { Val = VerticalPositionValues.Baseline }
+);
+
+// ===========================================================================
+// 3.10 CAPS / ALLCAPS / SMALLCAPS (caps, smallCaps)
+// ===========================================================================
+// caps = ALL CAPS (converts lowercase to uppercase visually)
+// smallCaps = Small Caps (converts lowercase to uppercase but with smaller font)
+
+// ALL CAPS (visual only, underlying text unchanged)
+RunProperties allCaps = new RunProperties(
+    new Caps()
+);
+
+// Small Caps (lowercase appears as smaller uppercase letters)
+RunProperties smallCaps = new RunProperties(
+    new SmallCaps()
+);
+
+// Both properties together (smallcaps takes precedence visually if both set)
+RunProperties emphasisCaps = new RunProperties(
+    new SmallCaps(),
+    new Caps()
+);
+
+// Turn off caps
+RunProperties noCaps = new RunProperties(
+    new Caps { Val = OnOffValueValues.Off }
+);
+
+// ===========================================================================
+// 3.11 SPACING / KERNING (spacing)
+// ===========================================================================
+// Spacing.Val is in TWIPS (1/20 of a point, same as DXA)
+// Positive = add space, Negative = remove space
+// Range: -240 to +240 twips typically
+
+// Add space between characters (letter spacing / kerning)
+RunProperties expandedSpacing = new RunProperties(
+    new Spacing
+    {
+        Val = 100,  // +100 twips = +5pt of space between characters
+        // Space "100" = 5 points (100/20 = 5)
+    }
+);
+
+// Compress characters
+RunProperties compressedSpacing = new RunProperties(
+    new Spacing
+    {
+        Val = -50,  // -50 twips = -2.5pt (characters closer together)
+    }
+);
+
+// Normal spacing (remove any spacing adjustments)
+RunProperties normalSpacing = new RunProperties(
+    new Spacing { Val = 0 }
+);
+
+// Combined with other properties
+RunProperties spacedBold = new RunProperties(
+    new Spacing { Val = 50 },
+    new Bold()
+);
+
+// ===========================================================================
+// 3.12 POSITION (position) — RAISED/LOWERED TEXT
+// ===========================================================================
+// Position.Val is in HALF-POINTS (not DXA!)
+// Positive = raise, Negative = lower
+// Range: -1584 to +1584 half-pts (-792pt to +792pt!)
+
+// Raise text 6pt (12 half-points)
+RunProperties raised = new RunProperties(
+    new Position
+    {
+        Val = 12  // +12 half-pts = +6pt raised
+    }
+);
+
+// Lower text 3pt
+RunProperties lowered = new RunProperties(
+    new Position
+    {
+        Val = -6  // -6 half-pts = -3pt lowered
+    }
+);
+
+// Position is often used for:
+ // - Footnote references
+// - Baseline alignment adjustments
+// - Mathematical subscripts/superscripts (though verticalAlign is better for these)
+
+// ===========================================================================
+// 3.13 TEXT EFFECTS (textEffect)
+// ===========================================================================
+// TextEffectValues: shimmer, blinkBackground, etc.
+// These are decorative effects for special visual emphasis
+
+// Shimmer effect (sparkle/light animation)
+RunProperties shimmerEffect = new RunProperties(
+    new TextEffect
+    {
+        Val = TextEffectValues.Shimmer
+    }
+);
+
+// Blink background effect
+RunProperties blinkEffect = new RunProperties(
+    new TextEffect
+    {
+        Val = TextEffectValues.BlinkBackground
+    }
+);
+
+// Anti-alias effect (smoother text rendering)
+// (usually applied via document settings, not per-run)
+
+// ===========================================================================
+// 3.14 SHADING ON RUNS (shd)
+// ===========================================================================
+// Shading on a run applies a background color/pattern to the text background
+// Different from Highlight: Shading uses pattern fills, Highlight is solid colors
+
+// Solid fill shading (run background color)
+RunProperties shadedRun = new RunProperties(
+    new Shading
+    {
+        Val = ShadingPatternValues.Clear,  // Clear = solid color
+        Color = "auto",                     // auto = no border
+        Fill = "FFFF00"                     // Yellow background
+    }
+);
+
+// Horizontal line pattern shading
+RunProperties hLineShading = new RunProperties(
+    new Shading
+    {
+        Val = ShadingPatternValues.HorizontalLine,  // Horizontal line pattern
+        Color = "0000FF",
+        Fill = "FFFF00"
+    }
+);
+
+// Reverse pattern (for special effects)
+RunProperties reverseShading = new RunProperties(
+    new Shading
+    {
+        Val = ShadingPatternValues.ReverseDiagonalStripe,
+        Color = "auto",
+        Fill = "E0E0E0"
+    }
+);
+
+// Clear shading (remove)
+RunProperties noShading = new RunProperties(
+    new Shading
+    {
+        Val = ShadingPatternValues.Clear,
+        Fill = "auto"
+    }
+);
+
+// Thatch pattern (diagonal lines, like legal document)
+RunProperties thatchShading = new RunProperties(
+    new Shading
+    {
+        Val = ShadingPatternValues.Thatch,
+        Color = "000000",
+        Fill = "FFFFFF"
+    }
+);
+
+// Common shading patterns:
+// Clear, Solid, HorizStripe, VertStripe, RevDiagStripe, DiagCross, DiagStripe,
+// ReverseDiagStripe, DiagHorizCross, ThinHorzStripe, ThinVertStripe,
+// ThinReverseDiagStripe, ThinDiagStripe, ThinDiagHorzCross, ThickHorzStripe,
+// ThickVertStripe, ThickDiagStripe, ThickDiagCross, ThickReverseDiagStripe,
+// ThickDiagonalCross, Shingle, ThickSmallCheck, SmallCheck, LargeCheck,
+// SmallConfetti, Confetti, Horizontal, Diagonal, BigConfetti, ZigZag
+
+// ===========================================================================
+// 3.15 RUN STYLE (rStyle) — APPLY CHARACTER STYLE
+// ===========================================================================
+// RunStyle applies a character style to a run
+// The style must be defined in styles.xml first
+
+// Apply character style by ID
+RunProperties styledRun = new RunProperties(
+    new RunStyle { Val = "Emphasis" }  // References a character style
+);
+
+// Combined with direct formatting (direct overrides style)
+RunProperties styledWithOverride = new RunProperties(
+    new RunStyle { Val = "Emphasis" },
+    new Bold { Val = OnOffValueValues.Off }  // Override: don't make it bold
+);
+
+// ===========================================================================
+// 3.16 BORDER ON RUNS (rPr/bdr)
+// ===========================================================================
+// Run borders apply a border around individual characters (rarely used)
+
+// WordArt-style character border
+RunProperties borderedRun = new RunProperties(
+    new CharacterBorder(
+        new TopBorder { Val = BorderValues.Single, Size = 4, Color = "0000FF", Space = 1 },
+        new BottomBorder { Val = BorderValues.Single, Size = 4, Color = "0000FF", Space = 1 },
+        new LeftBorder { Val = BorderValues.Single, Size = 4, Color = "0000FF", Space = 1 },
+        new RightBorder { Val = BorderValues.Single, Size = 4, Color = "0000FF", Space = 1 }
+    )
+);
+
+// Single border (typically used)
+RunProperties borderTop = new RunProperties(
+    new CharacterBorder(
+        new TopBorder { Val = BorderValues.Single, Size = 8, Color = "FF0000" }
+    )
+);
+
+// ===========================================================================
+// 3.17 VANISH / HIDDEN TEXT (vanish, webHidden)
+// ===========================================================================
+// vanish = hidden in both UI and print (like hidden field codes)
+// webHidden = hidden in web layout view
+
+// Hidden text (doesn't appear in UI or print)
+RunProperties hiddenText = new RunProperties(
+    new Vanish()
+);
+
+// Hidden in web view only
+RunProperties webHiddenText = new RunProperties(
+    new WebHidden()
+);
+
+// Both combined
+RunProperties hiddenBothViews = new RunProperties(
+    new Vanish(),
+    new WebHidden()
+);
+
+// Turn off hide (in a hidden context)
+RunProperties visible = new RunProperties(
+    new Vanish { Val = OnOffValueValues.Off }
+);
+
+// ===========================================================================
+// 3.18 RIGHT-TO-LEFT (bidi)
+// ===========================================================================
+// For bidirectional text (Arabic, Hebrew)
+
+// Right-to-left text
+RunProperties rtlRun = new RunProperties(
+    new RightToLeftText()
+);
+
+// Normal direction
+RunProperties ltrRun = new RunProperties(
+    new RightToLeftText { Val = OnOffValueValues.Off }
+);
+
+// ===========================================================================
+// 3.19 LIGATURES (ligatures)
+// ===========================================================================
+// Ligatures combine adjacent characters for typography (fi, fl, ff, etc.)
+// Standard=0 means no ligatures, Standard=1 means common ligatures
+
+// Standard ligatures (fi, fl, ff, ffi, ffl)
+RunProperties standardLigatures = new RunProperties(
+    new Ligatures { Val = 1 }  // Standard ligatures on
+);
+
+// No ligatures
+RunProperties noLigatures = new RunProperties(
+    new Ligatures { Val = 0 }
+);
+
+// Historical ligatures (old-style, for fonts that support them)
+RunProperties historicalLigatures = new RunProperties(
+    new Ligatures { Val = 2 }  // Historical
+);
+
+// ===========================================================================
+// 3.20 COMPLEX SCRIPT PROPERTIES (cs, csBdr, csShd, etc.)
+// ===========================================================================
+// Complex script properties mirror the ASCII properties but for
+// complex scripts (Arabic, Hebrew, Thai, etc.)
+
+// Complex script bold
+RunProperties csBold = new RunProperties(
+    new Bold(),
+    new BoldComplexScript()
+);
+
+// Complex script italic
+RunProperties csItalic = new RunProperties(
+    new Italic(),
+    new ItalicComplexScript()
+);
+
+// Complex script underline
+RunProperties csUnderline = new RunProperties(
+    new Underline { Val = UnderlineValues.Single },
+    new UnderlineComplexScript { Val = UnderlineValues.Single }
+);
+
+// Complex script border
+RunProperties csBorder = new RunProperties(
+    new CharacterBorder(
+        new TopBorder { Val = BorderValues.Single, Size = 4, Color = "000080" }
+    )
+);
+
+// Complex script shading
+RunProperties csShading = new RunProperties(
+    new Shading
+    {
+        Val = ShadingPatternValues.Clear,
+        Color = "auto",
+        Fill = "E6E6E6"
+    }
+);
+
+// ===========================================================================
+// 3.21 LANGUAGE (lang) — HYPHENATION/SPELL CHECK
+// ===========================================================================
+// Language determines hyphenation, spell-check dictionary, etc.
+
+// English (US)
+RunProperties enUsText = new RunProperties(
+    new Languages { Val = "en-US" }
+);
+
+// English (UK)
+RunProperties enGbText = new RunProperties(
+    new Languages { Val = "en-GB" }
+);
+
+// French
+RunProperties frenchText = new RunProperties(
+    new Languages { Val = "fr-FR" }
+);
+
+// German
+RunProperties germanText = new RunProperties(
+    new Languages { Val = "de-DE" }
+);
+
+// Chinese (Simplified)
+RunProperties chineseText = new RunProperties(
+    new Languages { Val = "zh-CN" }
+);
+
+// Japanese
+RunProperties japaneseText = new RunProperties(
+    new Languages { Val = "ja-JP" }
+);
+
+// Arabic
+RunProperties arabicText = new RunProperties(
+    new Languages { Val = "ar-SA" }
+);
+
+// Hebrew
+RunProperties hebrewText = new RunProperties(
+    new Languages { Val = "he-IL" }
+);
+
+// No language (apply directly)
+RunProperties noLangText = new RunProperties(
+    new Languages { Val = "" }
+);
+
+// ===========================================================================
+// 3.22 KERNING (kern)
+// ===========================================================================
+// Kern adjusts character spacing based on character pairs
+// Value is in hundredths of a point (100 = 1pt)
+
+// Enable kerning
+RunProperties kerning = new RunProperties(
+    new Kern { Val = 20 }  // 20 = 0.2pt minimum kerning threshold
+);
+
+// Disable kerning
+RunProperties noKerning = new RunProperties(
+    new Kern { Val = 0 }
+);
+
+// Standard document kerning
+RunProperties standardKerning = new RunProperties(
+    new Kern { Val = 12 }  // 12 = 0.12pt
+);
+
+// ===========================================================================
+// 3.23 SNAP TO GRID (snapToGrid)
+// ===========================================================================
+// SnapToGrid aligns characters to a document grid for consistent line spacing
+
+// Enable snap to grid
+RunProperties snapToGrid = new RunProperties(
+    new SnapToGrid()
+);
+
+// Disable snap to grid
+RunProperties noSnapToGrid = new RunProperties(
+    new SnapToGrid { Val = OnOffValueValues.Off }
+);
+
+// ===========================================================================
+// 3.24 COMBINED RUN FORMATTING EXAMPLE
+// ===========================================================================
+// Complete run properties combining many options
+
+RunProperties complexRunProps = new RunProperties(
+    // Style reference (should be first per schema)
+    new RunStyle { Val = "Emphasis" },
+
+    // Font
+    new RunFonts
+    {
+        Ascii = "Georgia",
+        HighAnsi = "Georgia",
+        EastAsia = "SimSun"
+    },
+
+    // Bold + Bold Complex Script
+    new Bold(),
+    new BoldComplexScript(),
+
+    // Italic + Italic Complex Script
+    new Italic(),
+    new ItalicComplexScript(),
+
+    // Underline
+    new Underline { Val = UnderlineValues.Single, Color = "000080" },
+
+    // Font size (14pt)
+    new FontSize { Val = "28" },
+    new FontSizeComplexScript { Val = "28" },
+
+    // Color
+    new Color { Val = "000080" },  // Navy blue
+
+    // Language
+    new Languages { Val = "en-US" },
+
+    // Spacing (slightly expanded)
+    new Spacing { Val = 50 },
+
+    // Small caps
+    new SmallCaps(),
+
+    // Highlight
+    new Highlight { Val = HighlightValues.LightGray },
+
+    // Shadow (decorative)
+    new Shadow()
+);
+
+// ===========================================================================
+// 3.25 APPLYING RUN PROPERTIES TO RUNS
+// ===========================================================================
+// RunProperties can be applied in multiple ways:
+
+// Method 1: Inline in Run (direct formatting)
+Paragraph inlineFormatting = new Paragraph(
+    new Run(
+        new RunProperties(
+            new Bold(),
+            new Color { Val = "FF0000" }
+        ),
+        new Text("This is bold red text")
+    )
+);
+
+// Method 2: Via RunStyle (character style)
+Paragraph styleFormatting = new Paragraph(
+    new Run(
+        new RunStyle { Val = "MyCharStyle" },
+        new Text("This uses the MyCharStyle character style")
+    )
+);
+
+// Method 3: Mix (direct overrides style)
+Paragraph mixedFormatting = new Paragraph(
+    new Run(
+        new RunProperties(
+            new RunStyle { Val = "Emphasis" },  // Apply style first
+            new Bold { Val = OnOffValueValues.Off }  // Override: unbold
+        ),
+        new Text("Emphasis style but not bold")
+    )
+);
+
+// Method 4: Empty RunProperties to clear formatting
+Paragraph clearedFormatting = new Paragraph(
+    new Run(
+        new RunProperties(
+            new Bold { Val = OnOffValueValues.Off },
+            new Italic { Val = OnOffValueValues.Off },
+            new Underline { Val = UnderlineValues.None },
+            new Color { Val = "000000" },
+            new FontSize { Val = "22" }
+        ),
+        new Text("Manually reset to defaults")
+    )
+);
+```
+
+---
+
+## 4. Paragraph Formatting (ParagraphProperties) — EXHAUSTIVE
+
+```csharp
+// =============================================================================
+// PARAGRAPH FORMATTING (PARAGRAPHPROPERTIES) — COMPLETE REFERENCE
+// =============================================================================
+// ParagraphProperties (w:pPr) controls paragraph-level formatting. It can appear in:
+// 1. Style definitions (w:style/w:pPr) — applies to all paragraphs using that style
+// 2. Direct formatting in paragraphs (w:p/w:pPr) — overrides style for specific paragraphs
+//
+// CHILD ELEMENT ORDER (w:pPr): MUST be in this order per OpenXML schema:
+// pStyle, keepNext, keepLines, pageBreakBefore, widowControl, numPr, pBdr,
+// shd, tabs, suppressAutoHyphens, spacing, ind, contextualSpacing,
+// mirrorIndents, oMath, textDirection, textAlignment, textboxTightWrap,
+// outlineLvl, divId, cnfStyle, rPr, sectPr, pPrChange
+//
+// CRITICAL: sectPr must be LAST child of w:body, but LAST BUT ONE in w:pPr context.
+// In body, sectPr defines section properties. In pPr, sectPr defines section break before paragraph.
+
+// ===========================================================================
+// 4.1 JUSTIFICATION / ALIGNMENT (jc)
+// ===========================================================================
+// JustificationValues enum: Left, Center, Right, Both (Justify), Distribute,
+// ThaiDistribute, Justified (same as Both in most cases)
+
+// Left justification (default for LTR languages)
+ParagraphProperties justifyLeft = new ParagraphProperties(
+    new Justification { Val = JustificationValues.Left }
+);
+
+// Center justification
+ParagraphProperties justifyCenter = new ParagraphProperties(
+    new Justification { Val = JustificationValues.Center }
+);
+
+// Right justification (common in Arabic/Hebrew documents)
+ParagraphProperties justifyRight = new ParagraphProperties(
+    new Justification { Val = JustificationValues.Right }
+);
+
+// Both/Justify (stretches lines to fill width — standard for books/newspapers)
+ParagraphProperties justifyBoth = new ParagraphProperties(
+    new Justification { Val = JustificationValues.Both }
+);
+
+// Distribute (each line individually stretched to fill — no ragging)
+// Often used in Asian typography
+ParagraphProperties justifyDistribute = new ParagraphProperties(
+    new Justification { Val = JustificationValues.Distribute }
+);
+
+// ThaiDistribute (special handling for Thai script)
+ParagraphProperties justifyThaiDistribute = new ParagraphProperties(
+    new Justification { Val = JustificationValues.ThaiDistribute }
+);
+
+// Center justification on a line (for titles)
+Paragraph titlePara = new Paragraph(
+    new ParagraphProperties(
+        new Justification { Val = JustificationValues.Center }
+    ),
+    new Run(new Text("Centered Title"))
+);
+
+// ===========================================================================
+// 4.2 INDENTATION (ind)
+// ===========================================================================
+// All indentation values in DXA (1 inch = 1440 DXA, 1 cm ≈ 567 DXA)
+// Positive = indent rightward, Negative = indent leftward
+//
+// Left/Right: from page edge
+// FirstLine: extra indent for first line (positive = indent right, negative = outdent)
+// Hanging: amount to "hang" first line (negative moves first line left of body)
+// FirstLineChars: CJK-specific, specifies in character counts
+
+// Basic left indent (1 inch from left edge)
+ParagraphProperties indentLeft1Inch = new ParagraphProperties(
+    new Indentation { Left = "1440" }  // 1440 DXA = 1 inch
+);
+
+// Left indent with hanging first line (negative FirstLine)
+ParagraphProperties hangingIndent = new ParagraphProperties(
+    new Indentation
+    {
+        Left = "720",           // Body starts 0.5 inch from left
+        FirstLine = "-720"      // First line aligns with body start
+    }
+);
+
+// FirstLine positive (first line indented more than body)
+ParagraphProperties firstLineIndent = new ParagraphProperties(
+    new Indentation
+    {
+        Left = "1440",          // Body at 1 inch
+        FirstLine = "720"       // First line at 1.5 inch (additional 0.5 inch)
+    }
+);
+
+// Right indent
+ParagraphProperties indentRight = new ParagraphProperties(
+    new Indentation { Right = "1440" }  // 1 inch from right edge
+);
+
+// Both left and right indent (centered block)
+ParagraphProperties blockIndent = new ParagraphProperties(
+    new Indentation
+    {
+        Left = "1440",   // 1 inch from left
+        Right = "1440"   // 1 inch from right
+    }
+);
+
+// Hanging indent (classic for bibliographies, numbered lists)
+// First line hangs to the left of the body
+ParagraphProperties hangingIndent720 = new ParagraphProperties(
+    new Indentation
+    {
+        Left = "1440",           // Body indent = 1 inch
+        Hanging = "720"          // First line hangs 0.5 inch to the left of body
+    }
+);
+
+// Outdent (first line starts BEFORE body start)
+ParagraphProperties outdent = new ParagraphProperties(
+    new Indentation
+    {
+        Left = "720",            // Body at 0.5 inch
+        FirstLine = "-720"       // First line at 0 (page edge)
+    }
+);
+
+// Line-specific: negative left indent (pull into margin)
+ParagraphProperties negativeIndent = new ParagraphProperties(
+    new Indentation { Left = "-720" }  // 0.5 inch into left margin
+);
+
+// CJK FirstLineChars (character-based first line indent)
+// This converts character count to DXA based on font metrics
+ParagraphProperties cjkFirstLine = new ParagraphProperties(
+    new Indentation
+    {
+        Left = "567",            // Body at 1 cm
+        FirstLineChars = 200     // 2 characters extra indent (200 = 2 chars × 100)
+    }
+);
+
+// CJK HangingChars
+ParagraphProperties cjkHanging = new ParagraphProperties(
+    new Indentation
+    {
+        Left = "567",
+        HangingChars = 100       // 1 character hanging
+    }
+);
+
+// ===========================================================================
+// 4.3 SPACING BETWEEN LINES (spacing)
+// ===========================================================================
+// SpacingBetweenLines has multiple attributes:
+// Before: space above paragraph in DXA
+// After: space below paragraph in DXA
+// Line: line height (in DXA for Exact/AtLeast, or value×240 for Auto)
+// LineRule: Auto (multiple of single), Exact (fixed DXA), AtLeast (minimum DXA)
+//
+// Special Line values for Auto:
+// 240 = single spacing
+// 360 = 1.5 line spacing
+// 480 = double spacing
+// 120 = half spacing (rare)
+// For other multiples: Line = (desired spacing in points) × 20
+
+// Space before only
+ParagraphProperties spaceBefore = new ParagraphProperties(
+    new SpacingBetweenLines { Before = "240" }  // 240 DXA = 12pt before
+);
+
+// Space after only
+ParagraphProperties spaceAfter = new ParagraphProperties(
+    new SpacingBetweenLines { After = "200" }  // 200 DXA = 10pt after
+);
+
+// Both before and after
+ParagraphProperties spaceBoth = new ParagraphProperties(
+    new SpacingBetweenLines
+    {
+        Before = "120",
+        After = "120"
+    }
+);
+
+// SINGLE LINE SPACING (Auto rule)
+ParagraphProperties singleSpacing = new ParagraphProperties(
+    new SpacingBetweenLines
+    {
+        Line = "240",
+        LineRule = LineSpacingRuleValues.Auto  // 240 = 1.0× line height
+    }
+);
+
+// DOUBLE LINE SPACING
+ParagraphProperties doubleSpacing = new ParagraphProperties(
+    new SpacingBetweenLines
+    {
+        Line = "480",
+        LineRule = LineSpacingRuleValues.Auto  // 480 = 2.0× line height
+    }
+);
+
+// 1.5 LINE SPACING
+ParagraphProperties oneAndHalfSpacing = new ParagraphProperties(
+    new SpacingBetweenLines
+    {
+        Line = "360",
+        LineRule = LineSpacingRuleValues.Auto  // 360 = 1.5× line height
+    }
+);
+
+// EXACT LINE HEIGHT (fixed height, regardless of content)
+ParagraphProperties exactLineHeight = new ParagraphProperties(
+    new SpacingBetweenLines
+    {
+        Line = "360",            // 360 DXA = 18pt
+        LineRule = LineSpacingRuleValues.Exact  // Exactly 18pt, even if text overflows
+    }
+);
+
+// AT-LEAST LINE HEIGHT (minimum, grows if needed)
+ParagraphProperties atLeastLineHeight = new ParagraphProperties(
+    new SpacingBetweenLines
+    {
+        Line = "288",            // At least 14.4pt
+        LineRule = LineSpacingRuleValues.AtLeast  // At least 14.4pt, more if content requires
+    }
+);
+
+// LINE SPACING WITH SPACE BEFORE/AFTER
+ParagraphProperties paragraphWithSpacing = new ParagraphProperties(
+    new SpacingBetweenLines
+    {
+        Before = "480",          // 24pt before (for heading paragraphs)
+        After = "240",           // 12pt after
+        Line = "276",            // 1.15× line spacing
+        LineRule = LineSpacingRuleValues.Auto
+    }
+);
+
+// SPACE BETWEEN LINES EXPLAINED:
+// LineRule = Auto:
+//   - Line value is a multiple of 240 (single spacing = 240)
+//   - Word multiplies by the font size to get actual line height
+//   - Example: Line="360" with 11pt font = 11pt × 1.5 = 16.5pt actual
+//   - Most common setting for body text
+//
+// LineRule = Exact:
+//   - Line value is in DXA directly
+//   - Line="360" = exactly 18pt, period
+//   - Text that exceeds will overflow
+//   - Used for fixed-height rows in tables
+//
+// LineRule = AtLeast:
+//   - Line value is minimum in DXA
+//   - Line="288" = at least 14.4pt, grows if text is taller
+//   - Used when you need minimum spacing but content varies
+
+// ===========================================================================
+// 4.4 KEEP OPTIONS (keepNext, keepLines, widowControl)
+// ===========================================================================
+// These control how paragraphs interact with page breaks
+
+// KEEP NEXT: Keep this paragraph on same page as the following paragraph
+// Essential for headings (don't separate heading from first paragraph)
+ParagraphProperties keepWithNext = new ParagraphProperties(
+    new KeepNext()
+);
+
+// KEEP LINES: Keep all lines of this paragraph together (no page break inside)
+// Used for: table rows, list items, or paragraphs that shouldn't split
+ParagraphProperties keepLinesTogether = new ParagraphProperties(
+    new KeepLines()
+);
+
+// BOTH: Keep next AND keep lines together
+ParagraphProperties keepBoth = new ParagraphProperties(
+    new KeepNext(),
+    new KeepLines()
+);
+
+// WIDOW CONTROL: Prevent single lines at page top/bottom (widow/orphan control)
+// Default is ON in Word. Only disable if you want orphans/widows.
+ParagraphProperties widowControl = new ParagraphProperties(
+    new WidowControl()
+);
+
+// NO WIDOW CONTROL (allow single lines at page breaks)
+ParagraphProperties noWidowControl = new ParagraphProperties(
+    new WidowControl { Val = OnOffValueValues.Off }
+);
+
+// PAGE BREAK BEFORE: Start this paragraph on a new page
+ParagraphProperties pageBreakBefore = new ParagraphProperties(
+    new PageBreakBefore()
+);
+
+// Combined: Heading style (keep with next, keep lines, page break before)
+ParagraphProperties headingProps = new ParagraphProperties(
+    new KeepNext(),
+    new KeepLines(),
+    new PageBreakBefore(),
+    new WidowControl(),
+    new SpacingBetweenLines { Before = "480", After = "120" }
+);
+
+// ===========================================================================
+// 4.5 OUTLINE LEVEL (outlineLvl)
+// ===========================================================================
+// OutlineLevel defines the heading level for document structure (TOC, Navigation)
+// Values 0-8 correspond to Heading 1 through Heading 9
+// Word uses this to identify headings in the Navigation Pane
+
+// Level 0 = Heading 1
+ParagraphProperties outlineLevel1 = new ParagraphProperties(
+    new OutlineLevel { Val = 0 }
+);
+
+// Level 1 = Heading 2
+ParagraphProperties outlineLevel2 = new ParagraphProperties(
+    new OutlineLevel { Val = 1 }
+);
+
+// Level 5 = Heading 6
+ParagraphProperties outlineLevel6 = new ParagraphProperties(
+    new OutlineLevel { Val = 5 }
+);
+
+// Level 8 = last possible level
+ParagraphProperties outlineLevel8 = new ParagraphProperties(
+    new OutlineLevel { Val = 8 }
+);
+
+// TOC integration: When you insert a TOC field, Word looks for paragraphs
+// with outlineLevel to generate entries. Without outlineLevel, TOC won't
+// recognize the heading.
+
+// Heading 1 style example (combining with style reference)
+Paragraph heading1 = new Paragraph(
+    new ParagraphProperties(
+        new ParagraphStyleId { Val = "Heading1" },  // Style reference
+        new OutlineLevel { Val = 0 }                 // Also set outline level directly
+    ),
+    new Run(new Text("Chapter One"))
+);
+
+// ===========================================================================
+// 4.6 PARAGRAPH BORDERS (pBdr)
+// ===========================================================================
+// Paragraph borders draw lines around/adjacent to paragraphs
+// Four borders: Top, Left, Bottom, Right, Between, Bar
+
+// Simple bottom border
+ParagraphProperties bottomBorder = new ParagraphProperties(
+    new ParagraphBorders(
+        new BottomBorder
+        {
+            Val = BorderValues.Single,
+            Size = 4,
+            Color = "000000",
+            Space = 4  // Space between text and border in DXA
+        }
+    )
+);
+
+// Top border only
+ParagraphProperties topBorder = new ParagraphProperties(
+    new ParagraphBorders(
+        new TopBorder
+        {
+            Val = BorderValues.Single,
+            Size = 8,
+            Color = "4472C4",
+            Space = 4
+        }
+    )
+);
+
+// Double line bottom border (common for headings)
+ParagraphProperties doubleBottomBorder = new ParagraphProperties(
+    new ParagraphBorders(
+        new BottomBorder
+        {
+            Val = BorderValues.Double,
+            Size = 4,
+            Color = "000000",
+            Space = 4
+        }
+    )
+);
+
+// All four borders
+ParagraphProperties allBorders = new ParagraphProperties(
+    new ParagraphBorders(
+        new TopBorder { Val = BorderValues.Single, Size = 4, Color = "CCCCCC", Space = 1 },
+        new LeftBorder { Val = BorderValues.Single, Size = 4, Color = "CCCCCC", Space = 4 },
+        new BottomBorder { Val = BorderValues.Single, Size = 4, Color = "CCCCCC", Space = 1 },
+        new RightBorder { Val = BorderValues.Single, Size = 4, Color = "CCCCCC", Space = 4 }
+    )
+);
+
+// Between border (line between adjacent paragraphs)
+// Used for paragraph groups with separator lines
+ParagraphProperties withBetweenBorder = new ParagraphProperties(
+    new ParagraphBorders(
+        new BetweenBorder
+        {
+            Val = BorderValues.Single,
+            Size = 2,
+            Color = "CCCCCC",
+            Space = 4
+        }
+    )
+);
+
+// Bar border (vertical bar on one side)
+// Val can be Left or Right — a solid bar in the margin
+ParagraphProperties leftBarBorder = new ParagraphProperties(
+    new ParagraphBorders(
+        new BarBorder { Val = BorderValues.Left, Color = "000080", Size = 12 }
+    )
+);
+
+// Thick top border with color
+ParagraphProperties thickTopBorder = new ParagraphProperties(
+    new ParagraphBorders(
+        new TopBorder
+        {
+            Val = BorderValues.Thick,
+            Size = 12,
+            Color = "2F5496",
+            Space = 8
+        }
+    )
+);
+
+// Wave border (decorative)
+ParagraphProperties waveBorder = new ParagraphProperties(
+    new ParagraphBorders(
+        new BottomBorder
+        {
+            Val = BorderValues.Wave,
+            Size = 6,
+            Color = "FF0000",
+            Space = 4
+        }
+    )
+);
+
+// Border.NONE to explicitly remove borders
+ParagraphProperties noBorders = new ParagraphProperties(
+    new ParagraphBorders(
+        new BottomBorder { Val = BorderValues.None }
+    )
+);
+
+// ===========================================================================
+// 4.7 SHADING / BACKGROUND (shd)
+// ===========================================================================
+// Shading applies background color/pattern to the paragraph area
+// Different from run-level highlight (which only covers the text)
+
+// Solid color shading (paragraph background)
+ParagraphProperties shadedBackground = new ParagraphProperties(
+    new Shading
+    {
+        Val = ShadingPatternValues.Clear,
+        Color = "auto",
+        Fill = "E6F2FF"  // Light blue
+    }
+);
+
+// Gray shading (common for quotes, notes)
+ParagraphProperties grayBackground = new ParagraphProperties(
+    new Shading
+    {
+        Val = ShadingPatternValues.Clear,
+        Color = "auto",
+        Fill = "F2F2F2"  // Light gray
+    }
+);
+
+// Accent1 theme color shading
+ParagraphProperties themedBackground = new ParagraphProperties(
+    new Shading
+    {
+        Val = ShadingPatternValues.Clear,
+        Color = "auto",
+        Fill = "D9E2F3",  // Light blue accent
+        ThemeColor = ThemeColorValues.Accent1,
+        ThemeShade = "80"  // 50% shade
+    }
+);
+
+// Pattern shading (horizontal lines)
+ParagraphProperties stripedBackground = new ParagraphProperties(
+    new Shading
+    {
+        Val = ShadingPatternValues.HorizStripe,
+        Color = "000000",
+        Fill = "FFFFFF"
+    }
+);
+
+// Diagonal stripe shading
+ParagraphProperties diagonalBackground = new ParagraphProperties(
+    new Shading
+    {
+        Val = ShadingPatternValues.ReverseDiagStripe,
+        Color = "auto",
+        Fill = "FFF2CC"  // Light yellow
+    }
+);
+
+// Clear shading (remove background)
+ParagraphProperties noBackground = new ParagraphProperties(
+    new Shading
+    {
+        Val = ShadingPatternValues.Clear,
+        Fill = "auto"
+    }
+);
+
+// Combined shading and border (common for callout boxes)
+ParagraphProperties calloutBox = new ParagraphProperties(
+    new ParagraphBorders(
+        new LeftBorder
+        {
+            Val = BorderValues.Single,
+            Size = 24,
+            Color = "4472C4",
+            Space = 8
+        }
+    ),
+    new Shading
+    {
+        Val = ShadingPatternValues.Clear,
+        Color = "auto",
+        Fill = "D9E2F3"
+    },
+    new Indentation { Left = "720" }
+);
+
+// ===========================================================================
+// 4.8 TABS (tabs)
+// ===========================================================================
+// TabStops define where tab characters position text
+// Each tab has: position (DXA from left margin), alignment, leader
+
+// Single left tab at 1 inch
+ParagraphProperties leftTab = new ParagraphProperties(
+    new Tabs(
+        new TabStop { Position = 1440, Val = TabStopValues.Left }
+    )
+);
+
+// Multiple tabs
+ParagraphProperties multipleTabs = new ParagraphProperties(
+    new Tabs(
+        new TabStop { Position = 1440, Val = TabStopValues.Left },              // 1"
+        new TabStop { Position = 2880, Val = TabStopValues.Center },            // 2"
+        new TabStop { Position = 4320, Val = TabStopValues.Right },             // 3"
+        new TabStop { Position = 5760, Val = TabStopValues.Decimal, TabChar = '.' }  // 4" decimal
+    )
+);
+
+// Tab with dot leader (dots connecting to tab position)
+ParagraphProperties dotLeaderTab = new ParagraphProperties(
+    new Tabs(
+        new TabStop
+        {
+            Position = 4320,  // 3 inches
+            Val = TabStopValues.Left,
+            Leader = TabStopLeaderCharValues.Dot
+        }
+    )
+);
+
+// Tab with dash leader
+ParagraphProperties dashLeaderTab = new ParagraphProperties(
+    new Tabs(
+        new TabStop
+        {
+            Position = 4320,
+            Val = TabStopValues.Left,
+            Leader = TabStopLeaderCharValues.Dash
+        }
+    )
+);
+
+// Tab with underscore leader
+ParagraphProperties underscoreLeaderTab = new ParagraphProperties(
+    new Tabs(
+        new TabStop
+        {
+            Position = 4320,
+            Val = TabStopValues.Left,
+            Leader = TabStopLeaderCharValues.Underscore
+        }
+    )
+);
+
+// Tab with heavy line leader
+ParagraphProperties heavyLeaderTab = new ParagraphProperties(
+    new TabStop
+    {
+        Position = 4320,
+        Val = TabStopValues.Left,
+        Leader = TabStopLeaderCharValues.Heavy
+    )
+);
+
+// Tab with middle dot leader
+ParagraphProperties middleDotLeaderTab = new ParagraphProperties(
+    new Tabs(
+        new TabStop
+        {
+            Position = 4320,
+            Val = TabStopValues.Left,
+            Leader = TabStopLeaderCharValues.MiddleDot
+        }
+    )
+);
+
+// CENTER TAB (text centered at tab position)
+ParagraphProperties centerTab = new ParagraphProperties(
+    new Tabs(
+        new TabStop { Position = 4320, Val = TabStopValues.Center }
+    )
+);
+
+// RIGHT TAB (text right-aligned at tab position)
+ParagraphProperties rightTab = new ParagraphProperties(
+    new Tabs(
+        new TabStop { Position = 5760, Val = TabStopValues.Right }
+    )
+);
+
+// DECIMAL TAB (aligns on decimal point)
+ParagraphProperties decimalTab = new ParagraphProperties(
+    new Tabs(
+        new TabStop
+        {
+            Position = 5040,  // 3.5 inches
+            Val = TabStopValues.Decimal,
+            TabChar = '.'    // Align on period (or specify comma for European)
+        }
+    )
+);
+
+// BAR TAB (vertical bar at tab position)
+ParagraphProperties barTab = new ParagraphProperties(
+    new Tabs(
+        new TabStop { Position = 2880, Val = TabStopValues.Bar }
+    )
+);
+
+// CLEAR TAB (removes inherited tab at this position)
+ParagraphProperties clearTab = new ParagraphProperties(
+    new Tabs(
+        new TabStop { Position = 1440, Val = TabStopValues.Clear }
+    )
+);
+
+// TAB STOP LEADER VALUES (Leader property):
+// None = no leader
+// Dot = ....... (dots)
+// Dash = ------- (dashes)
+// Underscore = _______ (underscores)
+// Heavy = ═══════ (heavy line)
+// MiddleDot = ········ (centered dots, European style)
+
+// ===========================================================================
+// 4.9 SUPPRESS AUTO HYPHENS (suppressAutoHyphens)
+// ===========================================================================
+// When true, Word won't auto-hyphenate this paragraph
+
+// Prevent auto-hyphenation
+ParagraphProperties noAutoHyphens = new ParagraphProperties(
+    new SuppressAutoHyphens()
+);
+
+// Allow hyphenation (default) — explicit
+ParagraphProperties allowAutoHyphens = new ParagraphProperties(
+    new SuppressAutoHyphens { Val = OnOffValueValues.Off }
+);
+
+// ===========================================================================
+// 4.10 NUMBERING PROPERTIES (numPr)
+// ===========================================================================
+// numPr links a paragraph to a numbering definition (bullets or lists)
+
+// Simple bullet list item
+Paragraph bulletItem = new Paragraph(
+    new ParagraphProperties(
+        new NumberingProperties(
+            new NumberingLevelReference { Val = 0 },    // Level 0 (top-level)
+            new NumberingId { Val = 1 }                  // References numbering definition
+        ),
+        new Indentation { Left = "720", Hanging = "360" }  // Standard hanging indent
+    ),
+    new Run(new Text("First bullet item"))
+);
+
+// Numbered list item
+Paragraph numberedItem = new Paragraph(
+    new ParagraphProperties(
+        new NumberingProperties(
+            new NumberingLevelReference { Val = 0 },
+            new NumberingId { Val = 2 }
+        ),
+        new Indentation { Left = "720", Hanging = "360" }
+    ),
+    new Run(new Text("First numbered item"))
+);
+
+// Multi-level list item (level 2)
+Paragraph level2Item = new Paragraph(
+    new ParagraphProperties(
+        new NumberingProperties(
+            new NumberingLevelReference { Val = 2 },  // Level 2 (sub-sub-item)
+            new NumberingId { Val = 1 }
+        ),
+        new Indentation { Left = "1440", Hanging = "360" }  // Deeper indent
+    ),
+    new Run(new Text("Sub-item under sub-item"))
+);
+
+// Restart numbering at this paragraph
+Paragraph restartNumberedItem = new Paragraph(
+    new ParagraphProperties(
+        new NumberingProperties(
+            new NumberingLevelReference { Val = 0 },
+            new NumberingId { Val = 3 },
+            new NumberingRestart { Val = NumberingRestartValues.Restart }  // Restart
+        ),
+        new Indentation { Left = "720", Hanging = "360" }
+    ),
+    new Run(new Text("Item 1 (restarted)"))
+);
+
+// Continue numbering (default)
+Paragraph continueNumberedItem = new Paragraph(
+    new ParagraphProperties(
+        new NumberingProperties(
+            new NumberingLevelReference { Val = 0 },
+            new NumberingId { Val = 3 },
+            new NumberingRestart { Val = NumberingRestartValues.Continuous }  // Continue
+        ),
+        new Indentation { Left = "720", Hanging = "360" }
+    ),
+    new Run(new Text("Item 4 (continued)"))
+);
+
+// ===========================================================================
+// 4.11 PARAGRAPH STYLE (pStyle)
+// ===========================================================================
+// pStyle references a paragraph style by ID
+
+// Apply Heading1 style
+ParagraphProperties styledPara = new ParagraphProperties(
+    new ParagraphStyleId { Val = "Heading1" }
+);
+
+// Apply custom style
+ParagraphProperties customStyledPara = new ParagraphProperties(
+    new ParagraphStyleId { Val = "MyCustomStyle" }
+);
+
+// Default paragraph style (Normal)
+ParagraphProperties normalPara = new ParagraphProperties(
+    new ParagraphStyleId { Val = "Normal" }
+);
+
+// ===========================================================================
+// 4.12 BIDIRECTIONAL (BiDi, rtl)
+// ===========================================================================
+// BiDi enables right-to-left paragraph layout for Arabic/Hebrew
+
+// Right-to-left paragraph
+ParagraphProperties rtlParagraph = new ParagraphProperties(
+    new BiDi()
+);
+
+// Left-to-right (default) — explicit
+ParagraphProperties ltrParagraph = new ParagraphProperties(
+    new BiDi { Val = OnOffValueValues.Off }
+);
+
+// When BiDi is on:
+// - Text flows right-to-left
+// - Justification defaults to right
+// - List numbering appears on the right
+
+// ===========================================================================
+// 4.13 CONTEXTUAL SPACING (contextualSpacing)
+// ===========================================================================
+// When true, suppresses space between paragraphs when they share the same style
+// Useful for headings followed by body text within the same style
+
+// Enable contextual spacing (suppress space between same-style paragraphs)
+ParagraphProperties contextualSpacing = new ParagraphProperties(
+    new ContextualSpacing()
+);
+
+// Disable contextual spacing (normal space between all paragraphs)
+ParagraphProperties noContextualSpacing = new ParagraphProperties(
+    new ContextualSpacing { Val = OnOffValueValues.Off }
+);
+
+// ===========================================================================
+// 4.14 MIRROR IN DENTS (mirrorIndents)
+// ===========================================================================
+// When enabled, Left/Right indents are mirrored for odd/even pages
+// (left indent on even pages becomes right indent on odd pages)
+// Used for book-style printing with binding margin
+
+// Enable mirror indents
+ParagraphProperties mirrorIndents = new ParagraphProperties(
+    new MirrorIndents()
+);
+
+// Disable mirror indents (default)
+ParagraphProperties noMirrorIndents = new ParagraphProperties(
+    new MirrorIndents { Val = OnOffValueValues.Off }
+);
+
+// ===========================================================================
+// 4.15 TEXT DIRECTION (textDirection)
+// ===========================================================================
+// Controls text flow direction within the paragraph
+
+// Left-to-right (default)
+ParagraphProperties ltrTextFlow = new ParagraphProperties(
+    new TextDirection { Val = TextDirectionValues.LeftToRight }
+);
+
+// Right-to-left
+ParagraphProperties rtlTextFlow = new ParagraphProperties(
+    new TextDirection { Val = TextDirectionValues.RightToLeft }
+);
+
+// Top-to-bottom (vertical, common in East Asian documents)
+ParagraphProperties verticalTextFlow = new ParagraphProperties(
+    new TextDirection { Val = TextDirectionValues.TopToBottom }
+);
+
+// Bottom-to-top (vertical rotated 180°)
+ParagraphProperties bottomToTopTextFlow = new ParagraphProperties(
+    new TextDirection { Val = TextDirectionValues.BottomToTop }
+);
+
+// Left-to-right rotated (90° clockwise)
+ParagraphProperties leftToRightRotated = new ParagraphProperties(
+    new TextDirection { Val = TextDirectionValues.LeftToRightRotated }
+);
+
+// Right-to-left rotated (90° counter-clockwise)
+ParagraphProperties rightToLeftRotated = new ParagraphProperties(
+    new TextDirection { Val = TextDirectionValues.RightToLeftRotated }
+);
+
+// ===========================================================================
+// 4.16 SNAP TO GRID (snapToGrid)
+// ===========================================================================
+// Aligns paragraph to document grid for consistent vertical spacing
+
+// Enable snap to grid
+ParagraphProperties snapToGridPara = new ParagraphProperties(
+    new SnapToGrid()
+);
+
+// Disable snap to grid
+ParagraphProperties noSnapToGridPara = new ParagraphProperties(
+    new SnapToGrid { Val = OnOffValueValues.Off }
+);
+
+// ===========================================================================
+// 4.17 TEXT ALIGNMENT (textAlignment)
+// ===========================================================================
+// Vertical alignment of text within a line box (rarely used)
+// Default is Auto (baseline)
+
+// Baseline alignment (default)
+ParagraphProperties baselineAlign = new ParagraphProperties(
+    new TextAlignment { Val = VerticalTextAlignmentValues.Auto }
+);
+
+// Top alignment
+ParagraphProperties topAlign = new ParagraphProperties(
+    new TextAlignment { Val = VerticalTextAlignmentValues.Top }
+);
+
+// Center alignment
+ParagraphProperties centerVerticalAlign = new ParagraphProperties(
+    new TextAlignment { Val = VerticalTextAlignmentValues.Center }
+);
+
+// Bottom alignment
+ParagraphProperties bottomAlign = new ParagraphProperties(
+    new TextAlignment { Val = VerticalTextAlignmentValues.Bottom }
+);
+
+// Baseline alignment (explicit)
+ParagraphProperties baselineAlignExplicit = new ParagraphProperties(
+    new TextAlignment { Val = VerticalTextAlignmentValues.Baseline }
+);
+
+// ===========================================================================
+// 4.18 DIV ID (divId)
+// ===========================================================================
+// Associates paragraph with a div for HTML/CSS mapping (很少使用)
+// Used when importing/exporting HTML content
+
+ParagraphProperties divIdPara = new ParagraphProperties(
+    new DivId { Val = "myDiv123" }
+);
+
+// ===========================================================================
+// 4.19 CNF STYLE (cnfStyle)
+// ===========================================================================
+// Conditional formatting style index (used by Word for table of contents,
+// styles pane grouping, etc.) — typically set automatically by Word
+
+ParagraphProperties cnfStylePara = new ParagraphProperties(
+    new CnfStyle { Val = 1 }  // Index into style's cnfStyle definitions
+);
+
+// ===========================================================================
+// 4.20 SECTION PROPERTIES IN PARAGRAPH (sectPr)
+// ===========================================================================
+// Section properties can appear INSIDE a paragraph to create a section break
+// BEFORE that paragraph. This is how you have different page layouts
+// in different parts of the document.
+
+// Section break with continuous layout
+Paragraph continuousSectionBreak = new Paragraph(
+    new ParagraphProperties(
+        new SectionProperties(
+            new SectionType { Val = SectionMarkValues.Continuous }
+        )
+    )
+);
+
+// Section break starting new page
+Paragraph newPageSectionBreak = new Paragraph(
+    new ParagraphProperties(
+        new SectionProperties(
+            new SectionType { Val = SectionMarkValues.NextPage }
+        )
+    )
+);
+
+// Section break with even page
+Paragraph evenPageSectionBreak = new Paragraph(
+    new ParagraphProperties(
+        new SectionProperties(
+            new SectionType { Val = SectionMarkValues.EvenPage }
+        )
+    )
+);
+
+// Section break with odd page
+Paragraph oddPageSectionBreak = new Paragraph(
+    new ParagraphProperties(
+        new SectionProperties(
+            new SectionType { Val = SectionMarkValues.OddPage }
+        )
+    )
+);
+
+// Section with custom page size
+Paragraph customSectionPara = new Paragraph(
+    new ParagraphProperties(
+        new SectionProperties(
+            new PageSize { Width = 12240u, Height = 15840u },  // Letter
+            new PageMargin
+            {
+                Top = 1440,
+                Bottom = 1440,
+                Left = 1440u,
+                Right = 1440u
+            }
+        )
+    )
+);
+
+// ===========================================================================
+// 4.21 COMBINED PARAGRAPH FORMATTING EXAMPLE
+// ===========================================================================
+// Complete paragraph properties combining many options
+
+ParagraphProperties complexParaProps = new ParagraphProperties(
+    // Style reference
+    new ParagraphStyleId { Val = "Normal" },
+
+    // Keep options
+    new KeepNext(),
+    new KeepLines(),
+    new WidowControl(),
+
+    // Spacing
+    new SpacingBetweenLines
+    {
+        Before = "240",
+        After = "200",
+        Line = "276",
+        LineRule = LineSpacingRuleValues.Auto
+    },
+
+    // Indentation
+    new Indentation
+    {
+        Left = "0",
+        Right = "0",
+        FirstLine = "0",
+        Hanging = "0"
+    },
+
+    // Alignment
+    new Justification { Val = JustificationValues.Left },
+
+    // Border (bottom line)
+    new ParagraphBorders(
+        new BottomBorder
+        {
+            Val = BorderValues.Single,
+            Size = 4,
+            Color = "CCCCCC",
+            Space = 4
+        }
+    ),
+
+    // Shading
+    new Shading
+    {
+        Val = ShadingPatternValues.Clear,
+        Color = "auto",
+        Fill = "auto"
+    },
+
+    // Tabs
+    new Tabs(
+        new TabStop { Position = 1440, Val = TabStopValues.Left },
+        new TabStop { Position = 2880, Val = TabStopValues.Center, Leader = TabStopLeaderCharValues.Dot }
+    ),
+
+    // Outline level (for TOC)
+    new OutlineLevel { Val = 0 },
+
+    // Bidirectional
+    new BiDi { Val = OnOffValueValues.Off },
+
+    // Contextual spacing
+    new ContextualSpacing(),
+
+    // Snap to grid
+    new SnapToGrid(),
+
+    // Suppress auto hyphens
+    new SuppressAutoHyphens { Val = OnOffValueValues.Off }
+);
+
+// ===========================================================================
+// 4.22 APPLYING PARAGRAPH PROPERTIES
+// ===========================================================================
+// ParagraphProperties can be applied in multiple ways:
+
+// Method 1: Inline in Paragraph (direct formatting)
+Paragraph inlineParaProps = new Paragraph(
+    new ParagraphProperties(
+        new Justification { Val = JustificationValues.Center },
+        new SpacingBetweenLines { After = "200" }
+    ),
+    new Run(new Text("Centered paragraph with space after"))
+);
+
+// Method 2: Via ParagraphStyleId (paragraph style)
+Paragraph styledParagraph = new Paragraph(
+    new ParagraphProperties(
+        new ParagraphStyleId { Val = "Heading1" }
+    ),
+    new Run(new Text("This is Heading 1"))
+);
+
+// Method 3: In Style definition (style-level)
+Style bodyTextStyle = new Style(
+    new StyleName { Val = "BodyText" },
+    new BasedOn { Val = "Normal" },
+    new StyleParagraphProperties(
+        new Justification { Val = JustificationValues.Both },  // Justify
+        new SpacingBetweenLines { After = "160", Line = "276", LineRule = LineSpacingRuleValues.Auto },
+        new Indentation { FirstLine = "568" }  // First line indent 0.5"
+    ),
+    new StyleRunProperties(
+        new FontSize { Val = "22" }
+    )
+)
+{ Type = StyleValues.Paragraph, StyleId = "BodyText" };
+
+// Method 4: Combination (style + direct overrides)
+Paragraph mixedParaProps = new Paragraph(
+    new ParagraphProperties(
+        new ParagraphStyleId { Val = "BodyText" },  // Apply style
+        new Justification { Val = JustificationValues.Left }  // Override justification
+    ),
+    new Run(new Text("Body text style but left-aligned"))
+);
+
+// ===========================================================================
+// 4.23 COMMON PATTERNS
+// ===========================================================================
+// Heading paragraph (with style + keep options)
+Paragraph headingPara = new Paragraph(
+    new ParagraphProperties(
+        new ParagraphStyleId { Val = "Heading1" },
+        new KeepNext(),
+        new KeepLines(),
+        new SpacingBetweenLines { Before = "480", After = "120" },
+        new OutlineLevel { Val = 0 }
+    ),
+    new Run(new Text("Chapter One"))
+);
+
+// Quote paragraph (indented, italic)
+Paragraph quotePara = new Paragraph(
+    new ParagraphProperties(
+        new Indentation { Left = "1440", Right = "1440" },
+        new SpacingBetweenLines { Before = "240", After = "240" },
+        new ParagraphBorders(
+            new LeftBorder
+            {
+                Val = BorderValues.Single,
+                Size = 24,
+                Color = "4472C4",
+                Space = 8
+            }
+        )
+    ),
+    new Run(
+        new RunProperties(new Italic()),
+        new Text("To be, or not to be, that is the question."))
+);
+
+// List item paragraph (hanging indent pattern)
+Paragraph listItemPara = new Paragraph(
+    new ParagraphProperties(
+        new NumberingProperties(
+            new NumberingLevelReference { Val = 0 },
+            new NumberingId { Val = 1 }
+        ),
+        new Indentation { Left = "720", Hanging = "360" }
+    ),
+    new Run(new Text("• List item text"))
+);
+
+// Block quote / callout (background, left border)
+Paragraph blockQuotePara = new Paragraph(
+    new ParagraphProperties(
+        new Indentation { Left = "720" },
+        new Shading
+        {
+            Val = ShadingPatternValues.Clear,
+            Fill = "F5F5F5"
+        },
+        new ParagraphBorders(
+            new LeftBorder
+            {
+                Val = BorderValues.Single,
+                Size = 12,
+                Color = "999999",
+                Space = 8
+            }
+        ),
+        new SpacingBetweenLines { Before = "120", After = "120" }
+    ),
+    new Run(new Text("Block quote text"))
+);
+
+// Caption (centered, small text, below figure)
+Paragraph captionPara = new Paragraph(
+    new ParagraphProperties(
+        new Justification { Val = JustificationValues.Center },
+        new SpacingBetweenLines { Before = "0", After = "240" },
+        new ParagraphStyleId { Val = "Caption" }
+    ),
+    new Run(
+        new RunProperties(
+            new FontSize { Val = "20" },  // 10pt
+            new Italic()
+        ),
+        new Text("Figure 1: Sample caption"))
+);
+
+// Page title (large, centered, space after)
+Paragraph pageTitlePara = new Paragraph(
+    new ParagraphProperties(
+        new Justification { Val = JustificationValues.Center },
+        new SpacingBetweenLines { After = "480" },
+        new KeepLines(),
+        new ParagraphBorders(
+            new BottomBorder
+            {
+                Val = BorderValues.Single,
+                Size = 4,
+                Color = "000000",
+                Space = 4
+            }
+        )
+    ),
+    new Run(
+        new RunProperties(
+            new FontSize { Val = "56" },  // 28pt
+            new Bold()
+        ),
+        new Text("Document Title"))
+);
+
+// Signature line (right-aligned, with tab for signature)
+Paragraph signatureLinePara = new Paragraph(
+    new ParagraphProperties(
+        new Tabs(
+            new TabStop { Position = 5760, Val = TabStopValues.Right }  // 4" right tab
+        )
+    ),
+    new Run(new Text("Name: ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new TabChar()),
+    new Run(new Text("Date: ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new TabChar()),
+    new Run(new Text("Signature: ") { Space = SpaceProcessingModeValues.Preserve })
+);
+
+// Bibliography entry (hanging indent, single-spaced)
+Paragraph bibliographyEntry = new Paragraph(
+    new ParagraphProperties(
+        new Indentation { Left = "720", Hanging = "720" },
+        new SpacingBetweenLines { Line = "240", LineRule = LineSpacingRuleValues.Auto },
+        new Bibliography()
+    ),
+    new Run(new Text("Smith, J. (2024). The Art of OpenXML. New York: Publisher."))
+);
+
+// ===========================================================================
+// 4.24 UNIT SYSTEM QUICK REFERENCE
+// ===========================================================================
+// DXA (Twentieths of a DXA / Twips):
+//   1 inch = 1440 DXA
+//   1 cm ≈ 567 DXA
+//   1 pt = 20 DXA
+//   Used for: margins, indents, spacing, tab stops, borders
+//
+// Half-Points (Font Size):
+//   24 = 12pt
+//   22 = 11pt
+//   20 = 10pt
+//   Used for: FontSize.Val
+//
+// Points (pt):
+//   Used for: border widths, some line spacing values
+//
+// EMU (English Metric Units):
+//   1 inch = 914400 EMU
+//   Used for: drawing objects, images, shapes
+//
+// COMMON DXA VALUES:
+//   720 = 0.5 inch
+//   1440 = 1 inch
+//   2160 = 1.5 inches
+//   2880 = 2 inches
+//   4320 = 3 inches
+//   5760 = 4 inches
+//   8640 = 6 inches
+```
+
+---
+
+## Appendix A: Complete Working Example
+
+```csharp
+// =============================================================================
+// COMPLETE WORKING EXAMPLE: BUSINESS REPORT
+// =============================================================================
+// This example demonstrates a complete, professional document with
+// all concepts covered in this encyclopedia.
+
+using DocumentFormat.OpenXml;
+using DocumentFormat.OpenXml.Packaging;
+using DocumentFormat.OpenXml.Wordprocessing;
+
+namespace OpenXmlExamples;
+
+public static class BusinessReportGenerator
+{
+    public static void Generate(string outputPath)
+    {
+        using var doc = WordprocessingDocument.Create(
+            outputPath,
+            WordprocessingDocumentType.Document);
+
+        var mainPart = doc.MainDocumentPart!;
+        mainPart.Document = new Document(new Body());
+        var body = mainPart.Document.Body!;
+
+        // Add all parts
+        AddStyles(mainPart);
+        AddNumbering(mainPart);
+        AddSettings(mainPart);
+        AddTheme(mainPart);
+        AddHeadersAndFooters(mainPart);
+
+        // Add content
+        AddTitle(body);
+        AddTableOfContents(body);
+        AddExecutiveSummary(body);
+        AddSection(body, "Introduction", @"
+            This is the introduction section of the business report.
+            It contains multiple paragraphs with various formatting.");
+        AddSection(body, "Methodology", @"
+            Our methodology section describes the approach taken.
+            Bulleted lists are used for key points:");
+        AddBulletPoints(body, new[]
+        {
+            "First methodology point",
+            "Second methodology point",
+            "Third methodology point with more text to demonstrate wrapping"
+        });
+        AddSection(body, "Results", @"
+            The results section presents data in tables:");
+        AddSampleTable(body);
+        AddSection(body, "Conclusion", @"
+            In conclusion, this report demonstrates the capabilities of the OpenXML SDK.
+            The formatting options are comprehensive and allow for professional document generation.");
+
+        // Section properties (must be last)
+        body.Append(CreateSectionProperties(mainPart));
+
+        mainPart.Document.Save();
+    }
+
+    private static void AddStyles(MainDocumentPart mainPart)
+    {
+        var stylesPart = mainPart.AddNewPart<StyleDefinitionsPart>();
+        var styles = CreateBusinessStyles();
+        stylesPart.Styles = styles;
+        stylesPart.Styles.Save();
+    }
+
+    private static Styles CreateBusinessStyles()
+    {
+        var styles = new Styles();
+
+        // DocDefaults
+        styles.Append(new DocDefaults(
+            new RunPropertiesDefault(
+                new RunPropertiesBaseStyle(
+                    new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
+                    new FontSize { Val = "22" },
+                    new FontSizeComplexScript { Val = "22" },
+                    new Languages { Val = "en-US" }
+                )
+            ),
+            new ParagraphPropertiesDefault(
+                new ParagraphPropertiesBaseStyle(
+                    new SpacingBetweenLines { After = "200", Line = "276", LineRule = LineSpacingRuleValues.Auto }
+                )
+            )
+        ));
+
+        // Normal
+        styles.Append(new Style(
+            new StyleName { Val = "Normal" },
+            new PrimaryStyle(),
+            new StyleRunProperties(
+                new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
+                new FontSize { Val = "22" }
+            )
+        )
+        { Type = StyleValues.Paragraph, StyleId = "Normal", Default = true });
+
+        // Title
+        styles.Append(new Style(
+            new StyleName { Val = "Title" },
+            new BasedOn { Val = "Normal" },
+            new NextParagraphStyle { Val = "Normal" },
+            new PrimaryStyle(),
+            new QuickStyle(),
+            new StyleParagraphProperties(
+                new Justification { Val = JustificationValues.Center },
+                new SpacingBetweenLines { After = "300" },
+                new KeepNext(),
+                new KeepLines()
+            ),
+            new StyleRunProperties(
+                new RunFonts { Ascii = "Calibri Light", HighAnsi = "Calibri Light" },
+                new FontSize { Val = "56" },
+                new Bold(),
+                new Color { Val = "1F497D" }
+            )
+        )
+        { Type = StyleValues.Paragraph, StyleId = "Title" });
+
+        // Heading 1
+        styles.Append(new Style(
+            new StyleName { Val = "heading 1" },
+            new BasedOn { Val = "Normal" },
+            new NextParagraphStyle { Val = "Normal" },
+            new PrimaryStyle(),
+            new QuickStyle(),
+            new StyleParagraphProperties(
+                new KeepNext(),
+                new KeepLines(),
+                new SpacingBetweenLines { Before = "480", After = "120" },
+                new OutlineLevel { Val = 0 },
+                new ParagraphBorders(
+                    new BottomBorder { Val = BorderValues.Single, Size = 4, Color = "4472C4", Space = 4 }
+                )
+            ),
+            new StyleRunProperties(
+                new RunFonts { Ascii = "Calibri Light", HighAnsi = "Calibri Light" },
+                new FontSize { Val = "48" },
+                new Bold(),
+                new Color { Val = "1F497D" }
+            )
+        )
+        { Type = StyleValues.Paragraph, StyleId = "Heading1" });
+
+        // Heading 2
+        styles.Append(new Style(
+            new StyleName { Val = "heading 2" },
+            new BasedOn { Val = "Normal" },
+            new NextParagraphStyle { Val = "Normal" },
+            new PrimaryStyle(),
+            new QuickStyle(),
+            new StyleParagraphProperties(
+                new KeepNext(),
+                new SpacingBetweenLines { Before = "240", After = "120" },
+                new OutlineLevel { Val = 1 }
+            ),
+            new StyleRunProperties(
+                new FontSize { Val = "32" },
+                new Bold(),
+                new Color { Val = "2F5496" }
+            )
+        )
+        { Type = StyleValues.Paragraph, StyleId = "Heading2" });
+
+        return styles;
+    }
+
+    private static void AddNumbering(MainDocumentPart mainPart)
+    {
+        var numberingPart = mainPart.AddNewPart<NumberingDefinitionsPart>();
+        var numbering = new Numbering();
+
+        var abstractNum = new AbstractNum { AbstractNumberId = 1 };
+        abstractNum.Append(new Level(
+            new StartNumberingValue { Val = 1 },
+            new NumberingFormat { Val = NumberFormatValues.Bullet },
+            new LevelText { Val = "•" },
+            new LevelJustification { Val = LevelJustificationValues.Left },
+            new PreviousParagraphProperties(
+                new Indentation { Left = "720", Hanging = "360" })
+        )
+        { LevelIndex = 0 });
+
+        numbering.Append(abstractNum);
+        numbering.Append(new NumberingInstance(
+            new AbstractNumId { Val = 1 }
+        )
+        { NumberID = 1 });
+
+        numberingPart.Numbering = numbering;
+        numberingPart.Numbering.Save();
+    }
+
+    private static void AddSettings(MainDocumentPart mainPart)
+    {
+        var settingsPart = mainPart.AddNewPart<DocumentSettingsPart>();
+        settingsPart.Settings = new Settings(
+            new Zoom { Val = "100", Percent = true },
+            new DefaultTabStop { Val = 720 },
+            new CharacterSpacingControl { Val = CharacterSpacingValues.CompressPunctuation }
+        );
+        settingsPart.Settings.Save();
+    }
+
+    private static void AddTheme(MainDocumentPart mainPart)
+    {
+        var themePart = mainPart.AddNewPart<ThemePart>();
+        themePart.Theme = new Theme(
+            new ThemeElements(
+                new ColorScheme(
+                    new Dark1Color(new Color { Val = "000000" }),
+                    new Light1Color(new Color { Val = "FFFFFF" }),
+                    new Accent1Color(new Color { Val = "4472C4" }),
+                    new Accent2Color(new Color { Val = "C0504D" }),
+                    new Accent3Color(new Color { Val = "9BBB59" }),
+                    new Accent4Color(new Color { Val = "8064A2" }),
+                    new Accent5Color(new Color { Val = "4BACC6" }),
+                    new Accent6Color(new Color { Val = "F79646" })
+                ),
+                new FontScheme(
+                    new MajorFont { Val = "Calibri Light" },
+                    new MinorFont { Val = "Calibri" }
+                )
+            ),
+            new ThemeName { Val = "Office Theme" }
+        );
+        themePart.Theme.Save();
+    }
+
+    private static void AddHeadersAndFooters(MainDocumentPart mainPart)
+    {
+        var headerPart = mainPart.AddNewPart<HeaderPart>();
+        headerPart.Header = new Header(
+            new Paragraph(
+                new ParagraphProperties(new Justification { Val = JustificationValues.Right }),
+                new Run(
+                    new RunProperties(new RunFonts { Ascii = "Calibri Light" }, new Italic(), new FontSize { Val = "18" }),
+                    new Text("Business Report"))
+            ));
+        var headerId = mainPart.GetIdOfPart(headerPart);
+
+        var footerPart = mainPart.AddNewPart<FooterPart>();
+        footerPart.Footer = new Footer(
+            new Paragraph(
+                new ParagraphProperties(new Justification { Val = JustificationValues.Center }),
+                new Run(new Text("Page ") { Space = SpaceProcessingModeValues.Preserve }),
+                new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+                new Run(new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }),
+                new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+                new Run(new Text(" of ") { Space = SpaceProcessingModeValues.Preserve }),
+                new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+                new Run(new FieldCode(" NUMPAGES ") { Space = SpaceProcessingModeValues.Preserve }),
+                new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+            ));
+        var footerId = mainPart.GetIdOfPart(footerPart);
+
+        // Store IDs for later use
+        mainPart.Document.Body!.Append(new Paragraph());  // Placeholder for sectPr
+    }
+
+    private static void AddTitle(Body body)
+    {
+        body.Append(new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "Title" }),
+            new Run(new Text("Business Report"))
+        ));
+
+        body.Append(new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "Subtitle" }),
+            new Run(new Text("Quarterly Performance Analysis"))
+        ));
+
+        body.Append(new Paragraph(
+            new ParagraphProperties(new SpacingBetweenLines { After = "400" }),
+            new Run(
+                new RunProperties(new Color { Val = "666666" }),
+                new Text("March 2026"))
+        ));
+    }
+
+    private static void AddTableOfContents(Body body)
+    {
+        body.Append(new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+            new Run(new Text("Table of Contents"))
+        ));
+
+        var tocPara = new Paragraph();
+        tocPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }));
+        tocPara.Append(new Run(new FieldCode(" TOC \\o \"1-2\" \\h \\z \\u ") { Space = SpaceProcessingModeValues.Preserve }));
+        tocPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }));
+        tocPara.Append(new Run(new Text("Update field to generate Table of Contents")));
+        tocPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.End }));
+        body.Append(tocPara);
+
+        body.Append(new Paragraph(new Run(new Break { Type = BreakValues.Page })));
+    }
+
+    private static void AddExecutiveSummary(Body body)
+    {
+        body.Append(new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+            new Run(new Text("Executive Summary"))
+        ));
+
+        body.Append(new Paragraph(
+            new Run(new Text("This executive summary provides a high-level overview of the quarterly performance. Key highlights include revenue growth, market expansion, and operational improvements."))
+        ));
+    }
+
+    private static void AddSection(Body body, string title, string content)
+    {
+        body.Append(new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+            new Run(new Text(title))
+        ));
+
+        body.Append(new Paragraph(
+            new Run(new Text(content))
+        ));
+    }
+
+    private static void AddBulletPoints(Body body, string[] points)
+    {
+        foreach (var point in points)
+        {
+            body.Append(new Paragraph(
+                new ParagraphProperties(
+                    new NumberingProperties(
+                        new NumberingLevelReference { Val = 0 },
+                        new NumberingId { Val = 1 }
+                    ),
+                    new Indentation { Left = "720", Hanging = "360" }
+                ),
+                new Run(new Text(point))
+            ));
+        }
+    }
+
+    private static void AddSampleTable(Body body)
+    {
+        var table = new Table(
+            new TableProperties(
+                new TableWidth { Width = "5000", Type = TableWidthUnitValues.Pct },
+                new TableBorders(
+                    new TopBorder { Val = BorderValues.Single, Size = 4, Color = "000000" },
+                    new BottomBorder { Val = BorderValues.Single, Size = 4, Color = "000000" },
+                    new LeftBorder { Val = BorderValues.Single, Size = 4, Color = "000000" },
+                    new RightBorder { Val = BorderValues.Single, Size = 4, Color = "000000" },
+                    new InsideHorizontalBorder { Val = BorderValues.Single, Size = 2, Color = "CCCCCC" },
+                    new InsideVerticalBorder { Val = BorderValues.Single, Size = 2, Color = "CCCCCC" }
+                ),
+                new TableCellMarginDefault(
+                    new TopMargin { Width = "50", Type = TableWidthUnitValues.DXA },
+                    new BottomMargin { Width = "50", Type = TableWidthUnitValues.DXA },
+                    new StartMargin { Width = "100", Type = TableWidthUnitValues.DXA },
+                    new EndMargin { Width = "100", Type = TableWidthUnitValues.DXA }
+                )
+            ),
+            new TableGrid(
+                new GridColumn { Width = "2000" },
+                new GridColumn { Width = "2000" },
+                new GridColumn { Width = "2000" }
+            )
+        );
+
+        // Header row
+        var headerRow = new TableRow(
+            new TableRowProperties(new TableHeader()),
+            CreateTableCell("Metric", bold: true),
+            CreateTableCell("Q1 2026", bold: true),
+            CreateTableCell("Q4 2025", bold: true)
+        );
+        table.Append(headerRow);
+
+        // Data rows
+        table.Append(CreateTableRow("Revenue", "$2.5M", "$2.1M"));
+        table.Append(CreateTableRow("Growth", "19%", "12%"));
+        table.Append(CreateTableRow("Customers", "1,250", "1,100"));
+
+        body.Append(table);
+    }
+
+    private static TableCell CreateTableCell(string text, bool bold = false)
+    {
+        var cell = new TableCell(
+            new Paragraph(
+                new Run(
+                    bold
+                        ? new RunProperties(new Bold())
+                        : new RunProperties(),
+                    new Text(text))
+            )
+        );
+        return cell;
+    }
+
+    private static TableRow CreateTableRow(string metric, string q1, string q4)
+    {
+        return new TableRow(
+            CreateTableCell(metric),
+            CreateTableCell(q1),
+            CreateTableCell(q4)
+        );
+    }
+
+    private static SectionProperties CreateSectionProperties(MainDocumentPart mainPart)
+    {
+        var sectPr = new SectionProperties();
+
+        // Header/Footer references
+        var headerPart = mainPart.HeaderParts.FirstOrDefault();
+        var footerPart = mainPart.FooterParts.FirstOrDefault();
+        if (headerPart != null)
+            sectPr.Append(new HeaderReference { Type = HeaderFooterValues.Default, Id = mainPart.GetIdOfPart(headerPart) });
+        if (footerPart != null)
+            sectPr.Append(new FooterReference { Type = HeaderFooterValues.Default, Id = mainPart.GetIdOfPart(footerPart) });
+
+        // Page size
+        sectPr.Append(new PageSize { Width = 12240u, Height = 15840u });
+
+        // Page margins
+        sectPr.Append(new PageMargin
+        {
+            Top = 1440,
+            Bottom = 1440,
+            Left = 1440u,
+            Right = 1440u,
+            Header = 720u,
+            Footer = 720u
+        });
+
+        return sectPr;
+    }
+}
+
+// ===========================================================================
+// USAGE
+// ===========================================================================
+/*
+public static void Main(string[] args)
+{
+    BusinessReportGenerator.Generate("C:\\Reports\\BusinessReport.docx");
+    Console.WriteLine("Report generated successfully!");
+}
+*/
+```
+
+---
+
+## Appendix B: OpenXmlUnits Helper Class
+
+```csharp
+// =============================================================================
+// UNIT CONVERSION HELPERS
+// =============================================================================
+// Copy this class into your project for convenient unit conversions.
+
+public static class OpenXmlUnits
+{
+    // DXA (Twentieths of a DXA / Twips) conversions
+    public static int InchesToDxa(double inches) => (int)(inches * 1440);
+    public static int CmToDxa(double cm) => (int)(cm * 567.0);
+    public static int PtToDxa(double pt) => (int)(pt * 20);
+    public static double DxaToInches(int dxa) => dxa / 1440.0;
+    public static double DxaToCm(int dxa) => dxa / 567.0;
+    public static double DxaToPt(int dxa) => dxa / 20.0;
+
+    // EMU (English Metric Units) conversions
+    public static long InchesToEmu(double inches) => (long)(inches * 914400);
+    public static long CmToEmu(double cm) => (long)(cm * 360000);
+    public static double EmuToInches(long emu) => emu / 914400.0;
+    public static double EmuToCm(long emu) => emu / 360000.0;
+
+    // Half-point conversions (font sizes)
+    public static int PtToHalfPt(double pt) => (int)(pt * 2);
+    public static int FontSizeToSz(double ptSize) => (int)(ptSize * 2);
+    public static double SzToPt(int sz) => sz / 2.0;
+
+    // Line spacing helpers
+    public static int SingleSpacing => 240;
+    public static int DoubleSpacing => 480;
+    public static int OneAndHalfSpacing => 360;
+    public static int LineSpacingPt(double pt) => (int)(pt * 20);
+
+    // Common measurements
+    public static int HalfInch => 720;
+    public static int OneInch => 1440;
+    public static int OneAndHalfInches => 2160;
+    public static int TwoInches => 2880;
+}
+```
+
+---
+
+*Document Version: 1.0*
+*OpenXML SDK: 3.x*
+*.NET Version: 10*
+*C# Version: 13*
diff --git a/builtin-skills/document-process/minimax-docx/references/openxml_encyclopedia_part2.md b/builtin-skills/document-process/minimax-docx/references/openxml_encyclopedia_part2.md
new file mode 100644
index 00000000..3cf04760
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/openxml_encyclopedia_part2.md
@@ -0,0 +1,2820 @@
+# OpenXML SDK 3.x Complete Reference Encyclopedia — Part 2
+
+**Target:** DocumentFormat.OpenXml 3.x / .NET 8+ / C# 12
+**Last Updated:** 2026-03-22
+
+This document covers page setup, tables, headers/footers, section breaks, document properties, and printing/compatibility settings. Every code block is ready to copy-paste.
+
+---
+
+## Namespace Aliases Used Throughout
+
+```csharp
+using DocumentFormat.OpenXml;
+using DocumentFormat.OpenXml.Packaging;
+using DocumentFormat.OpenXml.Wordprocessing;
+using A = DocumentFormat.OpenXml.Drawing;
+using DW = DocumentFormat.OpenXml.Drawing.Wordprocessing;
+using PIC = DocumentFormat.OpenXml.Drawing.Pictures;
+```
+
+---
+
+## Table of Contents
+
+1. [Page Setup](#1-page-setup)
+2. [Tables — Comprehensive](#2-tables--comprehensive)
+3. [Headers, Footers & Page Numbers](#3-headers-footers--page-numbers)
+4. [Section Breaks & Multi-Section](#4-section-breaks--multi-section)
+5. [Document Properties](#5-document-properties)
+6. [Printing & Compatibility Settings](#6-printing--compatibility-settings)
+
+---
+
+## 1. Page Setup
+
+Page setup is controlled via `SectionProperties`, which is placed as the **last child element** of `Body` for the final (or only) section, or inside `ParagraphProperties` for mid-document section breaks.
+
+### 1.1 PageSize — Standard Paper Sizes
+
+```csharp
+// =============================================================================
+// PAGE SIZE — STANDARD PAPER SIZES
+// =============================================================================
+// PageSize Width and Height are specified in DXA (twentieths of a point).
+// 1 inch = 1440 DXA.  1 cm ≈ 567 DXA.  1 mm ≈ 56.7 DXA.
+//
+// Common paper sizes (portrait orientation):
+//   Letter:  12240 × 15840  (8.5" × 11")
+//   A4:      11906 × 16838  (210mm × 297mm)
+//   Legal:   12240 × 20160  (8.5" × 14")
+//   A3:      16838 × 23811  (297mm × 420mm)
+//   B5:      10318 × 14570  (182mm × 257mm)
+//   16K:      10318 × 14570 (approximate, varies by region)
+
+var sectionProps = new SectionProperties();
+
+// --- Letter (US default) ---
+sectionProps.AppendChild(new PageSize
+{
+    Width = 12240U,   // 8.5 inches
+    Height = 15840U   // 11 inches
+});
+// Produces XML: <w:pgSz w:w="12240" w:h="15840" />
+
+// --- A4 (ISO default) ---
+var a4Size = new PageSize
+{
+    Width = 11906U,   // 210mm
+    Height = 16838U   // 297mm
+};
+
+// --- Legal ---
+var legalSize = new PageSize
+{
+    Width = 12240U,   // 8.5 inches
+    Height = 20160U   // 14 inches
+};
+
+// --- A3 ---
+var a3Size = new PageSize
+{
+    Width = 16838U,   // 297mm
+    Height = 23811U   // 420mm
+};
+
+body.AppendChild(sectionProps);
+```
+
+### 1.2 PageOrientation — CRITICAL Landscape Handling
+
+```csharp
+// =============================================================================
+// PAGE ORIENTATION — LANDSCAPE
+// =============================================================================
+// CRITICAL GOTCHA: Setting Orient = Landscape is NOT enough!
+// You MUST ALSO swap Width and Height values. Word uses the numeric dimensions
+// to determine actual page size; Orient only controls the print driver rotation.
+//
+// If you set Orient = Landscape but don't swap dimensions, Word will
+// display portrait but print rotated — a confusing bug.
+
+// --- Portrait (default, explicit) ---
+var portraitSize = new PageSize
+{
+    Width = 12240U,
+    Height = 15840U
+    // Orient is omitted for portrait (it's the default)
+};
+// Produces XML: <w:pgSz w:w="12240" w:h="15840" />
+
+// --- Landscape — CORRECT way ---
+var landscapeSize = new PageSize
+{
+    Width = 15840U,                                      // SWAPPED: was Height
+    Height = 12240U,                                     // SWAPPED: was Width
+    Orient = PageOrientationValues.Landscape              // AND set Orient
+};
+// Produces XML: <w:pgSz w:w="15840" w:h="12240" w:orient="landscape" />
+
+// --- Helper method for safe orientation switching ---
+static PageSize CreatePageSize(uint shortEdge, uint longEdge, bool landscape)
+{
+    return landscape
+        ? new PageSize
+        {
+            Width = longEdge,       // Long edge becomes width
+            Height = shortEdge,     // Short edge becomes height
+            Orient = PageOrientationValues.Landscape
+        }
+        : new PageSize
+        {
+            Width = shortEdge,
+            Height = longEdge
+        };
+}
+
+// Usage:
+var letterLandscape = CreatePageSize(12240, 15840, landscape: true);
+var a4Portrait = CreatePageSize(11906, 16838, landscape: false);
+```
+
+### 1.3 PageMargin — Common Presets
+
+```csharp
+// =============================================================================
+// PAGE MARGIN — ALL PROPERTIES
+// =============================================================================
+// All margin values are in DXA (twentieths of a point). 1 inch = 1440 DXA.
+//
+// Properties:
+//   Top, Bottom    — signed Int32 (can be negative for overlap)
+//   Left, Right    — unsigned UInt32
+//   Header, Footer — unsigned UInt32 (distance from page edge to header/footer)
+//   Gutter         — unsigned UInt32 (extra margin for binding; added to Left
+//                    unless GutterAtTop is set in Settings)
+
+// --- Normal / Standard (1" all around) ---
+var normalMargins = new PageMargin
+{
+    Top = 1440,         // 1 inch
+    Bottom = 1440,      // 1 inch
+    Left = 1440U,       // 1 inch
+    Right = 1440U,      // 1 inch
+    Header = 720U,      // 0.5 inch (distance from page edge)
+    Footer = 720U,      // 0.5 inch
+    Gutter = 0U         // No binding gutter
+};
+// Produces XML:
+// <w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"
+//          w:header="720" w:footer="720" w:gutter="0" />
+
+// --- Narrow (0.5" all around) ---
+var narrowMargins = new PageMargin
+{
+    Top = 720,
+    Bottom = 720,
+    Left = 720U,
+    Right = 720U,
+    Header = 720U,
+    Footer = 720U,
+    Gutter = 0U
+};
+
+// --- Moderate (1" top/bottom, 0.75" left/right) ---
+var moderateMargins = new PageMargin
+{
+    Top = 1440,
+    Bottom = 1440,
+    Left = 1080U,     // 0.75 inch
+    Right = 1080U,    // 0.75 inch
+    Header = 720U,
+    Footer = 720U,
+    Gutter = 0U
+};
+
+// --- Wide (1" top/bottom, 2" left/right) ---
+var wideMargins = new PageMargin
+{
+    Top = 1440,
+    Bottom = 1440,
+    Left = 2880U,     // 2 inches
+    Right = 2880U,    // 2 inches
+    Header = 720U,
+    Footer = 720U,
+    Gutter = 0U
+};
+
+// --- Chinese Government Document 公文 standard (GB/T 9704-2012) ---
+// Top: 37mm (2098 DXA), Bottom: 35mm (1984 DXA)
+// Left: 28mm (1588 DXA), Right: 26mm (1474 DXA)
+var chineseGovMargins = new PageMargin
+{
+    Top = 2098,        // 37mm
+    Bottom = 1984,     // 35mm
+    Left = 1588U,      // 28mm
+    Right = 1474U,     // 26mm
+    Header = 851U,     // 15mm
+    Footer = 567U,     // 10mm (approx)
+    Gutter = 0U
+};
+
+// --- With binding gutter (e.g., for book printing) ---
+var gutterMargins = new PageMargin
+{
+    Top = 1440,
+    Bottom = 1440,
+    Left = 1440U,
+    Right = 1440U,
+    Header = 720U,
+    Footer = 720U,
+    Gutter = 720U      // 0.5 inch added to left margin for binding
+};
+```
+
+### 1.4 PageBorders
+
+```csharp
+// =============================================================================
+// PAGE BORDERS
+// =============================================================================
+// PageBorders defines borders around the entire page.
+// OffsetFrom controls whether border distance is from page edge or text margin.
+//   PageBorderOffsetValues.Page = from page edge
+//   PageBorderOffsetValues.Text = from text margin
+//
+// Each border: Val (style), Size (eighth-points: 4=0.5pt, 8=1pt, 12=1.5pt),
+//              Color (hex RGB), Space (distance in points from text/page edge)
+
+var pageBorders = new PageBorders
+{
+    OffsetFrom = PageBorderOffsetValues.Page
+};
+
+// Top border: single line, 1pt, black
+pageBorders.AppendChild(new TopBorder
+{
+    Val = BorderValues.Single,
+    Size = 8U,               // 8 eighth-points = 1pt
+    Color = "000000",
+    Space = 24U              // 24 points from page edge
+});
+
+// Bottom border
+pageBorders.AppendChild(new BottomBorder
+{
+    Val = BorderValues.Single,
+    Size = 8U,
+    Color = "000000",
+    Space = 24U
+});
+
+// Left border
+pageBorders.AppendChild(new LeftBorder
+{
+    Val = BorderValues.Single,
+    Size = 8U,
+    Color = "000000",
+    Space = 24U
+});
+
+// Right border
+pageBorders.AppendChild(new RightBorder
+{
+    Val = BorderValues.Single,
+    Size = 8U,
+    Color = "000000",
+    Space = 24U
+});
+
+// --- Double border example ---
+var doubleBorder = new TopBorder
+{
+    Val = BorderValues.Double,   // Double line
+    Size = 4U,                   // 0.5pt per line
+    Color = "0000FF",            // Blue
+    Space = 24U
+};
+
+// --- Common BorderValues ---
+// Single, Double, Triple, DotDash, Dashed, Dotted, Thick, ThinThickSmallGap,
+// ThickThinSmallGap, Wave, DoubleWave, BasicBlackDots, None
+
+sectionProps.AppendChild(pageBorders);
+```
+
+### 1.5 Columns — Multi-Column Layout
+
+```csharp
+// =============================================================================
+// COLUMNS — MULTI-COLUMN LAYOUTS
+// =============================================================================
+// Columns element defines the column layout within a section.
+// Space is measured in DXA. EqualWidth=true makes all columns equal.
+
+// --- 2 equal columns ---
+var twoCols = new Columns
+{
+    EqualWidth = true,
+    ColumnCount = 2,
+    Space = "720"          // 0.5 inch gap between columns
+};
+// Produces XML: <w:cols w:num="2" w:space="720" w:equalWidth="1" />
+
+// --- 3 equal columns with separator ---
+var threeColsSep = new Columns
+{
+    EqualWidth = true,
+    ColumnCount = 3,
+    Space = "360",         // 0.25 inch gap
+    Separator = true       // Vertical line between columns
+};
+// Produces XML: <w:cols w:num="3" w:space="360" w:equalWidth="1" w:sep="1" />
+
+// --- Custom unequal columns (e.g., 2/3 + 1/3 of content width) ---
+// When using unequal widths, EqualWidth must be false and you define
+// each column explicitly with Column elements.
+// For Letter page with 1" margins: content width = 12240 - 1440 - 1440 = 9360 DXA
+// Column 1: 6000 DXA wide, 360 DXA space after
+// Column 2: 3000 DXA wide (6000 + 360 + 3000 = 9360)
+
+var unequalCols = new Columns { EqualWidth = false };
+unequalCols.AppendChild(new Column
+{
+    Width = "6000",
+    Space = "360"
+});
+unequalCols.AppendChild(new Column
+{
+    Width = "3000"
+    // No Space on last column
+});
+// Produces XML:
+// <w:cols w:equalWidth="0">
+//   <w:col w:w="6000" w:space="360" />
+//   <w:col w:w="3000" />
+// </w:cols>
+
+sectionProps.AppendChild(unequalCols);
+```
+
+### 1.6 LineNumbering
+
+```csharp
+// =============================================================================
+// LINE NUMBERING
+// =============================================================================
+// LineNumbering adds line numbers in the margin. Useful for legal/academic docs.
+// CountBy = show every Nth number (1 = every line, 5 = every 5th)
+// Start = starting number
+// Distance = distance from text in DXA
+// Restart: NewPage, NewSection, Continuous
+
+var lineNums = new LineNumbering
+{
+    CountBy = 5,                                         // Show every 5th line number
+    Start = 1,                                           // Start at line 1
+    Distance = 360U,                                     // 0.25 inch from text
+    Restart = LineNumberRestartValues.NewPage             // Restart each page
+};
+// Produces XML:
+// <w:lnNumType w:countBy="5" w:start="1" w:distance="360" w:restart="newPage" />
+
+sectionProps.AppendChild(lineNums);
+```
+
+### 1.7 DocGrid — CJK Document Grid
+
+```csharp
+// =============================================================================
+// DOCUMENT GRID — CJK LAYOUT
+// =============================================================================
+// DocGrid specifies a document grid (character grid) primarily for CJK documents.
+// Type: Default (no grid), Lines (line grid), LinesAndChars (line+char grid),
+//       SnapToChars (snap to character grid)
+// LinePitch = distance between lines in DXA (e.g., 312 for standard Chinese docs)
+// CharacterSpace = extra spacing between characters in DXA
+
+// --- Chinese document grid: 28 lines × 28 chars per line (common for 公文) ---
+var cjkGrid = new DocGrid
+{
+    Type = DocGridValues.LinesAndChars,
+    LinePitch = 579,          // DXA between lines (≈ 28 lines on A4 with std margins)
+    CharacterSpace = 0        // Default character spacing
+};
+// Produces XML:
+// <w:docGrid w:type="linesAndChars" w:linePitch="579" w:charSpace="0" />
+
+// --- Simple line-only grid ---
+var lineGrid = new DocGrid
+{
+    Type = DocGridValues.Lines,
+    LinePitch = 360            // Standard line pitch
+};
+
+sectionProps.AppendChild(cjkGrid);
+```
+
+### 1.8 VerticalTextAlignmentOnPage
+
+```csharp
+// =============================================================================
+// VERTICAL TEXT ALIGNMENT ON PAGE
+// =============================================================================
+// Controls vertical alignment of text within the page (above bottom margin).
+// Values: Top (default), Center, Both (justified), Bottom
+
+var vertAlign = new VerticalTextAlignmentOnPage
+{
+    Val = VerticalJustificationValues.Center
+};
+// Produces XML: <w:vAlign w:val="center" />
+// Use case: Title pages, certificate pages
+
+sectionProps.AppendChild(vertAlign);
+```
+
+### 1.9 Complete Page Setup Example
+
+```csharp
+// =============================================================================
+// COMPLETE PAGE SETUP — PUTTING IT ALL TOGETHER
+// =============================================================================
+// A4 portrait, moderate margins, 2-column layout with separator
+
+using var doc = WordprocessingDocument.Create(
+    "PageSetupDemo.docx", WordprocessingDocumentType.Document);
+
+var mainPart = doc.MainDocumentPart!;
+var body = mainPart.Document.Body!;
+
+// Add content paragraphs ...
+body.AppendChild(new Paragraph(
+    new Run(new Text("This is a two-column document on A4 paper."))));
+
+// Section properties — MUST be last child of Body
+var sectPr = new SectionProperties();
+
+// Page size: A4 portrait
+sectPr.AppendChild(new PageSize
+{
+    Width = 11906U,
+    Height = 16838U
+});
+
+// Margins: moderate
+sectPr.AppendChild(new PageMargin
+{
+    Top = 1440, Bottom = 1440,
+    Left = 1080U, Right = 1080U,
+    Header = 720U, Footer = 720U, Gutter = 0U
+});
+
+// 2-column with separator
+sectPr.AppendChild(new Columns
+{
+    EqualWidth = true,
+    ColumnCount = 2,
+    Space = "720",
+    Separator = true
+});
+
+// Line grid for CJK
+sectPr.AppendChild(new DocGrid
+{
+    Type = DocGridValues.Lines,
+    LinePitch = 312
+});
+
+body.AppendChild(sectPr);
+mainPart.Document.Save();
+```
+
+---
+
+## 2. Tables — Comprehensive
+
+### 2.1 TableProperties — Width, Layout, Alignment, Indent
+
+```csharp
+// =============================================================================
+// TABLE PROPERTIES — WIDTH, LAYOUT, ALIGNMENT
+// =============================================================================
+// Table width can be specified in three ways:
+//   Pct:  percentage of page width. 5000 = 100%. (multiply % by 50)
+//   Dxa:  absolute width in DXA (twentieths of a point). 1 inch = 1440 DXA.
+//   Auto: table auto-sizes to content.
+//
+// TableLayout:
+//   Fixed: columns maintain exact widths. Required for complex cell sizing.
+//   Autofit: columns adjust to content (default).
+//
+// TableJustification: Left (default), Center, Right
+
+var table = new Table();
+
+var tblProps = new TableProperties();
+
+// --- Width: 100% of page ---
+tblProps.AppendChild(new TableWidth
+{
+    Width = "5000",                           // 5000 = 100%
+    Type = TableWidthUnitValues.Pct
+});
+// Produces XML: <w:tblW w:w="5000" w:type="pct" />
+
+// --- Width: fixed DXA ---
+// var tblWidth = new TableWidth { Width = "9360", Type = TableWidthUnitValues.Dxa };
+
+// --- Width: auto ---
+// var tblWidth = new TableWidth { Width = "0", Type = TableWidthUnitValues.Auto };
+
+// Layout: fixed column widths
+tblProps.AppendChild(new TableLayout
+{
+    Type = TableLayoutValues.Fixed
+});
+
+// Center the table on the page
+tblProps.AppendChild(new TableJustification
+{
+    Val = TableRowAlignmentValues.Center
+});
+
+// Table indent (left offset when not centered) — in DXA
+// tblProps.AppendChild(new TableIndentation
+// {
+//     Width = 720,                           // 0.5 inch indent
+//     Type = TableWidthUnitValues.Dxa
+// });
+
+table.AppendChild(tblProps);
+```
+
+### 2.2 TableBorders — All Border Properties
+
+```csharp
+// =============================================================================
+// TABLE BORDERS
+// =============================================================================
+// TableBorders defines default borders for the entire table.
+// Each border has:
+//   Val   — BorderValues enum (Single, Double, Dotted, Dashed, None, etc.)
+//   Size  — in eighth-points: 4 = 0.5pt, 8 = 1pt, 12 = 1.5pt, 16 = 2pt, 24 = 3pt
+//   Color — hex RGB string (e.g., "000000" for black, "FF0000" for red)
+//   Space — space between border and content in points
+//
+// Border types: TopBorder, BottomBorder, LeftBorder, RightBorder,
+//               InsideHorizontalBorder, InsideVerticalBorder
+
+var tblBorders = new TableBorders();
+
+// Top border: single, 1pt, black
+tblBorders.AppendChild(new TopBorder
+{
+    Val = BorderValues.Single,
+    Size = 8U,           // 1pt (8 eighth-points)
+    Color = "000000",
+    Space = 0U
+});
+
+// Bottom border
+tblBorders.AppendChild(new BottomBorder
+{
+    Val = BorderValues.Single,
+    Size = 8U,
+    Color = "000000",
+    Space = 0U
+});
+
+// Left border
+tblBorders.AppendChild(new LeftBorder
+{
+    Val = BorderValues.Single,
+    Size = 8U,
+    Color = "000000",
+    Space = 0U
+});
+
+// Right border
+tblBorders.AppendChild(new RightBorder
+{
+    Val = BorderValues.Single,
+    Size = 8U,
+    Color = "000000",
+    Space = 0U
+});
+
+// Inside horizontal borders (between rows)
+tblBorders.AppendChild(new InsideHorizontalBorder
+{
+    Val = BorderValues.Single,
+    Size = 4U,           // 0.5pt — thinner than outer borders
+    Color = "000000",
+    Space = 0U
+});
+
+// Inside vertical borders (between columns)
+tblBorders.AppendChild(new InsideVerticalBorder
+{
+    Val = BorderValues.Single,
+    Size = 4U,
+    Color = "000000",
+    Space = 0U
+});
+
+// Produces XML:
+// <w:tblBorders>
+//   <w:top w:val="single" w:sz="8" w:color="000000" w:space="0" />
+//   <w:bottom w:val="single" w:sz="8" w:color="000000" w:space="0" />
+//   <w:left w:val="single" w:sz="8" w:color="000000" w:space="0" />
+//   <w:right w:val="single" w:sz="8" w:color="000000" w:space="0" />
+//   <w:insideH w:val="single" w:sz="4" w:color="000000" w:space="0" />
+//   <w:insideV w:val="single" w:sz="4" w:color="000000" w:space="0" />
+// </w:tblBorders>
+
+tblProps.AppendChild(tblBorders);
+```
+
+### 2.3 TableGrid — Column Definitions
+
+```csharp
+// =============================================================================
+// TABLE GRID — COLUMN WIDTH DEFINITIONS
+// =============================================================================
+// TableGrid defines the column structure of the table. Each GridColumn
+// specifies the width in DXA. The number of GridColumn elements determines
+// the number of columns.
+//
+// IMPORTANT: GridColumn widths should sum to the table width.
+// For a 100% table on Letter with 1" margins: 12240 - 1440 - 1440 = 9360 DXA
+
+var tableGrid = new TableGrid();
+
+// 3 columns: 3000 + 3000 + 3360 = 9360 DXA
+tableGrid.AppendChild(new GridColumn { Width = "3000" });
+tableGrid.AppendChild(new GridColumn { Width = "3000" });
+tableGrid.AppendChild(new GridColumn { Width = "3360" });
+
+// Produces XML:
+// <w:tblGrid>
+//   <w:gridCol w:w="3000" />
+//   <w:gridCol w:w="3000" />
+//   <w:gridCol w:w="3360" />
+// </w:tblGrid>
+
+table.AppendChild(tableGrid);
+```
+
+### 2.4 TableCellProperties — Width, Alignment, Direction, Shading
+
+```csharp
+// =============================================================================
+// TABLE CELL PROPERTIES
+// =============================================================================
+// TableCellProperties controls individual cell appearance.
+
+var cellProps = new TableCellProperties();
+
+// Cell width — should match the GridColumn width
+cellProps.AppendChild(new TableCellWidth
+{
+    Width = "3000",
+    Type = TableWidthUnitValues.Dxa
+});
+
+// Vertical alignment within cell: Top (default), Center, Bottom
+cellProps.AppendChild(new TableCellVerticalAlignment
+{
+    Val = TableVerticalAlignmentValues.Center
+});
+
+// Text direction (for vertical text in CJK, etc.)
+// Values: LefToRight (default), TopToBottom (text rotated 90° CW),
+//         TopToBottomV (vertical CJK), BottomToTopV
+cellProps.AppendChild(new TextDirection
+{
+    Val = TextDirectionValues.TopToBottom
+});
+
+// NoWrap — prevents text from wrapping within the cell
+cellProps.AppendChild(new NoWrap());
+
+// Cell shading (background color)
+cellProps.AppendChild(new Shading
+{
+    Val = ShadingPatternValues.Clear,
+    Color = "auto",
+    Fill = "D9E2F3"          // Light blue background
+});
+// Produces XML: <w:shd w:val="clear" w:color="auto" w:fill="D9E2F3" />
+```
+
+### 2.5 TableCellMargin — Table-Level Default vs Per-Cell Override
+
+```csharp
+// =============================================================================
+// TABLE CELL MARGINS
+// =============================================================================
+// There are TWO levels of cell margin control:
+//   1. Table-level default: TableCellMarginDefault (inside TableProperties)
+//   2. Per-cell override:   TableCellMargin (inside TableCellProperties)
+//
+// All values are in DXA. Default Word cell margins are approximately:
+//   Top: 0, Bottom: 0, Left: 108 (0.075"), Right: 108
+
+// --- Table-level default margins ---
+var defaultMargins = new TableCellMarginDefault();
+defaultMargins.AppendChild(new TopMargin
+{
+    Width = "72",                             // ~0.05 inch
+    Type = TableWidthUnitValues.Dxa
+});
+defaultMargins.AppendChild(new BottomMargin
+{
+    Width = "72",
+    Type = TableWidthUnitValues.Dxa
+});
+defaultMargins.AppendChild(new StartMargin
+{
+    Width = "108",                            // ~0.075 inch (default)
+    Type = TableWidthUnitValues.Dxa
+});
+defaultMargins.AppendChild(new EndMargin
+{
+    Width = "108",
+    Type = TableWidthUnitValues.Dxa
+});
+
+tblProps.AppendChild(defaultMargins);
+// Produces XML:
+// <w:tblCellMar>
+//   <w:top w:w="72" w:type="dxa" />
+//   <w:bottom w:w="72" w:type="dxa" />
+//   <w:start w:w="108" w:type="dxa" />
+//   <w:end w:w="108" w:type="dxa" />
+// </w:tblCellMar>
+
+// --- Per-cell override (larger padding for a specific cell) ---
+var cellMarginOverride = new TableCellMargin();
+cellMarginOverride.AppendChild(new TopMargin
+{
+    Width = "144",                            // 0.1 inch
+    Type = TableWidthUnitValues.Dxa
+});
+cellMarginOverride.AppendChild(new BottomMargin
+{
+    Width = "144",
+    Type = TableWidthUnitValues.Dxa
+});
+cellMarginOverride.AppendChild(new StartMargin
+{
+    Width = "216",                            // 0.15 inch
+    Type = TableWidthUnitValues.Dxa
+});
+cellMarginOverride.AppendChild(new EndMargin
+{
+    Width = "216",
+    Type = TableWidthUnitValues.Dxa
+});
+
+cellProps.AppendChild(cellMarginOverride);
+```
+
+### 2.6 Row Height
+
+```csharp
+// =============================================================================
+// TABLE ROW HEIGHT
+// =============================================================================
+// TableRowHeight is set inside TableRowProperties.
+// Val = height in DXA
+// HeightRuleType:
+//   Exact:   row is exactly this height (content may be clipped)
+//   AtLeast: row is at least this height, grows for content (default behavior)
+//   Auto:    height determined by content
+
+var rowProps = new TableRowProperties();
+
+// Row height: at least 0.5 inch
+rowProps.AppendChild(new TableRowHeight
+{
+    Val = 720U,                                // 0.5 inch in DXA
+    HeightRule = HeightRuleValues.AtLeast
+});
+// Produces XML: <w:trHeight w:val="720" w:hRule="atLeast" />
+
+// Exact height (content may clip):
+// rowProps.AppendChild(new TableRowHeight
+// {
+//     Val = 720U,
+//     HeightRule = HeightRuleValues.Exact
+// });
+
+var row = new TableRow();
+row.AppendChild(rowProps);
+```
+
+### 2.7 Header Row Repeat (Repeat on Every Page)
+
+```csharp
+// =============================================================================
+// HEADER ROW REPEAT
+// =============================================================================
+// TableHeader on TableRowProperties marks a row to repeat at the top
+// of each page when the table spans multiple pages.
+// IMPORTANT: Only works for rows at the TOP of the table (contiguous from first row).
+// You cannot repeat a row in the middle of a table.
+
+var headerRowProps = new TableRowProperties();
+headerRowProps.AppendChild(new TableHeader());  // No value needed — presence = true
+
+// Produces XML:
+// <w:trPr>
+//   <w:tblHeader />
+// </w:trPr>
+
+var headerRow = new TableRow();
+headerRow.AppendChild(headerRowProps);
+// ... add cells to headerRow ...
+```
+
+### 2.8 Per-Cell Border Override
+
+```csharp
+// =============================================================================
+// PER-CELL BORDER OVERRIDE
+// =============================================================================
+// TableCellBorders inside TableCellProperties overrides table-level borders
+// for a specific cell. Useful for special formatting, merging visual areas, etc.
+
+var cellBorders = new TableCellBorders();
+
+// Remove bottom border on this cell
+cellBorders.AppendChild(new BottomBorder
+{
+    Val = BorderValues.None,
+    Size = 0U,
+    Color = "auto",
+    Space = 0U
+});
+
+// Add thick right border
+cellBorders.AppendChild(new RightBorder
+{
+    Val = BorderValues.Single,
+    Size = 24U,          // 3pt thick
+    Color = "FF0000",    // Red
+    Space = 0U
+});
+
+// Produces XML:
+// <w:tcBorders>
+//   <w:bottom w:val="none" w:sz="0" w:color="auto" w:space="0" />
+//   <w:right w:val="single" w:sz="24" w:color="FF0000" w:space="0" />
+// </w:tcBorders>
+
+cellProps.AppendChild(cellBorders);
+```
+
+### 2.9 Horizontal Merge (GridSpan)
+
+```csharp
+// =============================================================================
+// HORIZONTAL MERGE — GRIDSPAN
+// =============================================================================
+// To merge cells horizontally, use GridSpan on the first cell's properties.
+// The cell spans across multiple grid columns. You do NOT add extra cells
+// for the spanned columns — only one cell covers the span.
+//
+// Example: 3-column table, first row merges columns 1+2
+
+var mergedRow = new TableRow();
+
+// Cell spanning columns 1 and 2
+var spanCell = new TableCell();
+var spanCellProps = new TableCellProperties();
+spanCellProps.AppendChild(new GridSpan { Val = 2 });      // Span 2 columns
+spanCellProps.AppendChild(new TableCellWidth
+{
+    Width = "6000",                                        // Combined width: 3000 + 3000
+    Type = TableWidthUnitValues.Dxa
+});
+spanCell.AppendChild(spanCellProps);
+spanCell.AppendChild(new Paragraph(new Run(new Text("Spans columns 1-2"))));
+mergedRow.AppendChild(spanCell);
+
+// Cell in column 3 (normal)
+var normalCell = new TableCell();
+normalCell.AppendChild(new TableCellProperties(
+    new TableCellWidth { Width = "3360", Type = TableWidthUnitValues.Dxa }));
+normalCell.AppendChild(new Paragraph(new Run(new Text("Column 3"))));
+mergedRow.AppendChild(normalCell);
+
+// Produces XML for the merged cell:
+// <w:tc>
+//   <w:tcPr>
+//     <w:gridSpan w:val="2" />
+//     <w:tcW w:w="6000" w:type="dxa" />
+//   </w:tcPr>
+//   <w:p><w:r><w:t>Spans columns 1-2</w:t></w:r></w:p>
+// </w:tc>
+```
+
+### 2.10 Vertical Merge
+
+```csharp
+// =============================================================================
+// VERTICAL MERGE
+// =============================================================================
+// To merge cells vertically across rows, use VerticalMerge:
+//   First row: VerticalMerge with Val = Restart  (starts the merge)
+//   Subsequent rows: VerticalMerge with Val = Continue (or omit Val — Continue is default)
+//
+// Each row still needs the cell placeholder, but continue cells should contain
+// an empty paragraph only.
+
+// Row 1: start of vertical merge
+var vRow1 = new TableRow();
+var vCell1 = new TableCell();
+var vCellProps1 = new TableCellProperties();
+vCellProps1.AppendChild(new VerticalMerge { Val = MergedCellValues.Restart });
+vCellProps1.AppendChild(new TableCellWidth { Width = "3000", Type = TableWidthUnitValues.Dxa });
+vCell1.AppendChild(vCellProps1);
+vCell1.AppendChild(new Paragraph(new Run(new Text("Merged vertically"))));
+vRow1.AppendChild(vCell1);
+// ... add remaining cells in row 1
+
+// Row 2: continue the vertical merge
+var vRow2 = new TableRow();
+var vCell2 = new TableCell();
+var vCellProps2 = new TableCellProperties();
+vCellProps2.AppendChild(new VerticalMerge());  // Val omitted = Continue
+vCellProps2.AppendChild(new TableCellWidth { Width = "3000", Type = TableWidthUnitValues.Dxa });
+vCell2.AppendChild(vCellProps2);
+vCell2.AppendChild(new Paragraph());           // Empty paragraph required — cell must have content
+vRow2.AppendChild(vCell2);
+// ... add remaining cells in row 2
+
+// Row 3: if no VerticalMerge, the merge stops and this cell is independent.
+
+// Produces XML:
+// Row 1 cell: <w:tcPr><w:vMerge w:val="restart" /></w:tcPr>
+// Row 2 cell: <w:tcPr><w:vMerge /></w:tcPr>  (continue is the default)
+```
+
+### 2.11 Nested Tables
+
+```csharp
+// =============================================================================
+// NESTED TABLES
+// =============================================================================
+// A table can be nested inside a table cell. Simply add a Table element
+// as a child of a TableCell (alongside the required Paragraph).
+// IMPORTANT: Every TableCell MUST contain at least one Paragraph, even if
+// it also contains a nested table. The Paragraph should come AFTER the table.
+
+var outerTable = new Table();
+// ... outer table properties and grid ...
+
+var containerCell = new TableCell();
+containerCell.AppendChild(new TableCellProperties(
+    new TableCellWidth { Width = "6000", Type = TableWidthUnitValues.Dxa }));
+
+// Build inner (nested) table
+var innerTable = new Table();
+var innerProps = new TableProperties();
+innerProps.AppendChild(new TableWidth { Width = "5000", Type = TableWidthUnitValues.Pct });
+innerProps.AppendChild(new TableBorders(
+    new TopBorder { Val = BorderValues.Single, Size = 4U, Color = "999999" },
+    new BottomBorder { Val = BorderValues.Single, Size = 4U, Color = "999999" },
+    new LeftBorder { Val = BorderValues.Single, Size = 4U, Color = "999999" },
+    new RightBorder { Val = BorderValues.Single, Size = 4U, Color = "999999" },
+    new InsideHorizontalBorder { Val = BorderValues.Single, Size = 4U, Color = "999999" },
+    new InsideVerticalBorder { Val = BorderValues.Single, Size = 4U, Color = "999999" }
+));
+innerTable.AppendChild(innerProps);
+
+var innerGrid = new TableGrid(
+    new GridColumn { Width = "2500" },
+    new GridColumn { Width = "2500" });
+innerTable.AppendChild(innerGrid);
+
+var innerRow = new TableRow(
+    new TableCell(
+        new TableCellProperties(new TableCellWidth { Width = "2500", Type = TableWidthUnitValues.Dxa }),
+        new Paragraph(new Run(new Text("Inner A")))),
+    new TableCell(
+        new TableCellProperties(new TableCellWidth { Width = "2500", Type = TableWidthUnitValues.Dxa }),
+        new Paragraph(new Run(new Text("Inner B"))))
+);
+innerTable.AppendChild(innerRow);
+
+// Add inner table to container cell
+containerCell.AppendChild(innerTable);
+// MUST have a paragraph after nested table
+containerCell.AppendChild(new Paragraph());
+```
+
+### 2.12 Table Positioning (Floating Table)
+
+```csharp
+// =============================================================================
+// TABLE POSITIONING — FLOATING TABLE
+// =============================================================================
+// TablePositionProperties makes a table "float" at a specific position
+// on the page, allowing text to wrap around it.
+// All position values are in DXA.
+
+var floatProps = new TablePositionProperties
+{
+    VerticalAnchor = VerticalAnchorValues.Page,
+    HorizontalAnchor = HorizontalAnchorValues.Page,
+    TablePositionX = 2880,           // 2 inches from left page edge
+    TablePositionY = 4320,           // 3 inches from top page edge
+    LeftFromText = 180,              // 0.125 inch gap from text on left
+    RightFromText = 180,
+    TopFromText = 0,
+    BottomFromText = 0
+};
+
+tblProps.AppendChild(floatProps);
+// Produces XML:
+// <w:tblpPr w:vertAnchor="page" w:horzAnchor="page"
+//           w:tblpX="2880" w:tblpY="4320"
+//           w:leftFromText="180" w:rightFromText="180"
+//           w:topFromText="0" w:bottomFromText="0" />
+```
+
+### 2.13 TableLook — Conditional Formatting Flags
+
+```csharp
+// =============================================================================
+// TABLE LOOK — CONDITIONAL FORMATTING FLAGS
+// =============================================================================
+// TableLook controls which conditional formatting bands are applied from
+// the table style. These flags tell Word which "special" formatting to use.
+//
+// Val is a hex bitmask. Common values:
+//   0x04A0 = FirstRow + LastRow + NoHBand (typical for styled tables)
+//   0x0000 = no conditional formatting
+//
+// Individual boolean flags can also be set:
+
+var tableLook = new TableLook
+{
+    Val = "04A0",
+    FirstRow = true,        // Apply first-row (header) formatting
+    LastRow = true,         // Apply last-row (totals) formatting
+    FirstColumn = false,
+    LastColumn = false,
+    NoHorizontalBand = true,  // Don't apply horizontal banding
+    NoVerticalBand = true     // Don't apply vertical banding
+};
+
+tblProps.AppendChild(tableLook);
+// Produces XML:
+// <w:tblLook w:val="04A0" w:firstRow="1" w:lastRow="1"
+//            w:firstColumn="0" w:lastColumn="0"
+//            w:noHBand="1" w:noVBand="1" />
+```
+
+### 2.14 Complete Styled Table — Header + Data + Totals + Zebra Striping
+
+```csharp
+// =============================================================================
+// COMPLETE STYLED TABLE
+// =============================================================================
+// Builds a professional table with:
+//   - Header row (dark background, white text, repeats on page break)
+//   - Data rows with alternating zebra-stripe shading
+//   - Totals row (bold, top border)
+//   - Full 100% width on Letter page
+
+static Table CreateStyledTable(string[][] data, bool hasHeaderRow = true, bool hasTotalsRow = true)
+{
+    int cols = data[0].Length;
+    // For Letter page with 1" margins: 12240 - 2 * 1440 = 9360
+    int totalWidth = 9360;
+    int colWidth = totalWidth / cols;
+
+    var table = new Table();
+
+    // --- Table Properties ---
+    var tblPr = new TableProperties(
+        new TableWidth { Width = "5000", Type = TableWidthUnitValues.Pct },
+        new TableLayout { Type = TableLayoutValues.Fixed },
+        new TableBorders(
+            new TopBorder { Val = BorderValues.Single, Size = 8U, Color = "000000" },
+            new BottomBorder { Val = BorderValues.Single, Size = 8U, Color = "000000" },
+            new LeftBorder { Val = BorderValues.Single, Size = 4U, Color = "BFBFBF" },
+            new RightBorder { Val = BorderValues.Single, Size = 4U, Color = "BFBFBF" },
+            new InsideHorizontalBorder { Val = BorderValues.Single, Size = 4U, Color = "BFBFBF" },
+            new InsideVerticalBorder { Val = BorderValues.Single, Size = 4U, Color = "BFBFBF" }
+        ),
+        new TableLook
+        {
+            Val = "04A0", FirstRow = true, LastRow = true,
+            FirstColumn = false, LastColumn = false,
+            NoHorizontalBand = true, NoVerticalBand = true
+        }
+    );
+    table.AppendChild(tblPr);
+
+    // --- Table Grid ---
+    var grid = new TableGrid();
+    for (int c = 0; c < cols; c++)
+    {
+        int w = (c == cols - 1) ? totalWidth - colWidth * (cols - 1) : colWidth;
+        grid.AppendChild(new GridColumn { Width = w.ToString() });
+    }
+    table.AppendChild(grid);
+
+    // --- Rows ---
+    for (int r = 0; r < data.Length; r++)
+    {
+        bool isHeader = hasHeaderRow && r == 0;
+        bool isTotals = hasTotalsRow && r == data.Length - 1;
+        bool isOddDataRow = !isHeader && !isTotals && (r % 2 == 1);
+
+        var row = new TableRow();
+
+        // Row properties
+        var trPr = new TableRowProperties();
+        trPr.AppendChild(new TableRowHeight
+        {
+            Val = isHeader ? 480U : 360U,
+            HeightRule = HeightRuleValues.AtLeast
+        });
+        if (isHeader)
+        {
+            trPr.AppendChild(new TableHeader());   // Repeat header on each page
+        }
+        row.AppendChild(trPr);
+
+        // Cells
+        for (int c = 0; c < cols; c++)
+        {
+            int w = (c == cols - 1) ? totalWidth - colWidth * (cols - 1) : colWidth;
+            var cell = new TableCell();
+            var tcPr = new TableCellProperties();
+            tcPr.AppendChild(new TableCellWidth
+            {
+                Width = w.ToString(),
+                Type = TableWidthUnitValues.Dxa
+            });
+            tcPr.AppendChild(new TableCellVerticalAlignment
+            {
+                Val = TableVerticalAlignmentValues.Center
+            });
+
+            // Header: dark blue background
+            if (isHeader)
+            {
+                tcPr.AppendChild(new Shading
+                {
+                    Val = ShadingPatternValues.Clear,
+                    Color = "auto",
+                    Fill = "2F5496"     // Dark blue
+                });
+            }
+            // Zebra stripe: light gray on odd data rows
+            else if (isOddDataRow)
+            {
+                tcPr.AppendChild(new Shading
+                {
+                    Val = ShadingPatternValues.Clear,
+                    Color = "auto",
+                    Fill = "F2F2F2"     // Light gray
+                });
+            }
+            // Totals row: top border emphasis
+            if (isTotals)
+            {
+                tcPr.AppendChild(new TableCellBorders(
+                    new TopBorder
+                    {
+                        Val = BorderValues.Single,
+                        Size = 12U,    // 1.5pt
+                        Color = "000000"
+                    }
+                ));
+            }
+            cell.AppendChild(tcPr);
+
+            // Paragraph with text
+            var runProps = new RunProperties();
+            if (isHeader)
+            {
+                runProps.AppendChild(new Bold());
+                runProps.AppendChild(new Color { Val = "FFFFFF" });   // White text
+                runProps.AppendChild(new FontSize { Val = "22" });    // 11pt
+            }
+            else if (isTotals)
+            {
+                runProps.AppendChild(new Bold());
+            }
+
+            var para = new Paragraph(
+                new ParagraphProperties(
+                    new Justification
+                    {
+                        Val = (c > 0) ? JustificationValues.Right : JustificationValues.Left
+                    }
+                ),
+                new Run(runProps, new Text(data[r][c]))
+            );
+            cell.AppendChild(para);
+            row.AppendChild(cell);
+        }
+        table.AppendChild(row);
+    }
+    return table;
+}
+
+// --- Usage ---
+string[][] salesData =
+[
+    ["Product",  "Q1",    "Q2",    "Q3",    "Q4"   ],
+    ["Widget A", "1,200", "1,350", "1,100", "1,500"],
+    ["Widget B", "800",   "920",   "870",   "1,010"],
+    ["Widget C", "2,100", "2,300", "2,150", "2,400"],
+    ["Total",    "4,100", "4,570", "4,120", "4,910"]
+];
+
+var styledTable = CreateStyledTable(salesData, hasHeaderRow: true, hasTotalsRow: true);
+body.AppendChild(styledTable);
+body.AppendChild(new Paragraph());  // Empty paragraph after table
+```
+
+### 2.15 Three-Line Table (学术三线表)
+
+```csharp
+// =============================================================================
+// THREE-LINE TABLE (学术三线表)
+// =============================================================================
+// Academic/scientific table style common in Chinese academic publishing:
+//   - Top border: THICK (1.5pt)
+//   - Border below header: THIN (0.75pt)
+//   - Bottom border: THICK (1.5pt)
+//   - NO vertical borders, NO other horizontal borders
+//
+// This is achieved by:
+// 1. Setting table borders to None (removes all defaults)
+// 2. Using per-cell borders on the header row (bottom) and first/last rows (top/bottom)
+
+static Table CreateThreeLineTable(string[] headers, string[][] rows)
+{
+    int cols = headers.Length;
+    int totalWidth = 9360;
+    int colWidth = totalWidth / cols;
+
+    var table = new Table();
+
+    // Table properties: NO borders by default
+    var tblPr = new TableProperties(
+        new TableWidth { Width = "5000", Type = TableWidthUnitValues.Pct },
+        new TableJustification { Val = TableRowAlignmentValues.Center },
+        new TableLayout { Type = TableLayoutValues.Fixed },
+        new TableBorders(
+            new TopBorder { Val = BorderValues.None, Size = 0U },
+            new BottomBorder { Val = BorderValues.None, Size = 0U },
+            new LeftBorder { Val = BorderValues.None, Size = 0U },
+            new RightBorder { Val = BorderValues.None, Size = 0U },
+            new InsideHorizontalBorder { Val = BorderValues.None, Size = 0U },
+            new InsideVerticalBorder { Val = BorderValues.None, Size = 0U }
+        )
+    );
+    table.AppendChild(tblPr);
+
+    // Table grid
+    var grid = new TableGrid();
+    for (int c = 0; c < cols; c++)
+    {
+        int w = (c == cols - 1) ? totalWidth - colWidth * (cols - 1) : colWidth;
+        grid.AppendChild(new GridColumn { Width = w.ToString() });
+    }
+    table.AppendChild(grid);
+
+    // --- Header row ---
+    var headerRow = new TableRow();
+    headerRow.AppendChild(new TableRowProperties(new TableHeader()));
+
+    for (int c = 0; c < cols; c++)
+    {
+        int w = (c == cols - 1) ? totalWidth - colWidth * (cols - 1) : colWidth;
+        var cell = new TableCell();
+        var tcPr = new TableCellProperties(
+            new TableCellWidth { Width = w.ToString(), Type = TableWidthUnitValues.Dxa },
+            new TableCellBorders(
+                // Top: THICK line (1.5pt = 12 eighth-points)
+                new TopBorder { Val = BorderValues.Single, Size = 12U, Color = "000000", Space = 0U },
+                // Bottom: THIN line (0.75pt = 6 eighth-points)
+                new BottomBorder { Val = BorderValues.Single, Size = 6U, Color = "000000", Space = 0U }
+            ),
+            new TableCellVerticalAlignment { Val = TableVerticalAlignmentValues.Center }
+        );
+        cell.AppendChild(tcPr);
+        cell.AppendChild(new Paragraph(
+            new ParagraphProperties(
+                new Justification { Val = JustificationValues.Center }),
+            new Run(
+                new RunProperties(new Bold()),
+                new Text(headers[c]))));
+        cell.AppendChild(cell);     // Fix: should be row.AppendChild
+        headerRow.AppendChild(cell);
+    }
+    table.AppendChild(headerRow);
+
+    // --- Data rows ---
+    for (int r = 0; r < rows.Length; r++)
+    {
+        var dataRow = new TableRow();
+        bool isLastRow = (r == rows.Length - 1);
+
+        for (int c = 0; c < cols; c++)
+        {
+            int w = (c == cols - 1) ? totalWidth - colWidth * (cols - 1) : colWidth;
+            var cell = new TableCell();
+            var tcPr = new TableCellProperties(
+                new TableCellWidth { Width = w.ToString(), Type = TableWidthUnitValues.Dxa }
+            );
+
+            // Last data row: add THICK bottom border
+            if (isLastRow)
+            {
+                tcPr.AppendChild(new TableCellBorders(
+                    new BottomBorder
+                    {
+                        Val = BorderValues.Single,
+                        Size = 12U,      // 1.5pt thick
+                        Color = "000000",
+                        Space = 0U
+                    }
+                ));
+            }
+
+            tcPr.AppendChild(new TableCellVerticalAlignment
+            {
+                Val = TableVerticalAlignmentValues.Center
+            });
+            cell.AppendChild(tcPr);
+            cell.AppendChild(new Paragraph(
+                new ParagraphProperties(
+                    new Justification { Val = JustificationValues.Center }),
+                new Run(new Text(rows[r][c]))));
+            dataRow.AppendChild(cell);
+        }
+        table.AppendChild(dataRow);
+    }
+
+    return table;
+}
+
+// --- Usage ---
+string[] columnHeaders = ["Variable", "Mean", "SD", "p-value"];
+string[][] dataRows =
+[
+    ["Age",    "45.2", "12.3", "0.032"],
+    ["BMI",    "26.8", "4.1",  "0.001"],
+    ["SBP",    "132",  "18.5", "< 0.001"],
+    ["HR",     "72.1", "11.2", "0.145"]
+];
+
+var threeLineTable = CreateThreeLineTable(columnHeaders, dataRows);
+body.AppendChild(threeLineTable);
+```
+
+---
+
+## 3. Headers, Footers & Page Numbers
+
+Headers and footers are stored in separate XML parts (HeaderPart, FooterPart) linked to SectionProperties via HeaderReference and FooterReference.
+
+### 3.1 Creating HeaderPart and FooterPart
+
+```csharp
+// =============================================================================
+// CREATING HEADER AND FOOTER PARTS
+// =============================================================================
+// Headers and footers are separate parts within the package, each containing
+// their own XML document tree rooted at <w:hdr> or <w:ftr>.
+// They are linked to sections via HeaderReference/FooterReference.
+//
+// Steps:
+// 1. Add a HeaderPart/FooterPart to the MainDocumentPart
+// 2. Set the part's root element (Header/Footer)
+// 3. Add content (paragraphs, tables, images) to the root element
+// 4. Create a HeaderReference/FooterReference in SectionProperties
+
+var mainPart = doc.MainDocumentPart!;
+
+// --- Create a header part ---
+var headerPart = mainPart.AddNewPart<HeaderPart>();
+string headerPartId = mainPart.GetIdOfPart(headerPart);
+
+// Build header content
+headerPart.Header = new Header(
+    new Paragraph(
+        new ParagraphProperties(
+            new Justification { Val = JustificationValues.Center }),
+        new Run(
+            new RunProperties(
+                new FontSize { Val = "18" },      // 9pt — typical header size
+                new Color { Val = "808080" }),     // Gray
+            new Text("Company Confidential"))
+    )
+);
+headerPart.Header.Save();
+
+// --- Create a footer part ---
+var footerPart = mainPart.AddNewPart<FooterPart>();
+string footerPartId = mainPart.GetIdOfPart(footerPart);
+
+footerPart.Footer = new Footer(
+    new Paragraph(
+        new ParagraphProperties(
+            new Justification { Val = JustificationValues.Center }),
+        new Run(
+            new RunProperties(new FontSize { Val = "18" }),
+            new Text("Footer text here"))
+    )
+);
+footerPart.Footer.Save();
+```
+
+### 3.2 HeaderReference and FooterReference — Types
+
+```csharp
+// =============================================================================
+// HEADER/FOOTER REFERENCE — LINKING TO SECTION
+// =============================================================================
+// HeaderReference/FooterReference types:
+//   Default — used on all pages (unless First/Even overrides)
+//   First   — used on the first page of the section (requires TitlePage)
+//   Even    — used on even-numbered pages (requires EvenAndOddHeaders setting)
+//
+// A section can have up to 3 headers and 3 footers (Default + First + Even).
+
+var sectPr = body.Elements<SectionProperties>().FirstOrDefault()
+    ?? body.AppendChild(new SectionProperties());
+
+// Default header (all pages)
+sectPr.AppendChild(new HeaderReference
+{
+    Type = HeaderFooterValues.Default,
+    Id = headerPartId
+});
+
+// Default footer (all pages)
+sectPr.AppendChild(new FooterReference
+{
+    Type = HeaderFooterValues.Default,
+    Id = footerPartId
+});
+
+// Produces XML:
+// <w:sectPr>
+//   <w:headerReference w:type="default" r:id="rId4" />
+//   <w:footerReference w:type="default" r:id="rId5" />
+// </w:sectPr>
+```
+
+### 3.3 Different First Page (TitlePage)
+
+```csharp
+// =============================================================================
+// DIFFERENT FIRST PAGE — TITLEPAGE
+// =============================================================================
+// To have a different header/footer on the first page, you must:
+// 1. Add a TitlePage element to SectionProperties
+// 2. Create separate HeaderPart/FooterPart for the first page
+// 3. Add HeaderReference/FooterReference with Type = First
+
+// Enable different first page
+sectPr.AppendChild(new TitlePage());
+// Produces XML: <w:titlePg />
+
+// Create first-page header (e.g., empty / no header on cover page)
+var firstHeaderPart = mainPart.AddNewPart<HeaderPart>();
+string firstHeaderId = mainPart.GetIdOfPart(firstHeaderPart);
+firstHeaderPart.Header = new Header(new Paragraph()); // Empty header
+firstHeaderPart.Header.Save();
+
+// Create first-page footer
+var firstFooterPart = mainPart.AddNewPart<FooterPart>();
+string firstFooterId = mainPart.GetIdOfPart(firstFooterPart);
+firstFooterPart.Footer = new Footer(new Paragraph()); // Empty footer
+firstFooterPart.Footer.Save();
+
+// Link to section
+sectPr.AppendChild(new HeaderReference
+{
+    Type = HeaderFooterValues.First,
+    Id = firstHeaderId
+});
+sectPr.AppendChild(new FooterReference
+{
+    Type = HeaderFooterValues.First,
+    Id = firstFooterId
+});
+```
+
+### 3.4 Even and Odd Page Headers
+
+```csharp
+// =============================================================================
+// EVEN AND ODD PAGE HEADERS/FOOTERS
+// =============================================================================
+// For different headers on even vs. odd pages (e.g., book-style layout):
+// 1. Set EvenAndOddHeaders in DocumentSettingsPart
+// 2. Create separate parts for Even pages
+// 3. "Default" type becomes the ODD page header/footer
+
+// Enable even/odd in Settings
+var settingsPart = mainPart.DocumentSettingsPart
+    ?? mainPart.AddNewPart<DocumentSettingsPart>();
+if (settingsPart.Settings == null)
+    settingsPart.Settings = new Settings();
+
+settingsPart.Settings.AppendChild(new EvenAndOddHeaders());
+settingsPart.Settings.Save();
+// Produces XML in settings.xml: <w:evenAndOddHeaders />
+
+// Create even-page header
+var evenHeaderPart = mainPart.AddNewPart<HeaderPart>();
+string evenHeaderId = mainPart.GetIdOfPart(evenHeaderPart);
+evenHeaderPart.Header = new Header(
+    new Paragraph(
+        new ParagraphProperties(
+            new Justification { Val = JustificationValues.Left }),
+        new Run(new Text("Chapter Title"))   // Left-aligned on even pages
+    )
+);
+evenHeaderPart.Header.Save();
+
+// Link: "Default" = odd pages, "Even" = even pages
+sectPr.AppendChild(new HeaderReference
+{
+    Type = HeaderFooterValues.Even,
+    Id = evenHeaderId
+});
+// The existing Default header is now used only on odd pages.
+```
+
+### 3.5 SimpleField — PAGE, NUMPAGES, SECTIONPAGES
+
+```csharp
+// =============================================================================
+// SIMPLE FIELDS — PAGE NUMBERS AND TOTALS
+// =============================================================================
+// SimpleField inserts a field code that Word evaluates at render time.
+// Common field codes:
+//   PAGE         — current page number
+//   NUMPAGES     — total pages in document
+//   SECTIONPAGES — total pages in current section
+//   DATE         — current date
+//   TIME         — current time
+//
+// The Instruction property contains the field code string.
+// A child Run with text is used for the "cached" display value (optional but
+// recommended for non-Word renderers).
+
+// --- Simple page number field ---
+var pageField = new SimpleField { Instruction = " PAGE " };
+pageField.AppendChild(new Run(new Text("1")));  // Cached display value
+// Produces XML: <w:fldSimple w:instr=" PAGE "><w:r><w:t>1</w:t></w:r></w:fldSimple>
+
+// --- Total page count ---
+var totalField = new SimpleField { Instruction = " NUMPAGES " };
+totalField.AppendChild(new Run(new Text("1")));
+
+// --- Section page count ---
+var sectionPagesField = new SimpleField { Instruction = " SECTIONPAGES " };
+sectionPagesField.AppendChild(new Run(new Text("1")));
+```
+
+### 3.6 "Page X of Y" Footer
+
+```csharp
+// =============================================================================
+// "PAGE X OF Y" FOOTER
+// =============================================================================
+// Combines text runs with SimpleField elements in a single paragraph.
+
+var pageXofYFooter = mainPart.AddNewPart<FooterPart>();
+string pageXofYId = mainPart.GetIdOfPart(pageXofYFooter);
+
+var footerPara = new Paragraph(
+    new ParagraphProperties(
+        new Justification { Val = JustificationValues.Center })
+);
+
+// "Page "
+footerPara.AppendChild(new Run(
+    new RunProperties(new FontSize { Val = "18" }),   // 9pt
+    new Text("Page ") { Space = SpaceProcessingModeValues.Preserve }
+));
+
+// PAGE field
+var pgField = new SimpleField { Instruction = " PAGE " };
+pgField.AppendChild(new Run(
+    new RunProperties(new FontSize { Val = "18" }),
+    new Text("1")));
+footerPara.AppendChild(pgField);
+
+// " of "
+footerPara.AppendChild(new Run(
+    new RunProperties(new FontSize { Val = "18" }),
+    new Text(" of ") { Space = SpaceProcessingModeValues.Preserve }
+));
+
+// NUMPAGES field
+var npField = new SimpleField { Instruction = " NUMPAGES " };
+npField.AppendChild(new Run(
+    new RunProperties(new FontSize { Val = "18" }),
+    new Text("1")));
+footerPara.AppendChild(npField);
+
+pageXofYFooter.Footer = new Footer(footerPara);
+pageXofYFooter.Footer.Save();
+
+// Link to section
+sectPr.AppendChild(new FooterReference
+{
+    Type = HeaderFooterValues.Default,
+    Id = pageXofYId
+});
+```
+
+### 3.7 Header with Logo Image
+
+```csharp
+// =============================================================================
+// HEADER WITH LOGO IMAGE
+// =============================================================================
+// To add an image to a header:
+// 1. Add an ImagePart to the HeaderPart (not MainDocumentPart)
+// 2. Build the Drawing/Inline/Graphic elements in the header paragraph
+// 3. Image sizing uses EMUs (English Metric Units): 1 inch = 914400 EMU
+
+var logoHeaderPart = mainPart.AddNewPart<HeaderPart>();
+string logoHeaderId = mainPart.GetIdOfPart(logoHeaderPart);
+
+// Add image to header part
+var imagePart = logoHeaderPart.AddImagePart(ImagePartType.Png);
+using (var stream = File.OpenRead("logo.png"))
+{
+    imagePart.FeedData(stream);
+}
+string imageRelId = logoHeaderPart.GetIdOfPart(imagePart);
+
+// Image dimensions in EMU (e.g., 1.5 inch wide × 0.5 inch tall)
+long widthEmu = 1371600;    // 1.5 * 914400
+long heightEmu = 457200;    // 0.5 * 914400
+
+// Build the inline drawing element
+var drawing = new Drawing(
+    new DW.Inline(
+        new DW.Extent { Cx = widthEmu, Cy = heightEmu },
+        new DW.EffectExtent { LeftEdge = 0L, TopEdge = 0L, RightEdge = 0L, BottomEdge = 0L },
+        new DW.DocProperties { Id = 1U, Name = "Logo" },
+        new DW.NonVisualGraphicFrameDrawingProperties(
+            new A.GraphicFrameLocks { NoChangeAspect = true }),
+        new A.Graphic(
+            new A.GraphicData(
+                new PIC.Picture(
+                    new PIC.NonVisualPictureProperties(
+                        new PIC.NonVisualDrawingProperties { Id = 1U, Name = "logo.png" },
+                        new PIC.NonVisualPictureDrawingProperties()),
+                    new PIC.BlipFill(
+                        new A.Blip { Embed = imageRelId },
+                        new A.Stretch(new A.FillRectangle())),
+                    new PIC.ShapeProperties(
+                        new A.Transform2D(
+                            new A.Offset { X = 0L, Y = 0L },
+                            new A.Extents { Cx = widthEmu, Cy = heightEmu }),
+                        new A.PresetGeometry(new A.AdjustValueList())
+                        { Preset = A.ShapeTypeValues.Rectangle })
+                )
+            ) { Uri = "http://schemas.openxmlformats.org/drawingml/2006/picture" }
+        )
+    )
+    {
+        DistanceFromTop = 0U,
+        DistanceFromBottom = 0U,
+        DistanceFromLeft = 0U,
+        DistanceFromRight = 0U
+    }
+);
+
+logoHeaderPart.Header = new Header(
+    new Paragraph(new Run(drawing))
+);
+logoHeaderPart.Header.Save();
+```
+
+### 3.8 Table-Layout Header (Logo Left, Text Center, Page Right)
+
+```csharp
+// =============================================================================
+// TABLE-LAYOUT HEADER
+// =============================================================================
+// A common professional header pattern: 3-column invisible table
+//   Left cell:   Company logo
+//   Center cell: Document title
+//   Right cell:  Page number
+// The table has no borders, giving a clean three-zone layout.
+
+var tblHeaderPart = mainPart.AddNewPart<HeaderPart>();
+string tblHeaderId = mainPart.GetIdOfPart(tblHeaderPart);
+
+// Content width for Letter with 1" margins = 9360 DXA
+var headerTable = new Table(
+    new TableProperties(
+        new TableWidth { Width = "5000", Type = TableWidthUnitValues.Pct },
+        new TableLayout { Type = TableLayoutValues.Fixed },
+        new TableBorders(
+            new TopBorder { Val = BorderValues.None },
+            new BottomBorder { Val = BorderValues.Single, Size = 4U, Color = "000000" },
+            new LeftBorder { Val = BorderValues.None },
+            new RightBorder { Val = BorderValues.None },
+            new InsideHorizontalBorder { Val = BorderValues.None },
+            new InsideVerticalBorder { Val = BorderValues.None }
+        )
+    ),
+    new TableGrid(
+        new GridColumn { Width = "3120" },   // ~1/3
+        new GridColumn { Width = "3120" },   // ~1/3
+        new GridColumn { Width = "3120" }    // ~1/3
+    )
+);
+
+// Left cell: logo placeholder (or image Drawing)
+var leftCell = new TableCell(
+    new TableCellProperties(
+        new TableCellWidth { Width = "3120", Type = TableWidthUnitValues.Dxa },
+        new TableCellVerticalAlignment { Val = TableVerticalAlignmentValues.Center }),
+    new Paragraph(
+        new ParagraphProperties(
+            new Justification { Val = JustificationValues.Left }),
+        new Run(
+            new RunProperties(new Bold(), new FontSize { Val = "18" }),
+            new Text("ACME Corp")))
+);
+
+// Center cell: document title
+var centerCell = new TableCell(
+    new TableCellProperties(
+        new TableCellWidth { Width = "3120", Type = TableWidthUnitValues.Dxa },
+        new TableCellVerticalAlignment { Val = TableVerticalAlignmentValues.Center }),
+    new Paragraph(
+        new ParagraphProperties(
+            new Justification { Val = JustificationValues.Center }),
+        new Run(
+            new RunProperties(new FontSize { Val = "18" }),
+            new Text("Technical Specification v2.0")))
+);
+
+// Right cell: page number
+var pageFieldRight = new SimpleField { Instruction = " PAGE " };
+pageFieldRight.AppendChild(new Run(
+    new RunProperties(new FontSize { Val = "18" }),
+    new Text("1")));
+
+var rightCell = new TableCell(
+    new TableCellProperties(
+        new TableCellWidth { Width = "3120", Type = TableWidthUnitValues.Dxa },
+        new TableCellVerticalAlignment { Val = TableVerticalAlignmentValues.Center }),
+    new Paragraph(
+        new ParagraphProperties(
+            new Justification { Val = JustificationValues.Right }),
+        new Run(
+            new RunProperties(new FontSize { Val = "18" }),
+            new Text("Page ") { Space = SpaceProcessingModeValues.Preserve }),
+        pageFieldRight)
+);
+
+headerTable.AppendChild(new TableRow(leftCell, centerCell, rightCell));
+
+tblHeaderPart.Header = new Header(headerTable, new Paragraph());
+tblHeaderPart.Header.Save();
+```
+
+### 3.9 Chinese Government Document Page Numbers (公文页码)
+
+```csharp
+// =============================================================================
+// CHINESE GOVERNMENT DOCUMENT PAGE NUMBERS (公文页码)
+// =============================================================================
+// Standard: bottom center, format "-X-" (em-dash surrounding page number)
+// Font: 宋体 (SimSun) 四号 (14pt = "28" half-points)
+// Per GB/T 9704-2012
+
+var govFooterPart = mainPart.AddNewPart<FooterPart>();
+string govFooterId = mainPart.GetIdOfPart(govFooterPart);
+
+var govFooterPara = new Paragraph(
+    new ParagraphProperties(
+        new Justification { Val = JustificationValues.Center })
+);
+
+// Run properties for 宋体四号
+RunProperties GovPageRunProps() => new RunProperties(
+    new RunFonts
+    {
+        Ascii = "SimSun",
+        HighAnsi = "SimSun",
+        EastAsia = "SimSun"
+    },
+    new FontSize { Val = "28" },           // 14pt = 四号
+    new FontSizeComplexScript { Val = "28" }
+);
+
+// "—" (em-dash before page number)
+govFooterPara.AppendChild(new Run(
+    GovPageRunProps(),
+    new Text("\u2014") { Space = SpaceProcessingModeValues.Preserve }
+));
+
+// PAGE field
+var govPageField = new SimpleField { Instruction = " PAGE " };
+govPageField.AppendChild(new Run(GovPageRunProps(), new Text("1")));
+govFooterPara.AppendChild(govPageField);
+
+// "—" (em-dash after page number)
+govFooterPara.AppendChild(new Run(
+    GovPageRunProps(),
+    new Text("\u2014") { Space = SpaceProcessingModeValues.Preserve }
+));
+
+govFooterPart.Footer = new Footer(govFooterPara);
+govFooterPart.Footer.Save();
+
+// Link to section
+sectPr.AppendChild(new FooterReference
+{
+    Type = HeaderFooterValues.Default,
+    Id = govFooterId
+});
+```
+
+### 3.10 Multi-Section with Different Headers
+
+```csharp
+// =============================================================================
+// MULTI-SECTION WITH DIFFERENT HEADERS
+// =============================================================================
+// Each section can have its own set of header/footer parts.
+// To change headers mid-document, create a section break and attach
+// different HeaderReference/FooterReference to each SectionProperties.
+// See Section 4 for full section break mechanics.
+
+// Section 1 header
+var sec1Header = mainPart.AddNewPart<HeaderPart>();
+string sec1HeaderId = mainPart.GetIdOfPart(sec1Header);
+sec1Header.Header = new Header(
+    new Paragraph(new Run(new Text("Chapter 1: Introduction"))));
+sec1Header.Header.Save();
+
+// Section 2 header
+var sec2Header = mainPart.AddNewPart<HeaderPart>();
+string sec2HeaderId = mainPart.GetIdOfPart(sec2Header);
+sec2Header.Header = new Header(
+    new Paragraph(new Run(new Text("Chapter 2: Methods"))));
+sec2Header.Header.Save();
+
+// Section 1 content + section break
+body.AppendChild(new Paragraph(new Run(new Text("Section 1 content..."))));
+
+// Mid-document section properties (in last paragraph of section 1)
+var sec1Break = new Paragraph(
+    new ParagraphProperties(
+        new SectionProperties(
+            new PageSize { Width = 12240U, Height = 15840U },
+            new PageMargin
+            {
+                Top = 1440, Bottom = 1440,
+                Left = 1440U, Right = 1440U,
+                Header = 720U, Footer = 720U, Gutter = 0U
+            },
+            new SectionType { Val = SectionMarkValues.NextPage },
+            new HeaderReference { Type = HeaderFooterValues.Default, Id = sec1HeaderId }
+        )
+    )
+);
+body.AppendChild(sec1Break);
+
+// Section 2 content
+body.AppendChild(new Paragraph(new Run(new Text("Section 2 content..."))));
+
+// Final section properties (last child of Body)
+var sec2Props = new SectionProperties(
+    new PageSize { Width = 12240U, Height = 15840U },
+    new PageMargin
+    {
+        Top = 1440, Bottom = 1440,
+        Left = 1440U, Right = 1440U,
+        Header = 720U, Footer = 720U, Gutter = 0U
+    },
+    new HeaderReference { Type = HeaderFooterValues.Default, Id = sec2HeaderId }
+);
+body.AppendChild(sec2Props);
+```
+
+---
+
+## 4. Section Breaks & Multi-Section
+
+### 4.1 Section Properties Placement Rules
+
+```csharp
+// =============================================================================
+// SECTION PROPERTIES PLACEMENT
+// =============================================================================
+// There are exactly TWO places SectionProperties can appear:
+//
+// 1. FINAL SECTION: As the last child element of <w:body>.
+//    This controls the last (or only) section of the document.
+//    body.AppendChild(new SectionProperties(...));
+//
+// 2. MID-DOCUMENT SECTION BREAK: Inside ParagraphProperties of the
+//    LAST paragraph of a section. This paragraph acts as the section divider.
+//    The paragraph's text content belongs to the PREVIOUS section.
+//
+// IMPORTANT: Mid-document SectionProperties goes inside pPr, NOT as a child
+// of Body. This is the #1 mistake when creating multi-section documents.
+
+// --- Final section (last child of Body) ---
+var finalSectPr = new SectionProperties(
+    new PageSize { Width = 12240U, Height = 15840U },
+    new PageMargin
+    {
+        Top = 1440, Bottom = 1440,
+        Left = 1440U, Right = 1440U,
+        Header = 720U, Footer = 720U, Gutter = 0U
+    }
+);
+body.AppendChild(finalSectPr);  // MUST be last child
+
+// --- Mid-document section break ---
+// This paragraph ends section 1 and starts section 2
+var sectionBreakPara = new Paragraph(
+    new ParagraphProperties(
+        new SectionProperties(
+            new PageSize { Width = 12240U, Height = 15840U },
+            new PageMargin
+            {
+                Top = 1440, Bottom = 1440,
+                Left = 1440U, Right = 1440U,
+                Header = 720U, Footer = 720U, Gutter = 0U
+            },
+            new SectionType { Val = SectionMarkValues.NextPage }
+        )
+    )
+);
+// Produces XML:
+// <w:p>
+//   <w:pPr>
+//     <w:sectPr>
+//       <w:pgSz w:w="12240" w:h="15840" />
+//       <w:pgMar ... />
+//       <w:type w:val="nextPage" />
+//     </w:sectPr>
+//   </w:pPr>
+// </w:p>
+```
+
+### 4.2 SectionType Values
+
+```csharp
+// =============================================================================
+// SECTION TYPE VALUES
+// =============================================================================
+// SectionType controls how the section break behaves:
+//
+//   NextPage    — new section starts on next page (most common)
+//   Continuous  — new section starts on same page (used for column changes)
+//   EvenPage    — new section starts on next even page (inserts blank if needed)
+//   OddPage     — new section starts on next odd page (inserts blank if needed)
+//
+// If SectionType is omitted, the default is NextPage.
+
+// Next page break (explicit)
+var nextPageBreak = new SectionType { Val = SectionMarkValues.NextPage };
+
+// Continuous — same page (e.g., switch from 1-column to 2-column)
+var continuousBreak = new SectionType { Val = SectionMarkValues.Continuous };
+
+// Even page — for chapters that must start on left page (in book layout)
+var evenPageBreak = new SectionType { Val = SectionMarkValues.EvenPage };
+
+// Odd page — for chapters that must start on right page
+var oddPageBreak = new SectionType { Val = SectionMarkValues.OddPage };
+```
+
+### 4.3 Per-Section Page Setup
+
+```csharp
+// =============================================================================
+// PER-SECTION PAGE SETUP
+// =============================================================================
+// Each section independently controls its own:
+//   - PageSize (portrait vs landscape, paper size)
+//   - PageMargin
+//   - Columns
+//   - Headers/Footers
+//   - PageNumberType (restart numbering)
+//   - LineNumbering
+//   - DocGrid
+
+// Example: Section with landscape A4 and narrow margins
+var landscapeSection = new SectionProperties(
+    new PageSize
+    {
+        Width = 16838U,    // A4 long edge (landscape: swap W/H)
+        Height = 11906U,   // A4 short edge
+        Orient = PageOrientationValues.Landscape
+    },
+    new PageMargin
+    {
+        Top = 720, Bottom = 720,
+        Left = 720U, Right = 720U,
+        Header = 720U, Footer = 720U, Gutter = 0U
+    },
+    new SectionType { Val = SectionMarkValues.NextPage }
+);
+```
+
+### 4.4 PageNumberType — Restart Numbering
+
+```csharp
+// =============================================================================
+// PAGE NUMBER TYPE — RESTART AND FORMAT
+// =============================================================================
+// PageNumberType controls page numbering within a section.
+//   Start  — starting page number (restarts counting)
+//   Format — numbering format (Decimal, UpperRoman, LowerRoman,
+//            UpperLetter, LowerLetter)
+//
+// Common pattern: front matter uses i, ii, iii; body restarts at 1.
+
+// Restart at page 1 (e.g., after front matter)
+var restartNumbering = new PageNumberType
+{
+    Start = 1,
+    Format = NumberFormatValues.Decimal
+};
+// Produces XML: <w:pgNumType w:start="1" w:fmt="decimal" />
+
+// Roman numeral numbering for front matter
+var romanNumbering = new PageNumberType
+{
+    Start = 1,
+    Format = NumberFormatValues.LowerRoman
+};
+// Produces XML: <w:pgNumType w:start="1" w:fmt="lowerRoman" />
+
+// Add to section properties
+landscapeSection.AppendChild(restartNumbering);
+```
+
+### 4.5 Complete Example: Portrait, Landscape, Portrait
+
+```csharp
+// =============================================================================
+// COMPLETE MULTI-SECTION EXAMPLE
+// =============================================================================
+// Document with three sections:
+//   Section 1: Letter portrait (cover + intro)
+//   Section 2: Letter landscape (wide table)
+//   Section 3: Letter portrait (conclusion), page numbers restart at 1
+//
+// Each section has its own header.
+
+using var doc = WordprocessingDocument.Create(
+    "MultiSection.docx", WordprocessingDocumentType.Document);
+
+var mainPart = doc.MainDocumentPart!;
+var body = mainPart.Document.Body!;
+
+// --- Create headers for each section ---
+HeaderPart CreateSimpleHeader(string text)
+{
+    var hp = mainPart.AddNewPart<HeaderPart>();
+    hp.Header = new Header(
+        new Paragraph(
+            new ParagraphProperties(
+                new ParagraphBorders(
+                    new BottomBorder
+                    {
+                        Val = BorderValues.Single, Size = 4U,
+                        Color = "999999", Space = 1U
+                    }),
+                new Justification { Val = JustificationValues.Right }),
+            new Run(
+                new RunProperties(
+                    new FontSize { Val = "18" },
+                    new Color { Val = "999999" }),
+                new Text(text)))
+    );
+    hp.Header.Save();
+    return hp;
+}
+
+var header1 = CreateSimpleHeader("Introduction");
+var header2 = CreateSimpleHeader("Data Tables");
+var header3 = CreateSimpleHeader("Conclusion");
+
+// --- Create "Page X of Y" footer (shared) ---
+var sharedFooter = mainPart.AddNewPart<FooterPart>();
+var fPara = new Paragraph(
+    new ParagraphProperties(new Justification { Val = JustificationValues.Center }));
+fPara.AppendChild(new Run(
+    new RunProperties(new FontSize { Val = "18" }),
+    new Text("Page ") { Space = SpaceProcessingModeValues.Preserve }));
+var pf = new SimpleField { Instruction = " PAGE " };
+pf.AppendChild(new Run(new RunProperties(new FontSize { Val = "18" }), new Text("1")));
+fPara.AppendChild(pf);
+fPara.AppendChild(new Run(
+    new RunProperties(new FontSize { Val = "18" }),
+    new Text(" of ") { Space = SpaceProcessingModeValues.Preserve }));
+var npf = new SimpleField { Instruction = " NUMPAGES " };
+npf.AppendChild(new Run(new RunProperties(new FontSize { Val = "18" }), new Text("1")));
+fPara.AppendChild(npf);
+sharedFooter.Footer = new Footer(fPara);
+sharedFooter.Footer.Save();
+string sharedFooterId = mainPart.GetIdOfPart(sharedFooter);
+
+// =================== SECTION 1: Portrait ===================
+body.AppendChild(new Paragraph(
+    new ParagraphProperties(
+        new Justification { Val = JustificationValues.Center }),
+    new Run(
+        new RunProperties(new Bold(), new FontSize { Val = "48" }),
+        new Text("Annual Report 2025"))));
+
+body.AppendChild(new Paragraph(new Run(new Text("Introduction content goes here..."))));
+
+// Section 1 break (inside pPr of last paragraph)
+body.AppendChild(new Paragraph(
+    new ParagraphProperties(
+        new SectionProperties(
+            new PageSize { Width = 12240U, Height = 15840U },
+            new PageMargin
+            {
+                Top = 1440, Bottom = 1440,
+                Left = 1440U, Right = 1440U,
+                Header = 720U, Footer = 720U, Gutter = 0U
+            },
+            new SectionType { Val = SectionMarkValues.NextPage },
+            new HeaderReference
+            {
+                Type = HeaderFooterValues.Default,
+                Id = mainPart.GetIdOfPart(header1)
+            },
+            new FooterReference
+            {
+                Type = HeaderFooterValues.Default,
+                Id = sharedFooterId
+            }
+        )
+    )
+));
+
+// =================== SECTION 2: Landscape ===================
+body.AppendChild(new Paragraph(new Run(
+    new RunProperties(new Bold(), new FontSize { Val = "28" }),
+    new Text("Wide Data Table"))));
+
+body.AppendChild(new Paragraph(new Run(
+    new Text("This section uses landscape orientation for a wide table."))));
+
+// Section 2 break
+body.AppendChild(new Paragraph(
+    new ParagraphProperties(
+        new SectionProperties(
+            new PageSize
+            {
+                Width = 15840U,     // SWAPPED for landscape
+                Height = 12240U,    // SWAPPED for landscape
+                Orient = PageOrientationValues.Landscape
+            },
+            new PageMargin
+            {
+                Top = 1440, Bottom = 1440,
+                Left = 1440U, Right = 1440U,
+                Header = 720U, Footer = 720U, Gutter = 0U
+            },
+            new SectionType { Val = SectionMarkValues.NextPage },
+            new HeaderReference
+            {
+                Type = HeaderFooterValues.Default,
+                Id = mainPart.GetIdOfPart(header2)
+            },
+            new FooterReference
+            {
+                Type = HeaderFooterValues.Default,
+                Id = sharedFooterId
+            }
+        )
+    )
+));
+
+// =================== SECTION 3: Portrait (restart page numbers) ===================
+body.AppendChild(new Paragraph(new Run(
+    new RunProperties(new Bold(), new FontSize { Val = "28" }),
+    new Text("Conclusion"))));
+
+body.AppendChild(new Paragraph(new Run(
+    new Text("Final section content with restarted page numbering."))));
+
+// Final section properties — last child of Body
+body.AppendChild(new SectionProperties(
+    new PageSize { Width = 12240U, Height = 15840U },
+    new PageMargin
+    {
+        Top = 1440, Bottom = 1440,
+        Left = 1440U, Right = 1440U,
+        Header = 720U, Footer = 720U, Gutter = 0U
+    },
+    new PageNumberType
+    {
+        Start = 1,                                         // Restart at page 1
+        Format = NumberFormatValues.Decimal
+    },
+    new HeaderReference
+    {
+        Type = HeaderFooterValues.Default,
+        Id = mainPart.GetIdOfPart(header3)
+    },
+    new FooterReference
+    {
+        Type = HeaderFooterValues.Default,
+        Id = sharedFooterId
+    }
+));
+
+mainPart.Document.Save();
+```
+
+---
+
+## 5. Document Properties
+
+### 5.1 CoreFilePropertiesPart (Dublin Core Metadata)
+
+```csharp
+// =============================================================================
+// CORE FILE PROPERTIES (DUBLIN CORE)
+// =============================================================================
+// Core properties map to the Dublin Core metadata standard.
+// They appear in File > Properties > Summary in Word.
+// The underlying XML is stored in docProps/core.xml.
+//
+// Available properties: Title, Subject, Creator (Author), Keywords,
+// Description, LastModifiedBy, Revision, Created, Modified, Category,
+// ContentStatus, ContentType, Identifier, Language, Version
+
+using var doc = WordprocessingDocument.Create(
+    "PropertiesDemo.docx", WordprocessingDocumentType.Document);
+
+// Core properties are accessed via the package-level properties
+// Use the OpenXml Packaging API:
+var corePart = doc.CoreFilePropertiesPart
+    ?? doc.AddCoreFilePropertiesPart();
+
+// The core properties use the OpenXmlPart's XML directly.
+// You can set properties via the PackageProperties interface:
+doc.PackageProperties.Title = "Quarterly Financial Report";
+doc.PackageProperties.Subject = "Q4 2025 Financial Summary";
+doc.PackageProperties.Creator = "Jane Smith";
+doc.PackageProperties.Keywords = "finance, quarterly, report, 2025";
+doc.PackageProperties.Description = "Comprehensive financial report for Q4 2025";
+doc.PackageProperties.LastModifiedBy = "John Doe";
+doc.PackageProperties.Revision = "3";
+doc.PackageProperties.Created = DateTime.UtcNow;
+doc.PackageProperties.Modified = DateTime.UtcNow;
+doc.PackageProperties.Category = "Financial Reports";
+doc.PackageProperties.ContentStatus = "Final";
+doc.PackageProperties.Language = "en-US";
+doc.PackageProperties.Version = "2.0";
+
+// Produces docProps/core.xml:
+// <cp:coreProperties>
+//   <dc:title>Quarterly Financial Report</dc:title>
+//   <dc:subject>Q4 2025 Financial Summary</dc:subject>
+//   <dc:creator>Jane Smith</dc:creator>
+//   <cp:keywords>finance, quarterly, report, 2025</cp:keywords>
+//   <dc:description>Comprehensive financial report...</dc:description>
+//   <cp:lastModifiedBy>John Doe</cp:lastModifiedBy>
+//   <cp:revision>3</cp:revision>
+//   <dcterms:created>2025-12-01T00:00:00Z</dcterms:created>
+//   <dcterms:modified>2025-12-01T00:00:00Z</dcterms:modified>
+//   <cp:category>Financial Reports</cp:category>
+//   <cp:contentStatus>Final</cp:contentStatus>
+// </cp:coreProperties>
+```
+
+### 5.2 ExtendedFilePropertiesPart (Application Properties)
+
+```csharp
+// =============================================================================
+// EXTENDED FILE PROPERTIES (APPLICATION PROPERTIES)
+// =============================================================================
+// Extended properties are stored in docProps/app.xml.
+// They include application-specific metadata like Company, Manager, etc.
+
+using DocumentFormat.OpenXml.ExtendedProperties;
+
+var extPart = doc.ExtendedFilePropertiesPart
+    ?? doc.AddExtendedFilePropertiesPart();
+
+extPart.Properties = new DocumentFormat.OpenXml.ExtendedProperties.Properties();
+
+// Company name
+extPart.Properties.AppendChild(
+    new DocumentFormat.OpenXml.ExtendedProperties.Company("ACME Corporation"));
+
+// Manager
+extPart.Properties.AppendChild(
+    new DocumentFormat.OpenXml.ExtendedProperties.Manager("Alice Johnson"));
+
+// Application name
+extPart.Properties.AppendChild(
+    new DocumentFormat.OpenXml.ExtendedProperties.Application("Custom Document Generator"));
+
+// Application version
+extPart.Properties.AppendChild(
+    new DocumentFormat.OpenXml.ExtendedProperties.ApplicationVersion("1.0.0"));
+
+// Total editing time in minutes
+extPart.Properties.AppendChild(
+    new DocumentFormat.OpenXml.ExtendedProperties.TotalTime("0"));
+
+// Pages, Words, Characters (these are hints; Word recalculates them)
+extPart.Properties.AppendChild(
+    new DocumentFormat.OpenXml.ExtendedProperties.Pages("1"));
+extPart.Properties.AppendChild(
+    new DocumentFormat.OpenXml.ExtendedProperties.Words("0"));
+extPart.Properties.AppendChild(
+    new DocumentFormat.OpenXml.ExtendedProperties.Characters("0"));
+
+extPart.Properties.Save();
+
+// Produces docProps/app.xml:
+// <Properties>
+//   <Company>ACME Corporation</Company>
+//   <Manager>Alice Johnson</Manager>
+//   <Application>Custom Document Generator</Application>
+//   <AppVersion>1.0.0</AppVersion>
+//   <TotalTime>0</TotalTime>
+//   <Pages>1</Pages>
+// </Properties>
+```
+
+### 5.3 CustomFilePropertiesPart (Custom Key-Value Properties)
+
+```csharp
+// =============================================================================
+// CUSTOM FILE PROPERTIES (KEY-VALUE PAIRS)
+// =============================================================================
+// Custom properties allow arbitrary key-value metadata.
+// Stored in docProps/custom.xml. Useful for document management systems,
+// workflow tracking, template variables, etc.
+//
+// Supported value types: Text (string), Number (int), Date (DateTime),
+// Boolean (bool), Filetime
+
+using DocumentFormat.OpenXml.CustomProperties;
+using DocumentFormat.OpenXml.VariantTypes;
+
+var customPart = doc.CustomFilePropertiesPart
+    ?? doc.AddCustomFilePropertiesPart();
+
+customPart.Properties = new DocumentFormat.OpenXml.CustomProperties.Properties();
+
+// Property IDs must start at 2 and increment
+int propertyId = 2;
+
+// --- String property ---
+customPart.Properties.AppendChild(new CustomDocumentProperty
+{
+    FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}",
+    PropertyId = propertyId++,
+    Name = "Department",
+    VTLPWSTR = new VTLPWSTR("Engineering")
+});
+
+// --- Integer property ---
+customPart.Properties.AppendChild(new CustomDocumentProperty
+{
+    FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}",
+    PropertyId = propertyId++,
+    Name = "DocumentVersion",
+    VTInt32 = new VTInt32("5")
+});
+
+// --- Boolean property ---
+customPart.Properties.AppendChild(new CustomDocumentProperty
+{
+    FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}",
+    PropertyId = propertyId++,
+    Name = "Approved",
+    VTBool = new VTBool("true")
+});
+
+// --- DateTime property ---
+customPart.Properties.AppendChild(new CustomDocumentProperty
+{
+    FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}",
+    PropertyId = propertyId++,
+    Name = "ApprovalDate",
+    VTFileTime = new VTFileTime(DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"))
+});
+
+// --- Double/Float property ---
+customPart.Properties.AppendChild(new CustomDocumentProperty
+{
+    FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}",
+    PropertyId = propertyId++,
+    Name = "ConfidenceScore",
+    VTDouble = new VTDouble("0.95")
+});
+
+customPart.Properties.Save();
+
+// Produces docProps/custom.xml:
+// <Properties>
+//   <property fmtid="{D5CDD505-...}" pid="2" name="Department">
+//     <vt:lpwstr>Engineering</vt:lpwstr>
+//   </property>
+//   <property fmtid="{D5CDD505-...}" pid="3" name="DocumentVersion">
+//     <vt:i4>5</vt:i4>
+//   </property>
+//   <property fmtid="{D5CDD505-...}" pid="4" name="Approved">
+//     <vt:bool>true</vt:bool>
+//   </property>
+//   ...
+// </Properties>
+```
+
+### 5.4 Reading and Modifying Existing Properties
+
+```csharp
+// =============================================================================
+// READING AND MODIFYING EXISTING PROPERTIES
+// =============================================================================
+
+using var existingDoc = WordprocessingDocument.Open("existing.docx", isEditable: true);
+
+// --- Read core properties ---
+string? title = existingDoc.PackageProperties.Title;
+string? author = existingDoc.PackageProperties.Creator;
+DateTime? modified = existingDoc.PackageProperties.Modified;
+
+// --- Modify core properties ---
+existingDoc.PackageProperties.Title = "Updated Title";
+existingDoc.PackageProperties.Modified = DateTime.UtcNow;
+
+// --- Read custom properties ---
+var customProps = existingDoc.CustomFilePropertiesPart?.Properties;
+if (customProps != null)
+{
+    foreach (var prop in customProps.Elements<CustomDocumentProperty>())
+    {
+        string name = prop.Name!;
+        // Value is in one of the VT* child elements
+        string? textValue = prop.VTLPWSTR?.Text;
+        string? intValue = prop.VTInt32?.Text;
+        string? boolValue = prop.VTBool?.Text;
+        // Use whichever is non-null
+    }
+}
+
+// --- Update a specific custom property ---
+var deptProp = customProps?.Elements<CustomDocumentProperty>()
+    .FirstOrDefault(p => p.Name == "Department");
+if (deptProp != null)
+{
+    deptProp.VTLPWSTR = new VTLPWSTR("Marketing");
+    customProps!.Save();
+}
+```
+
+---
+
+## 6. Printing & Compatibility Settings
+
+### 6.1 DocumentSettingsPart — Zoom, TabStop, ProofState
+
+```csharp
+// =============================================================================
+// DOCUMENT SETTINGS — ZOOM, TAB STOPS, PROOF STATE
+// =============================================================================
+// DocumentSettingsPart (settings.xml) contains document-wide settings.
+// These control behavior in Word's UI and rendering.
+
+var mainPart2 = doc.MainDocumentPart!;
+var settingsPart2 = mainPart2.DocumentSettingsPart
+    ?? mainPart2.AddNewPart<DocumentSettingsPart>();
+settingsPart2.Settings ??= new Settings();
+var settings = settingsPart2.Settings;
+
+// --- Zoom level ---
+// Val = percentage (100 = 100%). Percent is a string.
+settings.AppendChild(new Zoom
+{
+    Percent = "120",                                      // 120% zoom
+    Val = PresetZoomValues.BestFit                        // Or: None, FullPage, BestFit, TextFit
+});
+// Produces XML: <w:zoom w:percent="120" w:val="bestFit" />
+
+// --- Default Tab Stop ---
+// Distance in DXA for default tab stops. Standard is 720 (0.5 inch).
+settings.AppendChild(new DefaultTabStop
+{
+    Val = 720                                             // 0.5 inch
+});
+// Produces XML: <w:defaultTabStop w:val="720" />
+
+// For Chinese documents, common default tab stop is 420 (about 2 characters wide)
+// settings.AppendChild(new DefaultTabStop { Val = 420 });
+
+// --- Proof State ---
+// Tells Word the spell/grammar check status. Setting both to "clean"
+// prevents Word from showing the "Proofing" notification on open.
+settings.AppendChild(new ProofState
+{
+    Spelling = ProofingStateValues.Clean,
+    Grammar = ProofingStateValues.Clean
+});
+// Produces XML: <w:proofState w:spelling="clean" w:grammar="clean" />
+
+// --- Character Spacing Control ---
+// CompressWhitespace: whether to compress whitespace at line edges (CJK)
+settings.AppendChild(new CharacterSpacingControl
+{
+    Val = CharacterSpacingValues.DoNotCompress
+});
+
+// --- Remove personal information on save ---
+settings.AppendChild(new RemovePersonalInformation());
+// Produces XML: <w:removePersonalInformation />
+
+settings.Save();
+```
+
+### 6.2 Compatibility Settings
+
+```csharp
+// =============================================================================
+// COMPATIBILITY SETTINGS
+// =============================================================================
+// Compatibility settings control how Word renders the document,
+// providing backward compatibility with older Word versions.
+// CompatibilityMode is the most important setting.
+
+var compat = new Compatibility();
+
+// --- Compatibility Mode ---
+// 15 = Word 2013+ mode (current standard)
+// 14 = Word 2010 mode
+// 12 = Word 2007 mode
+// Omitted or 0 = oldest compatibility
+compat.AppendChild(new CompatibilitySetting
+{
+    Name = CompatSettingNameValues.CompatibilityMode,
+    Uri = "http://schemas.microsoft.com/office/word",
+    Val = "15"                                            // Word 2013+ mode
+});
+
+// --- Override page break rules ---
+// Useful compatibility flags for consistent rendering:
+
+// UseWord2002TableStyleRules: use newer table style rules
+compat.AppendChild(new CompatibilitySetting
+{
+    Name = CompatSettingNameValues.OverrideTableStyleFontSizeAndJustification,
+    Uri = "http://schemas.microsoft.com/office/word",
+    Val = "1"
+});
+
+// EnableOpenTypeFeatures: enable advanced typography
+compat.AppendChild(new CompatibilitySetting
+{
+    Name = CompatSettingNameValues.EnableOpenTypeFeatures,
+    Uri = "http://schemas.microsoft.com/office/word",
+    Val = "1"
+});
+
+// DifferentiateMultirowTableHeaders
+compat.AppendChild(new CompatibilitySetting
+{
+    Name = CompatSettingNameValues.DifferentiateMultirowTableHeaders,
+    Uri = "http://schemas.microsoft.com/office/word",
+    Val = "1"
+});
+
+// UseWord2013TrackBottomHyphenation
+compat.AppendChild(new CompatibilitySetting
+{
+    Name = CompatSettingNameValues.UseWord2013TrackBottomHyphenation,
+    Uri = "http://schemas.microsoft.com/office/word",
+    Val = "0"
+});
+
+settings.AppendChild(compat);
+settings.Save();
+
+// Produces XML:
+// <w:compat>
+//   <w:compatSetting w:name="compatibilityMode"
+//     w:uri="http://schemas.microsoft.com/office/word" w:val="15" />
+//   <w:compatSetting w:name="overrideTableStyleFontSizeAndJustification"
+//     w:uri="http://schemas.microsoft.com/office/word" w:val="1" />
+//   ...
+// </w:compat>
+```
+
+### 6.3 MirrorMargins, GutterAtTop, BookFoldPrinting
+
+```csharp
+// =============================================================================
+// MIRROR MARGINS, GUTTER, BOOK FOLD
+// =============================================================================
+// These settings are for documents intended for double-sided printing or
+// book binding.
+
+// --- Mirror Margins ---
+// When enabled, Left/Right margins become Inside/Outside.
+// On even pages, margins are swapped so the binding edge stays consistent.
+settings.AppendChild(new MirrorMargins());
+// Produces XML: <w:mirrorMargins />
+// After this, PageMargin.Left = inside margin, PageMargin.Right = outside margin.
+// Even pages automatically flip them.
+
+// --- Gutter at Top ---
+// By default, gutter is added to the left (or inside with MirrorMargins).
+// GutterAtTop moves the gutter to the top margin instead.
+// Used for calendar-style or top-bound documents.
+settings.AppendChild(new GutterAtTop());
+// Produces XML: <w:gutterAtTop />
+
+// --- Book Fold Printing ---
+// Enables booklet printing (2 pages per sheet, folded in half).
+// Word reorders pages for saddle-stitch binding.
+settings.AppendChild(new BookFoldPrinting());
+// Produces XML: <w:bookFoldPrinting />
+
+// Optional: sheets per booklet (for thick documents split into signatures)
+// Default 0 = all pages in one booklet
+settings.AppendChild(new BookFoldPrintingSheets { Val = 16 });
+// Produces XML: <w:bookFoldPrintingSheets w:val="16" />
+// 16 sheets = 64 pages per booklet signature
+
+// --- Book Fold Reversed ---
+// For right-to-left booklets (Hebrew, Arabic, Japanese right-bound)
+// settings.AppendChild(new BookFoldRevPrinting());
+
+settings.Save();
+```
+
+### 6.4 Additional Document Settings
+
+```csharp
+// =============================================================================
+// ADDITIONAL DOCUMENT SETTINGS
+// =============================================================================
+
+// --- Update Fields on Open ---
+// Forces Word to recalculate all fields (TOC, page numbers, etc.) on open.
+settings.AppendChild(new UpdateFieldsOnOpen { Val = true });
+// Produces XML: <w:updateFields w:val="true" />
+// WARNING: This causes a dialog popup in some Word versions.
+
+// --- Do Not Track Moves ---
+// Prevents move tracking in track changes (shows as delete + insert instead).
+// settings.AppendChild(new DoNotTrackMoves());
+
+// --- Do Not Track Formatting ---
+// Prevents formatting changes from being tracked.
+// settings.AppendChild(new DoNotTrackFormatting());
+
+// --- Default Zoom for Print Preview ---
+// PrintTwoOnOne: print 2 pages per sheet
+// settings.AppendChild(new PrintTwoOnOne());
+
+// --- Document protection (read-only, forms-only, etc.) ---
+// DocumentProtection can enforce read-only, allow only comments,
+// restrict to form fields, etc.
+// settings.AppendChild(new DocumentProtection
+// {
+//     Edit = DocumentProtectionValues.ReadOnly,
+//     Enforcement = true
+// });
+
+// --- Even and Odd Headers (setting-level flag) ---
+// Must be set here for the EvenPage header/footer references to work.
+// settings.AppendChild(new EvenAndOddHeaders());
+
+settings.Save();
+```
+
+### 6.5 Complete Settings Setup
+
+```csharp
+// =============================================================================
+// COMPLETE SETTINGS SETUP — PRODUCTION-READY
+// =============================================================================
+// A comprehensive settings configuration suitable for most documents.
+
+static void ConfigureDocumentSettings(WordprocessingDocument doc)
+{
+    var mainPart = doc.MainDocumentPart!;
+    var settingsPart = mainPart.DocumentSettingsPart
+        ?? mainPart.AddNewPart<DocumentSettingsPart>();
+    settingsPart.Settings = new Settings();
+    var s = settingsPart.Settings;
+
+    // Zoom to 100%
+    s.AppendChild(new Zoom
+    {
+        Percent = "100",
+        Val = PresetZoomValues.None
+    });
+
+    // Default tab stop: 0.5 inch
+    s.AppendChild(new DefaultTabStop { Val = 720 });
+
+    // Mark spell/grammar as clean
+    s.AppendChild(new ProofState
+    {
+        Spelling = ProofingStateValues.Clean,
+        Grammar = ProofingStateValues.Clean
+    });
+
+    // Character spacing control
+    s.AppendChild(new CharacterSpacingControl
+    {
+        Val = CharacterSpacingValues.DoNotCompress
+    });
+
+    // Compatibility: Word 2013+ mode with useful features
+    var compat = new Compatibility();
+    foreach (var (name, val) in new[]
+    {
+        (CompatSettingNameValues.CompatibilityMode, "15"),
+        (CompatSettingNameValues.OverrideTableStyleFontSizeAndJustification, "1"),
+        (CompatSettingNameValues.EnableOpenTypeFeatures, "1"),
+        (CompatSettingNameValues.DifferentiateMultirowTableHeaders, "1"),
+        (CompatSettingNameValues.UseWord2013TrackBottomHyphenation, "0"),
+    })
+    {
+        compat.AppendChild(new CompatibilitySetting
+        {
+            Name = name,
+            Uri = "http://schemas.microsoft.com/office/word",
+            Val = val
+        });
+    }
+    s.AppendChild(compat);
+
+    s.Save();
+}
+
+// Usage:
+ConfigureDocumentSettings(doc);
+```
+
+---
+
+## Quick Reference: Unit Conversions
+
+| Unit | Full Name | Relation |
+|------|-----------|----------|
+| DXA | Twentieths of a point | 1 inch = 1440 DXA; 1 cm = 567 DXA; 1 pt = 20 DXA |
+| Half-point | Half a typographic point | Font size: 24 = 12pt. 1 pt = 2 half-points |
+| Eighth-point | Eighth of a point | Border size: 8 = 1pt. 1 pt = 8 eighth-points |
+| EMU | English Metric Unit | 1 inch = 914400 EMU; 1 cm = 360000 EMU; 1 pt = 12700 EMU |
+| Pct (table width) | Fiftieths of a percent | 5000 = 100%. Multiply percentage by 50 |
+
+## Quick Reference: Common PageSize Values
+
+| Paper | Width (DXA) | Height (DXA) | Inches | mm |
+|-------|-------------|--------------|--------|-----|
+| Letter | 12240 | 15840 | 8.5 x 11 | 216 x 279 |
+| A4 | 11906 | 16838 | -- | 210 x 297 |
+| Legal | 12240 | 20160 | 8.5 x 14 | 216 x 356 |
+| A3 | 16838 | 23811 | -- | 297 x 420 |
+| B5 | 10318 | 14570 | -- | 182 x 257 |
+
+## Quick Reference: Common Margin Presets (DXA)
+
+| Preset | Top | Bottom | Left | Right |
+|--------|-----|--------|------|-------|
+| Normal | 1440 | 1440 | 1440 | 1440 |
+| Narrow | 720 | 720 | 720 | 720 |
+| Moderate | 1440 | 1440 | 1080 | 1080 |
+| Wide | 1440 | 1440 | 2880 | 2880 |
+| Chinese 公文 | 2098 | 1984 | 1588 | 1474 |
diff --git a/builtin-skills/document-process/minimax-docx/references/openxml_encyclopedia_part3.md b/builtin-skills/document-process/minimax-docx/references/openxml_encyclopedia_part3.md
new file mode 100644
index 00000000..04da2134
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/openxml_encyclopedia_part3.md
@@ -0,0 +1,3381 @@
+# OpenXML SDK C# Code Encyclopedia
+Complete, heavily commented C# code patterns for DocumentFormat.OpenXml 3.x / .NET 8+ / C# 12.
+
+**Namespace aliases used throughout:**
+```csharp
+using DocumentFormat.OpenXml;
+using DocumentFormat.OpenXml.Packaging;
+using DocumentFormat.OpenXml.Wordprocessing;
+using A  = DocumentFormat.OpenXml.Drawing;
+using DW = DocumentFormat.OpenXml.Drawing.Wordprocessing;
+using M  = DocumentFormat.OpenXml.Math;
+using PIC = DocumentFormat.OpenXml.Drawing.Pictures;
+```
+
+**EMU conversion reference** (used throughout image/shape code):
+```
+1 inch  = 914400 EMU
+1 cm    = 360000 EMU
+1 pixel @ 96dpi = 9525 EMU
+1 pt    = 12700 EMU
+```
+
+---
+
+## Table of Contents
+
+1. [Table of Contents (TOC)](#1-table-of-contents-toc)
+2. [Footnotes and Endnotes](#2-footnotes-and-endnotes)
+3. [Field Codes — Comprehensive](#3-field-codes--comprehensive)
+4. [Track Changes / Revisions](#4-track-changes--revisions)
+5. [Comments (4-File System)](#5-comments-4-file-system)
+6. [Images — Deep Dive](#6-images--deep-dive)
+7. [Drawing Shapes (Non-Image)](#7-drawing-shapes-non-image)
+8. [Math / Equations (OMML)](#8-math--equations-omml)
+9. [Numbering System — Deep Dive](#9-numbering-system--deep-dive)
+10. [Document Protection & Encryption](#10-document-protection--encryption)
+
+---
+
+## 1. Table of Contents (TOC)
+
+### 1.1 Basic TOC Field (SimpleField Pattern)
+
+The simplest way to insert a TOC. Uses `SimpleField` which wraps the entire field in one element.
+
+```csharp
+// Creates:
+// <w:p>
+//   <w:r>
+//     <w:fldChar w:fldCharType="begin"/>
+//   </w:r>
+//   <w:r>
+//     <w:instrText xml:space="preserve"> TOC \o "1-3" \h \z \u </w:instrText>
+//   </w:r>
+//   <w:r>
+//     <w:fldChar w:fldCharType="separate"/>
+//   </w:r>
+//   <w:r>
+//     <w:t>Update this field to generate table of contents.</w:t>
+//   </w:r>
+//   <w:r>
+//     <w:fldChar w:fldCharType="end"/>
+//   </w:r>
+// </w:p>
+
+var tocParagraph = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" TOC \\o \"1-3\" \\h \\z \\u ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    // Placeholder text shown before update
+    new Run(new Text("Update this field to generate table of contents.") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+body.Append(tocParagraph);
+```
+
+**TOC switch reference:**
+| Switch | Meaning |
+|--------|---------|
+| `\o "1-3"` | Include outline levels 1–3 (customize as needed) |
+| `\h` | Make entries hyperlinks (clickable) |
+| `\z` | Hide tab leader and page numbers in Web Layout view |
+| `\u` | Use applied paragraph outline level |
+| `\f` | TOC entry from bookmark |
+| `\t "style1,style2"` | Use custom styles instead of outline levels |
+| `\n "1-2"` | Omit page numbers for levels 1–2 |
+
+### 1.2 TOC Field with SdtBlock Wrapper
+
+Wrapping a TOC in a Structured Document Tag (SdtBlock) enables rich content control features.
+
+```csharp
+// SdtBlock wrapper provides:
+// - Ability to repeat/remove the entire TOC
+// - Richer programmatic control
+// - "Content Control" appearance in Word UI
+
+var sdtBlock = new SdtBlock(
+    // SdtProperties defines the control's identity and behavior
+    new SdtProperties(
+        new SdtAlias { Val = "Table of Contents" },
+        new Tag { Val = "toc" },
+        new SdtContentText()  // Plain text content
+    ),
+    // SdtContentBlock contains the actual TOC field
+    new SdtContentBlock(
+        new Paragraph(
+            new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+            new Run(new FieldCode(" TOC \\o \"1-2\" \\h \\z ") { Space = SpaceProcessingModeValues.Preserve }),
+            new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+            new Run(new Text("Press F9 or right-click and select 'Update Field'") { Space = SpaceProcessingModeValues.Preserve }),
+            new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+        )
+    )
+);
+body.Append(sdtBlock);
+```
+
+### 1.3 TOC with Custom Heading Levels
+
+Use the `\t` switch to build a TOC from arbitrary styles (not just Heading 1–9).
+
+```csharp
+// TOC using custom style names instead of outline levels:
+// \t switch format: "style1,level1,style2,level2,..."
+// This uses CustomHeading1 and CustomHeading2 styles mapped to TOC levels
+
+var customTocPara = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" TOC \\t \"CustomHeading1,1,CustomHeading2,2,CustomHeading3,3\" \\h \\z ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("Update to see entries from CustomHeading1/2/3 styles.") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+```
+
+### 1.4 TOC with Hyperlinks (\h switch)
+
+The `\h` switch makes TOC entries clickable hyperlinks. This requires the entries to have a hyperlink anchor.
+
+```csharp
+// When \h is used, Word generates internal hyperlinks to each heading.
+// The target is the bookmark automatically created by Word for headings.
+// This is the standard pattern — no additional work needed in the field code itself.
+
+var tocWithHyperlinks = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" TOC \\o \"1-3\" \\h \\z \\u ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    // In Web Layout/Print Layout, Word will populate this with real entries
+    // Each entry will be a hyperlink pointing to the heading's internal bookmark
+    new Run(new Text("Click to update...") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+```
+
+### 1.5 Auto-Update TOC on Document Open
+
+You cannot programmatically update a TOC field's content (Word does this on open). Instead, tell Word to update fields automatically.
+
+```csharp
+// Method 1: Via DocumentSettingsPart — UpdateFieldsOnOpen
+var settingsPart = mainDocumentPart.AddNewPart<DocumentSettingsPart>();
+settingsPart.Settings = new Settings(
+    new UpdateFieldsOnOpen { Val = true }  // Triggers field update on open
+);
+settingsPart.Settings.Save();
+
+// Method 2: Field code includes \w to preserve formatting changes
+// (Field code approach is limited — you still need Word to evaluate it)
+
+// GOTCHA: OpenXML SDK cannot evaluate field codes.
+// Word evaluates fields on open. Other readers (e.g., LibreOffice) may not.
+// The document opens without content until the user explicitly updates.
+```
+
+### 1.6 TOC Styles — Custom TOC1, TOC2, TOC3 Styles with Leaders
+
+Define custom TOC styles with indentation, tab leaders, and proper formatting.
+
+```csharp
+// First, add TOC1/TOC2/TOC3 styles to StyleDefinitionsPart
+var stylesPart = mainDocumentPart.AddNewPart<StyleDefinitionsPart>();
+var styles = new Styles();
+
+// TOC1 — Top-level entry (e.g., "1. Heading")
+var toc1Style = new Style(
+    new StyleName { Val = "toc 1" },
+    new BasedOn { Val = "Normal" },
+    new PrimaryStyle(),
+    new StyleParagraphProperties(
+        new SpacingBetweenLines { Before = "120", After = "60" },
+        new Tabs(new TabStop { Val = TabStopValues.Right, Leader = TabStopLeaderCharValues.Dot, Position = 9072 })  // 5 inches right-aligned with dot leader
+    ),
+    new StyleRunProperties(
+        new Bold(),
+        new FontSize { Val = "24" },  // 12pt
+        new FontSizeComplexScript { Val = "24" }
+    )
+) { Type = StyleValues.Paragraph, StyleId = "TOC1" };
+styles.Append(toc1Style);
+
+// TOC2 — Second-level entry (e.g., "1.1  Subheading")
+var toc2Style = new Style(
+    new StyleName { Val = "toc 2" },
+    new BasedOn { Val = "Normal" },
+    new PrimaryStyle(),
+    new StyleParagraphProperties(
+        new Indentation { Left = "220", Hanging = "220" },  // 0.15" indent, hang to align after number
+        new SpacingBetweenLines { Before = "60", After = "40" },
+        new Tabs(new TabStop { Val = TabStopValues.Right, Leader = TabStopLeaderCharValues.Dot, Position = 9072 })
+    ),
+    new StyleRunProperties(
+        new FontSize { Val = "20" },  // 10pt
+        new FontSizeComplexScript { Val = "20" }
+    )
+) { Type = StyleValues.Paragraph, StyleId = "TOC2" };
+styles.Append(toc2Style);
+
+// TOC3 — Third-level entry
+var toc3Style = new Style(
+    new StyleName { Val = "toc 3" },
+    new BasedOn { Val = "Normal" },
+    new PrimaryStyle(),
+    new StyleParagraphProperties(
+        new Indentation { Left = "440", Hanging = "440" },  // 0.3" indent
+        new SpacingBetweenLines { Before = "40", After = "20" },
+        new Tabs(new TabStop { Val = TabStopValues.Right, Leader = TabStopLeaderCharValues.Dot, Position = 9072 })
+    ),
+    new StyleRunProperties(
+        new Italic(),
+        new FontSize { Val = "20" },
+        new FontSizeComplexScript { Val = "20" }
+    )
+) { Type = StyleValues.Paragraph, StyleId = "TOC3" };
+styles.Append(toc3Style);
+
+stylesPart.Styles = styles;
+stylesPart.Styles.Save();
+
+// Now use \t switch to reference these styles in the TOC field:
+// TOC \t "TOC1,1,TOC2,2,TOC3,3" \h \z
+```
+
+**Tab leader options:** `TabStopLeaderCharValues.Dot` (........), `TabStopLeaderCharValues.Dash` (--------), `TabStopLeaderCharValues.Underscore` (________), `TabStopLeaderCharValues.MiddleDot` (·······).
+
+### 1.7 Mini TOC for a Section
+
+A mini TOC covers only a portion of the document using a bookmark-scoped `\f` switch.
+
+```csharp
+// Step 1: Define a bookmark around the section to be covered
+var sectionStart = new BookmarkStart { Id = "10", Name = "_Section1TOC" };
+var sectionEnd = new BookmarkEnd { Id = "10" };
+
+// Step 2: Put heading paragraphs inside the bookmark range
+var headingPara = new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+    new Run(new Text("Section A: Introduction"))
+);
+
+// Full section wrapped in bookmark
+body.Append(sectionStart);
+body.Append(headingPara);
+body.Append(sectionEnd);
+
+// Step 3: Mini TOC field references that bookmark with \f switch
+var miniTocPara = new Paragraph(
+    new Run(new Text("In this section: ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" TOC \\f _Section1TOC ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("Mini TOC placeholder") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+```
+
+---
+
+## 2. Footnotes and Endnotes
+
+### 2.1 FootnotesPart — Initialization
+
+Footnotes in Word require a dedicated `FootnotesPart`. The first three footnotes are special: separator, continuation separator, and continuation notice.
+
+```csharp
+// Initialize the FootnotesPart
+var footnotesPart = mainDocumentPart.AddNewPart<FootnotesPart>();
+var footnotes = new Footnotes();
+
+// CRITICAL: Footnotes must start with these 3 special footnotes:
+// 1. Separator (id="0") — thin line between main text and footnotes
+// 2. ContinuationSeparator (id="1") — thick line when footnotes continue to next column/page
+// 3. ContinuationNotice (id="2") — "..." text when footnotes overflow
+
+// Footnote ID=0: Separator (appears between main text and first footnote)
+var separatorFootnote = new Footnote(
+    new Paragraph(
+        new ParagraphProperties(
+            new SpacingBetweenLines { After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto }
+        ),
+        // The separator is just a paragraph with a border at the bottom
+        new Paragraph(
+            new Run(new Separator())
+        )
+    )
+) { Type = FootnoteEndnoteValues.Separator, Id = 0 };
+footnotes.Append(separatorFootnote);
+
+// Footnote ID=1: Continuation Separator
+var continuationSepFootnote = new Footnote(
+    new Paragraph(
+        new ParagraphProperties(
+            new SpacingBetweenLines { After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto }
+        ),
+        new Run(new ContinuationSeparator())
+    )
+) { Type = FootnoteEndnoteValues.ContinuationSeparator, Id = 1 };
+footnotes.Append(continuationSepFootnote);
+
+// Footnote ID=2: Continuation Notice (optional, appears when footnotes overflow)
+var continuationNoticeFootnote = new Footnote(
+    new Paragraph(
+        new ParagraphProperties(
+            new SpacingBetweenLines { After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto }
+        ),
+        new Run(new Text("...") { Space = SpaceProcessingModeValues.Preserve })
+    )
+) { Type = FootnoteEndnoteValues.ContinuationNotice, Id = 2 };
+footnotes.Append(continuationNoticeFootnote);
+
+footnotesPart.Footnotes = footnotes;
+footnotesPart.Footnotes.Save();
+```
+
+### 2.2 Adding a Normal Footnote
+
+Place a `FootnoteReference` in the document body and corresponding `Footnote` content in `FootnotesPart`.
+
+```csharp
+// In the document body, at the insertion point:
+var footnoteRefRun = new Run(
+    new RunProperties(
+        new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }
+    ),
+    new FootnoteReference { Id = 3 }  // ID must match the Footnote's Id
+);
+body.Append(new Paragraph(
+    new Run(new Text("Some text with a footnote marker.") { Space = SpaceProcessingModeValues.Preserve }),
+    footnoteRefRun
+));
+
+// In FootnotesPart, add the corresponding footnote content:
+// <w:footnote w:id="3">
+//   <w:p>
+//     <w:pPr><w:pStyle w:val="FootnoteText"/></w:pPr>
+//     <w:r><w:footnoteRef/></w:r>
+//     <w:r><w:t xml:space="preserve"> This is the footnote text.</w:t></w:r>
+//   </w:p>
+// </w:footnote>
+
+var newFootnote = new Footnote { Id = 3 };
+newFootnote.Append(new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "FootnoteText" }),
+    new Run(new FootnoteReferenceMark()),  // Small superscript mark
+    new Run(new Text(" This is the footnote text.") { Space = SpaceProcessingModeValues.Preserve })
+));
+footnotesPart.Footnotes!.Append(newFootnote);
+footnotesPart.Footnotes.Save();
+```
+
+### 2.3 Footnote with Custom Mark (Asterisk, Symbol)
+
+Override the default auto-numbering with a custom symbol.
+
+```csharp
+// Use FootnoteReferenceMark (the automatic symbol) OR provide a custom character.
+// For custom marks, use a regular Run with the symbol character instead of FootnoteReferenceMark.
+
+// Footnote ID=4 with custom asterisk mark
+var customFootnote = new Footnote { Id = 4 };
+customFootnote.Append(new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "FootnoteText" }),
+    // Custom mark: use a bold asterisk from Symbol font
+    new Run(
+        new RunProperties(
+            new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }
+        ),
+        new RunFonts { Ascii = "Symbol", HighAnsi = "Symbol" },
+        new Text("*")
+    ),
+    new Run(new Text(" Custom footnote with symbol mark.") { Space = SpaceProcessingModeValues.Preserve })
+));
+footnotesPart.Footnotes!.Append(customFootnote);
+
+// In document body, at the insertion point:
+var customFootnoteRef = new Run(
+    new RunProperties(
+        new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }
+    ),
+    new FootnoteReference { Id = 4 }
+);
+```
+
+### 2.4 FootnotePosition — Placement via SectionProperties
+
+Control whether footnotes appear at the bottom of each page or beneath the text.
+
+```csharp
+// Add FootnoteProperties to SectionProperties
+var sectPr = body.Elements<SectionProperties>().First()
+    ?? body.AppendChild(new SectionProperties());
+
+// Footnote placement:
+// - BottomOfPage (default) — footnotes appear at bottom of page
+// - BeneathText — footnotes appear immediately below the last text on the page
+sectPr.Append(new FootnoteProperties(
+    new FootnotePosition { Val = FootnotePositionValues.BeneathText }
+));
+
+// Footnote numbering restart options:
+// - RestartAtSection — restart numbering at each section
+// - RestartAtPage — restart at each page (Word default for footnotes)
+// - Continuous — don't restart (number sequentially through document)
+sectPr.Append(new FootnoteProperties(
+    new FootnotePosition { Val = FootnotePositionValues.BottomOfPage },
+    new FootnoteNumberingFormat { Val = NumberFormatValues.Decimal },  // 1, 2, 3...
+    new FootnoteNumberingStart { Val = 1 },  // Start at 1
+    new FootnoteNumberingRestart { Val = FootnoteRestartValues.RestartAtPage }
+));
+```
+
+### 2.5 EndnotesPart — Same Pattern
+
+Endnotes follow the exact same structure as footnotes but use `EndnotesPart`.
+
+```csharp
+var endnotesPart = mainDocumentPart.AddNewPart<EndnotesPart>();
+var endnotes = new Endnotes();
+
+// Endnote ID=0: Separator (same pattern as footnotes)
+var endnoteSeparator = new Endnote(
+    new Paragraph(new Run(new Separator()))
+) { Type = FootnoteEndnoteValues.Separator, Id = 0 };
+endnotes.Append(endnoteSeparator);
+
+// Endnote ID=1: ContinuationSeparator
+var endnoteContSep = new Endnote(
+    new Paragraph(new Run(new ContinuationSeparator()))
+) { Type = FootnoteEndnoteValues.ContinuationSeparator, Id = 1 };
+endnotes.Append(endnoteContSep);
+
+endnotesPart.Endnotes = endnotes;
+endnotesPart.Endnotes.Save();
+
+// In document body, use EndnoteReference instead of FootnoteReference
+var endnoteRefRun = new Run(
+    new RunProperties(
+        new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }
+    ),
+    new EndnoteReference { Id = 3 }
+);
+body.Append(new Paragraph(
+    new Run(new Text("An endnote marker.") { Space = SpaceProcessingModeValues.Preserve }),
+    endnoteRefRun
+));
+
+// Corresponding Endnote content in EndnotesPart
+var newEndnote = new Endnote { Id = 3 };
+newEndnote.Append(new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "EndnoteText" }),
+    new Run(new EndnoteReferenceMark()),
+    new Run(new Text(" This is the endnote content.") { Space = SpaceProcessingModeValues.Preserve })
+));
+endnotesPart.Endnotes!.Append(newEndnote);
+```
+
+### 2.6 Endnote Placement via SectionProperties
+
+```csharp
+// EndnoteProperties on SectionProperties controls endnote placement
+sectPr.Append(new EndnoteProperties(
+    new EndnotePosition { Val = EndnotePositionValues.EndOfDocument }  // Default
+    // Other options: EndOfSection, BeneathText (rarely used for endnotes)
+));
+```
+
+---
+
+## 3. Field Codes — Comprehensive
+
+### 3.1 SimpleField vs Complex Field Architecture
+
+**SimpleField** — single element, easier to write but less control:
+```csharp
+// <w:fldSimple w:instr=" PAGE "><w:r><w:t>1</w:t></w:r></w:fldSimple>
+new SimpleField(new Run(new Text("1"))) { Instruction = " PAGE " }
+```
+
+**Complex Field (Begin/Separate/End)** — full control over each field component:
+```csharp
+// <w:r><w:fldChar w:fldCharType="begin"/></w:r>
+// <w:r><w:instrText> PAGE </w:instrText></w:r>
+// <w:r><w:fldChar w:fldCharType="separate"/></w:r>
+// <w:r><w:t>1</w:t></w:r>
+// <w:r><w:fldChar w:fldCharType="end"/></w:r>
+new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+new Run(new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }),
+new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+new Run(new Text("1")),  // Cached result shown until update
+new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+```
+
+**Key differences:**
+- `SimpleField` is one `w:fldSimple` element containing one `w:r`
+- Complex field uses `FieldChar` with `FieldCharValues.Begin/Separate/End` to delimit regions
+- `FieldCode` is `w:instrText` — contains the field instruction string
+- The text between `Separate` and `End` is the "cached result" shown before update
+- After `Separate`, `FieldCode` contains the switches that define field behavior
+
+### 3.2 PAGE, NUMPAGES, DATE, TIME
+
+**PAGE — current page number:**
+```csharp
+// SimpleField version
+new SimpleField(new Run(new Text("1"))) { Instruction = " PAGE " }
+
+// Complex field version
+new Paragraph(
+    new Run(new Text("Page ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("1")),  // Cached value
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+```
+
+**NUMPAGES — total page count:**
+```csharp
+new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" NUMPAGES ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("10")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+    new Run(new Text(" pages") { Space = SpaceProcessingModeValues.Preserve })
+);
+```
+
+**DATE — current date with format switch:**
+```csharp
+// DATE with custom format: \@ "yyyy-MM-dd"
+// The \@ switch specifies the date picture
+new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" DATE \\@ \"yyyy-MM-dd\" ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("2026-03-22")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// DATE with time: \@ "MMMM d, yyyy h:mm AM/PM"
+new Run(new FieldCode(" DATE \\@ \"MMMM d, yyyy h:mm AM/PM\" ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// DATE with locale: \* MERGEFORMAT preserves formatting on update
+new Run(new FieldCode(" DATE \\@ \"d/M/yyyy\" \\* MERGEFORMAT ") { Space = SpaceProcessingModeValues.Preserve }),
+```
+
+**TIME — current time:**
+```csharp
+new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" TIME \\@ \"HH:mm:ss\" ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("14:30:00")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+```
+
+### 3.3 FILENAME, AUTHOR, TITLE (Document Properties)
+
+These fields pull from the document's core properties.
+
+```csharp
+// FILENAME — document filename
+new Run(new FieldCode(" FILENAME ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// FILENAME with path: \* MERGEFORMAT
+new Run(new FieldCode(" FILENAME \\* MERGEFORMAT ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// AUTHOR — from document core properties
+new Run(new FieldCode(" AUTHOR ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// TITLE — from document core properties
+new Run(new FieldCode(" TITLE ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// SUBJECT — from document core properties
+new Run(new FieldCode(" SUBJECT ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// Keywords — from document core properties
+new Run(new FieldCode(" KEYWORDS ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// All document property fields
+new Paragraph(
+    new Run(new Text("Title: ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" TITLE ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("My Document")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+```
+
+**Set document properties programmatically:**
+```csharp
+// Set core properties via PackageProperties (OfficePackage)
+var package = doc.ExtendedFilePropertiesPart?.Properties;
+if (package != null)
+{
+    package.Creator = "Author Name";
+    package.Title = "Document Title";
+    package.Subject = "Subject";
+    package.Description = "Description";
+    package.Keywords = "keyword1, keyword2";
+    package.Save();
+}
+```
+
+### 3.4 REF — Cross-Reference to Bookmark
+
+`REF` retrieves the text of a bookmarked paragraph or the value of a REF field.
+
+```csharp
+// First, create a bookmark around some content
+var bookmarkStart = new BookmarkStart { Id = "100", Name = "Figure1Caption" };
+var bookmarkEnd = new BookmarkEnd { Id = "100" };
+var captionPara = new Paragraph(
+    new Run(new Text("Figure 1: Architecture diagram") { Space = SpaceProcessingModeValues.Preserve })
+);
+body.Append(new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "Caption" }),
+    bookmarkStart,
+    new Run(new Text("Figure 1: Architecture diagram")),
+    bookmarkEnd
+));
+
+// Now reference it with REF field
+var refField = new Paragraph(
+    new Run(new Text("As shown in ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" REF Figure1Caption \\* MERGEFORMAT ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("Figure 1: Architecture diagram")),  // Cached result
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+    new Run(new Text(", the system consists of...") { Space = SpaceProcessingModeValues.Preserve })
+);
+```
+
+**REF switches:**
+| Switch | Effect |
+|--------|--------|
+| `\r` | Insert bookmarked text but as hyperlink |
+| `\h` | Make REF a hyperlink to the bookmark |
+| `\n` | Suppress paragraph number |
+| `\p` | Show relative position (above/below) |
+| `\t` | Suppress trailing spaces |
+| `\* MERGEFORMAT` | Preserve formatting |
+
+### 3.5 SEQ — Sequence Numbering for Figures/Tables
+
+`SEQ` generates auto-incrementing numbers for elements like figures, tables, and listings.
+
+```csharp
+// First figure caption
+var fig1Caption = new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "Caption" }),
+    new Run(new Text("Figure ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" SEQ Figure \\* ARABIC ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("1")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+    new Run(new Text(": System Architecture") { Space = SpaceProcessingModeValues.Preserve })
+);
+
+// Second figure (Word auto-increments)
+var fig2Caption = new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "Caption" }),
+    new Run(new Text("Figure ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" SEQ Figure \\* ARABIC ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("2")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+    new Run(new Text(": Data Flow") { Space = SpaceProcessingModeValues.Preserve })
+);
+
+// Reference a figure number
+var figRef = new Paragraph(
+    new Run(new Text("See Figure ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" SEQ Figure \\* ARABIC ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("1")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+    new Run(new Text(" above.") { Space = SpaceProcessingModeValues.Preserve })
+);
+
+// SEQ sequence identifier: "Figure" can be any name
+// Multiple sequences: SEQ Figure, SEQ Table, SEQ Listing are independent
+```
+
+### 3.6 HYPERLINK — Internal and External Links
+
+```csharp
+// External hyperlink (to URL)
+var extHyperlinkRel = mainDocumentPart.AddHyperlinkRelationship(
+    new Uri("https://example.com"), true);
+var extHyperlink = new Hyperlink(
+    new Run(
+        new RunProperties(new Color { Val = "0563C1" }, new Underline { Val = UnderlineValues.Single }),
+        new Text("Visit Example.com")
+    )
+) { Id = extHyperlinkRel.Id };  // Id references the relationship
+
+// Internal hyperlink (to bookmark)
+var intHyperlink = new Hyperlink(
+    new Run(
+        new RunProperties(new Color { Val = "0563C1" }, new Underline { Val = UnderlineValues.Single }),
+        new Text("Go to Chapter 1")
+    )
+) { Anchor = "Chapter1Bookmark" };  // Anchor = bookmark name
+
+// HYPERLINK field for advanced cases (with screen tip)
+var hyperlinkedField = new Run(
+    new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" HYPERLINK \\l \"Chapter1Bookmark\" \\t \"_top\" ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("Go to Chapter 1")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// \l = target (anchor for internal, URL for external)
+// \t = target frame (optional, e.g., "_top" to open in same window)
+```
+
+### 3.7 MERGEFIELD — Mail Merge
+
+```csharp
+// MERGEFIELD uses a special syntax: MERGEFIELD FieldName
+// The field name must match a mail merge data source column name
+
+// Simple MERGEFIELD
+var mergeFieldPara = new Paragraph(
+    new Run(new Text("Dear ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" MERGEFIELD FirstName ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("«FirstName»")),  // «» are Word's placeholder markers
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+    new Run(new Text(",") { Space = SpaceProcessingModeValues.Preserve })
+);
+
+// Full name with formatting
+var mergeFieldWithFormat = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" MERGEFIELD FullName \\* UPPERCASE ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("«FullName»")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// To actually perform mail merge, use Word's MailMerge settings
+var settingsPart = mainDocumentPart.AddNewPart<DocumentSettingsPart>();
+settingsPart.Settings = new Settings(
+    new MailMerge(
+        new DataType { Val = MailMergeDataValues.TextFile },
+        new DataSourceReference { Id = "rIdForDataSource" }
+    )
+);
+```
+
+### 3.8 IF Field — Conditional Text
+
+The `IF` field evaluates a condition and displays one of two text values. Commonly used with `MERGEFIELD`.
+
+```csharp
+// IF Field syntax: IF [expression] [operator] [value] "true_text" "false_text"
+// Often combined with MERGEFIELD:
+
+// If the recipient's region equals "USA", show "Dear Customer", otherwise "Dear Valued Customer"
+var ifFieldPara = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    // Complex nested: { IF { MERGEFIELD Region } = "USA" "Dear American Customer" "Dear Customer" }
+    new Run(new FieldCode(" IF ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),  // Nested MERGEFIELD begin
+    new Run(new FieldCode(" MERGEFIELD Region ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("«Region»")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),     // Nested MERGEFIELD end
+    new Run(new FieldCode(" = \"USA\" \"Dear American Customer\" \"Dear Customer\" ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("Dear Customer")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// Note: Nested fields within IF are tricky with complex field syntax.
+// A simpler approach: use two separate IF fields checking a bookmark value.
+```
+
+### 3.9 STYLEREF — Reference Heading Text
+
+`STYLEREF` displays the text of the nearest paragraph with a specified style — useful for running headers.
+
+```csharp
+// STYLEREF Heading1 — inserts the text of the most recent Heading1 paragraph
+// Great for running headers that show the current chapter
+
+// Running header in footer
+var footerPart = mainDocumentPart.AddNewPart<FooterPart>();
+footerPart.Footer = new Footer(
+    new Paragraph(
+        new ParagraphProperties(
+            new Justification { Val = JustificationValues.Right }
+        ),
+        // Left-aligned: chapter heading
+        new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+        new Run(new FieldCode(" STYLEREF \"Heading 1\" ") { Space = SpaceProcessingModeValues.Preserve }),
+        new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+        new Run(new Text("Chapter Title")),
+        new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+        new Run(new Text("\t") { Space = SpaceProcessingModeValues.Preserve }),  // Tab
+        // Right-aligned: page number
+        new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+        new Run(new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }),
+        new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+        new Run(new Text("1")),
+        new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+    )
+);
+
+// STYLEREF with \n switch to suppress paragraph numbering
+new Run(new FieldCode(" STYLEREF \"Heading 1\" \\n ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// STYLEREF with \p switch to show relative position
+new Run(new FieldCode(" STYLEREF \"Heading 2\" \\p ") { Space = SpaceProcessingModeValues.Preserve }),
+```
+
+### 3.10 SET and ASK Fields
+
+`SET` stores a value in a variable. `ASK` prompts the user and stores their response.
+
+```csharp
+// SET — define a document variable (accessed via DOCPROPERTY or REF)
+var setField = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" SET MyVariable \"some value\" ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// REF to read the variable
+var refMyVar = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" REF MyVariable ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("some value")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// ASK — prompt user for input when field is updated
+// Note: ASK displays a dialog box when updated
+var askField = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" ASK AuthorName \"Enter author name:\" ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+    // REF to display the stored value
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" REF AuthorName ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("Author Name")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+```
+
+### 3.11 Calculated Fields (= Expressions)
+
+The `=` field evaluates arithmetic expressions.
+
+```csharp
+// = field with arithmetic
+var calcPara = new Paragraph(
+    new Run(new Text("Total: $") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" = 100 + 250 - 30 ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("320")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// = with multiplication using SEQ references
+var calcWithSeq = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" = 3 * 5 ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("15")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// Combine with formatting
+new Run(new FieldCode(" = 1000 * 1.08 \\# \"#,##0.00\" ") { Space = SpaceProcessingModeValues.Preserve }),
+// \# switch applies number format to result
+```
+
+### 3.12 UpdateFieldsOnOpen — Automatic Field Updates
+
+```csharp
+// Settings that trigger field updates when document opens
+var settingsPart = mainDocumentPart.AddNewPart<DocumentSettingsPart>();
+settingsPart.Settings = new Settings(
+    // Update all fields (TOC, REF, PAGE, etc.) on open
+    new UpdateFieldsOnOpen { Val = true }
+);
+settingsPart.Settings.Save();
+
+// Additional field-related settings:
+var additionalSettings = new Settings(
+    // Auto-format fractions: 1/2 → ½
+    new AutomaticAdjustmentOfFontSizesToFitDocument(),
+
+    // True: use field codes instead of cached values on update
+    new UseXSLTWhenSaving(),
+
+    // Mail merge settings
+    new MailMerge(
+        new MainDocumentType { Val = MailMergeDocumentValues.FormLetters }
+    )
+);
+```
+
+---
+
+## 4. Track Changes / Revisions
+
+### 4.1 Enabling Track Changes
+
+Track changes must be explicitly enabled via DocumentSettingsPart.
+
+```csharp
+var settingsPart = mainDocumentPart.AddNewPart<DocumentSettingsPart>();
+settingsPart.Settings = new Settings(
+    // Enable track changes — any edit will be tracked
+    new TrackRevisions()
+);
+
+// Also recommended: prevent fields from being updated during tracking
+settingsPart.Settings.Append(new DonNotTrackFormatting());
+```
+
+### 4.2 InsertedRun (w:ins) — Tracked Insertion
+
+```csharp
+// <w:ins w:id="5" w:author="Alice" w:date="2026-03-22T10:00:00Z">
+//   <w:r>
+//     <w:t>Inserted text.</w:t>
+//   </w:r>
+// </w:ins>
+
+var insertedText = new InsertedRun(
+    new Run(
+        new Text("Inserted text.") { Space = SpaceProcessingModeValues.Preserve }
+    )
+)
+{
+    Author = "Alice",
+    Date = new DateTime(2026, 3, 22, 10, 0, 0, DateTimeKind.Utc),
+    Id = "5"
+};
+
+var para = new Paragraph(
+    new Run(new Text("Existing text. ") { Space = SpaceProcessingModeValues.Preserve }),
+    insertedText,
+    new Run(new Text(" More existing text.") { Space = SpaceProcessingModeValues.Preserve })
+);
+```
+
+### 4.3 DeletedRun (w:del) — Tracked Deletion
+
+**CRITICAL: Inside `w:del`, text MUST be `DeletedText` (`w:delText`), NOT `Text` (`w:t`)!**
+
+```csharp
+// <w:del w:id="6" w:author="Alice" w:date="2026-03-22T10:05:00Z">
+//   <w:r>
+//     <w:rPr><w:b/></w:rPr>
+//     <w:delText>Deleted text.</w:delText>
+//   </w:r>
+// </w:del>
+
+var deletedRun = new DeletedRun(
+    new Run(
+        new RunProperties(new Bold()),
+        new DeletedText("Deleted text.") { Space = SpaceProcessingModeValues.Preserve }
+    )
+)
+{
+    Author = "Alice",
+    Date = new DateTime(2026, 3, 22, 10, 5, 0, DateTimeKind.Utc),
+    Id = "6"
+};
+
+var para = new Paragraph(
+    new Run(new Text("Keep this. ") { Space = SpaceProcessingModeValues.Preserve }),
+    deletedRun,
+    new Run(new Text(" Keep this too.") { Space = SpaceProcessingModeValues.Preserve })
+);
+
+// GOTCHA: Never use <w:t> inside <w:del> — use <w:delText> only.
+// Using w:t inside w:del causes corruption or silent repair by Word.
+```
+
+### 4.4 RunPropertiesChange — Formatting Change Tracking
+
+Records that a run's formatting was changed. The `w:rPrChange` goes inside `w:rPr`.
+
+```csharp
+// <w:r>
+//   <w:rPr>
+//     <w:b/>  <!-- New: bold -->
+//     <w:rPrChange w:id="7" w:author="Bob" w:date="2026-03-22T11:00:00Z">
+//       <w:rPr/>  <!-- Old: no formatting -->
+//     </w:rPrChange>
+//   </w:rPr>
+//   <w:t>Formatted text.</w:t>
+// </w:r>
+
+// The current (new) formatting is in the outer w:rPr
+// The old (previous) formatting is in the w:rPrChange child
+var formattedTextRun = new Run(
+    new RunProperties(
+        new Bold(),  // New formatting: now bold
+        new RunPropertiesChange(  // Records the old formatting (empty = not bold)
+            new RunProperties()  // Empty = previously had no formatting
+        )
+        {
+            Author = "Bob",
+            Date = new DateTime(2026, 3, 22, 11, 0, 0, DateTimeKind.Utc),
+            Id = "7"
+        }
+    ),
+    new Text("Formatted text.") { Space = SpaceProcessingModeValues.Preserve }
+);
+```
+
+### 4.5 ParagraphPropertiesChange
+
+Records that paragraph-level properties were changed.
+
+```csharp
+// <w:pPr>
+//   <w:jc w:val="center"/>  <!-- New: centered -->
+//   <w:pPrChange w:id="8" w:author="Bob" w:date="2026-03-22T11:05:00Z">
+//     <w:pPr>
+//       <w:jc w:val="left"/>  <!-- Old: left-aligned -->
+//     </w:pPr>
+//   </w:pPrChange>
+// </w:pPr>
+
+var changedPara = new Paragraph(
+    new ParagraphProperties(
+        new Justification { Val = JustificationValues.Center },  // New
+        new ParagraphPropertiesChange(
+            new ParagraphProperties(
+                new Justification { Val = JustificationValues.Left }  // Old
+            )
+        )
+        {
+            Author = "Bob",
+            Date = new DateTime(2026, 3, 22, 11, 5, 0, DateTimeKind.Utc),
+            Id = "8"
+        }
+    ),
+    new Run(new Text("Centered paragraph."))
+);
+```
+
+### 4.6 ParagraphMarkRunPropertiesChange
+
+Records that the paragraph mark's formatting (trailing formatting) was changed.
+
+```csharp
+// <w:p>
+//   <w:pPr>
+//     <w:pPrChange .../>
+//   </w:pPr>
+//   <w:r>
+//     <w:rPr>
+//       <w:b/>  <!-- New paragraph mark: bold -->
+//       <w:rPrChange w:id="9" ...>
+//         <w:rPr/>  <!-- Old: no formatting on paragraph mark -->
+//       </w:rPrChange>
+//     </w:rPr>
+//   </w:r>
+// </w:r>
+```
+
+### 4.7 Table Revision Marks
+
+```csharp
+// TableRowInsertionRevision — a row was inserted
+// <w:trPr>
+//   <w:ins w:id="10" w:author="Alice" w:date="..."/>
+// </w:trPr>
+
+var insertedRow = new TableRow(
+    new TableRowProperties(
+        new TableRowInsertionRevision
+        {
+            Author = "Alice",
+            Date = new DateTime(2026, 3, 22, 12, 0, 0, DateTimeKind.Utc),
+            Id = "10"
+        }
+    ),
+    new TableCell(new Paragraph(new Run(new Text("New row cell"))))
+);
+
+// TableCellInsertionRevision — a cell was inserted
+var insertedCell = new TableCell(
+    new TableCellProperties(
+        new TableCellInsertionRevision
+        {
+            Author = "Alice",
+            Date = new DateTime(2026, 3, 22, 12, 1, 0, DateTimeKind.Utc),
+            Id = "11"
+        }
+    ),
+    new Paragraph(new Run(new Text("New cell")))
+);
+```
+
+### 4.8 SectionPropertiesChange
+
+```csharp
+// <w:sectPr>
+//   <w:sectPrChange w:id="12" w:author="Bob" w:date="...">
+//     <w:sectPr>
+//       <w:pgSz w:w="12240" w:h="15840"/>  <!-- Old: Letter -->
+//     </w:sectPr>
+//   </w:sectPrChange>
+//   <w:pgSz w:w="16838" w:h="11906"/>  <!-- New: A4 -->
+// </w:sectPr>
+
+var changedSection = new SectionProperties(
+    new PageSize { Width = 16838U, Height = 11906U },  // New: A4
+    new SectionPropertiesChange(
+        new SectionProperties(
+            new PageSize { Width = 12240U, Height = 15840U }  // Old: Letter
+        )
+    )
+    {
+        Author = "Bob",
+        Date = new DateTime(2026, 3, 22, 12, 30, 0, DateTimeKind.Utc),
+        Id = "12"
+    }
+);
+```
+
+### 4.9 NumberingChange
+
+```csharp
+// <w:numPr>
+//   <w:ilvl w:val="0"/>
+//   <w:numId w:val="3"/>
+//   <w:numPrChange w:id="13" w:author="Alice" w:date="...">
+//     <w:numPr>
+//       <w:ilvl w:val="0"/>
+//       <w:numId w:val="1"/>  <!-- Old: was numId 1 -->
+//     </w:numPr>
+//   </w:numPrChange>
+// </w:numPr>
+
+var changedNumbering = new NumberingProperties(
+    new NumberingLevelReference { Val = 0 },
+    new NumberingId { Val = 3 },  // New: numId 3
+    new NumberingChange(
+        new NumberingProperties(
+            new NumberingLevelReference { Val = 0 },
+            new NumberingId { Val = 1 }  // Old: numId 1
+        )
+    )
+    {
+        Author = "Alice",
+        Date = new DateTime(2026, 3, 22, 13, 0, 0, DateTimeKind.Utc),
+        Id = "13"
+    }
+);
+```
+
+### 4.10 Accepting All Revisions Programmatically
+
+```csharp
+// Accept all revisions: unwrap w:ins (keep content), remove w:del entirely
+public static void AcceptAllRevisions(WordprocessingDocument doc)
+{
+    var body = doc.MainDocumentPart?.Document?.Body;
+    if (body == null) return;
+
+    // Accept insertions: remove w:ins wrapper, keep inner runs
+    var insertions = body.Descendants<InsertedRun>().ToList();
+    foreach (var ins in insertions)
+    {
+        var parent = ins.Parent;
+        if (parent == null) continue;
+        var children = ins.ChildElements.ToList();
+        foreach (var child in children)
+        {
+            child.Remove();
+            parent.InsertBefore(child, ins);
+        }
+        ins.Remove();
+    }
+
+    // Accept deletions: remove entire w:del element
+    var deletions = body.Descendants<DeletedRun>().ToList();
+    foreach (var del in deletions)
+        del.Remove();
+}
+
+// Also accept formatting changes:
+// For w:rPrChange: replace the entire RunProperties with the "old" properties inside the change
+// For w:pPrChange: replace with the old properties
+```
+
+### 4.11 Rejecting All Revisions Programmatically
+
+```csharp
+// Reject all revisions: unwrap w:del (restore text), remove w:ins entirely
+public static void RejectAllRevisions(WordprocessingDocument doc)
+{
+    var body = doc.MainDocumentPart?.Document?.Body;
+    if (body == null) return;
+
+    // Reject insertions: remove entire w:ins element and its content
+    var insertions = body.Descendants<InsertedRun>().ToList();
+    foreach (var ins in insertions)
+        ins.Remove();
+
+    // Reject deletions: unwrap w:del, convert w:delText back to w:t
+    var deletions = body.Descendants<DeletedRun>().ToList();
+    foreach (var del in deletions)
+    {
+        var parent = del.Parent;
+        if (parent == null) continue;
+        foreach (var run in del.Elements<Run>().ToList())
+        {
+            foreach (var delText in run.Elements<DeletedText>().ToList())
+            {
+                var text = new Text(delText.Text) { Space = delText.Space };
+                delText.InsertAfterSelf(text);
+                delText.Remove();
+            }
+            run.Remove();
+            parent.InsertBefore(run, del);
+        }
+        del.Remove();
+    }
+}
+```
+
+### 4.12 MoveFrom / MoveTo — Tracked Text Moving
+
+```csharp
+// MoveFrom (w:moveFrom) marks the origin of moved text
+// MoveTo (w:moveTo) marks the destination
+// Both must have the same w:id
+
+// <w:moveFrom w:id="14" w:author="Alice" w:date="...">
+//   <w:r><w:t>Text that was moved.</w:t></w:r>
+// </w:moveFrom>
+
+// At destination:
+// <w:moveTo w:id="14" w:author="Alice" w:date="...">
+//   <w:r><w:t>Text that was moved.</w:t></w:r>
+// </w:moveTo>
+
+var movedFrom = new MoveFromRun(
+    new Run(new Text("Text that was moved.") { Space = SpaceProcessingModeValues.Preserve })
+)
+{
+    Author = "Alice",
+    Date = new DateTime(2026, 3, 22, 14, 0, 0, DateTimeKind.Utc),
+    Id = "14"
+};
+
+var movedTo = new MoveToRun(
+    new Run(new Text("Text that was moved.") { Space = SpaceProcessingModeValues.Preserve })
+)
+{
+    Author = "Alice",
+    Date = new DateTime(2026, 3, 22, 14, 0, 0, DateTimeKind.Utc),
+    Id = "14"
+};
+```
+
+### 4.13 RevisionId Generation
+
+All revision elements need unique, monotonically increasing integer IDs.
+
+```csharp
+public static int GetNextRevisionId(Body body)
+{
+    int maxId = 0;
+    foreach (var elem in body.Descendants<OpenXmlElement>())
+    {
+        // Check common revision element types for Id attribute
+        var idAttr = elem.GetAttributes()
+            .FirstOrDefault(a => a.LocalName == "id" &&
+                (elem is InsertedRun or DeletedRun or DeletedText or
+                 MoveFromRun or MoveToRun or RunPropertiesChange or
+                 ParagraphPropertiesChange or SectionPropertiesChange or
+                 TableRowInsertionRevision or TableCellInsertionRevision));
+        if (idAttr.Value != null && int.TryParse(idAttr.Value, out int id) && id > maxId)
+            maxId = id;
+    }
+    return maxId + 1;
+}
+
+// Simpler approach: scan all elements with "id" attribute in the document
+public static int GetNextRevisionIdSimple(Body body)
+{
+    int maxId = 0;
+    foreach (var elem in body.Descendants<OpenXmlElement>())
+    {
+        foreach (var attr in elem.GetAttributes())
+        {
+            if (attr.LocalName == "id" && int.TryParse(attr.Value, out int id) && id > maxId)
+                maxId = id;
+        }
+    }
+    return maxId + 1;
+}
+```
+
+---
+
+## 5. Comments (4-File System)
+
+### 5.1 Full 4-File Comment System Setup
+
+Comments require four XML files plus markers in `document.xml`.
+
+```csharp
+// This method creates a complete comment with all 4 files properly initialized
+public static int AddFullComment(
+    WordprocessingDocument doc,
+    string text,
+    string author,
+    string initials,
+    string rangeText,
+    int? existingCommentId = null)
+{
+    var mainPart = doc.MainDocumentPart
+        ?? throw new InvalidOperationException("Document has no MainDocumentPart.");
+
+    int commentId = existingCommentId ?? GetNextCommentId(doc);
+
+    // Generate paraId (8-char hex) and durableId (8-digit hex)
+    string paraId = Guid.NewGuid().ToString("N")[..8].ToUpperInvariant();
+    string durableId = new Random().Next(0x10000000, 0xFFFFFFFF).ToString("X8");
+
+    var body = mainPart.Document!.Body!;
+
+    // ─────────────────────────────────────────────────────────────
+    // FILE 1: word/comments.xml — Main comment content
+    // ─────────────────────────────────────────────────────────────
+    var commentsPart = mainPart.WordprocessingCommentsPart
+        ?? mainPart.AddNewPart<WordprocessingCommentsPart>();
+
+    if (commentsPart.Comments == null)
+        commentsPart.Comments = new Comments();
+
+    // Create a paragraph for the comment with a unique paraId (via w14:paraId)
+    var commentPara = new Paragraph(
+        new ParagraphProperties(
+            new ParagraphStyleId { Val = "CommentText" },
+            // w14:paraId for modern comment threading
+            new乳啜攠嘶嘐呓顾纨asiId { Val = paraId }
+        ),
+        new Run(
+            new RunProperties(new RunStyle { Val = "CommentReference" }),
+            new AnnotationReferenceMark()
+        ),
+        new Run(new Text(text))
+    );
+
+    var comment = new Comment
+    {
+        Id = commentId.ToString(),
+        Author = author,
+        Date = DateTime.UtcNow,
+        Initials = initials
+    };
+    comment.Append(commentPara);
+    commentsPart.Comments.Append(comment);
+    commentsPart.Comments.Save();
+
+    // ─────────────────────────────────────────────────────────────
+    // FILE 2: word/commentsExtended.xml — W15 extensions (paraId, done status)
+    // ─────────────────────────────────────────────────────────────
+    var commentsExPart = mainPart.WordprocessingCommentsExPart
+        ?? mainPart.AddNewPart<WordprocessingCommentsExPart>();
+
+    if (commentsExPart.CommentsEx == null)
+        commentsExPart.CommentsEx = new CommentExCollection();
+
+    // w15:commentEx links the comment to its paragraph and tracks done/resolved
+    var commentEx = new CommentEx
+    {
+        ParaId = new HexBinaryValue(paraId),
+        Done = new OnOffValue(false)  // done="0" = not resolved
+    };
+    commentsExPart.CommentsEx.Append(commentEx);
+    commentsExPart.CommentsEx.Save();
+
+    // ─────────────────────────────────────────────────────────────
+    // FILE 3: word/commentsIds.xml — Persistent ID mapping
+    // ─────────────────────────────────────────────────────────────
+    var commentsIdsPart = mainPart.WordprocessingCommentsIdsPart
+        ?? mainPart.AddNewPart<WordprocessingCommentsIdsPart>();
+
+    if (commentsIdsPart.CommentsIds == null)
+        commentsIdsPart.CommentsIds = new CommentIds();
+
+    // w16cid:commentId maps paraId to a durable (globally unique) ID
+    var commentIdEntry = new CommentId
+    {
+        ParaId = new HexBinaryValue(paraId),
+        DurableId = durableId
+    };
+    commentsIdsPart.CommentsIds.Append(commentIdEntry);
+    commentsIdsPart.CommentsIds.Save();
+
+    // ─────────────────────────────────────────────────────────────
+    // FILE 4: word/commentsExtensible.xml — W16 extensible
+    // ─────────────────────────────────────────────────────────────
+    var commentsExtPart = mainPart.WordprocessingCommentsExtensiblePart
+        ?? mainPart.AddNewPart<WordprocessingCommentsExtensiblePart>();
+
+    if (commentsExtPart.CommentsExtensible == null)
+        commentsExtPart.CommentsExtensible = new CommentExtensibleCollection();
+
+    // w16cex:commentExtensible provides the durable ID with UTC timestamp
+    var extensibleEntry = new CommentExtensible
+    {
+        DurableId = durableId,
+        DateUtc = DateTime.UtcNow
+    };
+    commentsExtPart.CommentsExtensible.Append(extensibleEntry);
+    commentsExtPart.CommentsExtensible.Save();
+
+    // ─────────────────────────────────────────────────────────────
+    // document.xml — Insert range markers around the target text
+    // ─────────────────────────────────────────────────────────────
+    // commentRangeStart and commentRangeEnd bracket the commented text
+    // commentReference is a run containing the visible superscript number
+    var rangeStart = new CommentRangeStart { Id = commentId.ToString() };
+    var rangeEnd = new CommentRangeEnd { Id = commentId.ToString() };
+    var refRun = new Run(
+        new RunProperties(new RunStyle { Val = "CommentReference" }),
+        new CommentReference { Id = commentId.ToString() }
+    );
+
+    // Find the paragraph containing rangeText and insert markers
+    // Simple approach: append at end of body
+    body.Append(rangeStart);
+    body.Append(new Paragraph(new Run(new Text(rangeText))));
+    body.Append(rangeEnd);
+    body.Append(new Paragraph(refRun));  // The comment ref must be in its own paragraph
+
+    return commentId;
+}
+
+// Helper: get next comment ID
+private static int GetNextCommentId(WordprocessingDocument doc)
+{
+    var commentsPart = doc.MainDocumentPart?.WordprocessingCommentsPart;
+    if (commentsPart?.Comments == null) return 1;
+    int max = 0;
+    foreach (var c in commentsPart.Comments.Elements<Comment>())
+        if (c.Id?.Value != null && int.TryParse(c.Id.Value, out int id) && id > max)
+            max = id;
+    return max + 1;
+}
+```
+
+**The 4 files at a glance:**
+
+| File | Part Class | Content | Key Attributes |
+|------|-----------|---------|----------------|
+| `comments.xml` | `WordprocessingCommentsPart` | Comment text | `w:id`, `w:author`, `w:date`, `w:initials` |
+| `commentsExtended.xml` | `WordprocessingCommentsExPart` | W15 extensions | `w15:paraId`, `w15:done` |
+| `commentsIds.xml` | `WordprocessingCommentsIdsPart` | Persistent IDs | `w16cid:paraId`, `w16cid:durableId` |
+| `commentsExtensible.xml` | `WordprocessingCommentsExtensiblePart` | W16 extensible | `w16cex:durableId`, `w16cex:dateUtc` |
+
+### 5.2 Comment Reply (Threaded Comments)
+
+```csharp
+// To add a reply, create a new comment and link it to the parent via commentsExtended.xml
+
+public static int AddCommentReply(
+    WordprocessingDocument doc,
+    int parentCommentId,
+    string replyText,
+    string author,
+    string initials)
+{
+    var mainPart = doc.MainDocumentPart!;
+
+    // Get parent's paraId from commentsExtended.xml
+    var commentsExPart = mainPart.WordprocessingCommentsExPart;
+    var parentParaId = "";
+    if (commentsExPart?.CommentsEx != null)
+    {
+        var parentCommentEx = commentsExPart.CommentsEx
+            .Elements<CommentEx>()
+            .FirstOrDefault(ce =>
+                ce.Parent is Comment c &&
+                c.Id?.Value == parentCommentId.ToString());
+        // Actually need to cross-reference through paraId...
+        // Simpler: look up via comments.xml paraId
+    }
+
+    // Generate new IDs for the reply
+    int replyId = GetNextCommentId(doc);
+    string replyParaId = Guid.NewGuid().ToString("N")[..8].ToUpperInvariant();
+    string durableId = new Random().Next(0x10000000, 0xFFFFFFFF).ToString("X8");
+
+    // Add to comments.xml (new comment with same structure)
+    var commentsPart = mainPart.WordprocessingCommentsPart!;
+    var replyComment = new Comment
+    {
+        Id = replyId.ToString(),
+        Author = author,
+        Date = DateTime.UtcNow,
+        Initials = initials
+    };
+    replyComment.Append(new Paragraph(
+        new ParagraphProperties(new ParagraphStyleId { Val = "CommentText" }),
+        new Run(new RunProperties(new RunStyle { Val = "CommentReference" }), new AnnotationReferenceMark()),
+        new Run(new Text(replyText))
+    ));
+    commentsPart.Comments!.Append(replyComment);
+    commentsPart.Comments.Save();
+
+    // KEY: In commentsExtended.xml, use paraIdParent to link to parent
+    var commentsEx = mainPart.WordprocessingCommentsExPart!;
+    var replyEx = new CommentEx
+    {
+        ParaId = new HexBinaryValue(replyParaId),
+        ParaIdParent = new HexBinaryValue(parentParaId),  // Link to parent
+        Done = new OnOffValue(false)
+    };
+    commentsEx.CommentsEx!.Append(replyEx);
+    commentsEx.CommentsEx.Save();
+
+    // Add to commentsIds.xml and commentsExtensible.xml (same pattern as parent)
+    // ... (same as AddFullComment for these two files)
+
+    // Note: Replies do NOT need range markers in document.xml
+    // They appear threaded under the parent in Word's UI
+
+    return replyId;
+}
+```
+
+### 5.3 Resolving a Comment
+
+```csharp
+// To resolve (mark done), set w15:done="1" in commentsExtended.xml
+public static void ResolveComment(WordprocessingDocument doc, int commentId)
+{
+    var mainPart = doc.MainDocumentPart!;
+
+    // Need to find the paraId for this commentId, then update commentsExtended.xml
+    // Step 1: Get paraId from comments.xml
+    var commentsPart = mainPart.WordprocessingCommentsPart!;
+    var comment = commentsPart.Comments!
+        .Elements<Comment>()
+        .FirstOrDefault(c => c.Id?.Value == commentId.ToString());
+
+    // Find the paragraph and get its paraId
+    string? paraId = null;
+    if (comment != null)
+    {
+        var para = comment.Elements<Paragraph>().FirstOrDefault();
+        var paraIdElem = para?.ParagraphProperties?
+            .Elements<乳啜攠嘶嘐呓顾纨asiId>().FirstOrDefault();
+        paraId = paraIdElem?.Val?.Value;
+    }
+
+    if (paraId == null) return;
+
+    // Step 2: Update commentsExtended.xml
+    var commentsExPart = mainPart.WordprocessingCommentsExPart!;
+    var commentEx = commentsExPart.CommentsEx!
+        .Elements<CommentEx>()
+        .FirstOrDefault(ce => ce.ParaId?.Value == paraId);
+
+    if (commentEx != null)
+        commentEx.Done = new OnOffValue(true);  // Sets done="1"
+
+    commentsExPart.CommentsEx!.Save();
+}
+```
+
+### 5.4 Deleting a Comment (All 4 Files)
+
+```csharp
+// Must remove from all 4 files AND from document.xml
+public static void DeleteComment(WordprocessingDocument doc, int commentId)
+{
+    var mainPart = doc.MainDocumentPart!;
+    string commentIdStr = commentId.ToString();
+
+    // ── Remove from comments.xml ──
+    var commentsPart = mainPart.WordprocessingCommentsPart;
+    if (commentsPart?.Comments != null)
+    {
+        var comment = commentsPart.Comments
+            .Elements<Comment>()
+            .FirstOrDefault(c => c.Id?.Value == commentIdStr);
+        if (comment != null)
+        {
+            // Get paraId before deletion for other files
+            string? paraId = null;
+            var para = comment.Elements<Paragraph>().FirstOrDefault();
+            var paraIdElem = para?.ParagraphProperties?
+                .Elements<乳啜攠嘶嘐呓顾纨asiId>().FirstOrDefault();
+            paraId = paraIdElem?.Val?.Value;
+
+            comment.Remove();
+
+            // ── Remove from commentsExtended.xml ──
+            var commentsExPart = mainPart.WordprocessingCommentsExPart;
+            if (commentsExPart?.CommentsEx != null && paraId != null)
+            {
+                var commentEx = commentsExPart.CommentsEx
+                    .Elements<CommentEx>()
+                    .FirstOrDefault(ce => ce.ParaId?.Value == paraId);
+                commentEx?.Remove();
+                commentsExPart.CommentsEx.Save();
+            }
+
+            // ── Remove from commentsIds.xml ──
+            var commentsIdsPart = mainPart.WordprocessingCommentsIdsPart;
+            if (commentsIdsPart?.CommentsIds != null && paraId != null)
+            {
+                var cidEntry = commentsIdsPart.CommentsIds
+                    .Elements<CommentId>()
+                    .FirstOrDefault(ci => ci.ParaId?.Value == paraId);
+                cidEntry?.Remove();
+                commentsIdsPart.CommentsIds.Save();
+            }
+
+            // ── Remove from commentsExtensible.xml ──
+            // Need to look up by durableId...
+            var commentsExtPart = mainPart.WordprocessingCommentsExtensiblePart;
+            if (commentsExtPart?.CommentsExtensible != null)
+            {
+                // Find by matching durableId (must track separately)
+                var extEntry = commentsExtPart.CommentsExtensible
+                    .Elements<CommentExtensible>()
+                    .FirstOrDefault();  // Match by durableId lookup
+                extEntry?.Remove();
+                commentsExtPart.CommentsExtensible.Save();
+            }
+        }
+    }
+
+    // ── Remove from document.xml ──
+    var body = mainPart.Document!.Body!;
+
+    // Remove CommentRangeStart
+    var rangeStart = body.Descendants<CommentRangeStart>()
+        .FirstOrDefault(crs => crs.Id?.Value == commentIdStr);
+    rangeStart?.Remove();
+
+    // Remove CommentRangeEnd
+    var rangeEnd = body.Descendants<CommentRangeEnd>()
+        .FirstOrDefault(cre => cre.Id?.Value == commentIdStr);
+    rangeEnd?.Remove();
+
+    // Remove CommentReference run (the superscript marker)
+    var commentRefs = body.Descendants<CommentReference>()
+        .Where(cr => cr.Id?.Value == commentIdStr)
+        .ToList();
+    foreach (var cr in commentRefs)
+    {
+        var run = cr.Parent as Run;
+        cr.Remove();
+        run?.Remove();
+    }
+
+    commentsPart?.Comments?.Save();
+}
+```
+
+---
+
+## 6. Images — Deep Dive
+
+### 6.1 Adding an ImagePart (All Image Types)
+
+```csharp
+// All image types supported by AddImagePart:
+void AddImageExamples(MainDocumentPart mainPart, string pngPath, string jpegPath,
+    string gifPath, string svgPath, string bmpPath, string tiffPath)
+{
+    // PNG
+    var pngPart = mainPart.AddImagePart(ImagePartType.Png);
+    using (var s = File.OpenRead(pngPath)) pngPart.FeedData(s);
+    string pngRelId = mainPart.GetIdOfPart(pngPart);
+
+    // JPEG
+    var jpegPart = mainPart.AddImagePart(ImagePartType.Jpeg);
+    using (var s = File.OpenRead(jpegPath)) jpegPart.FeedData(s);
+    string jpegRelId = mainPart.GetIdOfPart(jpegPart);
+
+    // GIF
+    var gifPart = mainPart.AddImagePart(ImagePartType.Gif);
+    using (var s = File.OpenRead(gifPath)) gifPart.FeedData(s);
+    string gifRelId = mainPart.GetIdOfPart(gifPart);
+
+    // SVG (may require additional handling for fallback)
+    var svgPart = mainPart.AddImagePart(ImagePartType.Svg);
+    using (var s = File.OpenRead(svgPath)) svgPart.FeedData(s);
+    string svgRelId = mainPart.GetIdOfPart(svgPart);
+
+    // BMP (stored internally as PNG in OOXML)
+    var bmpPart = mainPart.AddImagePart(ImagePartType.Bmp);
+    using (var s = File.OpenRead(bmpPath)) bmpPart.FeedData(s);
+    string bmpRelId = mainPart.GetIdOfPart(bmpPart);
+
+    // TIFF (similarly converted)
+    var tiffPart = mainPart.AddImagePart(ImagePartType.Tiff);
+    using (var s = File.OpenRead(tiffPath)) tiffPart.FeedData(s);
+    string tiffRelId = mainPart.GetIdOfPart(tiffPart);
+
+    // Also available: ImagePartType.Icon, ImagePartType.Emf, ImagePartType.Wmf
+}
+```
+
+### 6.2 Inline Image (DW.Inline)
+
+Inline images are anchored to a specific character position, not floating.
+
+```csharp
+// Dimensions: widthPx * 9525 EMU = EMU width, heightPx * 9525 EMU = EMU height
+// Assuming 600x400 pixel image at 96dpi:
+//   cx = 600 * 9525 = 5715000 EMU
+//   cy = 400 * 9525 = 3810000 EMU
+
+long cx = (long)(widthInches * 914400);    // From inches to EMU
+long cy = (long)(heightInches * 914400);   // From inches to EMU
+
+// Or from pixels at 96dpi:
+long cxPx = 600, cyPx = 400;
+long cx = cxPx * 9525L;  // 5715000 EMU
+long cy = cyPx * 9525L;  // 3810000 EMU
+
+// Drawing → DW.Inline → A.Graphic → A.GraphicData → PIC.Picture
+var drawing = new Drawing(
+    new DW.Inline(
+        // Extent: defines the image's display size in EMU
+        new DW.Extent { Cx = cx, Cy = cy },
+        // EffectExtent: needed for some effects (set to 0 for basic images)
+        new DW.EffectExtent { EffectExtentL = 0, EffectExtentT = 0, EffectExtentR = 0, EffectExtentB = 0 },
+        // DocProperties: metadata for the image (Id must be unique in document)
+        new DW.DocProperties { Id = 1U, Name = "Image_1", Description = "A sample image" },
+        // NonVisualGraphicFrameDrawingProperties: locks and frame settings
+        new DW.NonVisualGraphicFrameDrawingProperties(
+            new A.GraphicFrameLocks { NoChangeAspect = true }
+        ),
+        // The actual image
+        new A.Graphic(
+            new A.GraphicData(
+                new PIC.Picture(
+                    // Non-visual properties
+                    new PIC.NonVisualPictureProperties(
+                        new PIC.NonVisualDrawingProperties { Id = 0U, Name = "image1" },
+                        new PIC.NonVisualPictureDrawingProperties()
+                    ),
+                    // Fill: how the image is stretched to fill its frame
+                    new PIC.BlipFill(
+                        // Blip: the actual image data reference
+                        new A.Blip { Embed = relId, CompressionState = A.BlipCompressionValues.Print },
+                        // Stretch: how to fill if aspect ratio doesn't match
+                        new A.Stretch(new A.FillRectangle())
+                    ),
+                    // ShapeProperties: transform and geometry
+                    new PIC.ShapeProperties(
+                        new A.Transform2D(
+                            new A.Offset { X = 0L, Y = 0L },
+                            new A.Extents { Cx = cx, Cy = cy }
+                        ),
+                        new A.PresetGeometry(new A.AdjustValueList())
+                        { Preset = A.ShapeTypeValues.Rectangle }
+                    )
+                )
+            ) { Uri = "http://schemas.openxmlformats.org/drawingml/2006/picture" }
+        )
+    )
+    {
+        DistanceFromTop = 0U,
+        DistanceFromBottom = 0U,
+        DistanceFromLeft = 0U,
+        DistanceFromRight = 0U
+    }
+);
+
+// Append to a paragraph
+var para = new Paragraph(new Run(drawing));
+body.Append(para);
+```
+
+### 6.3 Floating / Anchored Image (DW.Anchor)
+
+Floating images have text wrapping and can be positioned relative to page, margin, column, or paragraph.
+
+```csharp
+// DW.Anchor — positioned floating image with text wrapping
+// Key differences from Inline:
+//   - DW.Anchor instead of DW.Inline
+//   - DW.PositionH / DW.PositionV for positioning
+//   - wrapping element (WrapSquare, WrapTight, etc.)
+//   - can have extent on the anchor (effect extent)
+
+var floatingDrawing = new Drawing(
+    new DW.Anchor(
+        // Horizontal positioning
+        new DW.SimplePosition { X = 0L, Y = 0L },  // Offset from anchor point
+        new DW.HorizontalPosition(
+            new DW.PositionOffset((914400L * 2).ToString())  // 2 inches from left
+        )
+        { RelativeFrom = DW.HorizontalRelativePositionValues.Page },
+        // Vertical positioning
+        new DW.VerticalPosition(
+            new DW.PositionOffset((914400L * 3).ToString())  // 3 inches from top
+        )
+        { RelativeFrom = DW.VerticalRelativePositionValues.Page },
+
+        // Image extent (size)
+        new DW.Extent { Cx = cx, Cy = cy },
+        new DW.EffectExtent { EffectExtentL = 0, EffectExtentT = 0, EffectExtentR = 0, EffectExtentB = 0 },
+
+        new DW.DocProperties { Id = 2U, Name = "Floating_Image" },
+        new DW.NonVisualGraphicFrameDrawingProperties(
+            new A.GraphicFrameLocks { NoChangeAspect = true }
+        ),
+
+        // Text wrapping — several options:
+        // WrapSquare: text wraps on all sides (default)
+        // WrapTight: text wraps close to image shape
+        // WrapThrough: text wraps through the image
+        // WrapTopAndBottom: image on its own line, text above and below
+        // WrapNone: image behind/in front of text
+        new DW.WrapSquare { WrapText = DW.WrapTextValues.RightMargin },
+
+        // Layout in table cell (if applicable)
+        new DW.DocPart Gallery { Val = DW.DocPartGalleryValues.Default },
+
+        // Change paragraph that the image is anchored to
+        // Allow the image to move with the paragraph
+        new DW.EditingIndependentFromParagraph { Val = false },
+
+        // Horizontal anchor: anchor to character/column/margin/page
+        new DW.HorizontalAnchor { Val = DW.HorizontalAnchorValues.Page },
+        // Vertical anchor: anchor to character/line/margin/page/paragraph
+        new DW.VerticalAnchor { Val = DW.VerticalAnchorValues.Page },
+
+        // Alignment (if using alignment-based positioning)
+        new DW.Aligned { Horizontal = DW.HorizontalAlignmentValues.Left,
+                         Vertical = DW.VerticalAlignmentValues.Top },
+
+        new A.Graphic(...)
+    )
+    {
+        // Anchor lock: prevents moving in Word UI
+        EditId = "1A2B3C",
+        BehindDoc = false,  // true = behind text, false = in front
+        Locked = false,
+        LayoutInCell = true,  // Allow layout inside table cells
+        AllowOverlap = true   // Allow overlap with other floating elements
+    }
+);
+```
+
+### 6.4 Text Wrapping Options
+
+```csharp
+// WrapSquare — text surrounds on all sides
+new DW.WrapSquare { WrapText = DW.WrapTextValues.RightMargin }
+
+// WrapTight — text follows contour of image (if shape has custom geometry)
+new DW.WrapTight { WrapText = DW.WrapTextValues.LeftMargin }
+
+// WrapThrough — text intermingles with image
+new DW.WrapThrough(
+    new DW.WrapTextValues.LeftMargin,  // Text on left
+    new DW.WrapTextValues.RightMargin   // Text on right
+)
+
+// WrapTopAndBottom — image on own line
+new DW.WrapTopAndBottom()
+
+// WrapNone — image is at anchor position, text overlays (or vice versa)
+new DW.WrapNone()
+
+// Behind document text:
+var anchor = new DW.Anchor(...){ BehindDoc = true, Locked = false };
+```
+
+### 6.5 Image Sizing — EMU Calculations
+
+```csharp
+// EMU reference:
+//   1 inch = 914400 EMU
+//   1 cm   = 360000 EMU
+//   1 pixel at 96dpi = 9525 EMU
+//   1 pixel at 72dpi = 635 EMU (point, not EMU)
+
+public static class ImageSizing
+{
+    // From pixel dimensions at given DPI
+    public static (long cx, long cy) FromPixels(int widthPx, int heightPx, int dpi = 96)
+    {
+        long emuPerPixel = 914400L / dpi;  // ~9525 at 96dpi
+        return (widthPx * emuPerPixel, heightPx * emuPerPixel);
+    }
+
+    // From inches
+    public static (long cx, long cy) FromInches(double widthIn, double heightIn)
+    {
+        return ((long)(widthIn * 914400), (long)(heightIn * 914400));
+    }
+
+    // From centimeters
+    public static (long cx, long cy) FromCentimeters(double widthCm, double heightCm)
+    {
+        return ((long)(widthCm * 360000), (long)(heightCm * 360000));
+    }
+
+    // Maintain aspect ratio given a target width
+    public static (long cx, long cy) ScaleToWidth(long originalCx, long originalCy, long targetCx)
+    {
+        double ratio = (double)originalCy / originalCx;
+        return (targetCx, (long)(targetCx * ratio));
+    }
+
+    // Common photo sizes in inches: 4x6, 5x7, 8x10
+    public static (long cx, long cy) PhotoSize4x6()
+        => FromInches(4, 6);
+
+    public static (long cx, long cy) PhotoSize5x7()
+        => FromInches(5, 7);
+
+    public static (long cx, long cy) PhotoSize8x10()
+        => FromInches(8, 10);
+}
+```
+
+### 6.6 Image with Border
+
+```csharp
+// Add border to image via PIC.ShapeProperties → A.Outline
+new PIC.ShapeProperties(
+    new A.Transform2D(
+        new A.Offset { X = 0L, Y = 0L },
+        new A.Extents { Cx = cx, Cy = cy }
+    ),
+    new A.PresetGeometry(new A.AdjustValueList())
+    { Preset = A.ShapeTypeValues.Rectangle },
+    // The border/outline
+    new A.Outline(
+        new A.SolidFill(new A.RgbColorModelHex { Val = "000000" }),
+        new A.PresetDash { Val = A.PresetLineDashValues.Solid }
+    )
+    { Width = 12700 }  // 12700 EMU = 1pt, so 25400 = 2pt
+);
+```
+
+### 6.7 Image with Alt Text (DocProperties.Description)
+
+```csharp
+// Alt text is set via DocProperties.Description
+// Also accessible via Picture's alternative text in Word UI
+
+new DW.DocProperties
+{
+    Id = 1U,
+    Name = "Chart showing growth",
+    Description = "Bar chart showing quarterly revenue growth from Q1 to Q4 2025"
+    // Title is also available but Description is what Word shows as alt text
+};
+
+// Also set via A.Descriptive (for some image types)
+```
+
+### 6.8 Image in Header / Footer
+
+```csharp
+// Images in headers/footers work the same as in body, just on the respective part
+var headerPart = mainPart.AddNewPart<HeaderPart>();
+
+// Logo in header
+var logoDrawing = new Drawing(
+    new DW.Inline(
+        new DW.Extent { Cx = 914400L, Cy = 457200L },  // 1" x 0.5" logo
+        new DW.EffectExtent(),
+        new DW.DocProperties { Id = 1U, Name = "HeaderLogo" },
+        new DW.NonVisualGraphicFrameDrawingProperties(
+            new A.GraphicFrameLocks { NoChangeAspect = true }),
+        new A.Graphic(
+            new A.GraphicData(
+                new PIC.Picture(
+                    new PIC.NonVisualPictureProperties(
+                        new PIC.NonVisualDrawingProperties { Id = 0U, Name = "logo" },
+                        new PIC.NonVisualPictureDrawingProperties()),
+                    new PIC.BlipFill(
+                        new A.Blip { Embed = headerLogoRelId },
+                        new A.Stretch(new A.FillRectangle())),
+                    new PIC.ShapeProperties(
+                        new A.Transform2D(
+                            new A.Offset { X = 0L, Y = 0L },
+                            new A.Extents { Cx = 914400L, Cy = 457200L }),
+                        new A.PresetGeometry(new A.AdjustValueList())
+                        { Preset = A.ShapeTypeValues.Rectangle }))
+                )
+            ) { Uri = "http://schemas.openxmlformats.org/drawingml/2006/picture" }
+        )
+    )
+    { DistanceFromTop = 0U, DistanceFromBottom = 0U,
+      DistanceFromLeft = 0U, DistanceFromRight = 0U }
+);
+
+headerPart.Header = new Header(
+    new Paragraph(
+        new ParagraphProperties(
+            new Justification { Val = JustificationValues.Right }),
+        new Run(logoDrawing)
+    )
+);
+```
+
+### 6.9 Image in Table Cell
+
+```csharp
+// Images in table cells use the same patterns
+// With inline: works fine within cell
+// With floating/anchor: set LayoutInCell = true
+
+var cellWithImage = new TableCell(
+    new TableCellProperties(
+        new TableCellWidth { Width = 2000, Type = TableWidthUnitValues.Dxa }
+    ),
+    new Paragraph(
+        new Run(
+            new Drawing(
+                new DW.Inline(
+                    new DW.Extent { Cx = 914400L, Cy = 914400L },  // 1"x1"
+                    new DW.EffectExtent(),
+                    new DW.DocProperties { Id = 5U, Name = "CellImage" },
+                    new DW.NonVisualGraphicFrameDrawingProperties(
+                        new A.GraphicFrameLocks { NoChangeAspect = true }),
+                    new A.Graphic(
+                        new A.GraphicData(
+                            new PIC.Picture(...)
+                        ) { Uri = "..." }
+                    )
+                )
+                { DistanceFromTop = 0U, DistanceFromBottom = 0U,
+                  DistanceFromLeft = 0U, DistanceFromRight = 0U }
+            )
+        )
+    )
+);
+```
+
+### 6.10 Replacing an Image (Update Blip.Embed)
+
+```csharp
+// To replace an existing image, update the Blip's Embed relationship ID
+// 1. Get the existing image's relationship ID from Blip.Embed
+// 2. Replace the image data in that ImagePart with new data
+// 3. Keep the same relationship ID (so all references remain valid)
+
+public static void ReplaceImage(WordprocessingDocument doc, string newImagePath)
+{
+    var mainPart = doc.MainDocumentPart!;
+    var body = mainPart.Document!.Body!;
+
+    foreach (var drawing in body.Descendants<Drawing>())
+    {
+        // Look for inline or anchor images
+        var inline = drawing.Descendants<DW.Inline>().FirstOrDefault();
+        var anchor = drawing.Descendants<DW.Anchor>().FirstOrDefault();
+
+        var blipFill = (inline ?? anchor as OpenXmlElement)?
+            .Descendants<PIC.BlipFill>().FirstOrDefault();
+
+        if (blipFill == null) continue;
+
+        var blip = blipFill.Blip;
+        if (blip?.Embed == null) continue;
+
+        string relId = blip.Embed.Value!;
+
+        // Get the existing ImagePart
+        if (mainPart.GetPartById(relId) is ImagePart existingImagePart)
+        {
+            // Replace the data
+            using (var newData = File.OpenRead(newImagePath))
+                existingImagePart.FeedData(newData);
+            return;  // Replace first found, or loop for all
+        }
+    }
+}
+```
+
+### 6.11 SVG with PNG Fallback (SvgBlip)
+
+```csharp
+// SVG images use SvgBlip for modern Word apps, with PNG fallback for older versions
+// This is handled through the package structure — Word picks the best supported format
+
+// SVG stored as ImagePartType.Svg, but rendered via BlipFill with extension:
+// <a:blip xmlns:a="..." r:embed="rId...">
+//   <a:extLst>
+//     <a:ext uri="http://schemas.openxmlformats.org/drawingml/2006/svg">
+//       <asvg:svg xmlns:asvg="..."/>  <!-- SVG-specific data -->
+//     </a:ext>
+//   </a:extLst>
+// </a:blip>
+
+var svgImagePart = mainPart.AddImagePart(ImagePartType.Svg);
+using (var s = File.OpenRead("chart.svg")) svgImagePart.FeedData(s);
+string svgRelId = mainPart.GetIdOfPart(svgImagePart);
+
+// Word automatically handles SVG→PNG fallback in older versions
+// No explicit fallback needed in code — the document format handles it
+
+// Note: SvgBlip class in SDK 3.x provides direct support
+new A.SvgBlip { Embed = svgRelId };
+```
+
+---
+
+## 7. Drawing Shapes (Non-Image)
+
+### 7.1 WordprocessingShape — Basic Shapes (wsp)
+
+WordprocessingShape uses the `wps` namespace for Word's built-in shape library.
+
+```csharp
+// Shapes require:
+// - MainDocumentPart.AddNewPart<WordprocessingShapePart>() or
+// - Embedded via DrawingML inside a Drawing element
+// The most common approach is embedding shapes directly in a Drawing element
+
+// Shapes in WordprocessingDrawing are placed like images (inline or anchored)
+var shapeDrawing = new Drawing(
+    new DW.Inline(
+        new DW.Extent { Cx = 1714500L, Cy = 914400L },  // 1.875" x 1" rectangle
+        new DW.EffectExtent(),
+        new DW.DocProperties { Id = 10U, Name = "Rectangle 1" },
+        new DW.NonVisualGraphicFrameDrawingProperties(
+            new A.GraphicFrameLocks()),
+        // The shape itself
+        new A.Graphic(
+            new A.GraphicData(
+                // WordprocessingShape = wsp:wsp (rectangle, roundedRect, ellipse, etc.)
+                new WSP.WordprocessingShape(
+                    // Non-visual properties
+                    new WSP.NonVisualDrawingShapeProperties(
+                        new A.ShapeLocks { NoChangeAspect = true }
+                    ),
+                    // Shape properties (fill, outline, geometry)
+                    new WSP.ShapeProperties(
+                        new A.Transform2D(
+                            new A.Offset { X = 0L, Y = 0L },
+                            new A.Extents { Cx = 1714500L, Cy = 914400L }
+                        ),
+                        // PresetGeometry determines the shape type
+                        new A.PresetGeometry(new A.AdjustValueList())
+                        {
+                            Preset = A.ShapeTypeValues.Rectangle
+                            // Other values: RoundedRectangle, Ellipse, Triangle, etc.
+                        },
+                        // Fill color (solid)
+                        new A.SolidFill(
+                            new A.RgbColorModelHex { Val = "4472C4" }
+                        ),
+                        // Outline
+                        new A.Outline(
+                            new A.NoFill()  // No outline
+                            // Or: new A.SolidFill(new A.RgbColorModelHex { Val = "000000" })
+                            // { Width = 12700 } for 1pt border
+                        )
+                    ),
+                    // Text box content
+                    new WSP.TextBoxInfo2(
+                        new TextBoxContent(
+                            new Paragraph(
+                                new ParagraphProperties(
+                                    new Justification { Val = JustificationValues.Center }),
+                                new Run(
+                                    new RunProperties(
+                                        new Color { Val = "FFFFFF" },
+                                        new Bold()),
+                                    new Text("Hello World"))
+                            )
+                        )
+                    )
+                )
+            ) { Uri = "http://schemas.microsoft.com/office/word/2010/wordprocessingShape" }
+        )
+    )
+    { DistanceFromTop = 0U, DistanceFromBottom = 0U,
+      DistanceFromLeft = 0U, DistanceFromRight = 0U }
+);
+```
+
+**Preset shape types (`A.ShapeTypeValues`):**
+- `Rectangle`, `RoundedRectangle`, `Ellipse`, `Triangle`, `RightTriangle`
+- `Parallelogram`, `Trapezoid`, `Pentagon`, `Hexagon`, `Octagon`
+- `Star4`, `Star5`, `Star6`, `Star8`, `Star10`, `Star12`
+- `Heart`, `ArrowRight`, `ArrowLeft`, `ArrowUp`, `ArrowDown`
+- `Callout1`, `Callout2`, `Callout3` (with tail)
+- `FlowChartProcess`, `FlowChartDecision`, `FlowChartDocument`
+
+### 7.2 Shape with Gradient Fill
+
+```csharp
+new WSP.ShapeProperties(
+    new A.Transform2D(...),
+    new A.PresetGeometry(new A.AdjustValueList())
+    { Preset = A.ShapeTypeValues.RoundedRectangle },
+    // Gradient fill
+    new A.GradientFill(
+        new A.LinearGradientFill(
+            new A.Stop { Offset = "0", Color = new A.RgbColorModelHex { Val = "4472C4" } },
+            new A.Stop { Offset = "100000", Color = new A.RgbColorModelHex { Val = "2F5496" } }
+        )
+        { Rotation = 5400000 }  // 54° = diagonal
+    )
+    // OR: A.RadialGradientFill for radial gradient
+);
+```
+
+### 7.3 Shape Positioning (Anchored)
+
+```csharp
+// Anchored (floating) shapes use DW.Anchor with the shape inside
+var anchoredShape = new Drawing(
+    new DW.Anchor(
+        new DW.SimplePosition { X = 0L, Y = 0L },
+        new DW.HorizontalPosition(
+            new DW.PositionOffset((914400L * 1).ToString()))  // 1 inch from left
+        { RelativeFrom = DW.HorizontalRelativePositionValues.Margin },
+        new DW.VerticalPosition(
+            new DW.PositionOffset((914400L * 2).ToString()))  // 2 inches from top
+        { RelativeFrom = DW.VerticalRelativePositionValues.Page },
+        new DW.Extent { Cx = 914400L, Cy = 914400L },
+        new DW.EffectExtent(),
+        new DW.DocProperties { Id = 11U, Name = "AnchoredShape" },
+        new DW.NonVisualGraphicFrameDrawingProperties(new A.GraphicFrameLocks()),
+        new DW.WrapSquare(),
+        new A.Graphic(new A.GraphicData(
+            new WSP.WordprocessingShape(...)
+        ) { Uri = "http://schemas.microsoft.com/office/word/2010/wordprocessingShape" })
+    )
+    { BehindDoc = false, LayoutInCell = true }
+);
+```
+
+### 7.4 Grouped Shapes (GroupShape)
+
+```csharp
+// GroupShape combines multiple shapes into one manipulable unit
+// Uses a different URI: "http://schemas.microsoft.com/office/word/2010/wordprocessingGroupShape"
+
+var groupShapeDrawing = new Drawing(
+    new DW.Inline(
+        new DW.Extent { Cx = 4572000L, Cy = 2286000L },  // 5" x 2.5"
+        new DW.EffectExtent(),
+        new DW.DocProperties { Id = 12U, Name = "Shape Group" },
+        new DW.NonVisualGraphicFrameDrawingProperties(new A.GraphicFrameLocks()),
+        new A.Graphic(
+            new A.GraphicData(
+                new WPG.GroupShape(
+                    // Child shapes are positioned relative to group origin
+                    // Shape 1 at (0,0)
+                    new WSP.WordprocessingShape(
+                        new WSP.NonVisualDrawingShapeProperties(
+                            new A.ShapeLocks { NoChangeAspect = true }),
+                        new WSP.ShapeProperties(
+                            new A.Transform2D(
+                                new A.Offset { X = 0L, Y = 0L },
+                                new A.Extents { Cx = 914400L, Cy = 914400L }),
+                            new A.PresetGeometry(new A.AdjustValueList())
+                            { Preset = A.ShapeTypeValues.Ellipse },
+                            new A.SolidFill(new A.RgbColorModelHex { Val = "FF0000" })),
+                        new WSP.TextBoxInfo2(
+                            new TextBoxContent(new Paragraph(
+                                new Run(new Text("Red Circle")))))
+                    ),
+                    // Shape 2 offset to the right
+                    new WSP.WordprocessingShape(
+                        new WSP.NonVisualDrawingShapeProperties(
+                            new A.ShapeLocks { NoChangeAspect = true }),
+                        new WSP.ShapeProperties(
+                            new A.Transform2D(
+                                new A.Offset { X = 914400L, Y = 0L },  // 1" to the right
+                                new A.Extents { Cx = 914400L, Cy = 914400L }),
+                            new A.PresetGeometry(new A.AdjustValueList())
+                            { Preset = A.ShapeTypeValues.Rectangle },
+                            new A.SolidFill(new A.RgbColorModelHex { Val = "00FF00" })),
+                        new WSP.TextBoxInfo2(
+                            new TextBoxContent(new Paragraph(
+                                new Run(new Text("Green Square")))))
+                    )
+                )
+            ) { Uri = "http://schemas.microsoft.com/office/word/2010/wordprocessingGroupShape" }
+        )
+    )
+    { DistanceFromTop = 0U, DistanceFromBottom = 0U,
+      DistanceFromLeft = 0U, DistanceFromRight = 0U }
+);
+```
+
+### 7.5 Shape Effects — Shadow, Reflection
+
+```csharp
+// Shadow effect
+new WSP.ShapeProperties(
+    new A.Transform2D(...),
+    new A.PresetGeometry(new A.AdjustValueList())
+    { Preset = A.ShapeTypeValues.RoundedRectangle },
+    new A.SolidFill(new A.RgbColorModelHex { Val = "4472C4" }),
+    // Shadow via EffectList
+    new A.EffectList(
+        new A.OuterShadow(
+            new A.RgbColorModelHex { Val = "000000" }
+        )
+        {
+            BlurRadius = 50800L,   // 4pt blur (50800 EMU = 4pt at 12700EMU/pt)
+            Distance = 38100L,     // 3pt offset
+            Direction = 2700000,   // 45° (in 60000ths of a degree)
+            Alignment = A.RectangleAlignmentValues.BottomRight
+        }
+    )
+);
+
+// Reflection
+new A.EffectList(
+    new A.Reflection(
+        new A.ReflectionEffect()
+        {
+            ReflectionBlurRadius = 63500L,  // 5pt
+            ReflectionDistance = 76200L,     // 6pt
+            ReflectionFade = 50000,         // 50% fade
+            ReflectionOverlap = 25000       // 25% overlap
+        }
+    )
+);
+```
+
+---
+
+## 8. Math / Equations (OMML)
+
+### 8.1 OfficeMath Container — Basic Setup
+
+```csharp
+// All math equations must be inside an OfficeMath container
+// OfficeMath can be inline (in a run) or display (in its own paragraph)
+
+// Inline equation in a run
+var inlineMathPara = new Paragraph(
+    new Run(
+        new RunProperties(new RunFonts { Ascii = "Cambria Math", HighAnsi = "Cambria Math" }),
+        // Inline math: use OfficeMath directly in Run
+        new OfficeMath(
+            new M.Fraction(
+                new M.Numerator(
+                    new M.Run(new M.Text("1"))
+                ),
+                new M.Denominator(
+                    new M.Run(new M.Text("2"))
+                )
+            )
+        )
+    )
+);
+
+// Display equation (on its own centered paragraph)
+var displayMathPara = new Paragraph(
+    new ParagraphProperties(
+        new Justification { Val = JustificationValues.Center }
+    ),
+    new Run(
+        new OfficeMath(
+            new M.Fraction(
+                new M.Numerator(
+                    new M.Run(new M.Text("x"))
+                ),
+                new M.Denominator(
+                    new M.Run(new M.Text("y"))
+                )
+            )
+        )
+    )
+);
+
+// To make a display equation centered with extra spacing:
+var displayEquationPara = new Paragraph(
+    new ParagraphProperties(
+        new SpacingBetweenLines { Before = "240", After = "240" },
+        new Justification { Val = JustificationValues.Center }
+    ),
+    new Run(new OfficeMath(
+        // Equation content here
+    ))
+);
+```
+
+### 8.2 Fraction (M.Fraction)
+
+```csharp
+// \frac{x}{y} pattern
+new M.Fraction(
+    new M.Numerator(
+        new M.Run(
+            new M.RunText("x") { Space = SpaceProcessingModeValues.Preserve }
+        )
+    ),
+    new M.Denominator(
+        new M.Run(
+            new M.RunText("y") { Space = SpaceProcessingModeValues.Preserve }
+        )
+    )
+);
+
+// Nested fraction: (a+b)/(c+d)
+new M.Fraction(
+    new M.Numerator(
+        new M.Run(new M.Text("a")) { FontSize = 24 },
+        new M.Run(new M.Text("+")) { FontSize = 24 },
+        new M.Run(new M.Text("b")) { FontSize = 24 }
+    ),
+    new M.Denominator(
+        new M.Run(new M.Text("c")) { FontSize = 24 },
+        new M.Run(new M.Text("+")) { FontSize = 24 },
+        new M.Run(new M.Text("d")) { FontSize = 24 }
+    )
+);
+
+// Display fraction (skips 1 as numerator/denominator style)
+new M.Fraction(
+    new M.Numerator(...),
+    new M.Denominator(...),
+    new M.FractionPr(
+        new M.Type { Val = M.FractionValues.Skewed }  // or Normal, Linear,丝
+    )
+);
+```
+
+### 8.3 Superscript and Subscript
+
+```csharp
+// Superscript: x²
+new M.Superscript(
+    new M.Base(
+        new M.Run(new M.Text("x")))
+    ),
+    new M.SuperscriptOperand(
+        new M.Run(new M.Text("2")))
+    )
+);
+
+// Subscript: x₁
+new M.Subscript(
+    new M.Base(
+        new M.Run(new M.Text("x")))
+    ),
+    new M.SubscriptOperand(
+        new M.Run(new M.Text("1")))
+    )
+);
+
+// Pre-sub/superscript: _b^a (baseline then super)
+// or use M.SubscriptSuperscript for combined
+
+// SubscriptSuperscript (both at once): _b^a C
+new M.SubscriptSuperscript(
+    new M.Base(new M.Run(new M.Text("C"))),
+    new M.Subscript(new M.Run(new M.Text("b"))),
+    new M.Superscript(new M.Run(new M.Text("a")))
+);
+```
+
+### 8.4 Square Root and Nth Root
+
+```csharp
+// Square root: √x
+new M.Radical(
+    new M.Root(
+        new M.Run(new M.Text("x")))
+    )
+);
+
+// Square root with degree hidden (just √)
+new M.Radical(
+    new M.Root(
+        new M.Run(new M.Text("x")))
+    ),
+    new M.RadicalPr(
+        new M.Degree { Val = false }  // Hide the root index
+    )
+);
+
+// Nth root: ∛(x+1)  — cube root of (x+1)
+new M.Radical(
+    new M.Root(
+        new M.Fraction(
+            new M.Numerator(new M.Run(new M.Text("1"))),
+            new M.Denominator(new M.Run(new M.Text("3")))
+        )
+    ),  // This is the "3" for cube root
+    new M.Root(
+        new M.Run(new M.Text("x"))),
+        new M.Run(new M.Text("+"))),
+        new M.Run(new M.Text("1")))
+    )
+);
+// Actually, for nth root: first Root is the index (degree), second is the radicand
+new M.Radical(
+    new M.Root(new M.Run(new M.Text("3"))),  // The index: 3rd root
+    new M.Root(
+        new M.Run(new M.Text("x")),
+        new M.Run(new M.Text("+")),
+        new M.Run(new M.Text("1"))
+    )
+);
+```
+
+### 8.5 N-ary Operators — Integral, Summation, Product
+
+```csharp
+// Integral ∫ from a to b of f(x) dx
+new M.Nary(
+    new M.NaryProperties(
+        new M.NaryType { Val = M.NaryValues.Integral }  // ∫
+    )
+    {
+        SubSuperscript = M.SubSuperscriptValues.NoSubSuperscript
+    },
+    new M.Base(
+        new M.Run(new M.Text("f(x)")))
+    ),
+    new M.Subscript(
+        new M.Run(new M.Text("a")))
+    ),
+    new M.Superscript(
+        new M.Run(new M.Text("b")))
+    )
+);
+
+// Summation Σ from i=1 to n of i²
+new M.Nary(
+    new M.NaryProperties(
+        new M.NaryType { Val = M.NaryValues.Sum },  // Σ
+        new M.GrowBindings = true
+    ),
+    new M.Base(
+        new M.SubscriptSuperscript(
+            new M.Base(new M.Run(new M.Text("i"))),
+            new M.Subscript(new M.Run(new M.Text("1"))),
+            new M.Superscript(new M.Run(new M.Text("n")))
+        )
+    ),
+    new M.Subscript(
+        new M.Run(new M.Text("i")))
+    ),
+    new M.Superscript(
+        new M.Run(new M.Text("2")))
+    )
+);
+
+// Product ∏ from i=1 to n
+new M.Nary(
+    new M.NaryProperties(
+        new M.NaryType { Val = M.NaryValues.Product }  // ∏
+    ),
+    new M.Base(
+        new M.SubscriptSuperscript(
+            new M.Base(new M.Run(new M.Text("i"))),
+            new M.Subscript(new M.Run(new M.Text("1"))),
+            new M.Superscript(new M.Run(new M.Text("n")))
+        )
+    ),
+    new M.Subscript(
+        new M.Run(new M.Text("i")))
+    ),
+    new M.Superscript(
+        new M.Run(new M.Text("2")))
+    )
+);
+
+// N-ary type values: Integral, Sum, Product, Union, Intersection, etc.
+```
+
+### 8.6 Matrix
+
+```csharp
+// 2x2 matrix
+// [a  b]
+// [c  d]
+new M.Matrix(
+    new M.MatrixRows(
+        // Row 1
+        new M.MatrixRow(
+            new M.MatrixCell(
+                new M.Run(new M.Text("a"))
+            ),
+            new M.MatrixCell(
+                new M.Run(new M.Text("b"))
+            )
+        ),
+        // Row 2
+        new M.MatrixRow(
+            new M.MatrixCell(
+                new M.Run(new M.Text("c"))
+            ),
+            new M.MatrixCell(
+                new M.Run(new M.Text("d"))
+            )
+        )
+    ),
+    new M.MatrixProperties(
+        new M.Jc { Val = M.JustificationValues.Center },  // Centered
+        new M.Structure { Val = M.MathStructureValues.SinglePUNCT },
+        new M.RowSpacing { Val = 120 },  // Row spacing in twips
+        new M.RowSpacing1 { Val = 120 }
+    )
+)
+```
+
+### 8.7 Delimiter (Parentheses/Brackets/Braces)
+
+```csharp
+// (a + b) or [a + b] or {a + b}
+new M.Delimiter(
+    new M.DelimiterProperties(
+        new M.Begin(new M.Text("(")),  // Opening char
+        new M.End(new M.Text(")")),   // Closing char
+        new M.Separator(new M.Text(",")),  // Separator between elements
+        new M.Structure { Val = M.MathStructureValues.Minimal }
+    ),
+    new M.DelimiterContents(
+        new M.Run(new M.Text("a")),
+        new M.Run(new M.Text("+")),
+        new M.Run(new M.Text("b"))
+    )
+);
+
+// {a, b, c} with curly braces
+new M.Delimiter(
+    new M.DelimiterProperties(
+        new M.Begin(new M.Text("{")),
+        new M.End(new M.Text("}")),
+        new M.Separator(new M.Text(","))
+    ),
+    new M.DelimiterContents(
+        new M.Run(new M.Text("a")),
+        new M.Run(new M.Text("b")),
+        new M.Run(new M.Text("c"))
+    )
+);
+
+// 2x2 matrix in parentheses
+new M.Delimiter(
+    new M.DelimiterProperties(
+        new M.Begin(new M.Text("(")),
+        new M.End(new M.Text(")"))
+    ),
+    new M.DelimiterContents(
+        // Inline 2x2 using subscripts
+        new M.SubscriptSuperscript(...)
+    )
+);
+```
+
+### 8.8 Equation Array (Aligned Equations)
+
+```csharp
+// EquationArray (M.EquationArray) creates a series of equations aligned at markers
+// Like \begin{align} in LaTeX
+
+new M.EquationArray(
+    new M.EquationArrayProperties(
+        new M.Jc { Val = M.JustificationValues.Left },
+        new M.RowSpacing { Val = 240 },
+        new M.RowSpacing1 { Val = 240 }
+    ),
+    // Each equation is a Paragraph inside the array
+    new Paragraph(new Run(new M.Text("x") { Space = SpaceProcessingModeValues.Preserve })),
+    new Paragraph(
+        new Run(new M.Text("+") { Space = SpaceProcessingModeValues.Preserve }),
+        new Run(new M.Text("y") { Space = SpaceProcessingModeValues.Preserve }),
+        new Run(new M.Text("=") { Space = SpaceProcessingModeValues.Preserve }),
+        new Run(new M.Text("z") { Space = SpaceProcessingModeValues.Preserve })
+    )
+);
+
+// Or use M.Break with AlignmentTab for manual alignment points
+```
+
+### 8.9 Greek Letters and Math Symbols
+
+```csharp
+// Greek letters via M.RunText with Symbol font or Unicode
+// Common Greek letters and their uses:
+
+// α (alpha)
+new M.Run(new M.Text("\u03B1"))  // or use Unicode directly
+
+// β (beta)
+new M.Run(new M.Text("\u03B2"))
+
+// γ (gamma)
+new M.Run(new M.Text("\u03B3"))
+
+// π (pi) — use Greek small letter pi
+new M.Run(new M.Text("\u03C0"))
+
+// σ (sigma)
+new M.Run(new M.Text("\u03C3"))
+
+// Σ (Sigma, capital) — summation symbol
+new M.Run(new M.Text("\u03A3"))
+
+// θ (theta)
+new M.Run(new M.Text("\u03B8"))
+
+// ∞ (infinity)
+new M.Run(new M.Text("\u221E"))
+
+// ≤ (less than or equal)
+new M.Run(new M.Text("\u2264"))
+
+// ≥ (greater than or equal)
+new M.Run(new M.Text("\u2265"))
+
+// ≠ (not equal)
+new M.Run(new M.Text("\u2260"))
+
+// ± (plus-minus)
+new M.Run(new M.Text("\u00B1"))
+
+// × (multiplication)
+new M.Run(new M.Text("\u00D7"))
+
+// ÷ (division)
+new M.Run(new M.Text("\u00F7"))
+
+// For best results, set the font to "Cambria Math" on math runs
+new M.Run(
+    new RunFonts { Ascii = "Cambria Math", HighAnsi = "Cambria Math" },
+    new M.Text("\u03C0")
+)
+```
+
+---
+
+## 9. Numbering System — Deep Dive
+
+### 9.1 Architecture Overview
+
+```
+NumberingDefinitionsPart (numbering.xml)
+    └── <w:numbering>
+        ├── <w:abstractNum>  (templates)
+        │     ├── <w:lvl> × 9 (levels 0-8)
+        │     └── <w:pPr><w:numPr> links to this abstractNum
+        └── <w:num> (instances)
+              └── <w:abstractNumId val="N"/>
+```
+
+**Key rule**: `AbstractNum` must appear BEFORE `NumberingInstance` in the XML root.
+
+### 9.2 AbstractNum with Multi-Level Decimal Numbering
+
+```csharp
+// AbstractNum: the numbering template (what it looks like)
+// NumberingInstance: a specific use of that template (how it's applied)
+
+var numberingPart = mainPart.AddNewPart<NumberingDefinitionsPart>();
+var numbering = new Numbering();
+
+// ─────────────────────────────────────────────────────────────
+// Step 1: Define AbstractNum (the template)
+// ─────────────────────────────────────────────────────────────
+var abstractNum = new AbstractNum { AbstractNumberId = 1 };
+// MultiLevelType specifies this is a multi-level list
+abstractNum.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
+
+// Level 0: "1." — decimal, bold number
+abstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Decimal },
+    new LevelText { Val = "%1." },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "360", Hanging = "360" }  // 0.25" hanging indent
+    ),
+    new NumberingSymbolRunProperties(
+        new Bold(),
+        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
+        new Color { Val = "2F5496" }
+    )
+) { LevelIndex = 0 });
+
+// Level 1: "1.1." — indent 0.5"
+abstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Decimal },
+    new LevelText { Val = "%1.%2." },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "720", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" }
+    )
+) { LevelIndex = 1 });
+
+// Level 2: "1.1.1."
+abstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Decimal },
+    new LevelText { Val = "%1.%2.%3." },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "1080", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" }
+    )
+) { LevelIndex = 2 });
+
+// ─────────────────────────────────────────────────────────────
+// Step 2: Create NumberingInstance (a reference to the template)
+// ─────────────────────────────────────────────────────────────
+var numInstance = new NumberingInstance(
+    new AbstractNumId { Val = 1 }  // Points to abstractNum above
+) { NumberID = 1 };
+
+// ─────────────────────────────────────────────────────────────
+// Step 3: Assemble — AbstractNum BEFORE NumberingInstance!
+// ─────────────────────────────────────────────────────────────
+numbering.Append(abstractNum);
+numbering.Append(numInstance);
+numberingPart.Numbering = numbering;
+numberingPart.Numbering.Save();
+
+// ─────────────────────────────────────────────────────────────
+// Step 4: Apply to a paragraph
+// ─────────────────────────────────────────────────────────────
+var numberedPara = new Paragraph(
+    new ParagraphProperties(
+        new NumberingProperties(
+            new NumberingLevelReference { Val = 0 },  // Use level 0 of numId 1
+            new NumberingId { Val = 1 }                // Use numbering instance 1
+        )
+    ),
+    new Run(new Text("First item"))
+);
+
+// For level 1 sub-item:
+var subItemPara = new Paragraph(
+    new ParagraphProperties(
+        new NumberingProperties(
+            new NumberingLevelReference { Val = 1 },  // Use level 1
+            new NumberingId { Val = 1 }
+        )
+    ),
+    new Run(new Text("Sub-item"))
+);
+```
+
+### 9.3 Bullet Lists with Custom Symbols
+
+```csharp
+// Bullet numbering uses NumberFormatValues.Bullet
+// The bullet character is defined in LevelText and NumberingSymbolRunProperties
+
+var bulletAbstractNum = new AbstractNum { AbstractNumberId = 2 };
+bulletAbstractNum.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
+
+// Level 0 bullet: ● (Unicode bullet)
+bulletAbstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Bullet },  // Key: Bullet format
+    new LevelText { Val = "\u2022" },  // ● bullet character
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "720", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new RunFonts { Ascii = "Symbol", HighAnsi = "Symbol" }
+        // Symbol font maps ● to character 0xD8 in Symbol encoding
+    )
+) { LevelIndex = 0 });
+
+// Level 1 bullet: ○ (white circle)
+bulletAbstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Bullet },
+    new LevelText { Val = "\u25CB" },  // ○ Unicode
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "1080", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new RunFonts { Ascii = "Courier New", HighAnsi = "Courier New" }
+    )
+) { LevelIndex = 1 });
+
+// Level 2 bullet: ■ (black square)
+bulletAbstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Bullet },
+    new LevelText { Val = "\u25A0" },  // ■
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "1440", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new RunFonts { Ascii = "Arial", HighAnsi = "Arial" }
+    )
+) { LevelIndex = 2 });
+
+var bulletNumInstance = new NumberingInstance(
+    new AbstractNumId { Val = 2 }
+) { NumberID = 2 };
+
+numbering.Append(bulletAbstractNum);
+numbering.Append(bulletNumInstance);
+```
+
+**Common bullet characters:**
+
+| Symbol | Character | Unicode | Common Font |
+|--------|-----------|---------|-------------|
+| ● Filled circle | Bullet | U+2022 | Symbol |
+| ○ Empty circle | White circle | U+25CB | Arial |
+| ■ Filled square | Black square | U+25A0 | Arial |
+| □ Empty square | White square | U+25A1 | Arial |
+| ➢ Right arrow | Right arrow | U+27A2 | Wingdings |
+| ✓ Checkmark | Check mark | U+2713 | Wingdings |
+| ✗ Cross | Ballot X | U+2717 | Wingdings |
+| ▶ Play | Right triangle | U+25B6 | Arial |
+
+### 9.4 Restart Numbering at Specific Point
+
+```csharp
+// Method 1: StartOverride on a specific paragraph
+// Use LevelOverride + StartOverride to restart at a specific level
+
+var restartNumInstance = new NumberingInstance(
+    new AbstractNumId { Val = 1 }
+) { NumberID = 3 };
+
+// Override level 0 to start at 5 instead of 1
+restartNumInstance.Append(new LevelOverride { LevelIndex = 0 },
+    new StartOverrideNumberingValue { Val = 5 }
+);
+
+// Apply this to a paragraph — this paragraph starts numbering at 5
+var restartPara = new Paragraph(
+    new ParagraphProperties(
+        new NumberingProperties(
+            new NumberingLevelReference { Val = 0 },
+            new NumberingId { Val = 3 }  // Use the restart instance
+        )
+    ),
+    new Run(new Text("Item 5 (restarted)"))
+);
+```
+
+### 9.5 Continue Numbering from Previous List
+
+```csharp
+// By default, Word continues numbering across lists using the same AbstractNum.
+// To force continuation, ensure the list uses the same numId.
+
+// If you need explicit continuation control:
+var continuedNumInstance = new NumberingInstance(
+    new AbstractNumId { Val = 1 }
+) { NumberID = 4 };
+
+// When multiple NumberingInstances share the same AbstractNumId,
+// they share the same numbering state (continuation)
+
+// To prevent continuation (start fresh), use a new AbstractNum:
+var freshAbstractNum = new AbstractNum { AbstractNumberId = 5 };
+freshAbstractNum.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
+// ... define levels ...
+var freshNumInstance = new NumberingInstance(
+    new AbstractNumId { Val = 5 }
+) { NumberID = 5 };
+// This starts at 1 again, independent of the previous list
+```
+
+### 9.6 Link Numbering to Heading Styles (Outline Numbering)
+
+```句话说，link numbering to heading styles so that Heading1 starts a new numbering sequence, Heading2 is a sub-item, etc.
+
+```csharp
+// This links styles to numbering levels automatically via StyleLink
+var abstractNumForOutline = new AbstractNum { AbstractNumberId = 10 };
+abstractNumForOutline.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
+abstractNumForOutline.Append(new StyleLink { Val = "Heading1" });  // Links level 0 to Heading1
+abstractNumForOutline.Append(new StyleLink { Val = "Heading2" });  // Links level 1 to Heading2
+abstractNumForOutline.Append(new StyleLink { Val = "Heading3" });  // Links level 2 to Heading3
+
+// Level 0 for Heading1
+abstractNumForOutline.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Decimal },
+    new LevelText { Val = "Chapter %1" },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "360", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new Bold(),
+        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
+        new FontSize { Val = "28" }
+    )
+) { LevelIndex = 0 });
+
+// Level 1 for Heading2
+abstractNumForOutline.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Decimal },
+    new LevelText { Val = "%1.%2" },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "720", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" }
+    )
+) { LevelIndex = 1 });
+
+// Level 2 for Heading3
+abstractNumForOutline.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Decimal },
+    new LevelText { Val = "%1.%2.%3" },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "1080", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" }
+    )
+) { LevelIndex = 2 });
+
+// Now when you apply Heading1/2/3 styles, numbering follows automatically
+var heading1Para = new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+    new Run(new Text("Introduction"))  // Automatically gets "Chapter 1" prefix
+);
+var heading2Para = new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "Heading2" }),
+    new Run(new Text("Background"))  // Automatically gets "1.1" prefix
+);
+```
+
+### 9.7 NumberingFormat Values Reference
+
+```csharp
+// NumberFormatValues enum — all supported numbering formats:
+NumberFormatValues.Decimal          // 1, 2, 3...
+NumberFormatValues.LowerRoman       // i, ii, iii...
+NumberFormatValues.UpperRoman       // I, II, III...
+NumberFormatValues.LowerLetter      // a, b, c...
+NumberFormatValues.UpperLetter      // A, B, C...
+NumberFormatValues.Ordinal          // 1st, 2nd, 3rd... (locale-dependent)
+NumberFormatValues.OrdinalText      // First, Second, Third... (locale-dependent)
+NumberFormatValues.Hex              // 0, 1, 2... F, 10, 11... (hexadecimal)
+NumberFormatValues.ChicagoManual    // Chapter numbering (I, A, 1, a)
+NumberFormatValues.Kanji           // 漢数字
+NumberFormatValues.KanjiDigit      // 一, 二, 三...
+NumberFormatValues.DoubleByte      // Ideographic: 一, 二, 三
+NumberFormatValues.ArabicFullWidth // Full-width: １, ２, ３
+NumberFormatValues.Bullet          // Custom symbol (●, ✓, etc.)
+NumberFormatValues.None            // No number
+```
+
+### 9.8 IsLegalNumberingStyle — Using Arabic with Nested Levels
+
+```csharp
+// IsLegalNumberingStyle=false (default): each level can have its own format
+// IsLegalNumberingStyle=true: forces all sub-levels to use Arabic numerals
+
+// This is important for legal/formal numbering where you want:
+// 1. level 1 = A, B, C (alphabetic)
+// 2. level 2 = 1, 2, 3 (Arabic) — NOT a, b, c
+// Without IsLegalNumberingStyle=false, level 2 would inherit alphabetic
+
+var legalAbstractNum = new AbstractNum { AbstractNumberId = 20 };
+legalAbstractNum.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
+legalAbstractNum.Append(new IsLegalNumberingStyle());  // No val = true (default when element present)
+
+// Level 0: A. B. C.
+legalAbstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.UpperLetter },
+    new LevelText { Val = "%1." },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "360", Hanging = "360" }
+    )
+) { LevelIndex = 0 });
+
+// Level 1: 1. 2. 3. (NOT a. b. c.)
+legalAbstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Decimal },
+    new LevelText { Val = "%2." },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "720", Hanging = "360" }
+    )
+) { LevelIndex = 1 });
+
+// Level 2: (a) (b) (c)
+legalAbstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.LowerLetter },
+    new LevelText { Val = "(%3)" },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "1080", Hanging = "360" }
+    )
+) { LevelIndex = 2 });
+```
+
+---
+
+## 10. Document Protection & Encryption
+
+### 10.1 DocumentProtection — Basic Forms
+
+```csharp
+// DocumentProtection is placed in DocumentSettingsPart
+var settingsPart = mainPart.AddNewPart<DocumentSettingsPart>();
+settingsPart.Settings = new Settings();
+
+// ReadOnly: prevents editing, allows reading
+settingsPart.Settings.Append(new DocumentProtection
+{
+    Edit = DocumentProtectionValues.ReadOnly,
+    Enforcement = true
+});
+
+// Comments: can only add/edit comments (not modify body text)
+settingsPart.Settings.Append(new DocumentProtection
+{
+    Edit = DocumentProtectionValues.Comments,
+    Enforcement = true
+});
+
+// TrackedChanges: can only edit with track changes ON
+settingsPart.Settings.Append(new DocumentProtection
+{
+    Edit = DocumentProtectionValues.TrackedChanges,
+    Enforcement = true
+});
+
+// Forms: only form fields are editable
+settingsPart.Settings.Append(new DocumentProtection
+{
+    Edit = DocumentProtectionValues.Forms,
+    Enforcement = true
+});
+```
+
+### 10.2 Password Hashing for DocumentProtection
+
+Modern Word uses SHA-512 with salt for password hashing (ECMA-376 standard).
+
+```csharp
+// SHA-512 password hashing for strong protection
+// CryptographicProviderType must be "rsaAES" or "rsaAES" for SHA-512
+
+settingsPart.Settings.Append(new DocumentProtection
+{
+    Edit = DocumentProtectionValues.ReadOnly,
+    Enforcement = true,
+    CryptographicProviderType = CryptProviderValues.RsaAES,
+    CryptographicAlgorithmClass = CryptAlgorithmClassValues.Hash,
+    CryptographicAlgorithmType = CryptAlgorithmValues.TypeAny,
+    CryptographicAlgorithmSid = 14,  // SHA-512
+    CryptographicSpinCount = 100000U,
+    Hash = "base64-encoded-hash-here",
+    Salt = "base64-encoded-salt-here"
+});
+
+// Generate hash in .NET:
+public static (string hash, string salt) GeneratePasswordHash(string password, int spinCount = 100000)
+{
+    byte[] saltBytes = new byte[16];
+    using (var rng = System.Security.Cryptography.RandomNumberGenerator.Create())
+        rng.GetBytes(saltBytes);
+
+    // PBKDF2 with SHA-512, 100000 iterations
+    using var pbkdf2 = new System.Security.Cryptography.Rfc2898DeriveBytes(
+        password, saltBytes, spinCount, System.Security.Cryptography.HashAlgorithmName.SHA512);
+    byte[] hash = pbkdf2.GetBytes(64);  // 512 bits
+
+    return (Convert.ToBase64String(hash), Convert.ToBase64String(saltBytes));
+}
+```
+
+### 10.3 WriteProtection — Recommend Opening as Read-Only
+
+```csharp
+// WriteProtection is different from DocumentProtection
+// It recommends (but doesn't enforce) that users open as read-only
+// Found in extended properties (docProps/custom.xml or settings)
+
+settingsPart.Settings.Append(new WriteProtection
+{
+    Recommended = true  // "Recommend opening as read-only"
+});
+
+// Or force read-only recommendation with a specific application name
+settingsPart.Settings.Append(new WriteProtection
+{
+    Recommended = true,
+    ApplicationName = "Microsoft Word"
+});
+```
+
+### 10.4 Restrict Editing to Form Fields Only
+
+```csharp
+// This protects the document but allows editing in form field content controls
+settingsPart.Settings = new Settings(
+    new DocumentProtection
+    {
+        Edit = DocumentProtectionValues.Forms,
+        Enforcement = true
+    },
+    // Also set to allow editing only in form fields
+    new EditingRestrictions { Val = EditingRestrictionValues.Forms }
+);
+```
+
+### 10.5 PermStart / PermEnd — Editable Regions in Protected Document
+
+Allow specific regions (ranges) to be edited even when the document is protected.
+
+```csharp
+// <w:permStart w:id="1" w:editor="everyone"/>
+// <w:r><w:t>Editable text</w:t></w:r>
+// <w:permEnd w:id="1"/>
+
+// Even when document protection is on, this range can be edited by everyone
+
+var editableRegion = new Paragraph(
+    new ParagraphProperties(
+        new PermStart { Id = 1, EditorGroup = RangePermissionEditingGroupValues.Everyone }
+    ),
+    new Run(new Text("This text can be edited even in a protected document.") { Space = SpaceProcessingModeValues.Preserve }),
+    new ParagraphProperties(
+        new PermEnd { Id = 1 }
+    )
+);
+
+// EditorGroup values:
+// Everyone         — anyone can edit
+// Administrators   — only administrators
+// Contributors     — only contributors
+// Editors          — only editors
+// Owners           — only document owners
+// Nobody           — nobody can edit (use with w:perm sbz="1" for "does not include")
+
+// Use specific user name:
+// <w:permStart w:id="2" w:author="Alice"/>
+
+// For tracked changes review scenario (allow comments but not direct editing):
+var commentableRegion = new Paragraph(
+    new ParagraphProperties(
+        new PermStart { Id = 2, EditorGroup = RangePermissionEditingGroupValues.Everyone }
+    ),
+    new Run(new Text("This region allows comments and tracked changes.") { Space = SpaceProcessingModeValues.Preserve }),
+    new ParagraphProperties(
+        new PermEnd { Id = 2 }
+    )
+);
+```
+
+### 10.6 Full Document Protection with Password and Salt
+
+```csharp
+public static void ProtectDocument(
+    WordprocessingDocument doc,
+    string password,
+    DocumentProtectionValues protectionType)
+{
+    var settingsPart = doc.MainDocumentPart!.AddNewPart<DocumentSettingsPart>();
+    if (settingsPart.Settings == null)
+        settingsPart.Settings = new Settings();
+
+    // Generate password hash
+    byte[] salt = new byte[16];
+    using (var rng = System.Security.Cryptography.RandomNumberGenerator.Create())
+        rng.GetBytes(salt);
+
+    int spinCount = 100000;
+    using var pbkdf2 = new System.Security.Cryptography.Rfc2898DeriveBytes(
+        password, salt, spinCount, System.Security.Cryptography.HashAlgorithmName.SHA512);
+    byte[] hash = pbkdf2.GetBytes(64);
+
+    var protection = new DocumentProtection
+    {
+        Edit = protectionType,
+        Enforcement = true,
+        CryptographicProviderType = CryptProviderValues.RsaAES,
+        CryptographicAlgorithmClass = CryptAlgorithmClassValues.Hash,
+        CryptographicAlgorithmType = CryptAlgorithmValues.TypeAny,
+        CryptographicAlgorithmSid = 14,  // SHA-512
+        CryptographicSpinCount = (UInt32Value)spinCount,
+        Hash = Convert.ToBase64String(hash),
+        Salt = Convert.ToBase64String(salt)
+    };
+
+    settingsPart.Settings.Append(protection);
+    settingsPart.Settings.Save();
+}
+```
+
+---
+
+## Quick Reference: Common Element Order in OpenXML
+
+When building complex elements, remember these ordering rules:
+
+### Run Elements Order (inside RunProperties):
+`RunFonts` → `Bold`/`Italic` → `Color` → `FontSize` → `Underline` → `VerticalTextAlignment` → `Emphasis` → (any other)
+
+### Paragraph Elements Order (inside ParagraphProperties):
+`ParagraphStyleId` → `KeepNext` → `KeepLines` → `PageBreakBefore` → `FrameProperties` → `WidowControl` → `NumPr` → `Indentation` → `SpacingBetweenLines` → `Justification` → `SectionProperties`
+
+### Table Properties Order:
+`TableWidth` → `TextDirection` → `Borders` → `Shading` → `TableLayout` → `TableCellMarginDefault`
+
+### SectionProperties Order:
+`FootnotePr` → `EndnotePr` → `Type` → `PageSize` → `PageMargin` → `PaperSource` → `PageBorders` → `LineNumberRestart` → `PageNumberFormat` → `TitlePage` → `TextDirection`
+
+---
+
+*Generated for DocumentFormat.OpenXml 3.x / .NET 8+ / C# 12*
+*Last updated: 2026-03-22*
diff --git a/builtin-skills/document-process/minimax-docx/references/openxml_namespaces.md b/builtin-skills/document-process/minimax-docx/references/openxml_namespaces.md
new file mode 100644
index 00000000..f1d6afa5
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/openxml_namespaces.md
@@ -0,0 +1,82 @@
+# OpenXML Namespaces, Relationship Types, and Content Types
+
+## Core Namespaces
+
+| Prefix | URI | Used In |
+|--------|-----|---------|
+| `w` | `http://schemas.openxmlformats.org/wordprocessingml/2006/main` | document.xml, styles.xml, numbering.xml, headers, footers |
+| `r` | `http://schemas.openxmlformats.org/officeDocument/2006/relationships` | Relationship references (r:id) |
+| `wp` | `http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing` | Image/drawing placement in document |
+| `a` | `http://schemas.openxmlformats.org/drawingml/2006/main` | DrawingML core (shapes, images, themes) |
+| `pic` | `http://schemas.openxmlformats.org/drawingml/2006/picture` | Picture element in DrawingML |
+| `v` | `urn:schemas-microsoft-com:vml` | VML (legacy shapes, watermarks) |
+| `o` | `urn:schemas-microsoft-com:office:office` | Office VML extensions |
+| `m` | `http://schemas.openxmlformats.org/officeDocument/2006/math` | Math equations (OMML) |
+| `mc` | `http://schemas.openxmlformats.org/markup-compatibility/2006` | Markup compatibility (Ignorable, AlternateContent) |
+
+## Extended Namespaces
+
+| Prefix | URI | Purpose |
+|--------|-----|---------|
+| `w14` | `http://schemas.microsoft.com/office/word/2010/wordml` | Word 2010 extensions (contentPart, etc.) |
+| `w15` | `http://schemas.microsoft.com/office/word/2012/wordml` | Word 2013 extensions (commentEx, etc.) |
+| `w16cid` | `http://schemas.microsoft.com/office/word/2016/wordml/cid` | Comment IDs (durable IDs) |
+| `w16cex` | `http://schemas.microsoft.com/office/word/2018/wordml/cex` | Comment extensible |
+| `w16se` | `http://schemas.microsoft.com/office/word/2015/wordml/symex` | Symbol extensions |
+| `wps` | `http://schemas.microsoft.com/office/word/2010/wordprocessingShape` | WordprocessingML shapes |
+| `wpc` | `http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas` | Drawing canvas |
+
+## Relationship Types
+
+| Relationship | Type URI |
+|-------------|----------|
+| Document | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument` |
+| Styles | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles` |
+| Numbering | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering` |
+| Font Table | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable` |
+| Settings | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings` |
+| Theme | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme` |
+| Image | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/image` |
+| Hyperlink | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink` |
+| Header | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/header` |
+| Footer | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer` |
+| Comments | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments` |
+| CommentsExtended | `http://schemas.microsoft.com/office/2011/relationships/commentsExtended` |
+| CommentsIds | `http://schemas.microsoft.com/office/2016/09/relationships/commentsIds` |
+| CommentsExtensible | `http://schemas.microsoft.com/office/2018/08/relationships/commentsExtensible` |
+| Footnotes | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes` |
+| Endnotes | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes` |
+| Glossary | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/glossaryDocument` |
+| Web Settings | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/webSettings` |
+
+## Content Types (`[Content_Types].xml`)
+
+### Default Extensions
+
+```xml
+<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml" />
+<Default Extension="xml" ContentType="application/xml" />
+<Default Extension="png" ContentType="image/png" />
+<Default Extension="jpeg" ContentType="image/jpeg" />
+<Default Extension="gif" ContentType="image/gif" />
+<Default Extension="emf" ContentType="image/x-emf" />
+```
+
+### Part Overrides
+
+| Part | Content Type |
+|------|-------------|
+| `/word/document.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml` |
+| `/word/styles.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml` |
+| `/word/numbering.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml` |
+| `/word/settings.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml` |
+| `/word/fontTable.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.fontTable+xml` |
+| `/word/theme/theme1.xml` | `application/vnd.openxmlformats-officedocument.theme+xml` |
+| `/word/header1.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml` |
+| `/word/footer1.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml` |
+| `/word/comments.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml` |
+| `/word/commentsExtended.xml` | `application/vnd.ms-word.commentsExtended+xml` |
+| `/word/commentsIds.xml` | `application/vnd.ms-word.commentsIds+xml` |
+| `/word/commentsExtensible.xml` | `application/vnd.ms-word.commentsExtensible+xml` |
+| `/word/footnotes.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml` |
+| `/word/endnotes.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml` |
diff --git a/builtin-skills/document-process/minimax-docx/references/openxml_units.md b/builtin-skills/document-process/minimax-docx/references/openxml_units.md
new file mode 100644
index 00000000..50a6b07f
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/openxml_units.md
@@ -0,0 +1,72 @@
+# OpenXML Unit Conversion Quick Reference
+
+## Master Conversion Table
+
+| Unit | 1 inch | 1 cm | 1 mm | 1 pt | Description |
+|------|--------|------|------|------|-------------|
+| DXA (twips) | 1440 | 567 | 56.7 | 20 | 1/20 of a point. Used for margins, indents, spacing, page size. |
+| EMU | 914400 | 360000 | 36000 | 12700 | English Metric Unit. Used for images, drawings, shapes. |
+| Half-points | 144 | 56.7 | 5.67 | 2 | Used for font sizes (`w:sz`, `w:szCs`). |
+| Points | 72 | 28.35 | 2.835 | 1 | Standard typographic unit. Not used directly in most attributes. |
+| Eighths of a point | 576 | 226.8 | 22.68 | 8 | Used for `w:spacing` character spacing. |
+
+## Common Page Sizes
+
+| Size | Width (DXA) | Height (DXA) | Width (mm) | Height (mm) |
+|------|-------------|--------------|------------|-------------|
+| A4 | 11906 | 16838 | 210 | 297 |
+| Letter | 12240 | 15840 | 215.9 | 279.4 |
+| Legal | 12240 | 20160 | 215.9 | 355.6 |
+| A3 | 16838 | 23811 | 297 | 420 |
+| A5 | 8391 | 11906 | 148 | 210 |
+
+## Common Margin Values
+
+| Margin | DXA | Inches | cm |
+|--------|-----|--------|----|
+| 0.5 inch | 720 | 0.5 | 1.27 |
+| 0.75 inch | 1080 | 0.75 | 1.91 |
+| 1 inch | 1440 | 1.0 | 2.54 |
+| 1.25 inch | 1800 | 1.25 | 3.18 |
+| 1.5 inch | 2160 | 1.5 | 3.81 |
+
+## Font Size Values (`w:sz`)
+
+| Display Size | w:sz value | Notes |
+|-------------|-----------|-------|
+| 8pt | 16 | |
+| 9pt | 18 | |
+| 10pt | 20 | |
+| 10.5pt | 21 | Common CJK body size |
+| 11pt | 22 | Default Calibri body |
+| 12pt | 24 | Default TNR body |
+| 14pt | 28 | Small heading |
+| 16pt | 32 | |
+| 18pt | 36 | |
+| 20pt | 40 | |
+| 24pt | 48 | |
+| 28pt | 56 | |
+| 36pt | 72 | |
+
+## Line Spacing Values
+
+Line spacing in `w:spacing` uses the `w:line` attribute in 240ths of a line (when `w:lineRule="auto"`):
+
+| Spacing | w:line value | w:lineRule |
+|---------|-------------|-----------|
+| Single | 240 | auto |
+| 1.15 (Word default) | 276 | auto |
+| 1.5 | 360 | auto |
+| Double | 480 | auto |
+| Exact 12pt | 240 | exact |
+| At least 12pt | 240 | atLeast |
+
+Note: When `lineRule="exact"` or `"atLeast"`, `w:line` is in **twips** (DXA), not 240ths. So `line="240"` with `lineRule="exact"` means exactly 12pt (240/20 = 12pt).
+
+## Conversion Formulas
+
+```
+DXA     = inches × 1440  = cm × 567     = pt × 20
+EMU     = inches × 914400 = cm × 360000 = pt × 12700
+sz      = pt × 2          (half-points)
+```
diff --git a/builtin-skills/document-process/minimax-docx/references/scenario_a_create.md b/builtin-skills/document-process/minimax-docx/references/scenario_a_create.md
new file mode 100644
index 00000000..4d1663e8
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/scenario_a_create.md
@@ -0,0 +1,284 @@
+# Scenario A: Creating a New DOCX from Scratch
+
+## When to Use
+
+Use Scenario A when:
+- The user has no existing file and wants a brand new document
+- The user provides content (text, tables, images) and wants it assembled into a DOCX
+- The user specifies a document type (report, letter, memo, academic) or describes a custom layout
+
+Do NOT use when: the user already has a DOCX they want to modify (→ Scenario B) or wants to restyle an existing document (→ Scenario C).
+
+---
+
+## Step-by-Step Workflow
+
+### 1. Determine Document Type
+
+Ask or infer the document type from the user's request:
+
+| Type | Typical Signals |
+|------|----------------|
+| Report | "report", "analysis", "whitepaper", sections with headings |
+| Letter | "letter", "dear", address block, salutation |
+| Memo | "memo", "memorandum", To/From/Subject fields |
+| Academic | "paper", "essay", "thesis", APA/MLA/Chicago mention |
+| Custom | None of the above, or user specifies exact formatting |
+
+### 2. Gather Content Requirements
+
+Collect from the user:
+- Title and subtitle (if any)
+- Author / organization
+- Section structure (headings and nesting)
+- Body content per section
+- Tables (headers + rows)
+- Images (file paths or placeholders)
+- Special elements: TOC, page numbers, watermark, headers/footers
+
+### 3. Select Style Set
+
+Based on document type, load the matching styles XML asset:
+- Report → `assets/styles/default_styles.xml` or `assets/styles/corporate_styles.xml`
+- Academic → `assets/styles/academic_styles.xml`
+- Letter / Memo / Custom → `assets/styles/default_styles.xml` (with overrides)
+
+### 4. Configure Page Setup
+
+Set `w:sectPr` values based on document type defaults (see below) or user overrides.
+
+```xml
+<w:sectPr>
+  <w:pgSz w:w="11906" w:h="16838" />  <!-- A4 -->
+  <w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"
+           w:header="720" w:footer="720" w:gutter="0" />
+</w:sectPr>
+```
+
+### 5. Build Document Structure
+
+Assemble `word/document.xml` with:
+1. `w:body` as root container
+2. Paragraphs (`w:p`) with heading styles for section titles
+3. Body paragraphs with `Normal` style
+4. Tables, images, and other elements as needed
+5. Final `w:sectPr` as last child of `w:body`
+
+### 6. Apply Typography Defaults
+
+Set document-level defaults in `styles.xml` under `w:docDefaults`:
+```xml
+<w:docDefaults>
+  <w:rPrDefault>
+    <w:rPr>
+      <w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:eastAsia="SimSun" w:cs="Arial" />
+      <w:sz w:val="22" />  <!-- 11pt -->
+      <w:szCs w:val="22" />
+    </w:rPr>
+  </w:rPrDefault>
+  <w:pPrDefault>
+    <w:pPr>
+      <w:spacing w:after="160" w:line="259" w:lineRule="auto" />
+    </w:pPr>
+  </w:pPrDefault>
+</w:docDefaults>
+```
+
+### 7. Add Complex Elements
+
+See the Complex Elements Guide section below.
+
+### 8. Run Validation Pipeline
+
+```
+dotnet run ... validate --xsd wml-subset.xsd
+dotnet run ... validate --xsd business-rules.xsd   # if applying a template
+```
+
+---
+
+## Document Type Defaults
+
+### Report
+| Property | Value |
+|----------|-------|
+| Body font | Calibri 11pt |
+| Heading font | Calibri Light |
+| H1 / H2 / H3 / H4 size | 28pt / 24pt / 18pt / 14pt |
+| Heading color | #2F5496 (corporate blue) |
+| Margins | 1 inch (1440 DXA) all sides |
+| Page size | A4 (11906 × 16838 DXA) |
+| Line spacing | Single (line="240") |
+| Paragraph spacing | 0pt before, 8pt after body |
+
+### Letter
+| Property | Value |
+|----------|-------|
+| Font | Calibri 11pt |
+| Page size | Letter (12240 × 15840 DXA) |
+| Margins | 1 inch all sides |
+| Structure | Date → Address → Salutation → Body → Closing → Signature |
+| Line spacing | Single |
+
+### Memo
+| Property | Value |
+|----------|-------|
+| Font | Arial 11pt |
+| Page size | Letter |
+| Margins | 0.75 inch (1080 DXA) |
+| Header | "MEMO" centered, bold, 16pt |
+| Fields | To, From, Date, Subject (bold labels, tab-aligned values) |
+
+### Academic
+| Property | Value |
+|----------|-------|
+| Font | Times New Roman 12pt |
+| Line spacing | Double (line="480") |
+| Margins | 1 inch all sides |
+| Page size | Letter |
+| Headings | Bold, same font, 14/13/12pt for H1/H2/H3 |
+| First line indent | 0.5 inch (720 DXA) |
+| Heading color | Black (no color) |
+
+---
+
+## Content Configuration JSON Format
+
+The CLI `create` command accepts a JSON config:
+
+```json
+{
+  "type": "report",
+  "title": "Quarterly Revenue Analysis",
+  "subtitle": "Q1 2026",
+  "author": "Finance Team",
+  "pageSize": "A4",
+  "margins": { "top": 1440, "right": 1440, "bottom": 1440, "left": 1440 },
+  "sections": [
+    {
+      "heading": "Executive Summary",
+      "level": 1,
+      "content": [
+        { "type": "paragraph", "text": "Revenue grew 12% year-over-year..." },
+        {
+          "type": "table",
+          "headers": ["Region", "Revenue", "Growth"],
+          "rows": [
+            ["North America", "$4.2M", "+15%"],
+            ["Europe", "$2.8M", "+8%"],
+            ["Asia Pacific", "$1.9M", "+18%"]
+          ]
+        },
+        { "type": "image", "path": "charts/revenue.png", "width": "5in", "alt": "Revenue chart" }
+      ]
+    },
+    {
+      "heading": "Detailed Analysis",
+      "level": 1,
+      "content": [
+        { "type": "paragraph", "text": "Breaking down by product line..." }
+      ]
+    }
+  ]
+}
+```
+
+Supported content types:
+- `paragraph` — body text (applies Normal style)
+- `table` — headers + rows (applies TableGrid style)
+- `image` — inline image with width/height control
+- `list` — bulleted or numbered list items
+- `pageBreak` — forces a page break
+
+---
+
+## Complex Elements Guide
+
+### Table of Contents
+
+Insert a TOC field code. Word will update the actual entries when the file is opened:
+
+```xml
+<w:p>
+  <w:pPr><w:pStyle w:val="TOCHeading" /></w:pPr>
+  <w:r><w:t>Table of Contents</w:t></w:r>
+</w:p>
+<w:p>
+  <w:r>
+    <w:fldChar w:fldCharType="begin" />
+  </w:r>
+  <w:r>
+    <w:instrText xml:space="preserve"> TOC \o "1-3" \h \z \u </w:instrText>
+  </w:r>
+  <w:r>
+    <w:fldChar w:fldCharType="separate" />
+  </w:r>
+  <w:r>
+    <w:t>[Table of contents — update to populate]</w:t>
+  </w:r>
+  <w:r>
+    <w:fldChar w:fldCharType="end" />
+  </w:r>
+</w:p>
+```
+
+### Page Numbers in Footer
+
+Add a footer part (`word/footer1.xml`) and reference it in `w:sectPr`:
+
+```xml
+<!-- In footer1.xml -->
+<w:ftr xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+  <w:p>
+    <w:pPr><w:jc w:val="center" /></w:pPr>
+    <w:r>
+      <w:fldChar w:fldCharType="begin" />
+    </w:r>
+    <w:r>
+      <w:instrText>PAGE</w:instrText>
+    </w:r>
+    <w:r>
+      <w:fldChar w:fldCharType="separate" />
+    </w:r>
+    <w:r><w:t>1</w:t></w:r>
+    <w:r>
+      <w:fldChar w:fldCharType="end" />
+    </w:r>
+  </w:p>
+</w:ftr>
+
+<!-- In sectPr -->
+<w:footerReference w:type="default" r:id="rId8" />
+```
+
+### Watermark
+
+Add a header part with a shape behind the text:
+
+```xml
+<w:hdr>
+  <w:p>
+    <w:r>
+      <w:pict>
+        <v:shape style="position:absolute;margin-left:0;margin-top:0;width:468pt;height:180pt;
+                        z-index:-251657216;mso-position-horizontal:center;
+                        mso-position-vertical:center"
+                 fillcolor="silver" stroked="f">
+          <v:textpath style="font-family:'Calibri';font-size:1pt" string="DRAFT" />
+        </v:shape>
+      </w:pict>
+    </w:r>
+  </w:p>
+</w:hdr>
+```
+
+---
+
+## Post-Creation Checklist
+
+1. **Validate** against `wml-subset.xsd` — all elements in correct order, required attributes present
+2. **Merge adjacent runs** with identical formatting to keep XML clean
+3. **Verify relationships** — every `r:id` in document.xml has a matching entry in `document.xml.rels`
+4. **Check content types** — every part in the package is registered in `[Content_Types].xml`
+5. **Preview** — open in Word or LibreOffice to visually confirm layout
+6. **File size** — confirm images are reasonably sized (compress if > 2MB each)
diff --git a/builtin-skills/document-process/minimax-docx/references/scenario_b_edit_content.md b/builtin-skills/document-process/minimax-docx/references/scenario_b_edit_content.md
new file mode 100644
index 00000000..8bd98a5f
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/scenario_b_edit_content.md
@@ -0,0 +1,295 @@
+# Scenario B: Editing / Filling Content in Existing DOCX
+
+## Core Principle
+
+**"First, do no harm."** When editing an existing document, minimize changes. Touch only what needs to change. Preserve all formatting, styles, relationships, and structure that are not directly involved in the edit.
+
+---
+
+## When to Use
+
+- Replacing placeholder text (`{{name}}`, `$DATE$`, `[PLACEHOLDER]`)
+- Updating specific paragraphs or table cells
+- Filling in form fields
+- Adding or removing paragraphs in a known location
+- Inserting tracked changes for review workflows
+
+Do NOT use when: the user wants to change the look/style of the entire document (→ Scenario C) or create from scratch (→ Scenario A).
+
+---
+
+## Workflow
+
+```
+1. Preview   → CLI: analyze <input.docx>
+2. Analyze   → Understand structure: sections, styles, headings, tables
+3. Identify  → Locate exact edit targets (paragraph index, table index, placeholder text)
+4. Edit      → Apply surgical changes via CLI or direct XML
+5. Validate  → CLI: validate <output.docx>
+6. Diff      → Compare before/after to verify only intended changes were made
+```
+
+---
+
+## When to Use API vs Direct XML
+
+### Use CLI Edit Command When:
+- Replacing placeholder text (e.g., `{{fieldName}}` → actual value)
+- Filling table data from JSON
+- Updating document properties (title, author)
+- Simple text insertions or deletions
+
+### Use Direct XML Manipulation When:
+- Text spans multiple runs with different formatting (run-boundary issues)
+- Adding complex structures (nested tables, multi-image layouts)
+- Manipulating Track Changes markup
+- Modifying header/footer content
+- Adjusting section properties
+
+---
+
+## Placeholder Patterns
+
+The CLI natively supports `{{fieldName}}` placeholders:
+
+```bash
+# Replace all {{placeholders}} from a JSON map
+dotnet run ... edit input.docx --fill-placeholders data.json --output filled.docx
+```
+
+Where `data.json`:
+```json
+{
+  "companyName": "Acme Corp",
+  "date": "March 21, 2026",
+  "amount": "$15,000.00",
+  "recipientName": "Jane Smith"
+}
+```
+
+Other placeholder formats (`$FIELD$`, `[PLACEHOLDER]`) require text replacement:
+```bash
+dotnet run ... edit input.docx --replace "$DATE$" "March 21, 2026" --output updated.docx
+```
+
+---
+
+## Text Replacement Strategies
+
+### Simple Replacement
+
+When the entire search text is within a single `w:r` (run):
+
+```xml
+<!-- Before -->
+<w:r>
+  <w:rPr><w:b /></w:rPr>
+  <w:t>{{companyName}}</w:t>
+</w:r>
+
+<!-- After — formatting preserved -->
+<w:r>
+  <w:rPr><w:b /></w:rPr>
+  <w:t>Acme Corp</w:t>
+</w:r>
+```
+
+Direct replacement. The run's `w:rPr` is untouched.
+
+### Complex Replacement (Split Runs)
+
+When the search text is split across multiple runs (common when Word applies spell-check or formatting mid-text):
+
+```xml
+<!-- "{{companyName}}" split into 3 runs -->
+<w:r><w:rPr><w:b /></w:rPr><w:t>{{company</w:t></w:r>
+<w:r><w:rPr><w:b /><w:i /></w:rPr><w:t>Na</w:t></w:r>
+<w:r><w:rPr><w:b /></w:rPr><w:t>me}}</w:t></w:r>
+```
+
+Strategy:
+1. Concatenate text across runs to find the match
+2. Place the replacement text in the **first** run (preserving its `w:rPr`)
+3. Remove the text from subsequent runs (or remove the runs entirely if empty)
+
+```xml
+<!-- After -->
+<w:r><w:rPr><w:b /></w:rPr><w:t>Acme Corp</w:t></w:r>
+```
+
+**Rule**: Always preserve the formatting of the first run in the match.
+
+---
+
+## Table Editing
+
+### By Index
+
+Tables are 0-indexed in document order:
+
+```bash
+dotnet run ... edit input.docx --table-index 0 --table-data data.json --output updated.docx
+```
+
+### By Header Matching
+
+Find a table by its header row content:
+
+```bash
+dotnet run ... edit input.docx --table-match "Name,Amount,Date" --table-data data.json
+```
+
+### Table Data JSON Format
+
+```json
+{
+  "rows": [
+    ["Alice Johnson", "$5,000", "2026-03-15"],
+    ["Bob Smith", "$3,200", "2026-03-18"]
+  ],
+  "appendRows": true
+}
+```
+
+- `appendRows: true` — add rows after existing data
+- `appendRows: false` (default) — replace all data rows (keeps header row)
+
+### Direct XML Table Editing
+
+To modify a specific cell, locate it by row/column index:
+
+```xml
+<!-- Row 2 (0-indexed), Column 1 -->
+<w:tr>  <!-- tr[2] -->
+  <w:tc>...</w:tc>
+  <w:tc>  <!-- tc[1] — target cell -->
+    <w:p>
+      <w:r><w:t>Old Value</w:t></w:r>
+    </w:p>
+  </w:tc>
+</w:tr>
+```
+
+Replace the `w:t` content. Do NOT modify `w:tcPr` (cell properties) or `w:tblPr` (table properties).
+
+---
+
+## Track Changes Guidance
+
+### When to Add Revision Marks
+- User explicitly requests tracked changes
+- Document already has tracking enabled (`w:trackChanges` in settings)
+- Collaborative review workflow
+
+### When NOT to Add Revision Marks
+- Form filling / placeholder replacement (these are "completing" the document, not "revising" it)
+- Direct edits where the user wants a clean result
+- Batch data filling operations
+
+### Adding Tracked Changes
+
+See `references/track_changes_guide.md` for full XML examples.
+
+Quick reference — inserting text with tracking:
+```xml
+<w:ins w:id="1" w:author="MiniMaxAI" w:date="2026-03-21T10:00:00Z">
+  <w:r>
+    <w:t>New text here</w:t>
+  </w:r>
+</w:ins>
+```
+
+Deleting text with tracking:
+```xml
+<w:del w:id="2" w:author="MiniMaxAI" w:date="2026-03-21T10:00:00Z">
+  <w:r>
+    <w:delText>Removed text</w:delText>  <!-- MUST use delText, not t -->
+  </w:r>
+</w:del>
+```
+
+---
+
+## Common Pitfalls
+
+### 1. Breaking Run Boundaries
+
+**Problem**: Replacing text that spans runs by naively modifying individual runs destroys inline formatting.
+
+**Fix**: Concatenate run text, find match boundaries, consolidate into the first run, remove consumed runs.
+
+### 2. Hyperlink Content
+
+**Problem**: Replacing text inside a `w:hyperlink` element without preserving the hyperlink wrapper removes the link.
+
+```xml
+<w:hyperlink r:id="rId5">
+  <w:r>
+    <w:rPr><w:rStyle w:val="Hyperlink" /></w:rPr>
+    <w:t>Click here</w:t>  <!-- Only replace this text -->
+  </w:r>
+</w:hyperlink>
+```
+
+**Fix**: Only modify the `w:t` inside the hyperlink's run. Never remove or replace the `w:hyperlink` element itself.
+
+### 3. Tracked Change Context
+
+**Problem**: Replacing text that is inside a `w:ins` or `w:del` element without understanding the revision context creates invalid markup.
+
+**Fix**: If the target text is inside a revision mark, either:
+- Replace within the revision context (preserving the `w:ins`/`w:del` wrapper)
+- Or delete the old revision and create a new one
+
+### 4. Style Preservation
+
+**Problem**: Adding new paragraphs without specifying a style causes them to inherit `Normal`, which may not match the surrounding context.
+
+**Fix**: When inserting paragraphs, copy the `w:pStyle` from an adjacent paragraph of the same type.
+
+### 5. Numbering Continuity
+
+**Problem**: Inserting a new list item breaks numbering sequence.
+
+**Fix**: Ensure the new paragraph has the same `w:numId` and `w:ilvl` as adjacent list items. If continuing a sequence, set `w:numPr` to match.
+
+### 6. XML Special Characters
+
+**Problem**: User content contains `&`, `<`, `>`, `"`, `'` — these must be escaped in XML.
+
+**Fix**: Always XML-escape user-provided text before inserting into `w:t` elements:
+- `&` → `&amp;`
+- `<` → `&lt;`
+- `>` → `&gt;`
+- `"` → `&quot;`
+- `'` → `&apos;`
+
+### 7. Whitespace Preservation
+
+**Problem**: Leading/trailing spaces in `w:t` are stripped by XML parsers.
+
+**Fix**: Add `xml:space="preserve"` attribute:
+```xml
+<w:t xml:space="preserve"> text with leading space</w:t>
+```
+
+---
+
+## Diff Verification
+
+After editing, always compare the before and after states:
+
+```bash
+# Structural diff — shows only changed elements
+dotnet run ... diff original.docx modified.docx
+
+# Text-only diff — shows content changes
+dotnet run ... diff original.docx modified.docx --text-only
+```
+
+Verify:
+- Only intended text changed
+- No styles were modified
+- No relationships were added/removed unexpectedly
+- Table structure intact (same number of rows/columns unless intentionally changed)
+- Images and other media unchanged
diff --git a/builtin-skills/document-process/minimax-docx/references/scenario_c_apply_template.md b/builtin-skills/document-process/minimax-docx/references/scenario_c_apply_template.md
new file mode 100644
index 00000000..fb74a073
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/scenario_c_apply_template.md
@@ -0,0 +1,456 @@
+# Scenario C: Applying Formatting / Templates
+
+## When to Use
+
+Use Scenario C when:
+- The user has an existing document and wants to apply a different visual style
+- The user wants to rebrand a document (new fonts, colors, heading styles)
+- The user provides a template DOCX and wants its look applied to a content document
+- The user wants consistent formatting across multiple documents
+
+Do NOT use when: the user wants to edit content (→ Scenario B) or create from scratch (→ Scenario A).
+
+---
+
+## Workflow
+
+```
+1. Analyze source    → CLI: analyze source.docx      (list styles, fonts, structure)
+2. Analyze template  → CLI: analyze template.docx     (list styles, fonts, structure)
+3. Map styles        → Create mapping plan (source style → template style)
+4. Apply template    → CLI: apply-template source.docx --template template.docx --output result.docx
+5. Validate (XSD)    → CLI: validate result.docx --xsd wml-subset.xsd
+6. GATE-CHECK        → CLI: validate result.docx --xsd business-rules.xsd   ← MUST PASS
+7. Diff verify       → CLI: diff source.docx result.docx --text-only   (content must be identical)
+```
+
+---
+
+## What Gets Copied from Template
+
+| Part | File | Description |
+|------|------|-------------|
+| Styles | `word/styles.xml` | All style definitions (paragraph, character, table, numbering) |
+| Theme | `word/theme/theme1.xml` | Color scheme, font scheme, format scheme |
+| Numbering | `word/numbering.xml` | List and numbering definitions |
+| Headers | `word/header*.xml` | Header content and formatting |
+| Footers | `word/footer*.xml` | Footer content and formatting |
+| Section props | `w:sectPr` | Margins, page size, orientation, columns |
+
+## What Does NOT Get Copied
+
+| Part | Reason |
+|------|--------|
+| Document content | Paragraphs, tables, images stay from source |
+| Comments | Belong to source document's review history |
+| Tracked changes | Belong to source document's revision history |
+| Custom XML parts | Application-specific data, not visual |
+| Document properties | Title, author, dates belong to source |
+| Glossary document | Template's building blocks are not transferred |
+
+---
+
+## Template Structure Analysis (REQUIRED)
+
+Before choosing Overlay or Base-Replace, you MUST analyze the template's internal structure. This is the #1 cause of failure when skipped.
+
+### Step 1: Count template paragraphs and identify structural zones
+
+Run `$CLI analyze --input template.docx` or manually inspect:
+
+```bash
+# Quick structure scan
+scripts/docx_preview.sh template.docx
+```
+
+Identify these zones in the template:
+```
+Zone A: Front matter (cover page, declaration, abstract, TOC)
+        → These are KEPT from template, never replaced
+Zone B: Example/placeholder body content ("第1章 XXX", sample paragraphs)
+        → This is REPLACED with user's actual content
+Zone C: Back matter (appendices, acknowledgments, blank pages)
+        → These are KEPT from template or removed
+Zone D: Final sectPr
+        → ALWAYS kept from template
+```
+
+### Step 2: Find Zone B boundaries (replacement range)
+
+Search the template's document.xml for anchor text that marks the start and end of example content:
+
+**Start anchor patterns** (first paragraph of example body):
+- "第1章", "第一章", "Chapter 1", "1 Introduction", "绪论"
+- The first paragraph with a Heading1-equivalent style after TOC
+
+**End anchor patterns** (last paragraph before back matter):
+- "参考文献", "References", "致谢", "Acknowledgments"
+- The last paragraph before appendices or final sectPr
+
+```python
+# Pseudocode for finding replacement range
+for i, element in enumerate(template_body_elements):
+    text = get_text(element)
+    style = get_style(element)
+    if style in heading1_styles and ("第1章" in text or "Chapter 1" in text):
+        replace_start = i
+    if "参考文献" in text or "References" in text:
+        replace_end = i
+        break
+```
+
+**CRITICAL**: Verify the range by printing what's inside:
+```
+Template elements [0..replace_start-1]: front matter (KEEP)
+Template elements [replace_start..replace_end]: example content (REPLACE)
+Template elements [replace_end+1..end]: back matter (KEEP)
+```
+
+If replace_start or replace_end cannot be found, DO NOT proceed. Ask the user to identify the replacement boundaries.
+
+### Step 3: Decide Overlay vs Base-Replace
+
+Now that you know the structure:
+
+| Observation | Decision |
+|-------------|----------|
+| Template has ≤30 paragraphs, no cover/TOC | **C-1: Overlay** (pure style template) |
+| Template has >100 paragraphs with cover/TOC/example sections | **C-2: Base-Replace** |
+| Template paragraph count ≈ user document | **C-1: Overlay** (similar structure) |
+| Template paragraph count >> user document (e.g., 263 vs 134) | **C-2: Base-Replace** |
+
+### Step 4: For Base-Replace, execute the replacement
+
+1. Load template as base (all files)
+2. Extract user content elements using `list(body)` — NOT `findall('w:p')` (which misses tables)
+3. Build new body: `template[0:replace_start] + cleaned_user_content + template[replace_end+1:]`
+4. Apply style mapping to every paragraph
+5. Clean direct formatting (see rules below)
+6. Rebuild document.xml, keeping template's namespace declarations
+7. Merge relationships (images + hyperlinks)
+8. Write output using template as ZIP base
+
+---
+
+## Style Mapping Strategy
+
+When template style names differ from source style names, a mapping is required. **This step is mandatory** — skipping it is the #1 cause of formatting failures in template application.
+
+### Step 0: Extract StyleIds from Both Documents (REQUIRED)
+
+Before any template application, extract and compare styleIds from both documents:
+
+```bash
+# Extract all styleIds from source
+$CLI analyze --input source.docx --styles-only
+# Output example:
+#   Heading1  (paragraph, basedOn: Normal)
+#   Heading2  (paragraph, basedOn: Normal)
+#   Normal    (paragraph)
+#   ListBullet (paragraph, basedOn: Normal)
+
+# Extract all styleIds from template
+$CLI analyze --input template.docx --styles-only
+# Output example:
+#   1         (paragraph, basedOn: a, name: "heading 1")
+#   2         (paragraph, basedOn: a, name: "heading 2")
+#   3         (paragraph, basedOn: a, name: "heading 3")
+#   a         (paragraph, name: "Normal")
+#   a0        (character, name: "Default Paragraph Font")
+```
+
+**Critical distinction**: `w:styleId` vs `w:name`:
+```xml
+<!-- styleId="1" but name="heading 1" -->
+<w:style w:type="paragraph" w:styleId="1">
+  <w:name w:val="heading 1"/>
+  <w:basedOn w:val="a"/>
+</w:style>
+```
+
+The `w:styleId` attribute is what `<w:pStyle w:val="..."/>` references. The `w:name` attribute is the human-readable display name. **They can be completely different.** Many CJK templates use numeric styleIds (`1`, `2`, `3`, `a`, `a0`) instead of English names.
+
+### Tier 1: Exact StyleId Match
+If source uses `Heading1` and template defines `Heading1` as a styleId, map directly. No action needed.
+
+### Tier 2: Name-Based Match
+If no exact styleId match, try matching by `w:name` attribute:
+- Source `Heading1` (name="heading 1") → Template styleId `1` (name="heading 1")
+- Match is case-insensitive on the name value
+
+Within the same type, also try matching by:
+- Built-in style ID (Word's internal ID, e.g., heading 1 = built-in ID 1)
+- Style type (paragraph → paragraph, character → character, table → table)
+
+### Tier 3: Manual Mapping
+For renamed or custom styles, provide an explicit mapping:
+
+```json
+{
+  "styleMap": {
+    "Heading1": "1",
+    "Heading2": "2",
+    "Heading3": "3",
+    "Heading4": "3",
+    "Normal": "a",
+    "BodyText": "a",
+    "ListBullet": "a",
+    "CompanyName": "Title",
+    "OldTableStyle": "TableGrid"
+  }
+}
+```
+
+### Common Non-Standard StyleId Patterns
+
+| Template Origin | StyleId Pattern | Example |
+|----------------|-----------------|---------|
+| Chinese Word (default) | Numeric/alphabetic | `1`, `2`, `3`, `a`, `a0` |
+| English Word (default) | English names | `Heading1`, `Normal`, `Title` |
+| Google Docs export | Prefixed | `Subtitle`, `NormalWeb` |
+| WPS Office | Mixed | `1`, `Heading1`, custom names |
+| Academic templates | Custom | `ThesisHeading1`, `ThesisBody` |
+
+### Building the Mapping Table
+
+Follow this algorithm:
+
+1. **List source styleIds** actually used in `document.xml` (not all defined in `styles.xml`):
+   ```python
+   # Pseudocode: find all unique pStyle values in source document.xml
+   used_styles = set()
+   for p in body.iter('w:p'):
+       pStyle = p.find('w:pPr/w:pStyle')
+       if pStyle is not None:
+           used_styles.add(pStyle.get('val'))
+   ```
+
+2. **For each used style**, find the best match in template:
+   - First try: exact styleId match
+   - Second try: match by `w:name` value (case-insensitive)
+   - Third try: match by style purpose (any heading → template's heading style)
+   - Fallback: map to template's default paragraph style (usually `Normal` or `a`)
+
+3. **Validate the mapping** — every source styleId must map to an existing template styleId:
+   ```
+   ✓ Heading1 → 1 (name match: "heading 1")
+   ✓ Heading2 → 2 (name match: "heading 2")
+   ✓ Normal   → a (name match: "Normal")
+   ✗ CustomCallout → ??? (no match found, will fallback to 'a')
+   ```
+
+4. **Apply the mapping** when copying content — update every `<w:pStyle w:val="..."/>`:
+   ```xml
+   <!-- Source -->
+   <w:pPr><w:pStyle w:val="Heading1"/></w:pPr>
+   <!-- After mapping -->
+   <w:pPr><w:pStyle w:val="1"/></w:pPr>
+   ```
+
+### Unmapped Styles
+Styles in the source document that have no match in the template are logged as warnings:
+```
+WARNING: Style 'CustomCallout' has no mapping in template. Content will fall back to 'a' (Normal).
+```
+
+The content is preserved; only the style reference is updated to the template's default paragraph style.
+
+### C-2 BASE-REPLACE: Additional StyleId Considerations
+
+When using the template as a base document (C-2 strategy), the template's `styles.xml` is already in place. You must:
+
+1. **Never copy source `styles.xml`** — the template's styles are the authority
+2. **Map every content paragraph's pStyle** to the template's styleId before insertion
+3. **Strip direct formatting selectively** (see detailed rules below) — let the template style control appearance
+4. **Verify table styles** — if source tables use `TableGrid` but template defines it as `a3` or similar, remap `<w:tblStyle>` too
+5. **Check character styles** — `rPr` inside runs may reference character styles like `Hyperlink` or `Strong` that have different IDs in the template
+
+### Direct Formatting Cleanup Rules (Detailed)
+
+When copying content from source to template, apply these rules to EACH paragraph and run:
+
+**REMOVE from `<w:rPr>`:**
+- `<w:rFonts w:ascii="..." w:hAnsi="..."/>` — Latin font overrides (EXCEPT: keep `w:eastAsia`)
+- `<w:sz>`, `<w:szCs>` — font size (let style control)
+- `<w:color>` — text color
+- `<w:highlight>` — highlight color
+- `<w:shd>` — shading
+- `<w:b>`, `<w:i>` — bold/italic UNLESS the source style requires it (e.g., emphasis)
+- `<w:u>` — underline
+- `<w:spacing>` — character spacing
+
+**KEEP in `<w:rPr>`:**
+- `<w:rFonts w:eastAsia="宋体"/>` — CJK font declaration (MUST keep, or Chinese text renders wrong)
+- `<w:rFonts w:eastAsia="华文中宋"/>` — same reason
+- Anything inside `<w:drawing>` — image references (handle separately via rId remapping)
+
+**REMOVE from `<w:pPr>`:**
+- `<w:pBdr>` — paragraph borders
+- `<w:shd>` — paragraph shading
+- `<w:spacing>` — line/paragraph spacing (let style control)
+- `<w:jc>` — justification (let style control)
+- `<w:tabs>` — custom tab stops
+- `<w:rPr>` inside pPr — default run formatting for the paragraph
+
+**KEEP in `<w:pPr>`:**
+- `<w:pStyle>` — style reference (after mapping to template's styleId)
+- `<w:sectPr>` — section properties (if intentionally inserting section breaks)
+- `<w:numPr>` — numbering reference (after mapping numId to template's numbering)
+
+**Table cells (`<w:tc>`):**
+Apply the same rPr/pPr cleanup to every paragraph inside every cell. Also:
+- Keep `<w:tcPr>` structural properties (column span, row span, width)
+- Remove `<w:tcPr><w:shd>` (cell shading — let table style control)
+
+---
+
+## Relationship ID Remapping
+
+When copying parts (headers, footers, images) from the template into the source package, relationship IDs (`r:id`) may collide.
+
+**Problem**:
+- Source has `rId7` → `image1.png`
+- Template has `rId7` → `header1.xml`
+- Copying template's `rId7` overwrites source's image reference
+
+**Solution**:
+1. Scan source's `document.xml.rels` for all existing `rId` values
+2. Find the maximum numeric ID (e.g., `rId12`)
+3. Remap all template relationship IDs starting from `rId13`
+4. Update all references in copied parts to use new IDs
+
+```xml
+<!-- Template original -->
+<Relationship Id="rId1" Type="...header" Target="header1.xml" />
+
+<!-- After remapping into source package -->
+<Relationship Id="rId13" Type="...header" Target="header1.xml" />
+
+<!-- Update sectPr reference -->
+<w:headerReference w:type="default" r:id="rId13" />
+```
+
+### Hyperlink Relationship Merging
+
+When the source document contains external hyperlinks (e.g., URLs in references or footnotes), these are stored as relationships in `word/_rels/document.xml.rels`:
+
+```xml
+<Relationship Id="rId15" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
+              Target="https://example.com/paper" TargetMode="External"/>
+```
+
+The corresponding text in document.xml references this rId:
+```xml
+<w:hyperlink r:id="rId15">
+  <w:r><w:t>https://example.com/paper</w:t></w:r>
+</w:hyperlink>
+```
+
+**Merging steps:**
+1. Scan source document.xml for all `<w:hyperlink r:id="...">` elements
+2. For each, find the corresponding relationship in source's rels file
+3. Check if template already has a relationship with the same Target URL
+   - If yes: reuse the existing rId, update the hyperlink reference
+   - If no: assign a new rId (starting from template's max rId + 1), add the relationship to template's rels, update the hyperlink reference
+4. Also check for hyperlink relationships used in footnotes (`word/_rels/footnotes.xml.rels`) and endnotes
+
+**Common mistake:** Copying hyperlink paragraphs without merging rels → hyperlinks silently break (clicking does nothing in Word).
+
+---
+
+## XSD Gate-Check
+
+### What It Is
+
+After template application, the output document **MUST** pass `business-rules.xsd` validation. This is a **hard gate** — if it fails, the document is **NOT deliverable**.
+
+### What business-rules.xsd Checks
+
+| Rule | What It Validates |
+|------|-------------------|
+| Template styles exist | All styles referenced by content paragraphs are defined in `styles.xml` |
+| Margins match | Page margins match template specification |
+| Fonts correct | `w:docDefaults` fonts match template's font scheme |
+| Heading hierarchy | Heading levels are sequential (no H1 → H3 without H2) |
+| Required styles present | `Normal`, `Heading1`-`Heading3`, `TableGrid` exist |
+| Page size | Matches template's declared page size |
+
+### Handling Failures
+
+```
+GATE-CHECK FAILED:
+  - Style 'CustomStyle1' referenced in paragraph 14 but not defined in styles.xml
+  - Margin w:left=1080 does not match template requirement 1440
+```
+
+Fix each failure:
+1. **Missing style**: Add the style definition to `styles.xml`, or remap the paragraph to an existing style
+2. **Margin mismatch**: Update `w:sectPr` margins to match template
+3. **Font mismatch**: Update `w:docDefaults` to match template font scheme
+4. **Heading hierarchy gap**: Insert intermediate heading levels or adjust existing levels
+
+Re-validate after every fix until gate-check passes.
+
+---
+
+## Common Pitfalls
+
+### 1. Orphaned Numbering References
+
+**Problem**: Source document uses `w:numId="5"` in list paragraphs, but after replacing `numbering.xml` with the template's version, numbering ID 5 doesn't exist.
+
+**Symptom**: Lists appear as plain paragraphs (no bullets/numbers).
+
+**Fix**:
+- Map source numbering IDs to template numbering IDs
+- Update all `w:numId` references in document content
+- Or merge source numbering definitions into template's `numbering.xml`
+
+### 2. Missing Theme Colors
+
+**Problem**: Source document's styles reference theme colors (`w:themeColor="accent1"`) that have different values in the template's theme.
+
+**Symptom**: Colors change unexpectedly (usually acceptable — this IS the point of re-theming). But if a style uses `w:color` with both `w:val` and `w:themeColor`, the theme color wins in Word.
+
+**Fix**: Review color changes. If specific colors must be preserved, use explicit `w:val` without `w:themeColor`.
+
+### 3. Section Property Conflicts
+
+**Problem**: Source document has multiple sections (e.g., portrait + landscape pages), but the template assumes a single section.
+
+**Symptom**: All sections get the same margins/orientation, breaking landscape pages.
+
+**Fix**:
+- Only apply template section properties to the final `w:sectPr` in `w:body`
+- Preserve intermediate `w:sectPr` elements (inside `w:pPr`) from the source
+- Or apply template properties to all sections but preserve orientation overrides
+
+### 4. Embedded Font Conflicts
+
+**Problem**: Template specifies fonts not available on the target system.
+
+**Fix**: Either embed fonts in the DOCX (`word/fonts/`) or use web-safe alternatives:
+- Calibri → available on Windows/Mac/Office online
+- Arial → universal fallback
+- Times New Roman → universal serif fallback
+
+### 5. Broken Style Inheritance
+
+**Problem**: Template has `Heading1` based on `Normal`, but after applying template, `Normal` has different properties, cascading unwanted changes to headings.
+
+**Fix**: Verify the `w:basedOn` chain for all critical styles. Ensure base styles are also correctly transferred from template.
+
+---
+
+## Verification Checklist
+
+After template application, verify:
+
+1. **Content preserved** — text diff shows zero content changes
+2. **Gate-check passed** — `business-rules.xsd` validation succeeds
+3. **Styles applied** — headings, body text, tables use template formatting
+4. **Images intact** — all images render correctly (relationship IDs valid)
+5. **Lists working** — numbered and bulleted lists display correctly
+6. **Headers/footers** — template headers/footers appear on all pages
+7. **Page layout** — margins, page size, orientation match template
+8. **No corruption** — file opens without errors in Word
diff --git a/builtin-skills/document-process/minimax-docx/references/track_changes_guide.md b/builtin-skills/document-process/minimax-docx/references/track_changes_guide.md
new file mode 100644
index 00000000..9bcfa34e
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/track_changes_guide.md
@@ -0,0 +1,200 @@
+# Track Changes Guide
+
+## Overview
+
+Track Changes in OpenXML uses revision markup elements to record insertions, deletions, and formatting changes. Each revision has a unique ID, author, and timestamp.
+
+---
+
+## Insertion: `<w:ins>`
+
+Wraps runs that were inserted during tracking:
+
+```xml
+<w:ins w:id="1" w:author="John Smith" w:date="2026-03-21T10:30:00Z">
+  <w:r>
+    <w:rPr>
+      <w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" />
+      <w:sz w:val="22" />
+    </w:rPr>
+    <w:t>This text was inserted.</w:t>
+  </w:r>
+</w:ins>
+```
+
+- `w:id` — unique revision ID (integer, must be unique across document)
+- `w:author` — free text string identifying the author
+- `w:date` — ISO 8601 format with timezone: `YYYY-MM-DDTHH:MM:SSZ`
+- Content inside is normal runs (`w:r`) with optional formatting
+
+---
+
+## Deletion: `<w:del>`
+
+Wraps runs that were deleted during tracking:
+
+```xml
+<w:del w:id="2" w:author="John Smith" w:date="2026-03-21T10:31:00Z">
+  <w:r>
+    <w:rPr>
+      <w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" />
+      <w:sz w:val="22" />
+    </w:rPr>
+    <w:delText xml:space="preserve">This text was deleted.</w:delText>
+  </w:r>
+</w:del>
+```
+
+**CRITICAL**: Inside `<w:del>`, text MUST use `<w:delText>`, NOT `<w:t>`. Using `<w:t>` inside a deletion is invalid and will cause corruption or unexpected behavior. Word may silently repair it, but other consumers will fail.
+
+---
+
+## Formatting Change: `<w:rPrChange>`
+
+Records that a run's formatting was changed. Placed inside `w:rPr`, it stores the **previous** formatting:
+
+```xml
+<w:r>
+  <w:rPr>
+    <w:b />  <!-- Current: bold -->
+    <w:rPrChange w:id="3" w:author="Jane Doe" w:date="2026-03-21T11:00:00Z">
+      <w:rPr>
+        <!-- Previous: not bold (empty rPr means no formatting) -->
+      </w:rPr>
+    </w:rPrChange>
+  </w:rPr>
+  <w:t>This text was made bold.</w:t>
+</w:r>
+```
+
+The outer `w:rPr` holds the **new** (current) formatting. The `w:rPrChange` child holds the **old** (previous) formatting.
+
+---
+
+## Paragraph Property Change: `<w:pPrChange>`
+
+Records paragraph-level formatting changes (alignment, spacing, style):
+
+```xml
+<w:pPr>
+  <w:jc w:val="center" />  <!-- Current: centered -->
+  <w:pPrChange w:id="4" w:author="Jane Doe" w:date="2026-03-21T11:05:00Z">
+    <w:pPr>
+      <w:jc w:val="left" />  <!-- Previous: left-aligned -->
+    </w:pPr>
+  </w:pPrChange>
+</w:pPr>
+```
+
+---
+
+## Revision ID Management
+
+- Every revision element (`w:ins`, `w:del`, `w:rPrChange`, `w:pPrChange`, `w:tblPrChange`, etc.) requires a `w:id` attribute
+- IDs must be **unique integers** across the entire document
+- IDs should be **monotonically increasing** (not strictly required, but expected by Word)
+- When adding revisions, scan for the current maximum `w:id` and increment from there
+
+```
+Existing max ID: 47
+New insertion: w:id="48"
+New deletion: w:id="49"
+```
+
+---
+
+## Author and Date
+
+- **Author**: Free text. Use consistent strings (e.g., `"MiniMaxAI"` for all automated edits)
+- **Date**: ISO 8601 with UTC timezone marker: `2026-03-21T10:30:00Z`
+  - Must include the `T` separator and `Z` suffix (or `+HH:MM` offset)
+  - Omitting the date is allowed but not recommended
+
+---
+
+## Operations
+
+### Propose Insertion
+
+Add `<w:ins>` wrapper around new content at the target location:
+
+```xml
+<w:p>
+  <w:r><w:t>Existing text. </w:t></w:r>
+  <w:ins w:id="5" w:author="MiniMaxAI" w:date="2026-03-21T12:00:00Z">
+    <w:r><w:t>Proposed new text. </w:t></w:r>
+  </w:ins>
+  <w:r><w:t>More existing text.</w:t></w:r>
+</w:p>
+```
+
+### Propose Deletion
+
+Wrap existing content in `<w:del>` and change `<w:t>` to `<w:delText>`:
+
+```xml
+<w:p>
+  <w:r><w:t>Keep this. </w:t></w:r>
+  <w:del w:id="6" w:author="MiniMaxAI" w:date="2026-03-21T12:01:00Z">
+    <w:r>
+      <w:rPr><w:b /></w:rPr>
+      <w:delText>Remove this.</w:delText>
+    </w:r>
+  </w:del>
+  <w:r><w:t> Keep this too.</w:t></w:r>
+</w:p>
+```
+
+### Accept a Tracked Change
+
+- **Accept insertion**: Remove the `<w:ins>` wrapper, keep the inner runs as normal content
+- **Accept deletion**: Remove the entire `<w:del>` element and its content
+
+### Reject a Tracked Change
+
+- **Reject insertion**: Remove the entire `<w:ins>` element and its content
+- **Reject deletion**: Remove the `<w:del>` wrapper, change `<w:delText>` back to `<w:t>`
+
+---
+
+## Cross-Paragraph Operations
+
+### Deleting a Paragraph Break (Merging Paragraphs)
+
+When tracked deletion spans a paragraph boundary, use `<w:pPrChange>` on the merged paragraph:
+
+```xml
+<w:p>
+  <w:pPr>
+    <w:pPrChange w:id="7" w:author="MiniMaxAI" w:date="2026-03-21T12:05:00Z">
+      <w:pPr>
+        <w:pStyle w:val="Normal" />
+      </w:pPr>
+    </w:pPrChange>
+  </w:pPr>
+  <w:r><w:t>First paragraph text. </w:t></w:r>
+  <w:del w:id="8" w:author="MiniMaxAI" w:date="2026-03-21T12:05:00Z">
+    <w:r><w:delText> </w:delText></w:r>
+  </w:del>
+  <w:r><w:t>Second paragraph text (now merged).</w:t></w:r>
+</w:p>
+```
+
+### Inserting a New Paragraph
+
+The entire new paragraph is wrapped in `<w:ins>`:
+
+```xml
+<w:p>
+  <w:pPr>
+    <w:rPr>
+      <w:ins w:id="9" w:author="MiniMaxAI" w:date="2026-03-21T12:10:00Z" />
+    </w:rPr>
+  </w:pPr>
+  <w:ins w:id="10" w:author="MiniMaxAI" w:date="2026-03-21T12:10:00Z">
+    <w:r><w:t>Entirely new paragraph.</w:t></w:r>
+  </w:ins>
+</w:p>
+```
+
+The paragraph mark itself is marked as inserted via `w:ins` inside `w:pPr > w:rPr`.
diff --git a/builtin-skills/document-process/minimax-docx/references/troubleshooting.md b/builtin-skills/document-process/minimax-docx/references/troubleshooting.md
new file mode 100644
index 00000000..a2f750ec
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/troubleshooting.md
@@ -0,0 +1,506 @@
+# Troubleshooting Guide — Symptom-Driven
+
+## How to Use This Guide
+
+Search by the **SYMPTOM** you observe, not the technical concept. Each entry follows:
+- **Symptom** — what you see or what the user reports
+- **Diagnosis** — how to confirm the root cause
+- **Fix** — exact steps, commands, or code
+- **Prevention** — how to avoid it next time
+
+**Quick search keywords:** headings wrong, body text, repair, corrupt, font, tables missing, images missing, TOC broken, update table, page break, section break, hyperlink, numbered list, bullets, margins, page size, Chinese tofu, cover page, track changes, revision marks
+
+---
+
+## 1. "All headings look like body text" (Heading Styles Not Applied)
+
+**Symptom:** After template application, headings have no formatting — they look like Normal paragraphs. Font size, bold, spacing are all wrong.
+
+**Diagnosis:** The `pStyle` values in `document.xml` don't match the `styleId` values in `styles.xml`.
+
+Common mismatches:
+- Source uses `Heading1` but template defines the style as `1` (Chinese templates often use numeric styleIds)
+- Source uses `heading1` (lowercase) but template has `Heading1` (case-sensitive!)
+- `pStyle` references a style that simply doesn't exist in the output's `styles.xml`
+
+Check with:
+```bash
+# List all pStyle values used in the document
+$CLI analyze --input output.docx | grep -i "pStyle"
+
+# List all styleIds defined in styles.xml
+$CLI analyze --input template.docx --part styles | grep "styleId"
+```
+
+**Fix:** Build a styleId mapping table before applying the template. Update every `pStyle` value in the document content.
+
+```csharp
+// Build mapping: source styleId → template styleId
+var mapping = new Dictionary<string, string>();
+// Compare by style name (w:name), not by styleId
+foreach (var srcStyle in sourceStyles)
+{
+    var templateStyle = templateStyles.FirstOrDefault(
+        s => s.StyleName?.Val?.Value == srcStyle.StyleName?.Val?.Value);
+    if (templateStyle != null)
+        mapping[srcStyle.StyleId!] = templateStyle.StyleId!;
+}
+
+// Apply mapping to all paragraphs
+foreach (var para in body.Descendants<Paragraph>())
+{
+    var pStyle = para.ParagraphProperties?.ParagraphStyleId;
+    if (pStyle != null && mapping.TryGetValue(pStyle.Val!, out var newId))
+        pStyle.Val = newId;
+}
+```
+
+**Prevention:** ALWAYS extract and compare styleIds from both source and template before template application. Never assume styleIds are the same across documents.
+
+---
+
+## 2. "Document opens with repair warnings" (XML Corruption)
+
+**Symptom:** Word says "We found a problem with some content" or "Word found unreadable content" when opening.
+
+**Diagnosis:** Element ordering is wrong. OpenXML is strict about child element order.
+
+Common violations:
+- `pPr` must come before runs in `w:p`
+- `tblPr` must come before `tblGrid` in `w:tbl`
+- `rPr` must come before `t`/`br`/`tab` in `w:r`
+- `trPr` must come before `tc` in `w:tr`
+- `tcPr` must come before content in `w:tc`
+
+```bash
+# Validate to find ordering issues
+$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd
+
+# Auto-fix element ordering
+$CLI fix-order --input doc.docx
+
+# Re-validate
+$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd
+```
+
+**Fix:**
+```bash
+$CLI fix-order --input doc.docx
+```
+
+If auto-fix doesn't resolve it, unpack and inspect manually:
+```bash
+$CLI unpack --input doc.docx --output unpacked/
+# Check word/document.xml for ordering issues
+# Fix, then repack:
+$CLI pack --input unpacked/ --output fixed.docx
+```
+
+**Prevention:** Read `references/openxml_element_order.md` before writing any XML manipulation code. Always append properties elements first, then content elements.
+
+---
+
+## 3. "All text is in wrong font" (Font Contamination)
+
+**Symptom:** Template specifies 宋体/Times New Roman but document shows Google Sans, Arial, Calibri, or whatever font the source document used.
+
+**Diagnosis:** Source document's `rPr` contains inline `rFonts` declarations that override template styles. Direct formatting always wins over style-based formatting in OpenXML.
+
+```bash
+# Check for font contamination
+$CLI analyze --input output.docx | grep -i "font"
+# Look for rFonts in the content — if present, they're overriding styles
+```
+
+**Fix:** Strip `rFonts` from `rPr` when copying content, but KEEP `w:eastAsia` for CJK text:
+
+```csharp
+foreach (var rPr in body.Descendants<RunProperties>())
+{
+    var rFonts = rPr.GetFirstChild<RunFonts>();
+    if (rFonts != null)
+    {
+        // Preserve EastAsia font for CJK — removing it causes tofu (□□□)
+        var eastAsia = rFonts.EastAsia?.Value;
+        rFonts.Remove();
+
+        // Re-add only eastAsia if it was set and text contains CJK
+        if (!string.IsNullOrEmpty(eastAsia))
+        {
+            rPr.Append(new RunFonts { EastAsia = eastAsia });
+        }
+    }
+}
+```
+
+Also strip these common direct formatting overrides:
+- `w:sz` / `w:szCs` (font size)
+- `w:color` (text color)
+- `w:b` / `w:i` when they contradict the style
+
+**Prevention:** Always clean direct formatting when copying content between documents. Keep only `pStyle`/`rStyle` references and `w:t` text.
+
+---
+
+## 4. "Tables are missing" (Tables Lost During Copy)
+
+**Symptom:** Source had 5 tables but output only has 2 (or 0).
+
+**Diagnosis:** Code used `body.findall('w:p')` or `body.Descendants<Paragraph>()` at the top level instead of iterating all children. This skips `w:tbl` elements.
+
+```bash
+# Verify table count
+$CLI analyze --input source.docx | grep -i "table"
+$CLI analyze --input output.docx | grep -i "table"
+```
+
+**Fix:** Use `list(body)` or `body.ChildElements` to get ALL top-level children including tables:
+
+```csharp
+// WRONG — skips tables, section properties, and other non-paragraph elements
+var paragraphs = body.Elements<Paragraph>();
+
+// CORRECT — gets everything: paragraphs, tables, SDT blocks, etc.
+var allElements = body.ChildElements.ToList();
+```
+
+In Python with lxml:
+```python
+# WRONG
+elements = body.findall('{http://schemas.openxmlformats.org/wordprocessingml/2006/main}p')
+
+# CORRECT
+elements = list(body)  # all direct children
+```
+
+**Prevention:** Always use `list(body)` or `body.ChildElements` for iteration, never filter by a single element type alone when copying content.
+
+---
+
+## 5. "Images are missing or show broken icon"
+
+**Symptom:** Image placeholders appear but images don't render. Or images are completely absent.
+
+**Diagnosis:** The `r:embed` rId in `w:drawing` doesn't match any relationship in `document.xml.rels`, or the media file wasn't copied to the output ZIP.
+
+```bash
+# Check relationships
+$CLI analyze --input output.docx --part rels | grep -i "image"
+
+# Check if media files exist
+$CLI unpack --input output.docx --output unpacked/
+ls unpacked/word/media/
+```
+
+**Fix:**
+1. Check source rels for image file paths
+2. Copy media files from source to output
+3. Add/update relationships in output rels
+4. Update `r:embed` values in drawing elements
+
+```csharp
+// When copying content with images between documents:
+foreach (var drawing in body.Descendants<Drawing>())
+{
+    var blip = drawing.Descendants<DocumentFormat.OpenXml.Drawing.Blip>().FirstOrDefault();
+    if (blip?.Embed?.Value != null)
+    {
+        var sourceRel = sourcePart.GetReferenceRelationship(blip.Embed.Value);
+        // Copy the image part to the target document
+        var imagePart = targetPart.AddImagePart(ImagePartType.Png);
+        using var stream = sourcePart.GetPartById(blip.Embed.Value).GetStream();
+        imagePart.FeedData(stream);
+        // Update the rId reference
+        blip.Embed = targetPart.GetIdOfPart(imagePart);
+    }
+}
+```
+
+**Prevention:** Always do rId remapping + media file copy when moving content between documents. Never assume rIds are portable across documents.
+
+---
+
+## 6. "TOC shows stale/wrong entries" or "Update Table doesn't work"
+
+**Symptom:** Table of contents shows the template's example entries (e.g., "第1章 绪论...1") instead of actual headings. Or clicking "Update Table" in Word does nothing.
+
+**Diagnosis:**
+- **Stale entries (normal):** TOC entries are static text cached inside the field. They don't auto-update until the user explicitly updates in Word.
+- **Update Table fails:** The SDT wrapper or field code structure is damaged. The TOC in real templates is a mixed structure: SDT block + field code + static entries.
+
+```bash
+# Check if TOC SDT exists
+$CLI analyze --input output.docx | grep -i "sdt\|toc"
+```
+
+**Fix:**
+- **If entries are just stale:** This is expected behavior. The user must right-click TOC, then "Update Field" in Word. Or enable auto-update:
+  ```csharp
+  // See FieldAndTocSamples.EnableUpdateFieldsOnOpen()
+  FieldAndTocSamples.EnableUpdateFieldsOnOpen(settingsPart);
+  ```
+- **If SDT is damaged:** Keep the entire SDT block from the template intact. Do not modify it.
+- **If field code is missing:** Ensure the TOC contains: `fldChar begin` + `instrText` + `fldChar separate` + static entries + `fldChar end`. See `FieldAndTocSamples.CreateMixedTocStructure()` for the complete pattern.
+- **If you rebuilt TOC from scratch (common mistake):** You likely destroyed the SDT wrapper. Use the template's original SDT block instead. See `Samples/FieldAndTocSamples.cs` method `CreateMixedTocStructure` for how real-world TOC is structured.
+
+**Prevention:** When doing Base-Replace (C-2), keep the template's TOC zone completely untouched. Do not strip, rebuild, or modify the SDT block. The TOC will auto-update when the user opens in Word.
+
+---
+
+## 7. "Chapters don't start on new pages" (Missing Section Breaks)
+
+**Symptom:** Content flows continuously without page breaks between chapters. Chapter 2 starts right after Chapter 1's last paragraph on the same page.
+
+**Diagnosis:** No `sectPr` elements or page break paragraphs between chapters.
+
+**Fix:** Insert a paragraph with `sectPr` in its `pPr` before each chapter heading, or insert a page break:
+
+```csharp
+// Option 1: Section break (preserves per-section settings like headers/margins)
+var breakPara = new Paragraph(
+    new ParagraphProperties(
+        new SectionProperties(
+            new SectionType { Val = SectionMarkValues.NextPage })));
+
+// Option 2: Simple page break (lighter weight)
+var breakPara = new Paragraph(
+    new Run(new Break { Type = BreakValues.Page }));
+
+// Insert before each Heading1
+body.InsertBefore(breakPara, heading1Paragraph);
+```
+
+**Prevention:** When copying content, insert page/section breaks before Heading1 paragraphs as needed. Check source document's section structure before copying.
+
+---
+
+## 8. "Hyperlinks don't work" (Broken Links)
+
+**Symptom:** Clicking a hyperlink in the output document does nothing, or it navigates to the wrong URL.
+
+**Diagnosis:** `w:hyperlink r:id` points to a relationship that doesn't exist in `document.xml.rels`.
+
+```bash
+# Check hyperlink relationships
+$CLI analyze --input output.docx --part rels | grep -i "hyperlink"
+```
+
+**Fix:** Merge source document's hyperlink relationships into output's rels file. Update rId references.
+
+```csharp
+foreach (var hyperlink in body.Descendants<Hyperlink>())
+{
+    if (hyperlink.Id?.Value != null)
+    {
+        var sourceRel = sourcePart.HyperlinkRelationships
+            .FirstOrDefault(r => r.Id == hyperlink.Id.Value);
+        if (sourceRel != null)
+        {
+            targetPart.AddHyperlinkRelationship(sourceRel.Uri, sourceRel.IsExternal);
+            var newRel = targetPart.HyperlinkRelationships.Last();
+            hyperlink.Id = newRel.Id;
+        }
+    }
+}
+```
+
+**Prevention:** Always merge ALL relationship types (images, hyperlinks, headers, footers) when combining documents. Never assume source rIds work in the target.
+
+---
+
+## 9. "Numbered lists show wrong numbers" or "Bullets disappeared"
+
+**Symptom:** Lists that were numbered 1, 2, 3 now show 1, 1, 1 or have no numbers/bullets at all.
+
+**Diagnosis:** `numId` in `pPr` references a numbering definition that doesn't exist in `numbering.xml`, or `abstractNumId` mapping is broken.
+
+```bash
+# Check numbering definitions
+$CLI analyze --input output.docx --part numbering
+```
+
+**Fix:** Map source numIds to template numIds, or merge numbering definitions:
+
+```csharp
+// 1. Copy abstractNum definitions from source to target numbering.xml
+// 2. Create new num entries pointing to the copied abstractNum
+// 3. Update all numId references in document content
+
+var sourceNumbering = sourceNumberingPart.Numbering;
+var targetNumbering = targetNumberingPart.Numbering;
+
+// Get max existing IDs to avoid collisions
+int maxAbstractNumId = targetNumbering.Elements<AbstractNum>()
+    .Max(a => a.AbstractNumberId?.Value ?? 0) + 1;
+int maxNumId = targetNumbering.Elements<NumberingInstance>()
+    .Max(n => n.NumberID?.Value ?? 0) + 1;
+```
+
+**Prevention:** Include `numbering.xml` reconciliation in template application workflow. See `Samples/ListAndNumberingSamples.cs` for correct numbering setup.
+
+---
+
+## 10. "Page margins/size are wrong"
+
+**Symptom:** Output has different margins, page size, or orientation than the template.
+
+**Diagnosis:** Source document's `sectPr` is overriding the template's `sectPr`. The final `sectPr` (child of `body`) controls the last section's layout.
+
+```bash
+# Compare section properties
+$CLI analyze --input template.docx | grep -i "sectPr\|margin\|pgSz"
+$CLI analyze --input output.docx | grep -i "sectPr\|margin\|pgSz"
+```
+
+**Fix:** Use the template's final `sectPr`. For intermediate `sectPr` elements (multi-section documents), merge carefully.
+
+```csharp
+// Replace output's final sectPr with template's
+var templateSectPr = templateBody.Elements<SectionProperties>().LastOrDefault();
+var outputSectPr = outputBody.Elements<SectionProperties>().LastOrDefault();
+
+if (templateSectPr != null)
+{
+    var cloned = templateSectPr.CloneNode(true) as SectionProperties;
+    if (outputSectPr != null)
+        outputBody.ReplaceChild(cloned!, outputSectPr);
+    else
+        outputBody.Append(cloned!);
+}
+```
+
+**Prevention:** Always use the template's `sectPr` as authority for page layout. Strip source document's `sectPr` before copying content.
+
+---
+
+## 11. "Chinese text renders as boxes/tofu"
+
+**Symptom:** Chinese characters display as square boxes (□□□) or missing glyphs.
+
+**Diagnosis:** `rFonts w:eastAsia` is set to a font that doesn't exist on the system, or is missing entirely. Without an East Asian font declaration, the rendering engine may fall back to a font without CJK coverage.
+
+**Fix:** Ensure all CJK text has `w:eastAsia` set to an available font:
+
+```csharp
+foreach (var run in body.Descendants<Run>())
+{
+    var text = run.InnerText;
+    if (ContainsCjk(text))
+    {
+        var rPr = run.RunProperties ?? new RunProperties();
+        var rFonts = rPr.GetFirstChild<RunFonts>();
+        if (rFonts == null)
+        {
+            rFonts = new RunFonts();
+            rPr.Append(rFonts);
+        }
+        // Set to a universally available CJK font
+        rFonts.EastAsia = "SimSun"; // 宋体 — safest default
+        if (run.RunProperties == null) run.PrependChild(rPr);
+    }
+}
+
+static bool ContainsCjk(string text)
+{
+    return text.Any(c => c >= 0x4E00 && c <= 0x9FFF);
+}
+```
+
+Common safe CJK fonts: 宋体 (SimSun), 黑体 (SimHei), 仿宋 (FangSong), 楷体 (KaiTi).
+
+**Prevention:** When cleaning `rPr` formatting, ALWAYS preserve `w:eastAsia` font declarations. See also `references/cjk_typography.md`.
+
+---
+
+## 12. "Template's cover page / declaration page is missing"
+
+**Symptom:** Output document starts directly with body content — no cover page, no declaration, no abstract, no table of contents. The template's structural front matter was discarded.
+
+**Diagnosis:** Used Overlay (C-1) strategy when Base-Replace (C-2) was needed. Overlay applies styles to the source document but discards the template's structural content (cover, declaration, abstract, TOC).
+
+```bash
+# Check template structure
+$CLI analyze --input template.docx
+# If template has >50 paragraphs with cover/TOC/declaration, C-2 is needed
+```
+
+**Fix:** Use Base-Replace (C-2) strategy — template is the base, only replace the example body content zone with the user's content:
+
+1. Identify the template's "body zone" (everything between TOC and final sectPr)
+2. Remove the template's example body content
+3. Insert the user's content into the body zone
+4. Keep everything else from the template (cover, declaration, abstract, TOC, sectPr)
+
+```bash
+$CLI apply-template --input source.docx --template template.docx --output out.docx --strategy base-replace
+```
+
+**Prevention:** Analyze template structure FIRST. If template has structural content (cover, TOC, declaration sections), always use C-2 (Base-Replace). Read `references/scenario_c_apply_template.md` for detailed decision criteria.
+
+---
+
+## 13. "Track changes markers appear unexpectedly"
+
+**Symptom:** Output shows red/green revision marks (insertions, deletions) that weren't in the source document.
+
+**Diagnosis:** Template had track changes enabled, or content was inserted as revisions rather than normal text.
+
+```bash
+# Check for revision marks
+$CLI analyze --input output.docx | grep -i "revision\|ins\|del\|track"
+```
+
+**Fix:** Accept all revisions by flattening `w:ins` and `w:del` elements:
+
+```csharp
+// Accept insertions: unwrap w:ins, keep content
+foreach (var ins in body.Descendants<InsertedRun>().ToList())
+{
+    var parent = ins.Parent!;
+    foreach (var child in ins.ChildElements.ToList())
+    {
+        parent.InsertBefore(child.CloneNode(true), ins);
+    }
+    ins.Remove();
+}
+
+// Accept deletions: remove w:del and its content entirely
+foreach (var del in body.Descendants<DeletedRun>().ToList())
+{
+    del.Remove();
+}
+```
+
+Or disable tracking in settings:
+```csharp
+var settings = settingsPart.Settings;
+var trackChanges = settings.GetFirstChild<TrackChanges>();
+trackChanges?.Remove();
+```
+
+**Prevention:** Check template's `settings.xml` for `trackChanges` before starting. If present, accept all revisions in the template first.
+
+---
+
+## Recovery Strategy — When Multiple Issues Exist
+
+When a document has multiple problems, fix them in this priority order:
+
+```
+1. [Content_Types].xml  — without this, nothing opens
+2. _rels/.rels          — package relationships
+3. word/_rels/document.xml.rels — part relationships (images, hyperlinks)
+4. word/document.xml    — element ordering (fix-order)
+5. word/styles.xml      — style definitions and styleId mapping
+6. word/numbering.xml   — list/numbering definitions
+7. Everything else      — headers, footers, comments, settings
+```
+
+```bash
+# Full recovery pipeline
+$CLI unpack --input broken.docx --output unpacked/
+$CLI validate --input broken.docx --xsd assets/xsd/wml-subset.xsd  # find all errors
+$CLI fix-order --input broken.docx                                   # fix element ordering
+$CLI validate --input broken.docx --business                         # check business rules
+scripts/docx_preview.sh broken.docx                                  # visual check
+```
diff --git a/builtin-skills/document-process/minimax-docx/references/typography_guide.md b/builtin-skills/document-process/minimax-docx/references/typography_guide.md
new file mode 100644
index 00000000..039c99cc
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/typography_guide.md
@@ -0,0 +1,294 @@
+# Professional Document Design & Typography Guide
+
+## Table of Contents
+1. [Font Pairing](#font-pairing)
+2. [Font Sizes by Document Type](#font-sizes-by-document-type)
+3. [Line Spacing](#line-spacing)
+4. [Paragraph Spacing](#paragraph-spacing)
+5. [Page Layout](#page-layout)
+6. [Table Design](#table-design)
+7. [Color Schemes](#color-schemes)
+8. [Visual Hierarchy](#visual-hierarchy)
+9. [Quick Reference Defaults](#quick-reference-defaults)
+
+---
+
+## Font Pairing
+
+### Recommended Pairs
+
+| Headings | Body | Style | Best For |
+|----------|------|-------|----------|
+| Calibri Light | Calibri | Modern sans | Corporate reports |
+| Aptos | Aptos | Office 365 default | Modern business docs |
+| Cambria | Calibri | Serif + sans | Academic-corporate hybrid |
+| Times New Roman | Times New Roman | Traditional serif | Academic, legal |
+| Arial | Arial | Clean sans | Memos, internal docs |
+| Georgia | Garamond | Classical serif pair | Formal reports |
+
+### Rules
+
+- **Limit**: 2 font families max (3 if CJK mixed)
+- **Contrast**: Pair serif with sans-serif, OR use weight contrast within one family
+- **Consistency**: Same font for all body text, same font for all headings
+
+---
+
+## Font Sizes by Document Type
+
+| Document Type | Body | H1 | H2 | H3 | Footnotes |
+|--------------|------|----|----|----|----|
+| **Business report** | 11pt | 18-20pt | 14-16pt | 12-13pt bold | 9pt |
+| **Business letter** | 11-12pt | — | — | — | 9-10pt |
+| **Memo** | 11pt | 14pt bold | 12pt bold | 11pt bold | 9pt |
+| **Contract / Legal** | 12pt | 14pt bold caps | 12pt bold | 12pt bold | 10pt |
+| **Academic (APA 7)** | 12pt | 12pt bold center | 12pt bold left | 12pt bold italic | 10pt |
+| **Resume / CV** | 10-11pt | 14-16pt | 12pt bold | 11pt bold | 8-9pt |
+| **Chinese 公文** | 三号(16pt) | 二号(22pt) | 三号(16pt) | 四号(14pt) | 小四(12pt) |
+
+### OpenXML `w:sz` Values (half-points)
+
+| Point Size | `w:sz` Val | Common Use |
+|-----------|-----------|------------|
+| 9pt | 18 | Footnotes, captions |
+| 10pt | 20 | Compact body text |
+| 10.5pt (五号) | 21 | CJK body small |
+| 11pt | 22 | Standard body (Calibri) |
+| 12pt (小四) | 24 | Standard body (TNR), CJK |
+| 14pt (四号) | 28 | CJK body, subheading |
+| 16pt (三号) | 32 | CJK heading, western H2 |
+| 18pt (小二) | 36 | Western H1 |
+| 22pt (二号) | 44 | CJK document title |
+| 26pt (一号) | 52 | Large title |
+
+---
+
+## Line Spacing
+
+| Spacing | OpenXML `w:spacing line` | When to Use |
+|---------|--------------------------|-------------|
+| Single (1.0) | `line="240"` lineRule="auto" | Tables, footnotes, captions |
+| 1.08 (MS default) | `line="259"` lineRule="auto" | Modern Office documents |
+| 1.15 | `line="276"` lineRule="auto" | Business reports — best general default |
+| 1.5 | `line="360"` lineRule="auto" | Some academic, drafts for markup |
+| Double (2.0) | `line="480"` lineRule="auto" | APA/MLA manuscripts, legal briefs |
+| Fixed 28pt | `line="560"` lineRule="exact" | Chinese 公文 (GB/T 9704) |
+
+**`lineRule` values**: `auto` = proportional (240 = 1 line), `exact` = fixed height, `atLeast` = minimum.
+
+---
+
+## Paragraph Spacing
+
+| Element | Space Before (DXA) | Space After (DXA) |
+|---------|-------------------|-------------------|
+| Body paragraph | 0 | 120-160 (6-8pt) |
+| Heading 1 | 480 (24pt) | 120-240 |
+| Heading 2 | 360 (18pt) | 120 |
+| Heading 3 | 240 (12pt) | 80-120 |
+| List items | 0 | 40-80 (2-4pt) |
+| Block quote | 120-240 | 120-240 |
+| Table/Figure caption | 240 | 240 |
+
+**Principle**: Space before a heading > space after, so heading visually "belongs to" content below (2:1 or 3:1 ratio).
+
+---
+
+## Page Layout
+
+### Margins by Document Type
+
+| Document Type | Top | Bottom | Left | Right | DXA Values |
+|--------------|-----|--------|------|-------|------------|
+| **Standard business** | 1 in | 1 in | 1 in | 1 in | 1440 all |
+| **Academic (APA/MLA)** | 1 in | 1 in | 1 in | 1 in | 1440 all |
+| **Thesis (binding)** | 1 in | 1 in | 1.5 in | 1 in | T/B:1440 L:2160 R:1440 |
+| **Chinese 公文** | 37mm | 35mm | 28mm | 26mm | T:2098 B:1984 L:1588 R:1474 |
+| **Narrow modern** | 0.75 in | 0.75 in | 0.75 in | 0.75 in | 1080 all |
+| **Wide** | 1 in | 1 in | 2 in | 2 in | T/B:1440 L/R:2880 |
+
+### Page Sizes
+
+| Size | Width × Height | DXA Width × Height |
+|------|---------------|-------------------|
+| US Letter | 8.5 × 11 in | 12240 × 15840 |
+| A4 | 210 × 297 mm | 11906 × 16838 |
+| Legal | 8.5 × 14 in | 12240 × 20160 |
+| A3 | 297 × 420 mm | 16838 × 23811 |
+
+**Rule**: A4 for international audiences, Letter for US-only.
+
+### Page Numbers
+
+| Convention | Placement | Common In |
+|-----------|-----------|-----------|
+| Bottom center | Footer, centered | Academic, government |
+| Bottom right | Footer, right-aligned | Business reports |
+| "Page X of Y" | Footer, right-aligned | Contracts, legal |
+| Bottom outside | Alternating L/R for odd/even | Books, bound reports |
+| Chinese 公文 | Bottom center, format "-X-" | Government documents |
+
+---
+
+## Table Design
+
+### Style Patterns
+
+| Style | Description | When to Use |
+|-------|------------|-------------|
+| **Three-line (三线表)** | Top rule + header-bottom rule + bottom rule only, no vertical lines | Academic, scientific — gold standard |
+| **Banded rows** | Alternating white/light-gray, no borders | Modern corporate |
+| **Light grid** | Thin 0.5pt gray borders all cells | Business reports |
+| **Header-accent** | Dark/colored header row, no other borders | Modern templates |
+| **Full border** | All cells bordered | Financial tables, forms |
+
+### Border Weights (OpenXML `w:sz` in eighths of a point)
+
+| Visual | `Size` value | Points |
+|--------|-------------|--------|
+| Hairline | 2 | 0.25pt |
+| Thin | 4 | 0.5pt |
+| Medium | 8 | 1pt |
+| Thick | 12 | 1.5pt |
+
+### Cell Padding
+
+- **Minimum**: 0.05 in (28 DXA) — too tight for most uses
+- **Recommended**: 0.08-0.1 in (57-72 DXA) top/bottom, 0.1-0.15 in (72-108 DXA) left/right
+- **Spacious**: 0.12 in (86 DXA) top/bottom, 0.19 in (137 DXA) left/right
+
+### Header Row Best Practices
+
+- Bold text, optionally SMALL CAPS
+- Background: light gray (#F2F2F2) or dark with white text (#2F5496 + white)
+- Repeat header row on each page (`w:tblHeader` on `w:trPr`)
+- Right-align number columns, left-align text columns
+
+---
+
+## Color Schemes
+
+### Corporate / Business
+
+| Element | Hex | Notes |
+|---------|-----|-------|
+| Primary heading | #1F3864 | Dark navy, authoritative |
+| Secondary heading | #2E75B6 | Medium blue |
+| Body text | #333333 | Near-black (softer than #000) |
+| Table header bg | #4472C4 | With white #FFFFFF text |
+| Alternate row | #F2F2F2 | Subtle gray banding |
+| Hyperlink | #0563C1 | Standard blue |
+
+### Academic
+
+All text **#000000** (black). Color only in figures/charts.
+
+### Chinese Government (公文)
+
+| Element | Color |
+|---------|-------|
+| All body text | Black (required) |
+| 红头 agency name | Red #FF0000 |
+| 红线 separator | Red #FF0000 |
+| 公章 seal | Red |
+
+### Accessibility
+
+- Minimum contrast ratio 4.5:1 for normal text, 3:1 for large text (WCAG AA)
+- Never use color as sole means of conveying information
+- Ensure distinguishable in grayscale for printed documents
+
+---
+
+## Visual Hierarchy
+
+### Heading Levels by Document Length
+
+| Pages | Recommended Levels |
+|-------|-------------------|
+| 1-5 (memo, letter) | 1-2 levels |
+| 5-20 (report) | 2-3 levels |
+| 20-100 (long report) | 3-4 levels |
+| 100+ (thesis) | 4-5 levels max |
+
+### Numbering Systems
+
+**Decimal (ISO 2145)** — technical, international:
+```
+1 → 1.1 → 1.1.1 → 1.1.1.1
+```
+
+**Traditional outline (US legal):**
+```
+I. → A. → 1. → a. → (1) → (a)
+```
+
+**Chinese government (公文):**
+```
+一、(黑体) → （一）(楷体) → 1.(仿宋加粗) → (1)(仿宋)
+```
+
+### Typography Emphasis
+
+| Format | Use For | Avoid |
+|--------|---------|-------|
+| **Bold** | Key terms, headings, emphasis | Entire paragraphs |
+| *Italic* | Titles, foreign words, mild emphasis | Long passages (hard to read) |
+| Underline | Hyperlinks only (digital) | General emphasis (archaic) |
+| SMALL CAPS | Legal defined terms, acronyms | Body text |
+| ALL CAPS | Very short headings | Long text (reduces readability 15%) |
+
+**CJK note**: Chinese/Japanese have no true italic. Use bold for emphasis.
+
+### List Formatting
+
+**Bullets** (unordered): `•` → `○` → `■` by level
+
+**Numbers** (ordered): `1.` → `a.` → `i.` by level
+
+- Indent each level 0.25-0.5 in (360-720 DXA)
+- Hanging indent: number hangs, text aligns consistently
+- Spacing between items: 2-4pt (less than paragraph spacing)
+
+---
+
+## Quick Reference Defaults
+
+### Business Report (Safe Default)
+
+| Parameter | Value | OpenXML |
+|-----------|-------|---------|
+| Body font | Calibri 11pt | sz="22", RunFonts Ascii="Calibri" |
+| H1 | 18pt Bold Dark Blue | sz="36", Bold, Color="#1F3864" |
+| H2 | 14pt Bold Dark Blue | sz="28", Bold |
+| H3 | 12pt Bold Dark Blue | sz="24", Bold |
+| Line spacing | 1.15 | line="276" lineRule="auto" |
+| Para after | 8pt | after="160" |
+| Margins | 1 in all | 1440 DXA all |
+| Page size | Letter or A4 | 12240×15840 or 11906×16838 |
+| Page numbers | Bottom right, 10pt | |
+
+### Academic Paper (APA 7th)
+
+| Parameter | Value | OpenXML |
+|-----------|-------|---------|
+| Font | Times New Roman 12pt | sz="24" |
+| Line spacing | Double | line="480" lineRule="auto" |
+| First-line indent | 0.5 in | ind firstLine="720" |
+| Margins | 1 in all | 1440 DXA all |
+| Page numbers | Top right | Header, right-aligned |
+
+### Chinese Government (公文 GB/T 9704)
+
+| Parameter | Value | OpenXML |
+|-----------|-------|---------|
+| Body font | 仿宋_GB2312 三号 | sz="32", EastAsia="FangSong_GB2312" |
+| Title | 小标宋 二号 centered | sz="44" |
+| L1 heading | 黑体 三号 | sz="32", EastAsia="SimHei" |
+| L2 heading | 楷体 三号 | sz="32", EastAsia="KaiTi_GB2312" |
+| Line spacing | Fixed 28pt | line="560" lineRule="exact" |
+| Margins | T:37mm B:35mm L:28mm R:26mm | T:2098 B:1984 L:1588 R:1474 |
+| Page size | A4 | 11906×16838 |
+| Page numbers | Bottom center, 宋体 四号, "-X-" | sz="28" |
+| Chars/line | 28 | |
+| Lines/page | 22 | |
diff --git a/builtin-skills/document-process/minimax-docx/references/xsd_validation_guide.md b/builtin-skills/document-process/minimax-docx/references/xsd_validation_guide.md
new file mode 100644
index 00000000..8f67ef31
--- /dev/null
+++ b/builtin-skills/document-process/minimax-docx/references/xsd_validation_guide.md
@@ -0,0 +1,158 @@
+# XSD Validation Guide
+
+## Running Validation
+
+```bash
+# Validate against the WML subset schema
+dotnet run --project minimax-docx validate input.docx --xsd assets/xsd/wml-subset.xsd
+
+# Validate against business rules (REQUIRED for Scenario C gate-check)
+dotnet run --project minimax-docx validate input.docx --xsd assets/xsd/business-rules.xsd
+
+# Validate against both
+dotnet run --project minimax-docx validate input.docx --xsd assets/xsd/wml-subset.xsd --xsd assets/xsd/business-rules.xsd
+```
+
+---
+
+## What wml-subset.xsd Covers
+
+The subset schema validates the most common WordprocessingML elements:
+
+| Area | Elements Validated |
+|------|--------------------|
+| Document structure | `w:document`, `w:body`, `w:sectPr` |
+| Paragraphs | `w:p`, `w:pPr`, `w:r`, `w:rPr`, `w:t` |
+| Tables | `w:tbl`, `w:tblPr`, `w:tblGrid`, `w:tr`, `w:tc` |
+| Styles | `w:styles`, `w:style`, `w:docDefaults` |
+| Lists | `w:numbering`, `w:abstractNum`, `w:num` |
+| Headers/Footers | `w:hdr`, `w:ftr` |
+| Track Changes | `w:ins`, `w:del`, `w:rPrChange`, `w:pPrChange` |
+| Comments | `w:comment`, `w:commentRangeStart`, `w:commentRangeEnd` |
+
+### What It Does NOT Cover
+
+- DrawingML elements (`a:`, `pic:`, `wp:`) — image/shape internals
+- VML elements (`v:`, `o:`) — legacy shapes
+- Math elements (`m:`) — equations
+- Extended namespaces (`w14`, `w15`, `w16*`) — vendor extensions
+- Custom XML data parts
+- Relationship and content type validation (structural, not schema-based)
+
+---
+
+## Interpreting Errors
+
+### Element Ordering Error
+
+```
+ERROR: Element 'w:jc' is not expected at this position.
+Expected: w:spacing, w:ind, w:contextualSpacing, ...
+Location: /word/document.xml, line 45
+```
+
+**Cause**: Child elements are in wrong order. See `references/openxml_element_order.md`.
+**Fix**: Reorder children to match schema sequence.
+
+### Missing Required Element
+
+```
+ERROR: Element 'w:tbl' missing required child 'w:tblPr'.
+Location: /word/document.xml, line 102
+```
+
+**Cause**: A required child element is absent.
+**Fix**: Add the missing element. Tables require both `w:tblPr` and `w:tblGrid`.
+
+### Invalid Attribute Value
+
+```
+ERROR: Attribute 'w:val' has invalid value 'middle'.
+Expected: 'left', 'center', 'right', 'both', 'distribute'
+Location: /word/document.xml, line 78
+```
+
+**Cause**: An attribute value is not in the allowed enumeration.
+**Fix**: Use one of the valid values listed in the error.
+
+### Unexpected Element
+
+```
+ERROR: Element 'w:customTag' is not expected.
+Location: /word/document.xml, line 200
+```
+
+**Cause**: An element not defined in the subset schema. May be a vendor extension.
+**Fix**: Check if it's a known extension (w14/w15/w16). If so, it's likely safe. If unknown, investigate or remove.
+
+---
+
+## Business Rules XSD
+
+The `business-rules.xsd` schema enforces project-specific constraints beyond standard OpenXML validity:
+
+| Rule | What It Checks |
+|------|---------------|
+| Required styles | `Normal`, `Heading1`-`Heading3`, `TableGrid` must exist in `styles.xml` |
+| Font consistency | `w:docDefaults` fonts match expected values |
+| Margin ranges | Page margins within acceptable range (720-2160 DXA) |
+| Page size | Must be A4 or Letter |
+| Heading hierarchy | No gaps (e.g., H1 → H3 without H2) |
+| Style chain | `w:basedOn` references must resolve to existing styles |
+
+### Extending Business Rules
+
+To add project-specific rules, add `xs:assert` or `xs:restriction` elements:
+
+```xml
+<!-- Require minimum 1-inch margins -->
+<xs:element name="pgMar">
+  <xs:complexType>
+    <xs:attribute name="top" type="xs:integer">
+      <xs:restriction>
+        <xs:minInclusive value="1440" />
+      </xs:restriction>
+    </xs:attribute>
+  </xs:complexType>
+</xs:element>
+```
+
+---
+
+## Gate-Check: Scenario C Hard Gate
+
+In Scenario C (Apply Template), the output document **MUST** pass `business-rules.xsd` validation before delivery:
+
+```
+1. Apply template  →  output.docx
+2. Validate        →  dotnet run ... validate output.docx --xsd business-rules.xsd
+3. PASS?           →  Deliver to user
+4. FAIL?           →  Fix issues, re-validate, repeat until PASS
+```
+
+**This is a hard gate.** A document that fails business-rules validation is NOT deliverable, even if it opens correctly in Word.
+
+---
+
+## False Positives
+
+### Vendor Extensions
+
+Elements from extended namespaces (`w14`, `w15`, `w16*`) are not in the subset schema and may trigger warnings:
+
+```
+WARNING: Element '{http://schemas.microsoft.com/office/word/2010/wordml}shadow' is not expected.
+```
+
+These are generally safe to ignore — they are Microsoft extensions for newer features (e.g., advanced text effects, comment extensions).
+
+### Markup Compatibility
+
+Documents may contain `mc:AlternateContent` blocks with fallback content. The subset schema may not recognize the `mc:` namespace processing. These are safe if the document opens correctly in Word.
+
+### Recommended Approach
+
+1. Run validation
+2. Treat **errors** as must-fix
+3. Review **warnings** — ignore known vendor extensions, investigate unknown elements
+4. After fixing errors, re-validate to confirm
diff --git a/builtin-skills/document-process/minimax-pdf/README.md b/builtin-skills/document-process/minimax-pdf/README.md
new file mode 100644
index 00000000..b2bc2861
--- /dev/null
+++ b/builtin-skills/document-process/minimax-pdf/README.md
@@ -0,0 +1,222 @@
+# minimax-pdf
+
+A Claude skill for creating and editing visually polished PDFs.  
+Three routes. One design system. Tokens flow from content analysis through every renderer.
+
+## Quick start
+
+```bash
+bash scripts/make.sh check   # verify deps
+bash scripts/make.sh fix     # auto-install missing deps
+bash scripts/make.sh demo    # → demo.pdf
+```
+
+---
+
+## Route A: CREATE — generate a new PDF
+
+```bash
+bash scripts/make.sh run \
+  --title   "Q3 Strategy Review" \
+  --type    "proposal" \
+  --author  "Strategy Team" \
+  --date    "October 2025" \
+  --content content.json \
+  --out     report.pdf
+```
+
+**`--type` options:**
+
+| Type | Palette | Cover pattern | Google Fonts (cover) |
+|---|---|---|---|
+| `report` | Deep ink, teal accent | `fullbleed` | Playfair Display / IBM Plex Sans |
+| `proposal` | Near-black, amber accent | `split` | Syne / Nunito Sans |
+| `resume` | White, navy accent | `typographic` | DM Serif Display / DM Sans |
+| `portfolio` | Deep violet, coral accent | `atmospheric` | Fraunces / Inter |
+| `academic` | Warm white, navy accent | `typographic` | EB Garamond / Source Sans 3 |
+| `general` | Dark slate, blue accent | `fullbleed` | Outfit / Outfit |
+| `minimal` | Near-white, red accent | `minimal` | Cormorant Garamond / Jost |
+| `stripe` | Dark navy, amber accent | `stripe` | Barlow Condensed / Barlow |
+| `diagonal` | Dark blue, teal accent | `diagonal` | Montserrat / Montserrat |
+| `frame` | Warm cream, brown accent | `frame` | Cormorant / Crimson Pro |
+| `editorial` | White, red accent | `editorial` | Bebas Neue / Libre Franklin |
+| `magazine` | Warm linen, deep navy accent | `magazine` | Playfair Display / EB Garamond |
+| `darkroom` | Deep navy, steel blue accent | `darkroom` | Playfair Display / EB Garamond |
+| `terminal` | Near-black, neon green accent | `terminal` | Space Mono |
+| `poster` | White, near-black accent | `poster` | Barlow Condensed / Courier Prime |
+
+**content.json block types:**
+
+```json
+[
+  {"type": "h1",      "text": "Section Title"},
+  {"type": "h2",      "text": "Subsection"},
+  {"type": "h3",      "text": "Sub-subsection"},
+  {"type": "body",    "text": "Paragraph. Supports <b>bold</b> and <i>italic</i>."},
+  {"type": "bullet",  "text": "Unordered list item"},
+  {"type": "numbered","text": "Ordered list item — counter auto-resets between lists"},
+  {"type": "callout", "text": "Key insight or highlighted finding"},
+  {"type": "table",
+    "headers": ["Col A", "Col B"],
+    "rows":    [["a", "b"], ["c", "d"]]
+  },
+  {"type": "image",   "path": "chart.png", "caption": "Figure 1: optional caption"},
+  {"type": "code",    "text": "def hello():\n    print('world')"},
+  {"type": "math",    "text": "\\int_0^\\infty e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}", "label": "(1)"},
+  {"type": "divider"},
+  {"type": "caption", "text": "Table 1: standalone caption label"},
+  {"type": "pagebreak"},
+  {"type": "spacer",  "pt": 16}
+]
+```
+
+---
+
+## Route B: FILL — fill form fields in an existing PDF
+
+```bash
+# See what fields the PDF has
+bash scripts/make.sh fill --input form.pdf --inspect
+
+# Fill fields
+bash scripts/make.sh fill \
+  --input  form.pdf \
+  --out    filled.pdf \
+  --values '{"FirstName": "Jane", "Agree": "true", "Country": "US"}'
+
+# Or from a JSON file
+bash scripts/make.sh fill --input form.pdf --out filled.pdf --data values.json
+```
+
+Field value rules:
+- `text` → any string
+- `checkbox` → `"true"` or `"false"`
+- `dropdown` → must match a choice value shown by `--inspect`
+- `radio` → must match a radio value shown by `--inspect`
+
+---
+
+## Route C: REFORMAT — apply design to an existing document
+
+```bash
+bash scripts/make.sh reformat \
+  --input  source.md \
+  --title  "Annual Report" \
+  --type   "report" \
+  --author "Research Team" \
+  --out    output.pdf
+```
+
+Supported input: `.md` `.txt` `.pdf` `.json`
+
+---
+
+## Architecture
+
+```
+SKILL.md                      ← Claude entry point, route table
+design/design.md              ← Aesthetic system (read before CREATE/REFORMAT)
+scripts/
+  make.sh                     ← Unified CLI
+  palette.py                  ← metadata → tokens.json       [CREATE, REFORMAT]
+  cover.py                    ← tokens.json → cover.html     [CREATE, REFORMAT]
+  render_cover.js             ← cover.html → cover.pdf       [CREATE, REFORMAT]
+  render_body.py              ← tokens + content → body.pdf  [CREATE, REFORMAT]
+  merge.py                    ← cover + body → final.pdf     [CREATE, REFORMAT]
+  fill_inspect.py             ← PDF → field list             [FILL]
+  fill_write.py               ← PDF + values → filled PDF    [FILL]
+  reformat_parse.py           ← doc → content.json           [REFORMAT]
+```
+
+Design tokens (`tokens.json`) flow from `palette.py` to every renderer — cover and body are always visually consistent.
+
+## Dependencies
+
+| Tool | Used by | Install |
+|---|---|---|
+| Python 3.9+ | all `.py` scripts | system |
+| `reportlab` | `render_body.py` | `pip install reportlab` |
+| `pypdf` | fill, merge, reformat | `pip install pypdf` |
+| Node.js 18+ | `render_cover.js` | system |
+| `playwright` + Chromium | `render_cover.js` | `npm install -g playwright && npx playwright install chromium` |
+
+## License
+
+MIT
+
+## Document types
+
+| `--type` | Mood | Cover pattern | Cover fonts |
+|---|---|---|---|
+| `report` | Authoritative | `fullbleed` | Playfair Display / IBM Plex Sans |
+| `proposal` | Confident | `split` | Syne / Nunito Sans |
+| `resume` | Clean | `typographic` | DM Serif Display / DM Sans |
+| `portfolio` | Expressive | `atmospheric` | Fraunces / Inter |
+| `academic` | Scholarly | `typographic` | EB Garamond / Source Sans 3 |
+| `general` | Neutral | `fullbleed` | Outfit |
+| `minimal` | Restrained | `minimal` | Cormorant Garamond / Jost |
+| `stripe` | Bold | `stripe` | Barlow Condensed / Barlow |
+| `diagonal` | Dynamic | `diagonal` | Montserrat |
+| `frame` | Classical | `frame` | Cormorant / Crimson Pro |
+| `editorial` | Editorial | `editorial` | Bebas Neue / Libre Franklin |
+
+Cover fonts load via Google Fonts `@import` at render time — no local caching.
+Body pages always use system fonts (Times / Helvetica) via ReportLab.
+
+## content.json schema
+
+```json
+[
+  {"type": "h1",      "text": "Section Title"},
+  {"type": "h2",      "text": "Subsection"},
+  {"type": "h3",      "text": "Sub-subsection"},
+  {"type": "body",    "text": "Paragraph text. Supports <b>bold</b> and <i>italic</i>."},
+  {"type": "bullet",  "text": "Unordered list item"},
+  {"type": "numbered","text": "Ordered list item — auto-numbered, counter resets between lists"},
+  {"type": "callout", "text": "Highlighted insight or key finding"},
+  {"type": "table",
+    "headers": ["Column A", "Column B", "Column C"],
+    "rows":    [["row1a", "row1b", "row1c"], ["row2a", "row2b", "row2c"]]
+  },
+  {"type": "image",   "path": "chart.png", "caption": "Figure 1: Sales by quarter"},
+  {"type": "code",    "text": "SELECT * FROM users\nWHERE active = 1;"},
+  {"type": "math",    "text": "\\sigma = \\sqrt{\\frac{1}{N}\\sum_{i=1}^N (x_i - \\mu)^2}", "label": "(2)"},
+  {"type": "divider"},
+  {"type": "caption", "text": "Table 2: standalone label"},
+  {"type": "pagebreak"},
+  {"type": "spacer",  "pt": 16}
+]
+```
+
+## Architecture
+
+```
+SKILL.md                  ← Claude entry point, routing only
+design/design.md          ← Aesthetic system (read before any script)
+scripts/
+  make.sh                 ← Unified CLI: check / fix / run / demo
+  palette.py              ← content metadata → tokens.json
+  cover.py                ← tokens.json → cover.html
+  render_cover.js         ← cover.html → cover.pdf  (Playwright)
+  render_body.py          ← tokens.json + content.json → body.pdf  (ReportLab)
+  merge.py                ← cover.pdf + body.pdf → final.pdf + QA report
+```
+
+Design tokens (color, typography, spacing) are written once by `palette.py` and consumed by every downstream script. This guarantees visual consistency between cover and body without any manual coordination.
+
+## Dependencies
+
+| Tool | Purpose | Install |
+|---|---|---|
+| Python 3.9+ | palette, cover, render_body, merge | system |
+| `reportlab` | Body page rendering | `pip install reportlab` |
+| `pypdf` | Merging PDFs | `pip install pypdf` |
+| Node.js 18+ | Cover rendering | system |
+| `playwright` | Headless Chromium for cover | `npm install -g playwright && npx playwright install chromium` |
+
+Run `bash scripts/make.sh check` to verify everything at once.  
+Run `bash scripts/make.sh fix` to auto-install what is missing.
+
+## License
+
+MIT
diff --git a/builtin-skills/document-process/minimax-pdf/SKILL.md b/builtin-skills/document-process/minimax-pdf/SKILL.md
new file mode 100644
index 00000000..35cfdb94
--- /dev/null
+++ b/builtin-skills/document-process/minimax-pdf/SKILL.md
@@ -0,0 +1,192 @@
+---
+name: minimax-pdf
+description: >
+  Use this skill when visual quality and design identity matter for a PDF.
+  CREATE (generate from scratch): "make a PDF", "generate a report", "write a proposal",
+  "create a resume", "beautiful PDF", "professional document", "cover page",
+  "polished PDF", "client-ready document".
+  FILL (complete form fields): "fill in the form", "fill out this PDF",
+  "complete the form fields", "write values into PDF", "what fields does this PDF have".
+  REFORMAT (apply design to an existing doc): "reformat this document", "apply our style",
+  "convert this Markdown/text to PDF", "make this doc look good", "re-style this PDF".
+  This skill uses a token-based design system: color, typography, and spacing are derived
+  from the document type and flow through every page. The output is print-ready.
+  Prefer this skill when appearance matters, not just when any PDF output is needed.
+license: MIT
+metadata:
+  version: "1.0"
+  category: document-generation
+---
+
+# minimax-pdf
+
+Three tasks. One skill.
+
+## Read `design/design.md` before any CREATE or REFORMAT work.
+
+---
+
+## Route table
+
+| User intent | Route | Scripts used |
+|---|---|---|
+| Generate a new PDF from scratch | **CREATE** | `palette.py` → `cover.py` → `render_cover.js` → `render_body.py` → `merge.py` |
+| Fill / complete form fields in an existing PDF | **FILL** | `fill_inspect.py` → `fill_write.py` |
+| Reformat / re-style an existing document | **REFORMAT** | `reformat_parse.py` → then full CREATE pipeline |
+
+**Rule:** when in doubt between CREATE and REFORMAT, ask whether the user has an existing document to start from. If yes → REFORMAT. If no → CREATE.
+
+---
+
+## Route A: CREATE
+
+Full pipeline — content → design tokens → cover → body → merged PDF.
+
+```bash
+bash scripts/make.sh run \
+  --title "Q3 Strategy Review" --type proposal \
+  --author "Strategy Team" --date "October 2025" \
+  --accent "#2D5F8A" \
+  --content content.json --out report.pdf
+```
+
+**Doc types:** `report` · `proposal` · `resume` · `portfolio` · `academic` · `general` · `minimal` · `stripe` · `diagonal` · `frame` · `editorial` · `magazine` · `darkroom` · `terminal` · `poster`
+
+| Type | Cover pattern | Visual identity |
+|---|---|---|
+| `report` | `fullbleed` | Dark bg, dot grid, Playfair Display |
+| `proposal` | `split` | Left panel + right geometric, Syne |
+| `resume` | `typographic` | Oversized first-word, DM Serif Display |
+| `portfolio` | `atmospheric` | Near-black, radial glow, Fraunces |
+| `academic` | `typographic` | Light bg, classical serif, EB Garamond |
+| `general` | `fullbleed` | Dark slate, Outfit |
+| `minimal` | `minimal` | White + single 8px accent bar, Cormorant Garamond |
+| `stripe` | `stripe` | 3 bold horizontal color bands, Barlow Condensed |
+| `diagonal` | `diagonal` | SVG angled cut, dark/light halves, Montserrat |
+| `frame` | `frame` | Inset border, corner ornaments, Cormorant |
+| `editorial` | `editorial` | Ghost letter, all-caps title, Bebas Neue |
+| `magazine` | `magazine` | Warm cream bg, centered stack, hero image, Playfair Display |
+| `darkroom` | `darkroom` | Navy bg, centered stack, grayscale image, Playfair Display |
+| `terminal` | `terminal` | Near-black, grid lines, monospace, neon green |
+| `poster` | `poster` | White bg, thick sidebar, oversized title, Barlow Condensed |
+
+Cover extras (inject into tokens via `--abstract`, `--cover-image`):
+- `--abstract "text"` — abstract text block on the cover (magazine/darkroom)
+- `--cover-image "url"` — hero image URL/path (magazine, darkroom, poster)
+
+**Color overrides — always choose these based on document content:**
+- `--accent "#HEX"` — override the accent color; `accent_lt` is auto-derived by lightening toward white
+- `--cover-bg "#HEX"` — override the cover background color
+
+**Accent color selection guidance:**
+
+You have creative authority over the accent color. Pick it from the document's semantic context — title, industry, purpose, audience — not from generic "safe" choices. The accent appears on section rules, callout bars, table headers, and the cover: it carries the document's visual identity.
+
+| Context | Suggested accent range |
+|---|---|
+| Legal / compliance / finance | Deep navy `#1C3A5E`, charcoal `#2E3440`, slate `#3D4C5E` |
+| Healthcare / medical | Teal-green `#2A6B5A`, cool green `#3A7D6A` |
+| Technology / engineering | Steel blue `#2D5F8A`, indigo `#3D4F8A` |
+| Environmental / sustainability | Forest `#2E5E3A`, olive `#4A5E2A` |
+| Creative / arts / culture | Burgundy `#6B2A35`, plum `#5A2A6B`, terracotta `#8A3A2A` |
+| Academic / research | Deep teal `#2A5A6B`, library blue `#2A4A6B` |
+| Corporate / neutral | Slate `#3D4A5A`, graphite `#444C56` |
+| Luxury / premium | Warm black `#1A1208`, deep bronze `#4A3820` |
+
+**Rule:** choose a color that a thoughtful designer would select for this specific document — not the type's default. Muted, desaturated tones work best; avoid vivid primaries. When in doubt, go darker and more neutral.
+
+**content.json block types:**
+
+| Block | Usage | Key fields |
+|---|---|---|
+| `h1` | Section heading + accent rule | `text` |
+| `h2` | Subsection heading | `text` |
+| `h3` | Sub-subsection (bold) | `text` |
+| `body` | Justified paragraph; supports `<b>` `<i>` markup | `text` |
+| `bullet` | Unordered list item (• prefix) | `text` |
+| `numbered` | Ordered list item — counter auto-resets on non-numbered blocks | `text` |
+| `callout` | Highlighted insight box with accent left bar | `text` |
+| `table` | Data table — accent header, alternating row tints | `headers`, `rows`, `col_widths`?, `caption`? |
+| `image` | Embedded image scaled to column width | `path`/`src`, `caption`? |
+| `figure` | Image with auto-numbered "Figure N:" caption | `path`/`src`, `caption`? |
+| `code` | Monospace code block with accent left border | `text`, `language`? |
+| `math` | Display math — LaTeX syntax via matplotlib mathtext | `text`, `label`?, `caption`? |
+| `chart` | Bar / line / pie chart rendered with matplotlib | `chart_type`, `labels`, `datasets`, `title`?, `x_label`?, `y_label`?, `caption`?, `figure`? |
+| `flowchart` | Process diagram with nodes + edges via matplotlib | `nodes`, `edges`, `caption`?, `figure`? |
+| `bibliography` | Numbered reference list with hanging indent | `items` [{id, text}], `title`? |
+| `divider` | Accent-colored full-width rule | — |
+| `caption` | Small muted label | `text` |
+| `pagebreak` | Force a new page | — |
+| `spacer` | Vertical whitespace | `pt` (default 12) |
+
+**chart / flowchart schemas:**
+```json
+{"type":"chart","chart_type":"bar","labels":["Q1","Q2","Q3","Q4"],
+ "datasets":[{"label":"Revenue","values":[120,145,132,178]}],"caption":"Q results"}
+
+{"type":"flowchart",
+ "nodes":[{"id":"s","label":"Start","shape":"oval"},
+          {"id":"p","label":"Process","shape":"rect"},
+          {"id":"d","label":"Valid?","shape":"diamond"},
+          {"id":"e","label":"End","shape":"oval"}],
+ "edges":[{"from":"s","to":"p"},{"from":"p","to":"d"},
+          {"from":"d","to":"e","label":"Yes"},{"from":"d","to":"p","label":"No"}]}
+
+{"type":"bibliography","items":[
+  {"id":"1","text":"Author (Year). Title. Publisher."}]}
+```
+
+---
+
+## Route B: FILL
+
+Fill form fields in an existing PDF without altering layout or design.
+
+```bash
+# Step 1: inspect
+python3 scripts/fill_inspect.py --input form.pdf
+
+# Step 2: fill
+python3 scripts/fill_write.py --input form.pdf --out filled.pdf \
+  --values '{"FirstName": "Jane", "Agree": "true", "Country": "US"}'
+```
+
+| Field type | Value format |
+|---|---|
+| `text` | Any string |
+| `checkbox` | `"true"` or `"false"` |
+| `dropdown` | Must match a choice value from inspect output |
+| `radio` | Must match a radio value (often starts with `/`) |
+
+Always run `fill_inspect.py` first to get exact field names.
+
+---
+
+## Route C: REFORMAT
+
+Parse an existing document → content.json → CREATE pipeline.
+
+```bash
+bash scripts/make.sh reformat \
+  --input source.md --title "My Report" --type report --out output.pdf
+```
+
+**Supported input formats:** `.md` `.txt` `.pdf` `.json`
+
+---
+
+## Environment
+
+```bash
+bash scripts/make.sh check   # verify all deps
+bash scripts/make.sh fix     # auto-install missing deps
+bash scripts/make.sh demo    # build a sample PDF
+```
+
+| Tool | Used by | Install |
+|---|---|---|
+| Python 3.9+ | all `.py` scripts | system |
+| `reportlab` | `render_body.py` | `pip install reportlab` |
+| `pypdf` | fill, merge, reformat | `pip install pypdf` |
+| Node.js 18+ | `render_cover.js` | system |
+| `playwright` + Chromium | `render_cover.js` | `npm install -g playwright && npx playwright install chromium` |
diff --git a/builtin-skills/document-process/minimax-pdf/design/design.md b/builtin-skills/document-process/minimax-pdf/design/design.md
new file mode 100644
index 00000000..2f28c5de
--- /dev/null
+++ b/builtin-skills/document-process/minimax-pdf/design/design.md
@@ -0,0 +1,381 @@
+# Design System
+
+The aesthetic layer. Read this before touching any script.
+This file answers "what should it look like and why."
+
+---
+
+## The one rule
+
+Every design decision must be **rooted in the document's content and purpose**.
+Dark teal + cream is not "professional". Serif + beige is not "elegant".
+A color chosen because it fits the content will always outperform a color chosen
+because it seems safe.
+
+---
+
+## Palette logic
+
+`palette.py` takes a short content description and outputs `tokens.json`.
+Here is the reasoning it applies:
+
+### Mood → base palette
+
+| Content signal | Mood | Background | Accent | Text |
+|---|---|---|---|---|
+| Research, science, analysis | Authoritative | `#0F1F2E` deep ink | `#00B4A6` teal | `#F0EDE6` warm white |
+| Business, strategy, finance | Confident | `#1C1C2B` near-black | `#E8A020` amber | `#F5F2EC` cream |
+| Creative, portfolio, design | Expressive | `#1A0A2E` deep violet | `#FF6B6B` coral | `#FAF5FF` lavender white |
+| Education, academic paper | Scholarly | `#FAFAF7` warm white | `#2C4A7C` navy | `#1A1A2E` dark |
+| Healthcare, wellness | Calm | `#F5F9F8` pale mint | `#2D8B72` forest | `#1E3830` deep green |
+| Resume / personal | Clean | `#FFFFFF` white | pick from content | `#111111` near-black |
+| General / unknown | Neutral | `#F8F6F1` warm off-white | `#3D3D3D` dark gray | `#1A1A1A` black |
+| Formal publications, annual reports | Magazine | `#F2F0EC` warm linen | `#1C3557` deep navy | `#0D1A2B` near-black |
+| Premium/dark reports, tech reviews | Darkroom | `#151C27` deep navy | `#4A6FA5` steel blue | `#F0EDE6` warm white |
+| Technical docs, developer reports | Terminal | `#0D1117` near-black | `#39D353` neon green | `#E6EDF3` cool white |
+| Portfolios, creative, photography | Poster | `#FFFFFF` white | `#0A0A0A` near-black | `#0A0A0A` near-black |
+
+### Accent selection rules
+
+- **One accent color only.** Using two accents splits visual energy.
+- Accent appears on: cover geometric elements, section rules, callout left borders,
+  table header background, page header rule. Nowhere else.
+- Accent must contrast with the cover background by at least 4.5:1 (WCAG AA).
+- Do not default to blue. Blue is the most overused accent in AI-generated documents.
+
+### Color pairing anti-patterns (never use these)
+
+| ❌ Avoid | Why |
+|---|---|
+| Purple gradient on white | The default AI aesthetic — immediately signals "generated" |
+| Navy + gold | Overused corporate cliché |
+| All-black background | Prints badly, feels aggressive |
+| More than 3 colors in the system | Visual noise |
+| Accent on body text | Destroys readability |
+
+---
+
+## Typography system
+
+### Font pairing logic
+
+Two typefaces maximum. Always.
+
+| Role | Criteria | Good choices (system-safe) |
+|---|---|---|
+| Display (cover title, H1) | Distinctive, strong contrast, high weight | Times New Roman, Georgia (serif) |
+| Text (body, captions, UI) | Highly readable at 10–11pt | Helvetica, Arial (sans) |
+
+Cover fonts are loaded live via `@import url(...)` in the cover HTML — Playwright
+fetches them at render time, no local caching. Body pages always use system fonts
+(Times-Bold / Helvetica) via ReportLab — consistent and offline-safe.
+
+Pairs by mood (cover HTML only — body always uses system fonts):
+- Authoritative: `Playfair Display` / `IBM Plex Sans`
+- Confident: `Syne` / `Nunito Sans`
+- Expressive: `Fraunces` / `Inter`
+- Scholarly: `EB Garamond` / `Source Sans 3`
+- Clean: `DM Serif Display` / `DM Sans`
+- Restrained: `Cormorant Garamond` / `Jost`
+- Bold: `Barlow Condensed` / `Barlow`
+- Dynamic: `Montserrat` / `Montserrat`
+- Classical: `Cormorant` / `Crimson Pro`
+- Editorial: `Bebas Neue` / `Libre Franklin`
+- Body fallback (always): `Times-Bold` / `Helvetica` (ReportLab system fonts)
+
+### Type scale
+
+All sizes in points. This scale is used by `palette.py` to populate `tokens.json`.
+
+| Token | Size | Leading | Usage |
+|---|---|---|---|
+| `display` | 54pt | 1.0 | Cover title |
+| `h1` | 22pt | 1.3 | Section headings |
+| `h2` | 15pt | 1.4 | Subsection headings |
+| `h3` | 11.5pt | 1.5 | Sub-subsection |
+| `body` | 10.5pt | 1.6 | Main prose |
+| `caption` | 8.5pt | 1.4 | Figure/table captions |
+| `meta` | 8pt | 1.3 | Header/footer text |
+
+### Spacing system
+
+Margins and rhythm are what separate "looks designed" from "looks printed".
+
+| Token | Value | Notes |
+|---|---|---|
+| `margin_outer` | 2.8cm | Left/right page margin |
+| `margin_top` | 2.8cm | Top page margin |
+| `margin_bottom` | 2.5cm | Bottom page margin |
+| `section_gap` | 26pt | Space before H1 |
+| `para_gap` | 8pt | Space after paragraph |
+| `line_gap` | 17pt | Leading for body text |
+
+Never use ReportLab's default margins (too tight). Always set explicitly.
+
+---
+
+## Cover design
+
+The cover is the most important page. It determines whether a reader trusts the document.
+
+### Thirteen cover patterns
+
+`cover.py` selects one based on `tokens.json["cover_pattern"]`.
+
+**1. `fullbleed`** — used for: `report`, `general`
+- Deep background fills 100% of page
+- Title: large, left-aligned, upper 60% of page
+- Accent: thin horizontal rule + top-right corner strip
+- Dot-grid background texture (subtle, 8–10% opacity)
+- Footer band: author + date metadata
+- Fonts: Playfair Display / IBM Plex Sans
+
+**2. `split`** — used for: `proposal`
+- Left 42% panel: solid cover color, title + author
+- Right 58%: off-white, dot-grid decoration
+- Hard vertical dividing line in accent color
+- No gradients — pure flat geometry
+- Fonts: Syne / Nunito Sans
+
+**3. `typographic`** — used for: `resume`, `academic`
+- White/off-white background
+- Name or title as oversized display type (60–80pt), left-aligned
+- First word in accent color, remainder in dark
+- Thin rule below title block
+- Fonts: DM Serif Display / DM Sans (resume) · EB Garamond / Source Sans 3 (academic)
+
+**4. `atmospheric`** — used for: `portfolio`
+- Near-black background
+- Soft radial glow in accent color (upper-right quadrant)
+- Title centered-left, 2 lines max
+- Short rule in accent below title
+- Dot-grid texture at low opacity
+- Fonts: Fraunces / Inter
+
+**5. `minimal`** — used for: `minimal`
+- Near-white background, 8px left accent bar is the only color
+- Title in very large, light-weight display type (300 weight)
+- Hairline rule, author + date as single muted line
+- Nothing else — the bar does all the visual work
+- Fonts: Cormorant Garamond / Jost
+
+**6. `stripe`** — used for: `stripe`
+- Page cut into three horizontal bands: accent / dark / light
+- Top band: category label; middle: oversized title in white; bottom: metadata
+- Hard edges, no gradients, no textures — newspaper / brand poster aesthetic
+- Fonts: Barlow Condensed / Barlow
+
+**7. `diagonal`** — used for: `diagonal`
+- SVG polygon cuts page diagonally: dark upper-left, light lower-right
+- Accent-colored edge line traces the diagonal cut
+- Title on dark area, metadata on light area
+- Fonts: Montserrat / Montserrat
+
+**8. `frame`** — used for: `frame`
+- White/cream background with an inset rectangular border (1.2px, 28px from edges)
+- Accent strips inside top + bottom of frame; small accent corner squares
+- Title centered in the frame space, centered alignment, classical weight
+- Formal, timeless — annual reports, legal documents, academic papers
+- Fonts: Cormorant / Crimson Pro
+
+**9. `editorial`** — used for: `editorial`
+- Ghost first-letter of title fills upper-right at 5% opacity — visual texture
+- 5px accent top bar; full-width uppercase title in condensed weight
+- Title all-caps, very large (80px), flush-left
+- Footer rule + author/date metadata
+- Fonts: Bebas Neue / Libre Franklin
+
+**10. `magazine`** — used for: `magazine`
+- Warm cream/linen background; fully centered, vertical stack layout
+- Org/company name in small spaced caps + 2px accent rule beneath (top anchor)
+- Large bold serif title (52px) centered; short accent rule under title
+- Italic subtitle; optional `cover_image` URL renders as centered hero thumbnail
+- Optional `abstract` field: justified text block with bold "Abstract:" label
+- Author name in accent color (large, bold); date beneath
+- Fonts: Playfair Display / EB Garamond
+
+**11. `darkroom`** — used for: `darkroom`
+- Same centered stack layout as `magazine` but deep navy background, white text
+- Org name + rules in semi-transparent white; accent rules desaturated
+- Hero image (if provided) gets `grayscale(20%) brightness(0.9)` filter
+- Fonts: Playfair Display / EB Garamond
+
+**12. `terminal`** — used for: `terminal`
+- Near-black background; neon green accent; Space Mono monospace throughout
+- Grid overlay: faint horizontal + vertical lines at 48px intervals (7% opacity)
+- Status label top-left: green dot + `SYSTEM_REPORT // <date>`
+- Title inside a bracket frame (border-left + border-top + pseudo-element corner)
+- Subtitle prefixed with `>` in accent color
+- Abstract text left; author block right; status bar at bottom (UTF-8 / Ln 1)
+- Fonts: Space Mono / Space Mono
+
+**13. `poster`** — used for: `poster`
+- White background; thick 52px left sidebar in accent (typically near-black)
+- Title: 96px, 900-weight, all-caps, condensed — the dominant visual element
+- Subtitle in typewriter font below title; thin 2px rule as separator
+- Author + meta in Courier Prime monospace beneath rule
+- Optional `cover_image` rendered as 260×340 grayscale thumbnail, right-aligned
+- Accent square icon block (lower-right) with white horizontal lines
+- Fonts: Barlow Condensed / Courier Prime
+
+### Optional token: `cover_image`
+
+Patterns `magazine`, `darkroom`, and `poster` accept an optional `cover_image`
+token containing an absolute URL or `file://` path to an image.
+The image renders via `<img src="...">` — Playwright fetches it at render time.
+If omitted, the image area is simply skipped (layout adjusts gracefully).
+
+### Cover CSS requirements (critical for Playwright rendering)
+
+These three rules must appear in every cover HTML file or the output will have
+white borders / incorrect dimensions:
+
+```css
+body { margin: 0; padding: 0; }
+html, body { width: 794px; height: 1123px; overflow: hidden; }
+```
+
+No `@page` rules needed — Playwright handles page size via the `pdf()` call.
+Do NOT use CSS `background-image` for textures — use inline SVG or `<canvas>`.
+Always use `position: absolute` + `z-index` for layered elements.
+
+### What always kills a cover
+
+- Centered title on white background with a thin horizontal line underneath
+- Gradient from one color to another (reads as PowerPoint, not print design)
+- Drop shadows on text
+- More than one accent color
+- Emoji or icon fonts (fail silently on headless Chromium)
+
+---
+
+## Inner page rules
+
+### What "restraint" means in practice
+
+Every design decision should remove something, not add something.
+The page is done when there is nothing left to remove.
+
+- Accent color appears on section rules only — not on headings, not on bullets
+- No card components (bordered boxes with colored headers)
+- No rounded corners on anything except callout boxes (4px max)
+- No shadows anywhere
+- Tables: header row in accent, alternating row tint, no grid lines except outer box
+- Callout boxes: left border in accent (4px), very light tint background, no icon
+
+### Page header / footer
+
+Header: document title (left, 7.5pt, muted) + accent rule (1.5pt, full width below)
+Footer: author name (left, 7.5pt, muted) + page number (right, 7.5pt, muted) + light rule above
+
+---
+
+## Quality bar
+
+A PDF passes if a designer would not be embarrassed to hand it to a client.
+Concretely:
+
+- Cover has a clear visual identity that is not "generic AI output"
+- Body text is readable at arm's length without squinting
+- Every page looks like it belongs to the same document
+- No element bleeds off the edge or overlaps another
+- Page numbers are present and correct
+- The accent color appears fewer than 8 times per page on average
+
+---
+
+## Block type reference
+
+All body blocks use the same token system — colors and fonts come from `tokens.json`, never hardcoded.
+
+| Block | Rendering | Design notes |
+|---|---|---|
+| `h1` | 22pt heading + full-width accent rule below | KeepTogether with rule — heading never orphaned |
+| `h2` | 15pt heading, dark text | No rule, no accent — visual hierarchy through size only |
+| `h3` | 11.5pt bold, dark text | **No accent color** — accent on body headings violates the one-accent-location rule |
+| `body` | 10.5pt justified, 17pt leading | Supports `<b>` `<i>` `<font>` markup |
+| `bullet` | Body size with `•` prefix, 14pt indent | Use for unordered lists |
+| `numbered` | Body size with `N.` prefix, hanging indent | Counter auto-resets on any non-numbered block — no manual numbering needed |
+| `callout` | Accent left-border (4px) + light tint background | Max one callout per section — overuse kills impact |
+| `table` | Accent header row, alternating row tint, outer box only | Supports `col_widths` (fractions, e.g. `[0.3, 0.5, 0.2]`) for custom column widths |
+| `image` | Scaled to column width, preserving aspect ratio | Use `path` or `src`; always provide a `caption` |
+| `figure` | Same as image, but caption auto-prefixed "Figure N:" | Figure counter increments across all `figure`, `chart`, `flowchart` blocks |
+| `code` | Courier 8.5pt, accent left-border, light tint background | Supports optional `language` label (rendered above block) |
+| `math` | Formula centered, optional right-aligned equation label | LaTeX syntax; matplotlib mathtext renderer |
+| `chart` | Bar / line / pie chart rendered via matplotlib | Color palette derived from document accent; figure auto-numbered |
+| `flowchart` | Process diagram with labeled arrows | Supports 4 node shapes; back-edges drawn as curved arcs |
+| `bibliography` | Numbered reference list with hanging indent | Heading rendered as h2 + accent rule; items as `[N] text` |
+| `divider` | Accent-colored 1.2pt rule with padding | Use sparingly — only for major thematic breaks |
+| `caption` | 8.5pt muted text, centered | Appears below images/tables via field or explicit block |
+| `pagebreak` | Force page break | — |
+| `spacer` | Vertical whitespace | `pt` field (default 12) |
+
+### Math formula guidance
+
+**Input syntax:** standard LaTeX math notation — `\frac{}{}`, `\int`, `\sum`, `\alpha`, `^`, `_`, etc.
+**Rendering engine:** matplotlib mathtext — pure Python, no LaTeX compiler, no browser required.
+
+| Syntax example | Rendered as |
+|---|---|
+| `E = mc^2` | Inline expression |
+| `\frac{\sqrt{\pi}}{2}` | Fraction |
+| `\int_0^\infty e^{-x^2} dx` | Integral |
+| `\sum_{i=1}^{n} x_i` | Summation |
+| `\alpha + \beta = \gamma` | Greek letters |
+
+**Limitations:** matplotlib mathtext covers most common expressions but not advanced LaTeX environments (`align`, `cases`, `matrix`). Split complex multi-line proofs into multiple `math` blocks.
+
+**Fallback:** if matplotlib is not installed, renders as `expression` in code style. Run `make.sh fix` to install.
+
+**Equation labels:** `"label": "(1)"` — rendered right-aligned beside the formula.
+
+### Chart guidance
+
+**Rendered entirely in Python** — no external chart services, image files, or internet required.
+
+| chart_type | Use case | Required fields |
+|---|---|---|
+| `bar` | Comparing discrete categories | `labels`, `datasets` |
+| `line` | Trends over time or ordered categories | `labels`, `datasets` |
+| `pie` | Part-to-whole composition | `labels`, `datasets[0].values` |
+
+- Colors are derived from the document accent for visual consistency — do not set custom colors.
+- Multi-series: add multiple objects to `datasets`, each with a `label` and `values` array.
+- Figure auto-numbering: set `"figure": true` (default) or `"figure": false` to suppress.
+
+### Flowchart guidance
+
+**Node shapes:**
+
+| shape | Use for |
+|---|---|
+| `rect` (default) | Process step |
+| `diamond` | Decision / condition |
+| `oval` or `terminal` | Start / End |
+| `parallelogram` | Input / Output |
+
+- Nodes are placed in input order (top to bottom). This controls the layout.
+- Forward edges draw straight arrows; back-edges (to earlier nodes) draw curved arcs.
+- Keep labels short (3–5 words max) — the diagram is A4-column-width at 78% scale.
+- Figure auto-numbering applies same as chart.
+
+### Bibliography guidance
+
+- `id` field is the reference label — use numbers ("1", "2") or alphanumeric ("Smith23").
+- Text should be in a consistent citation style (APA, Chicago, etc.) — the renderer does not enforce style.
+- The `title` field defaults to "References". Set `"title": ""` to suppress the heading.
+- A `bibliography` block always starts with a new section heading + accent rule.
+
+### Image / figure guidance
+
+- Preferred formats: PNG, JPEG
+- Scaled down if wider than the text column; never scaled up
+- `figure` blocks auto-number; `image` blocks do not — use `figure` for numbered figures
+- If the file does not exist at render time, a `[Image not found]` placeholder is substituted
+
+### Code block guidance
+
+- Preserves whitespace exactly — do not indent code in the JSON value
+- Optional `language` field renders a small language label above the block (e.g., `"language": "python"`)
+- No syntax highlighting (by design) — consistent with restraint principle
+- Keep lines under ~90 characters for A4 column width
diff --git a/builtin-skills/document-process/minimax-xlsx/SKILL.md b/builtin-skills/document-process/minimax-xlsx/SKILL.md
new file mode 100644
index 00000000..0d02cebc
--- /dev/null
+++ b/builtin-skills/document-process/minimax-xlsx/SKILL.md
@@ -0,0 +1,138 @@
+---
+name: minimax-xlsx
+description: "Open, create, read, analyze, edit, or validate Excel/spreadsheet files (.xlsx, .xlsm, .csv, .tsv). Use when the user asks to create, build, modify, analyze, read, validate, or format any Excel spreadsheet, financial model, pivot table, or tabular data file. Covers: creating new xlsx from scratch, reading and analyzing existing files, editing existing xlsx with zero format loss, formula recalculation and validation, and applying professional financial formatting standards. Triggers on 'spreadsheet', 'Excel', '.xlsx', '.csv', 'pivot table', 'financial model', 'formula', or any request to produce tabular data in Excel format."
+license: MIT
+metadata:
+  version: "1.0"
+  category: productivity
+  sources:
+    - ECMA-376 Office Open XML File Formats
+    - Microsoft Open XML SDK documentation
+---
+
+# MiniMax XLSX Skill
+
+Handle the request directly. Do NOT spawn sub-agents. Always write the output file the user requests.
+
+## Task Routing
+
+| Task | Method | Guide |
+|------|--------|-------|
+| **READ** — analyze existing data | `xlsx_reader.py` + pandas | `references/read-analyze.md` |
+| **CREATE** — new xlsx from scratch | XML template | `references/create.md` + `references/format.md` |
+| **EDIT** — modify existing xlsx | XML unpack→edit→pack | `references/edit.md` (+ `format.md` if styling needed) |
+| **FIX** — repair broken formulas in existing xlsx | XML unpack→fix `<f>` nodes→pack | `references/fix.md` |
+| **VALIDATE** — check formulas | `formula_check.py` | `references/validate.md` |
+
+## READ — Analyze data (read `references/read-analyze.md` first)
+
+Start with `xlsx_reader.py` for structure discovery, then pandas for custom analysis. Never modify the source file.
+
+**Formatting rule**: When the user specifies decimal places (e.g. "2 decimal places"), apply that format to ALL numeric values — use `f'{v:.2f}'` on every number. Never output `12875` when `12875.00` is required.
+
+**Aggregation rule**: Always compute sums/means/counts directly from the DataFrame column — e.g. `df['Revenue'].sum()`. Never re-derive column values before aggregation.
+
+## CREATE — XML template (read `references/create.md` + `references/format.md`)
+
+Copy `templates/minimal_xlsx/` → edit XML directly → pack with `xlsx_pack.py`. Every derived value MUST be an Excel formula (`<f>SUM(B2:B9)</f>`), never a hardcoded number. Apply font colors per `format.md`.
+
+## EDIT — XML direct-edit (read `references/edit.md` first)
+
+**CRITICAL — EDIT INTEGRITY RULES:**
+1. **NEVER create a new `Workbook()`** for edit tasks. Always load the original file.
+2. The output MUST contain the **same sheets** as the input (same names, same data).
+3. Only modify the specific cells the task asks for — everything else must be untouched.
+4. **After saving output.xlsx, verify it**: open with `xlsx_reader.py` or `pandas` and confirm the original sheet names and a sample of original data are present. If verification fails, you wrote the wrong file — fix it before delivering.
+
+Never use openpyxl round-trip on existing files (corrupts VBA, pivots, sparklines). Instead: unpack → use helper scripts → repack.
+
+**"Fill cells" / "Add formulas to existing cells" = EDIT task.** If the input file already exists and you are told to fill, update, or add formulas to specific cells, you MUST use the XML edit path. Never create a new `Workbook()`. Example — fill B3 with a cross-sheet SUM formula:
+```bash
+python3 SKILL_DIR/scripts/xlsx_unpack.py input.xlsx /tmp/xlsx_work/
+# Find the target sheet's XML via xl/workbook.xml → xl/_rels/workbook.xml.rels
+# Then use the Edit tool to add <f> inside the target <c> element:
+#   <c r="B3"><f>SUM('Sales Data'!D2:D13)</f><v></v></c>
+python3 SKILL_DIR/scripts/xlsx_pack.py /tmp/xlsx_work/ output.xlsx
+```
+
+**Add a column** (formulas, numfmt, styles auto-copied from adjacent column):
+```bash
+python3 SKILL_DIR/scripts/xlsx_unpack.py input.xlsx /tmp/xlsx_work/
+python3 SKILL_DIR/scripts/xlsx_add_column.py /tmp/xlsx_work/ --col G \
+    --sheet "Sheet1" --header "% of Total" \
+    --formula '=F{row}/$F$10' --formula-rows 2:9 \
+    --total-row 10 --total-formula '=SUM(G2:G9)' --numfmt '0.0%' \
+    --border-row 10 --border-style medium
+python3 SKILL_DIR/scripts/xlsx_pack.py /tmp/xlsx_work/ output.xlsx
+```
+The `--border-row` flag applies a top border to ALL cells in that row (not just the new column). Use it when the task requires accounting-style borders on total rows.
+
+**Insert a row** (shifts existing rows, updates SUM formulas, fixes circular refs):
+```bash
+python3 SKILL_DIR/scripts/xlsx_unpack.py input.xlsx /tmp/xlsx_work/
+# IMPORTANT: Find the correct --at row by searching for the label text
+# in the worksheet XML, NOT by using the row number from the prompt.
+# The prompt may say "row 5 (Office Rent)" but Office Rent might actually
+# be at row 4. Always locate the row by its text label first.
+python3 SKILL_DIR/scripts/xlsx_insert_row.py /tmp/xlsx_work/ --at 5 \
+    --sheet "Budget FY2025" --text A=Utilities \
+    --values B=3000 C=3000 D=3500 E=3500 \
+    --formula 'F=SUM(B{row}:E{row})' --copy-style-from 4
+python3 SKILL_DIR/scripts/xlsx_pack.py /tmp/xlsx_work/ output.xlsx
+```
+**Row lookup rule**: When the task says "after row N (Label)", always find the row by searching for "Label" in the worksheet XML (`grep -n "Label" /tmp/xlsx_work/xl/worksheets/sheet*.xml` or check sharedStrings.xml). Use the actual row number + 1 for `--at`. Do NOT call `xlsx_shift_rows.py` separately — `xlsx_insert_row.py` calls it internally.
+
+**Apply row-wide borders** (e.g. accounting line on a TOTAL row):
+After running helper scripts, apply borders to ALL cells in the target row, not just newly added cells. In `xl/styles.xml`, append a new `<border>` with the desired style, then append a new `<xf>` in `<cellXfs>` that clones each cell's existing `<xf>` but sets the new `borderId`. Apply the new style index to every `<c>` in the row via the `s` attribute:
+```xml
+<!-- In xl/styles.xml, append to <borders>: -->
+<border>
+  <left/><right/><top style="medium"/><bottom/><diagonal/>
+</border>
+<!-- Then append to <cellXfs> an xf clone with the new borderId for each existing style -->
+```
+**Key rule**: When a task says "add a border to row N", iterate over ALL cells A through the last column, not just newly added cells.
+
+**Manual XML edit** (for anything the helper scripts don't cover):
+```bash
+python3 SKILL_DIR/scripts/xlsx_unpack.py input.xlsx /tmp/xlsx_work/
+# ... edit XML with the Edit tool ...
+python3 SKILL_DIR/scripts/xlsx_pack.py /tmp/xlsx_work/ output.xlsx
+```
+
+## FIX — Repair broken formulas (read `references/fix.md` first)
+
+This is an EDIT task. Unpack → fix broken `<f>` nodes → pack. Preserve all original sheets and data.
+
+## VALIDATE — Check formulas (read `references/validate.md` first)
+
+Run `formula_check.py` for static validation. Use `libreoffice_recalc.py` for dynamic recalculation when available.
+
+## Financial Color Standard
+
+| Cell Role | Font Color | Hex Code |
+|-----------|-----------|----------|
+| Hard-coded input / assumption | Blue | `0000FF` |
+| Formula / computed result | Black | `000000` |
+| Cross-sheet reference formula | Green | `00B050` |
+
+## Key Rules
+
+1. **Formula-First**: Every calculated cell MUST use an Excel formula, not a hardcoded number
+2. **CREATE → XML template**: Copy minimal template, edit XML directly, pack with `xlsx_pack.py`
+3. **EDIT → XML**: Never openpyxl round-trip. Use unpack/edit/pack scripts
+4. **Always produce the output file** — this is the #1 priority
+5. **Validate before delivery**: `formula_check.py` exit code 0 = safe
+
+## Utility Scripts
+
+```bash
+python3 SKILL_DIR/scripts/xlsx_reader.py input.xlsx                 # structure discovery
+python3 SKILL_DIR/scripts/formula_check.py file.xlsx --json         # formula validation
+python3 SKILL_DIR/scripts/formula_check.py file.xlsx --report      # standardized report
+python3 SKILL_DIR/scripts/xlsx_unpack.py in.xlsx /tmp/work/         # unpack for XML editing
+python3 SKILL_DIR/scripts/xlsx_pack.py /tmp/work/ out.xlsx          # repack after editing
+python3 SKILL_DIR/scripts/xlsx_shift_rows.py /tmp/work/ insert 5 1  # shift rows for insertion
+python3 SKILL_DIR/scripts/xlsx_add_column.py /tmp/work/ --col G ... # add column with formulas
+python3 SKILL_DIR/scripts/xlsx_insert_row.py /tmp/work/ --at 6 ...  # insert row with data
+```
diff --git a/builtin-skills/document-process/minimax-xlsx/references/create.md b/builtin-skills/document-process/minimax-xlsx/references/create.md
new file mode 100644
index 00000000..8dd42bec
--- /dev/null
+++ b/builtin-skills/document-process/minimax-xlsx/references/create.md
@@ -0,0 +1,691 @@
+# Build New xlsx from Scratch
+
+Create new, production-quality xlsx files using the XML approach. NEVER use openpyxl
+for writing. NEVER hardcode Python-computed values — every derived number must be a
+live Excel formula.
+
+---
+
+## When to Use This Path
+
+Use this document when the user wants:
+- A brand-new Excel file that does not yet exist
+- A generated report, financial model, or data table
+- Any "create / build / generate / make" request
+
+If the user provides an existing file to modify, switch to `edit.md` instead.
+
+---
+
+## The Non-Negotiable Rules
+
+Before touching any file, internalize these four rules:
+
+1. **Formula-First**: Every calculated value (`SUM`, growth rate, ratio, subtotal, etc.)
+   MUST be written as `<f>SUM(B2:B9)</f>`, not as a hardcoded `<v>5000</v>`. Hardcoded
+   numbers go stale when source data changes. Only raw inputs and assumption parameters
+   may be hardcoded values.
+
+2. **No openpyxl for writing**: The entire file is built by editing XML directly. Python
+   is only allowed for reading/analysis (`pandas.read_excel()`) and for running helper
+   scripts (`xlsx_pack.py`, `formula_check.py`).
+
+3. **Style encodes meaning**: Blue font = user input/assumption. Black font = formula
+   result. Green font = cross-sheet reference. See `format.md` for the full color system
+   and style index table.
+
+4. **Validate before delivery**: Run `formula_check.py` and fix all errors before
+   handing the file to the user.
+
+---
+
+## Complete Creation Workflow
+
+### Step 1 — Plan Before Writing
+
+Define the full structure on paper before touching any XML:
+
+- **Sheets**: names, order, purpose (e.g., Assumptions / Model / Summary)
+- **Layout per sheet**: which rows are headers, inputs, formulas, totals
+- **String inventory**: collect all text labels you will need in sharedStrings
+- **Style choices**: what number format each column needs (currency, %, integer, year)
+- **Cross-sheet links**: which sheets pull data from other sheets
+
+This planning step prevents the costly cycle of adding strings to sharedStrings
+mid-way and recomputing all indices.
+
+---
+
+### Step 2 — Copy Minimal Template
+
+```bash
+cp -r SKILL_DIR/templates/minimal_xlsx/ /tmp/xlsx_work/
+```
+
+The template gives you a complete, valid 7-file xlsx skeleton:
+
+```
+/tmp/xlsx_work/
+├── [Content_Types].xml        ← MIME type registry
+├── _rels/
+│   └── .rels                  ← root relationship (points to workbook.xml)
+└── xl/
+    ├── workbook.xml            ← sheet list and calc settings
+    ├── styles.xml              ← 13 pre-built financial style slots
+    ├── sharedStrings.xml       ← text string table (starts empty)
+    ├── _rels/
+    │   └── workbook.xml.rels  ← maps rId → file paths
+    └── worksheets/
+        └── sheet1.xml          ← one empty sheet
+```
+
+After copying, rename sheets and add content. Do not create files from scratch —
+always start from the template.
+
+---
+
+### Step 3 — Configure Sheet Structure
+
+#### Single-Sheet Workbook
+
+The template already has one sheet named "Sheet1". Just change the `name` attribute
+in `xl/workbook.xml`:
+
+```xml
+<sheets>
+  <sheet name="Revenue Model" sheetId="1" r:id="rId1"/>
+</sheets>
+```
+
+No other files need to change for a single-sheet workbook.
+
+#### Multi-Sheet Workbook
+
+Four files must be kept in sync. Work through them in this order:
+
+**IMPORTANT — rId collision rule**: In the template's `workbook.xml.rels`, the IDs
+`rId1`, `rId2`, and `rId3` are already taken:
+- `rId1` → `worksheets/sheet1.xml`
+- `rId2` → `styles.xml`
+- `rId3` → `sharedStrings.xml`
+
+New worksheet entries MUST start at `rId4` and count upward.
+
+**File 1 of 4 — `xl/workbook.xml`** (sheet list):
+
+```xml
+<sheets>
+  <sheet name="Assumptions" sheetId="1" r:id="rId1"/>
+  <sheet name="Model"       sheetId="2" r:id="rId4"/>
+  <sheet name="Summary"     sheetId="3" r:id="rId5"/>
+</sheets>
+```
+
+Special characters in sheet names:
+- `&` → `&amp;` in XML: `<sheet name="P&amp;L" .../>`
+- Max 31 characters
+- Forbidden: `/ \ ? * [ ] :`
+- Sheet names with spaces need single quotes in formula references: `'Q1 Data'!B5`
+
+**File 2 of 4 — `xl/_rels/workbook.xml.rels`** (ID → file mapping):
+
+```xml
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1"
+    Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet"
+    Target="worksheets/sheet1.xml"/>
+  <Relationship Id="rId2"
+    Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles"
+    Target="styles.xml"/>
+  <Relationship Id="rId3"
+    Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings"
+    Target="sharedStrings.xml"/>
+  <Relationship Id="rId4"
+    Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet"
+    Target="worksheets/sheet2.xml"/>
+  <Relationship Id="rId5"
+    Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet"
+    Target="worksheets/sheet3.xml"/>
+</Relationships>
+```
+
+**File 3 of 4 — `[Content_Types].xml`** (MIME type declarations):
+
+```xml
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+  <Default Extension="xml"  ContentType="application/xml"/>
+  <Override PartName="/xl/workbook.xml"
+    ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>
+  <Override PartName="/xl/worksheets/sheet1.xml"
+    ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>
+  <Override PartName="/xl/worksheets/sheet2.xml"
+    ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>
+  <Override PartName="/xl/worksheets/sheet3.xml"
+    ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>
+  <Override PartName="/xl/styles.xml"
+    ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>
+  <Override PartName="/xl/sharedStrings.xml"
+    ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml"/>
+</Types>
+```
+
+**File 4 of 4 — Create new worksheet XML files**
+
+Copy `sheet1.xml` to `sheet2.xml` and `sheet3.xml`, then clear the `<sheetData>` content:
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<worksheet
+  xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+  xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+  <sheetViews>
+    <sheetView workbookViewId="0"/>
+  </sheetViews>
+  <sheetFormatPr defaultRowHeight="15" x14ac:dyDescent="0.25"
+    xmlns:x14ac="http://schemas.microsoft.com/office/spreadsheetml/2009/9/ac"/>
+  <sheetData>
+    <!-- Data rows go here -->
+  </sheetData>
+  <pageMargins left="0.7" right="0.7" top="0.75" bottom="0.75" header="0.3" footer="0.3"/>
+</worksheet>
+```
+
+**Sync checklist** — every time you add a sheet, verify all four are consistent:
+
+| Check | What to verify |
+|-------|---------------|
+| `workbook.xml` | New `<sheet name="..." sheetId="N" r:id="rIdX"/>` exists |
+| `workbook.xml.rels` | New `<Relationship Id="rIdX" ... Target="worksheets/sheetN.xml"/>` exists |
+| `[Content_Types].xml` | New `<Override PartName="/xl/worksheets/sheetN.xml" .../>` exists |
+| Filesystem | `xl/worksheets/sheetN.xml` file actually exists |
+
+---
+
+### Step 4 — Populate sharedStrings
+
+All text values (headers, row labels, category names, any string the user will read)
+must be stored in `xl/sharedStrings.xml`. Cells reference them by 0-based index.
+
+**Recommended workflow**: collect ALL text you need first, write the complete table once,
+then fill in indices while writing worksheet XML. This avoids re-counting indices mid-way.
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<sst xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+     count="10" uniqueCount="10">
+  <si><t>Item</t></si>                  <!-- index 0 -->
+  <si><t>FY2023A</t></si>               <!-- index 1 -->
+  <si><t>FY2024E</t></si>               <!-- index 2 -->
+  <si><t>FY2025E</t></si>               <!-- index 3 -->
+  <si><t>YoY Growth</t></si>            <!-- index 4 -->
+  <si><t>Revenue</t></si>               <!-- index 5 -->
+  <si><t>Cost of Goods Sold</t></si>    <!-- index 6 -->
+  <si><t>Gross Profit</t></si>          <!-- index 7 -->
+  <si><t>EBITDA</t></si>                <!-- index 8 -->
+  <si><t>Net Income</t></si>            <!-- index 9 -->
+</sst>
+```
+
+**Attribute rules**:
+- `uniqueCount` = number of `<si>` elements (unique strings in the table)
+- `count` = total number of cell references to strings across the entire workbook
+  (if "Revenue" appears in 3 sheets, count is `uniqueCount + 2`)
+- For new files where each string appears once, `count == uniqueCount`
+- Both attributes MUST be accurate — wrong values trigger warnings in some Excel versions
+
+**Special character escaping**:
+
+```xml
+<si><t>R&amp;D Expenses</t></si>          <!-- & must be &amp; -->
+<si><t>Revenue &lt; Target</t></si>        <!-- < must be &lt; -->
+<si><t xml:space="preserve">  (note)  </t></si>  <!-- preserve leading/trailing spaces -->
+```
+
+**Helper script**: use `shared_strings_builder.py` to generate the complete
+`sharedStrings.xml` from a plain list of strings:
+
+```bash
+python3 SKILL_DIR/scripts/shared_strings_builder.py \
+  "Item" "FY2024" "FY2025" "Revenue" "Gross Profit" \
+  > /tmp/xlsx_work/xl/sharedStrings.xml
+```
+
+Or interactively from a file listing one string per line:
+
+```bash
+python3 SKILL_DIR/scripts/shared_strings_builder.py --file strings.txt \
+  > /tmp/xlsx_work/xl/sharedStrings.xml
+```
+
+---
+
+### Step 5 — Write Worksheet Data
+
+Edit each `xl/worksheets/sheetN.xml`. Replace the empty `<sheetData>` with rows
+and cells.
+
+#### Cell XML Anatomy
+
+```
+<c r="B5" t="s" s="4">
+      ↑     ↑    ↑
+   address  type  style index (from cellXfs in styles.xml)
+
+  <v>3</v>
+     ↑
+  value (for t="s": sharedStrings index; for numbers: the number itself)
+```
+
+#### Data Type Reference
+
+| Data | `t` attr | XML Example | Notes |
+|------|---------|-------------|-------|
+| Shared string (text) | `s` | `<c r="A1" t="s" s="4"><v>0</v></c>` | `<v>` = sharedStrings index |
+| Number | omit | `<c r="B2" s="5"><v>1000000</v></c>` | default type, `t` omitted |
+| Percentage (as decimal) | omit | `<c r="C2" s="7"><v>0.125</v></c>` | 12.5% stored as 0.125 |
+| Boolean | `b` | `<c r="D1" t="b"><v>1</v></c>` | 1=TRUE, 0=FALSE |
+| Formula | omit | `<c r="B4" s="2"><f>SUM(B2:B3)</f><v></v></c>` | `<v>` left empty |
+| Cross-sheet formula | omit | `<c r="C1" s="3"><f>Assumptions!B2</f><v></v></c>` | use s=3 (green) |
+
+#### A Full Sheet Data Example
+
+```xml
+<cols>
+  <col min="1" max="1" width="26" customWidth="1"/>   <!-- A: label column -->
+  <col min="2" max="5" width="14" customWidth="1"/>   <!-- B-E: data columns -->
+</cols>
+<sheetData>
+
+  <!-- Row 1: headers (style 4 = bold header) -->
+  <row r="1" ht="18" customHeight="1">
+    <c r="A1" t="s" s="4"><v>0</v></c>   <!-- "Item" -->
+    <c r="B1" t="s" s="4"><v>1</v></c>   <!-- "FY2023A" -->
+    <c r="C1" t="s" s="4"><v>2</v></c>   <!-- "FY2024E" -->
+    <c r="D1" t="s" s="4"><v>3</v></c>   <!-- "FY2025E" -->
+    <c r="E1" t="s" s="4"><v>4</v></c>   <!-- "YoY Growth" -->
+  </row>
+
+  <!-- Row 2: Revenue — actual value (input) + formula (computed) -->
+  <row r="2">
+    <c r="A2" t="s" s="1"><v>5</v></c>    <!-- "Revenue", blue input label -->
+    <c r="B2" s="5"><v>85000000</v></c>   <!-- FY2023A actual: $85M, currency input -->
+    <c r="C2" s="6"><f>B2*(1+Assumptions!C3)</f><v></v></c>   <!-- formula, currency -->
+    <c r="D2" s="6"><f>C2*(1+Assumptions!D3)</f><v></v></c>
+    <c r="E2" s="8"><f>D2/C2-1</f><v></v></c>   <!-- YoY growth, percentage formula -->
+  </row>
+
+  <!-- Row 3: Gross Profit -->
+  <row r="3">
+    <c r="A3" t="s" s="2"><v>7</v></c>    <!-- "Gross Profit", black formula label -->
+    <c r="B3" s="6"><f>B2*Assumptions!B4</f><v></v></c>
+    <c r="C3" s="6"><f>C2*Assumptions!C4</f><v></v></c>
+    <c r="D3" s="6"><f>D2*Assumptions!D4</f><v></v></c>
+    <c r="E3" s="8"><f>D3/C3-1</f><v></v></c>
+  </row>
+
+  <!-- Row 5: SUM total row -->
+  <row r="5">
+    <c r="A5" t="s" s="4"><v>8</v></c>    <!-- "EBITDA" -->
+    <c r="B5" s="6"><f>SUM(B2:B4)</f><v></v></c>
+    <c r="C5" s="6"><f>SUM(C2:C4)</f><v></v></c>
+    <c r="D5" s="6"><f>SUM(D2:D4)</f><v></v></c>
+    <c r="E5" s="8"><f>D5/C5-1</f><v></v></c>
+  </row>
+
+</sheetData>
+```
+
+#### Column Width and Freeze Pane
+
+Column widths go **before** `<sheetData>`, freeze pane goes inside `<sheetView>`:
+
+```xml
+<!-- Inside <sheetViews><sheetView ...> — freeze the header row -->
+<pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/>
+
+<!-- Before <sheetData> — set column widths -->
+<cols>
+  <col min="1" max="1" width="28" customWidth="1"/>
+  <col min="2" max="8" width="14" customWidth="1"/>
+</cols>
+```
+
+---
+
+### Step 6 — Apply Styles
+
+The template's `xl/styles.xml` has 13 pre-built semantic style slots (indices 0–12).
+**Read `format.md` for the complete style index table, color system, and how to add new styles.**
+
+Quick reference for the most common slots:
+
+| `s` | Role | Example |
+|-----|------|---------|
+| 4 | Header (bold) | Column/row titles |
+| 5 / 6 | Currency input (blue) / formula (black) | `$#,##0` |
+| 7 / 8 | Percentage input / formula | `0.0%` |
+| 11 | Year (no comma) | 2024 not 2,024 |
+
+Design principle: Blue = human sets this. Black = Excel computes this. Green = cross-sheet.
+
+If you need a style not in the 13 pre-built slots, follow the append-only procedure in `format.md` section 3.2.
+
+---
+
+### Step 7 — Formula Cookbook
+
+#### XML Formula Syntax Reminder
+
+Formulas in XML have **no leading `=`**:
+
+```xml
+<!-- Excel UI: =SUM(B2:B9)   →   XML: -->
+<c r="B10" s="6"><f>SUM(B2:B9)</f><v></v></c>
+```
+
+#### Basic Aggregations
+
+```xml
+<c r="B10" s="6"><f>SUM(B2:B9)</f><v></v></c>
+<c r="B11" s="6"><f>AVERAGE(B2:B9)</f><v></v></c>
+<c r="B12" s="10"><f>COUNT(B2:B9)</f><v></v></c>
+<c r="B13" s="10"><f>COUNTA(A2:A100)</f><v></v></c>
+<c r="B14" s="6"><f>MAX(B2:B9)</f><v></v></c>
+<c r="B15" s="6"><f>MIN(B2:B9)</f><v></v></c>
+```
+
+#### Financial Calculations
+
+```xml
+<!-- YoY growth rate: current / prior - 1 -->
+<c r="E5" s="8"><f>D5/C5-1</f><v></v></c>
+
+<!-- Gross profit: revenue × gross margin -->
+<c r="B6" s="6"><f>B4*B3</f><v></v></c>
+
+<!-- EBITDA margin: EBITDA / Revenue -->
+<c r="B9" s="8"><f>B8/B4</f><v></v></c>
+
+<!-- Suppress #DIV/0! when denominator may be zero -->
+<c r="E5" s="8"><f>IF(C5=0,0,D5/C5-1)</f><v></v></c>
+
+<!-- NPV and IRR (cash flows in B2:B7, discount rate in B1) -->
+<c r="C1" s="6"><f>NPV(B1,B3:B7)+B2</f><v></v></c>
+<c r="C2" s="8"><f>IRR(B2:B7)</f><v></v></c>
+```
+
+#### Cross-Sheet References
+
+```xml
+<!-- No spaces in name: no quotes needed -->
+<c r="B3" s="3"><f>Assumptions!B5</f><v></v></c>
+
+<!-- Space in sheet name: single quotes required -->
+<c r="B3" s="3"><f>'Q1 Data'!B5</f><v></v></c>
+
+<!-- Ampersand in sheet name (XML-escaped in workbook.xml, but in formula: literal &) -->
+<c r="B3" s="3"><f>'R&amp;D'!B5</f><v></v></c>
+
+<!-- Cross-sheet range: SUM of a range in another sheet -->
+<c r="B10" s="6"><f>SUM(Data!C2:C1000)</f><v></v></c>
+
+<!-- 3D reference: sum same cell across multiple sheets -->
+<c r="B5" s="6"><f>SUM(Jan:Dec!B5)</f><v></v></c>
+```
+
+Cross-sheet formula cells should use `s="3"` (green) to signal the data origin.
+
+#### Shared Formulas (Same Pattern Repeated Down a Column)
+
+When many consecutive cells share the same formula structure with only the row number
+changing, use shared formulas to keep the XML compact:
+
+```xml
+<!-- D2: defines the shared group (si="0", ref="D2:D11") -->
+<c r="D2" s="8"><f t="shared" ref="D2:D11" si="0">C2/B2-1</f><v></v></c>
+
+<!-- D3 through D11: reference the same group, no formula text needed -->
+<c r="D3" s="8"><f t="shared" si="0"/><v></v></c>
+<c r="D4" s="8"><f t="shared" si="0"/><v></v></c>
+<c r="D5" s="8"><f t="shared" si="0"/><v></v></c>
+<c r="D6" s="8"><f t="shared" si="0"/><v></v></c>
+<c r="D7" s="8"><f t="shared" si="0"/><v></v></c>
+<c r="D8" s="8"><f t="shared" si="0"/><v></v></c>
+<c r="D9" s="8"><f t="shared" si="0"/><v></v></c>
+<c r="D10" s="8"><f t="shared" si="0"/><v></v></c>
+<c r="D11" s="8"><f t="shared" si="0"/><v></v></c>
+```
+
+Excel adjusts relative references automatically (D3 computes `C3/B3-1`, etc.).
+If you have multiple shared formula groups, assign sequential `si` values (0, 1, 2, …).
+
+#### Absolute References
+
+```xml
+<!-- $B$2 locks to that cell when the formula is copied -->
+<c r="C5" s="8"><f>B5/$B$2</f><v></v></c>
+```
+
+The `$` character needs no XML escaping — write it literally.
+
+#### Lookup Formulas
+
+```xml
+<!-- VLOOKUP: exact match (last arg 0) -->
+<c r="C5" s="6"><f>VLOOKUP(A5,Assumptions!A:C,2,0)</f><v></v></c>
+
+<!-- INDEX/MATCH: more flexible -->
+<c r="C5" s="6"><f>INDEX(B:B,MATCH(A5,A:A,0))</f><v></v></c>
+
+<!-- XLOOKUP (Excel 2019+) -->
+<c r="C5" s="6"><f>XLOOKUP(A5,A:A,B:B)</f><v></v></c>
+```
+
+---
+
+### Step 8 — Pack and Validate
+
+**Pack**:
+
+```bash
+python3 SKILL_DIR/scripts/xlsx_pack.py /tmp/xlsx_work/ /path/to/output.xlsx
+```
+
+`xlsx_pack.py` will:
+1. Check that `[Content_Types].xml` exists at the root
+2. Parse every `.xml` and `.rels` file for well-formedness — abort if any fail
+3. Create the ZIP archive with correct compression
+
+**Validate**:
+
+```bash
+python3 SKILL_DIR/scripts/formula_check.py /path/to/output.xlsx
+```
+
+`formula_check.py` will:
+1. Scan every cell for `<c t="e">` entries (cached error values) — all 7 error types
+2. Extract sheet name references from every `<f>` formula
+3. Verify each referenced sheet exists in `workbook.xml`
+
+Fix every reported error before delivery. Exit code 0 = safe to deliver.
+
+---
+
+## Pre-Delivery Checklist
+
+Run through this list before handing the file to the user:
+
+- [ ] `formula_check.py` reports 0 errors
+- [ ] Every calculated cell has `<f>` — not just `<v>` with a number
+- [ ] `sharedStrings.xml` `count` and `uniqueCount` match actual `<si>` count
+- [ ] Every cell `s` attribute value is in range `0` to `cellXfs count - 1`
+- [ ] Every sheet in `workbook.xml` has a matching entry in `workbook.xml.rels`
+- [ ] Every `worksheets/sheetN.xml` file has a matching `<Override>` in `[Content_Types].xml`
+- [ ] Year columns use `s="11"` (format `0`, no thousands separator)
+- [ ] Cross-sheet reference formulas use `s="3"` (green font)
+- [ ] Assumption inputs use `s="1"` or `s="5"` or `s="7"` (blue font)
+
+---
+
+## Common Mistakes and Fixes
+
+| Mistake | Symptom | Fix |
+|---------|---------|-----|
+| Formula has leading `=` | Cell shows `=SUM(...)` as text | Remove `=` from `<f>` content |
+| sharedStrings `count` not updated | Excel warning or blank cells | Count `<si>` elements, update both `count` and `uniqueCount` |
+| Style index out of range | File corruption / Excel repair | Ensure `s` < `cellXfs count`; append new `<xf>` if needed |
+| New sheet rId conflicts with styles/sharedStrings rId | Sheet missing or styles lost | New sheets use rId4, rId5, … (rId1-3 are reserved in template) |
+| Sheet name has `&` unescaped in XML | XML parse error | Use `&amp;` in `workbook.xml` name attribute |
+| Cross-sheet ref to sheet with space, no quotes | `#REF!` error | Wrap sheet name in single quotes: `'Sheet Name'!B5` |
+| Cross-sheet ref to non-existent sheet | `#REF!` error | Check `workbook.xml` sheet list vs formula |
+| Number stored as text (`t="s"`) | Left-aligned, can't sum | Remove `t` attribute from number cells |
+| Year displayed as `2,024` | Readability issue | Use `s="11"` (numFmtId=1, format `0`) |
+| Hardcoded Python result instead of formula | "Dead table" — won't update | Replace `<v>N</v>` with `<f>formula</f><v></v>` |
+
+---
+
+## Column Letter Reference
+
+| Col # | Letter | Col # | Letter | Col # | Letter |
+|-------|--------|-------|--------|-------|--------|
+| 1 | A | 26 | Z | 27 | AA |
+| 28 | AB | 52 | AZ | 53 | BA |
+| 54 | BB | 78 | BZ | 79 | CA |
+
+Python conversion (use when building formulas programmatically):
+
+```python
+def col_letter(n: int) -> str:
+    """Convert 1-based column number to Excel letter (A, B, ..., Z, AA, AB, ...)."""
+    result = ""
+    while n > 0:
+        n, rem = divmod(n - 1, 26)
+        result = chr(65 + rem) + result
+    return result
+
+def col_number(s: str) -> int:
+    """Convert Excel column letter to 1-based number."""
+    n = 0
+    for c in s.upper():
+        n = n * 26 + (ord(c) - 64)
+    return n
+```
+
+---
+
+## Typical Scenario Walkthroughs
+
+### Scenario A — Three-Year Financial Model (Single Sheet)
+
+Layout: rows 1-12 = Assumptions (blue inputs) / rows 14-30 = Model (black formulas).
+
+```xml
+<!-- sharedStrings.xml (excerpt) -->
+<sst count="8" uniqueCount="8">
+  <si><t>Metric</t></si>           <!-- 0 -->
+  <si><t>FY2023A</t></si>          <!-- 1 -->
+  <si><t>FY2024E</t></si>          <!-- 2 -->
+  <si><t>FY2025E</t></si>          <!-- 3 -->
+  <si><t>Revenue Growth</t></si>   <!-- 4 -->
+  <si><t>Gross Margin</t></si>     <!-- 5 -->
+  <si><t>Revenue</t></si>          <!-- 6 -->
+  <si><t>Gross Profit</t></si>     <!-- 7 -->
+</sst>
+
+<!-- sheet1.xml (excerpt) -->
+<sheetData>
+  <!-- Header -->
+  <row r="1">
+    <c r="A1" t="s" s="4"><v>0</v></c>
+    <c r="B1" t="s" s="4"><v>1</v></c>
+    <c r="C1" t="s" s="4"><v>2</v></c>
+    <c r="D1" t="s" s="4"><v>3</v></c>
+  </row>
+  <!-- Assumptions (rows 2-3) -->
+  <row r="2">
+    <c r="A2" t="s" s="1"><v>4</v></c>    <!-- "Revenue Growth", blue -->
+    <c r="B2" s="7"><v>0</v></c>          <!-- FY2023A: n/a, 0% placeholder -->
+    <c r="C2" s="7"><v>0.12</v></c>       <!-- FY2024E: 12.0% input -->
+    <c r="D2" s="7"><v>0.15</v></c>       <!-- FY2025E: 15.0% input -->
+  </row>
+  <row r="3">
+    <c r="A3" t="s" s="1"><v>5</v></c>    <!-- "Gross Margin", blue -->
+    <c r="B3" s="7"><v>0.45</v></c>
+    <c r="C3" s="7"><v>0.46</v></c>
+    <c r="D3" s="7"><v>0.47</v></c>
+  </row>
+  <!-- Model (rows 14-15) -->
+  <row r="14">
+    <c r="A14" t="s" s="2"><v>6</v></c>      <!-- "Revenue", black -->
+    <c r="B14" s="5"><v>85000000</v></c>     <!-- actual, currency input -->
+    <c r="C14" s="6"><f>B14*(1+C2)</f><v></v></c>
+    <c r="D14" s="6"><f>C14*(1+D2)</f><v></v></c>
+  </row>
+  <row r="15">
+    <c r="A15" t="s" s="2"><v>7</v></c>      <!-- "Gross Profit", black -->
+    <c r="B15" s="6"><f>B14*B3</f><v></v></c>
+    <c r="C15" s="6"><f>C14*C3</f><v></v></c>
+    <c r="D15" s="6"><f>D14*D3</f><v></v></c>
+  </row>
+</sheetData>
+```
+
+### Scenario B — Data + Summary (Two Sheets)
+
+The `Summary` sheet pulls from `Data` using cross-sheet formulas (green, `s="3"`):
+
+```xml
+<!-- Summary/sheet2.xml sheetData excerpt -->
+<sheetData>
+  <row r="1">
+    <c r="A1" t="s" s="4"><v>0</v></c>   <!-- "Metric" -->
+    <c r="B1" t="s" s="4"><v>1</v></c>   <!-- "Value" -->
+  </row>
+  <row r="2">
+    <c r="A2" t="s" s="0"><v>2</v></c>   <!-- "Total Revenue" -->
+    <c r="B2" s="3"><f>SUM(Data!C2:C10000)</f><v></v></c>
+  </row>
+  <row r="3">
+    <c r="A3" t="s" s="0"><v>3</v></c>   <!-- "Deal Count" -->
+    <c r="B3" s="3"><f>COUNTA(Data!A2:A10000)</f><v></v></c>
+  </row>
+  <row r="4">
+    <c r="A4" t="s" s="0"><v>4</v></c>   <!-- "Avg Deal Size" -->
+    <c r="B4" s="3"><f>IF(B3=0,0,B2/B3)</f><v></v></c>
+  </row>
+</sheetData>
+```
+
+### Scenario C — Multi-Department Consolidation
+
+`Consolidated` sheet sums the same cells from multiple department sheets:
+
+```xml
+<!-- Consolidated/sheet4.xml — summing across Dept_Eng and Dept_Mkt -->
+<sheetData>
+  <row r="5">
+    <c r="A5" t="s" s="2"><v>0</v></c>
+    <!-- No spaces in sheet names → no quotes needed -->
+    <c r="B5" s="3"><f>Dept_Engineering!B5+Dept_Marketing!B5</f><v></v></c>
+  </row>
+  <row r="6">
+    <c r="A6" t="s" s="2"><v>1</v></c>
+    <c r="B6" s="3"><f>SUM(Dept_Engineering!B6,Dept_Marketing!B6)</f><v></v></c>
+  </row>
+</sheetData>
+```
+
+---
+
+## What You Must NOT Do
+
+- Do NOT use openpyxl or any Python library to write the final xlsx file
+- Do NOT hardcode any calculated value — use `<f>` formulas for every derived number
+- Do NOT deliver without running `formula_check.py` first
+- Do NOT set a cell's `s` attribute to a value >= `cellXfs count`
+- Do NOT modify an existing `<xf>` entry in `styles.xml` — only append new ones
+- Do NOT add a new sheet without updating all four sync points (workbook.xml,
+  workbook.xml.rels, [Content_Types].xml, actual .xml file)
+- Do NOT assign new worksheet rIds that overlap with rId1, rId2, or rId3 (reserved
+  for sheet1, styles, sharedStrings in the template)
diff --git a/builtin-skills/document-process/minimax-xlsx/references/edit.md b/builtin-skills/document-process/minimax-xlsx/references/edit.md
new file mode 100644
index 00000000..ca709718
--- /dev/null
+++ b/builtin-skills/document-process/minimax-xlsx/references/edit.md
@@ -0,0 +1,684 @@
+# Minimal-Invasive Editing of Existing xlsx
+
+Make precise, surgical changes to existing xlsx files while preserving everything you do not touch: styles, macros, pivot tables, charts, sparklines, named ranges, data validation, conditional formatting, and all other embedded content.
+
+---
+
+## 1. When to Use This Path
+
+Use the edit (unpack → XML edit → pack) path whenever the task involves **modifying an existing xlsx file**:
+
+- Template filling — populating designated input cells with values or formulas
+- Data updates — replacing outdated numbers, text, or dates in a live file
+- Content corrections — fixing wrong values, broken formulas, or mistyped labels
+- Adding new data rows to an existing table
+- Renaming a sheet
+- Applying a new style to specific cells
+
+Do NOT use this path for creating a brand-new workbook from scratch. For that, see `create.md`.
+
+---
+
+## 2. Why openpyxl round-trip Is Forbidden for Existing Files
+
+openpyxl `load_workbook()` followed by `workbook.save()` is a **destructive operation** on any file that contains advanced features. The library silently drops content it does not understand:
+
+| Feature | openpyxl behavior | Consequence |
+|---------|-------------------|-------------|
+| VBA macros (`vbaProject.bin`) | Dropped entirely | All automation is lost; file saved as `.xlsx` not `.xlsm` |
+| Pivot tables (`xl/pivotTables/`) | Dropped | Interactive analysis is destroyed |
+| Slicers | Dropped | Filter UI is lost |
+| Sparklines (`<sparklineGroups>`) | Dropped | In-cell mini-charts disappear |
+| Chart formatting details | Partially lost | Series colors, custom axes may revert |
+| Print area / page breaks | Sometimes lost | Print layout changes |
+| Custom XML parts | Dropped | Third-party data bindings broken |
+| Theme-linked colors | May be de-themed | Colors converted to absolute, breaking theme switching |
+
+Even on a "plain" file without these features, openpyxl may normalize whitespace in XML that Excel relies on, alter namespace declarations, or reset `calcMode` flags.
+
+**The rule is absolute: never open an existing file with openpyxl for the purpose of re-saving it.**
+
+The XML direct-edit approach is safe because it operates on the raw bytes. You only change the nodes you touch. Everything else is byte-equivalent to the original.
+
+---
+
+## 3. Standard Operating Procedure
+
+### Step 1 — Unpack
+
+```bash
+python3 SKILL_DIR/scripts/xlsx_unpack.py input.xlsx /tmp/xlsx_work/
+```
+
+The script unzips the xlsx, pretty-prints every XML and `.rels` file, and prints a categorized inventory of key files plus a warning if high-risk content is detected (VBA, pivot tables, charts).
+
+Read the printed output carefully before proceeding. If the script reports `xl/vbaProject.bin` or `xl/pivotTables/`, follow the constraints in Section 7.
+
+### Step 2 — Reconnaissance
+
+Map the structure before touching anything.
+
+**Identify sheet names and their XML files:**
+
+```
+xl/workbook.xml  →  <sheet name="Revenue" sheetId="1" r:id="rId1"/>
+xl/_rels/workbook.xml.rels  →  <Relationship Id="rId1" Target="worksheets/sheet1.xml"/>
+```
+
+The sheet named "Revenue" lives in `xl/worksheets/sheet1.xml`. Always resolve this mapping before editing a worksheet.
+
+**Understand the shared strings table:**
+
+```bash
+# Count existing entries in xl/sharedStrings.xml
+grep -c "<si>" /tmp/xlsx_work/xl/sharedStrings.xml
+```
+
+Every text cell uses a zero-based index into this table. Know the current count before appending.
+
+**Understand the styles table:**
+
+```bash
+# Count existing cellXfs entries
+grep -c "<xf " /tmp/xlsx_work/xl/styles.xml
+```
+
+New style slots are appended after existing ones. The index of the first new slot = current count.
+
+**Scan for high-risk XML regions in the target worksheet:**
+
+Look for these elements in the target `sheet*.xml` before editing:
+
+- `<mergeCell>` — merged cell ranges; row/column insertion shifts these
+- `<conditionalFormatting>` — condition ranges; row/column insertion shifts these
+- `<dataValidations>` — validation ranges; row/column insertion shifts these
+- `<tableParts>` — table definitions; row insertion inside a table needs `<tableColumn>` updates
+- `<sparklineGroups>` — sparklines; preserve without modification
+
+### Step 3 — Map Intent to Minimal XML Changes
+
+Before writing a single character, produce a written list of exactly which XML nodes change. This prevents scope creep.
+
+| User intent | Files to change | Nodes to change |
+|-------------|----------------|-----------------|
+| Change a cell's numeric value | `xl/worksheets/sheetN.xml` | `<v>` inside target `<c>` |
+| Change a cell's text | `xl/sharedStrings.xml` (append) + `xl/worksheets/sheetN.xml` | New `<si>`, update cell `<v>` index |
+| Change a cell's formula | `xl/worksheets/sheetN.xml` | `<f>` text inside target `<c>` |
+| Add a new data row at the bottom | `xl/worksheets/sheetN.xml` + possibly `xl/sharedStrings.xml` | Append `<row>` element |
+| Apply a new style to cells | `xl/styles.xml` + `xl/worksheets/sheetN.xml` | Append `<xf>` in `<cellXfs>`, update `s` attribute on `<c>` |
+| Rename a sheet | `xl/workbook.xml` | `name` attribute on `<sheet>` element |
+| Rename a sheet (with cross-sheet formulas) | `xl/workbook.xml` + all `xl/worksheets/*.xml` | `name` attribute + `<f>` text referencing old name |
+
+### Step 4 — Execute Changes
+
+Use the Edit tool. Edit the minimum. Never rewrite whole files.
+
+See Section 4 for precise XML patterns for each operation type.
+
+### Step 5 — Cascade Check
+
+After any change that shifts row or column positions, audit all affected XML regions. See Section 5.
+
+### Step 6 — Pack and Validate
+
+```bash
+python3 SKILL_DIR/scripts/xlsx_pack.py /tmp/xlsx_work/ output.xlsx
+python3 SKILL_DIR/scripts/formula_check.py output.xlsx
+```
+
+The pack script validates XML well-formedness before creating the ZIP. Fix any reported parse errors before packing. After packing, run `formula_check.py` to confirm no formula errors were introduced.
+
+---
+
+## 4. Precise XML Patterns for Common Edits
+
+### 4.1 Changing a Numeric Cell Value
+
+Find the `<c r="B5">` element in the worksheet XML and replace the `<v>` text.
+
+**Before:**
+```xml
+<c r="B5">
+  <v>1000</v>
+</c>
+```
+
+**After (new value 1500):**
+```xml
+<c r="B5">
+  <v>1500</v>
+</c>
+```
+
+Rules:
+- Do not add or remove the `s` attribute (style) unless explicitly changing the style.
+- Do not add a `t` attribute — numbers omit `t` or use `t="n"`.
+- Do not change the `r` attribute (cell reference).
+
+---
+
+### 4.2 Changing a Text Cell Value
+
+Text cells reference the shared strings table by index (`t="s"`). You cannot edit the string in-place without affecting every other cell that uses the same index. The safe approach is to append a new entry.
+
+**Before — shared strings file (`xl/sharedStrings.xml`):**
+```xml
+<sst count="4" uniqueCount="4">
+  <si><t>Revenue</t></si>
+  <si><t>Cost</t></si>
+  <si><t>Margin</t></si>
+  <si><t>Old Label</t></si>
+</sst>
+```
+
+**After — append new string, increment counts:**
+```xml
+<sst count="5" uniqueCount="5">
+  <si><t>Revenue</t></si>
+  <si><t>Cost</t></si>
+  <si><t>Margin</t></si>
+  <si><t>Old Label</t></si>
+  <si><t>New Label</t></si>
+</sst>
+```
+
+New string is at index 4 (zero-based).
+
+**Before — cell in worksheet XML:**
+```xml
+<c r="A7" t="s">
+  <v>3</v>
+</c>
+```
+
+**After — point to new index:**
+```xml
+<c r="A7" t="s">
+  <v>4</v>
+</c>
+```
+
+Rules:
+- Never modify or delete existing `<si>` entries. Only append.
+- Both `count` and `uniqueCount` must be incremented together.
+- If the new string contains `&`, `<`, or `>`, escape them: `&amp;`, `&lt;`, `&gt;`.
+- If the string has leading or trailing spaces, add `xml:space="preserve"` to `<t>`:
+  ```xml
+  <si><t xml:space="preserve">  indented text  </t></si>
+  ```
+
+---
+
+### 4.3 Changing a Formula
+
+Formulas are stored in `<f>` elements **without a leading `=`** (unlike what you type in Excel's UI).
+
+**Before:**
+```xml
+<c r="C10">
+  <f>SUM(C2:C9)</f>
+  <v>4800</v>
+</c>
+```
+
+**After (extended range):**
+```xml
+<c r="C10">
+  <f>SUM(C2:C11)</f>
+  <v></v>
+</c>
+```
+
+Rules:
+- Clear `<v>` to an empty string when changing the formula. The cached value is now stale.
+- Do not add `t="s"` or any type attribute to formula cells. The `t` attribute is absent or uses a result-type value, not a formula marker.
+- Cross-sheet references use `SheetName!CellRef`. If the sheet name contains spaces, wrap in single quotes: `'Q1 Data'!B5`.
+- The `<f>` text must not include the leading `=`.
+
+**Before (converting a hardcoded value to a live formula):**
+```xml
+<c r="D15">
+  <v>95000</v>
+</c>
+```
+
+**After:**
+```xml
+<c r="D15">
+  <f>SUM(D2:D14)</f>
+  <v></v>
+</c>
+```
+
+---
+
+### 4.4 Adding a New Data Row
+
+Append after the last `<row>` element inside `<sheetData>`. Row numbers in OOXML are 1-based and must be sequential.
+
+**Before (last row is row 10):**
+```xml
+  <row r="10">
+    <c r="A10" t="s"><v>3</v></c>
+    <c r="B10"><v>2023</v></c>
+    <c r="C10"><v>88000</v></c>
+    <c r="D10"><f>C10*1.1</f><v></v></c>
+  </row>
+</sheetData>
+```
+
+**After (new row 11 appended):**
+```xml
+  <row r="10">
+    <c r="A10" t="s"><v>3</v></c>
+    <c r="B10"><v>2023</v></c>
+    <c r="C10"><v>88000</v></c>
+    <c r="D10"><f>C10*1.1</f><v></v></c>
+  </row>
+  <row r="11">
+    <c r="A11" t="s"><v>4</v></c>
+    <c r="B11"><v>2024</v></c>
+    <c r="C11"><v>96000</v></c>
+    <c r="D11"><f>C11*1.1</f><v></v></c>
+  </row>
+</sheetData>
+```
+
+Rules:
+- Every `<c>` inside the row must have `r` set to the correct cell address (e.g., `A11`).
+- Text cells need `t="s"` and a sharedStrings index in `<v>`. Numeric cells omit `t`.
+- Formula cells use `<f>` and an empty `<v>`.
+- Copy the `s` attribute from the row above if you want matching styles. Do not invent a style index that does not exist in `styles.xml`.
+- If the sheet contains a `<dimension>` element (e.g., `<dimension ref="A1:D10"/>`), update it to include the new row: `<dimension ref="A1:D11"/>`.
+- If the sheet contains a `<tableparts>` referencing a table, update the table's `ref` attribute in the corresponding `xl/tables/tableN.xml` file.
+
+---
+
+### 4.5 Adding a New Column
+
+Append new `<c>` elements to each existing `<row>` and, if present, update the `<cols>` section.
+
+**Before (rows have columns A–C):**
+```xml
+<cols>
+  <col min="1" max="3" width="14" customWidth="1"/>
+</cols>
+<sheetData>
+  <row r="1">
+    <c r="A1" t="s"><v>0</v></c>
+    <c r="B1" t="s"><v>1</v></c>
+    <c r="C1" t="s"><v>2</v></c>
+  </row>
+  <row r="2">
+    <c r="A2"><v>100</v></c>
+    <c r="B2"><v>200</v></c>
+    <c r="C2"><v>300</v></c>
+  </row>
+</sheetData>
+```
+
+**After (adding column D):**
+```xml
+<cols>
+  <col min="1" max="3" width="14" customWidth="1"/>
+  <col min="4" max="4" width="14" customWidth="1"/>
+</cols>
+<sheetData>
+  <row r="1">
+    <c r="A1" t="s"><v>0</v></c>
+    <c r="B1" t="s"><v>1</v></c>
+    <c r="C1" t="s"><v>2</v></c>
+    <c r="D1" t="s"><v>5</v></c>
+  </row>
+  <row r="2">
+    <c r="A2"><v>100</v></c>
+    <c r="B2"><v>200</v></c>
+    <c r="C2"><v>300</v></c>
+    <c r="D2"><f>A2+B2+C2</f><v></v></c>
+  </row>
+</sheetData>
+```
+
+Rules:
+- Adding a column at the end (after the last existing column) is safe — no existing formula references shift.
+- Inserting a column in the middle shifts all columns to the right, which requires the same cascade updates as row insertion (see Section 5).
+- Update the `<dimension>` element if present.
+
+---
+
+### 4.6 Modifying or Adding Styles
+
+Styles use a multi-level indirect reference chain. Read `ooxml-cheatsheet.md` for the full chain. The key rule: **only append new entries, never modify existing ones**.
+
+**Scenario:** Add a blue-font style (for hardcoded input cells) that doesn't yet exist.
+
+**Step 1 — Check if a matching font already exists in `xl/styles.xml`:**
+```xml
+<!-- Look inside <fonts> for an existing blue font -->
+<font>
+  <color rgb="000000FF"/>
+  <!-- other attributes -->
+</font>
+```
+
+If found, note its index (zero-based position in the `<fonts>` list). If not found, append.
+
+**Step 2 — Append the new font if needed:**
+
+Before:
+```xml
+<fonts count="3">
+  <font>...</font>   <!-- index 0 -->
+  <font>...</font>   <!-- index 1 -->
+  <font>...</font>   <!-- index 2 -->
+</fonts>
+```
+
+After:
+```xml
+<fonts count="4">
+  <font>...</font>   <!-- index 0 -->
+  <font>...</font>   <!-- index 1 -->
+  <font>...</font>   <!-- index 2 -->
+  <font>
+    <b/>
+    <sz val="11"/>
+    <color rgb="000000FF"/>
+    <name val="Calibri"/>
+  </font>             <!-- index 3 (new) -->
+</fonts>
+```
+
+**Step 3 — Append a new `<xf>` in `<cellXfs>`:**
+
+Before:
+```xml
+<cellXfs count="5">
+  <xf .../>   <!-- index 0 -->
+  <xf .../>   <!-- index 1 -->
+  <xf .../>   <!-- index 2 -->
+  <xf .../>   <!-- index 3 -->
+  <xf .../>   <!-- index 4 -->
+</cellXfs>
+```
+
+After:
+```xml
+<cellXfs count="6">
+  <xf .../>   <!-- index 0 -->
+  <xf .../>   <!-- index 1 -->
+  <xf .../>   <!-- index 2 -->
+  <xf .../>   <!-- index 3 -->
+  <xf .../>   <!-- index 4 -->
+  <xf numFmtId="0" fontId="3" fillId="0" borderId="0" xfId="0"
+      applyFont="1"/>   <!-- index 5 (new) -->
+</cellXfs>
+```
+
+**Step 4 — Apply to target cells:**
+
+Before:
+```xml
+<c r="B3">
+  <v>0.08</v>
+</c>
+```
+
+After:
+```xml
+<c r="B3" s="5">
+  <v>0.08</v>
+</c>
+```
+
+Rules:
+- Never delete or reorder existing entries in `<fonts>`, `<fills>`, `<borders>`, `<cellXfs>`.
+- Always update the `count` attribute when appending.
+- The new `cellXfs` index = the old `count` value before appending (zero-based: if count was 5, new index is 5).
+- Custom `numFmt` IDs must be 164 or above. IDs 0–163 are built-in and must not be re-declared.
+- If the desired style already exists elsewhere in the file (on a similar cell), reuse its `s` index rather than creating a duplicate.
+
+---
+
+### 4.7 Renaming a Sheet
+
+**Only `xl/workbook.xml` needs to change** — unless cross-sheet formulas reference the old name.
+
+**Before (`xl/workbook.xml`):**
+```xml
+<sheet name="Sheet1" sheetId="1" r:id="rId1"/>
+```
+
+**After:**
+```xml
+<sheet name="Revenue" sheetId="1" r:id="rId1"/>
+```
+
+**If any formula in any worksheet references the old name, update those too:**
+
+Before (`xl/worksheets/sheet2.xml`):
+```xml
+<c r="B5"><f>Sheet1!C10</f><v></v></c>
+```
+
+After:
+```xml
+<c r="B5"><f>Revenue!C10</f><v></v></c>
+```
+
+If the new name contains spaces:
+```xml
+<c r="B5"><f>'Q1 Revenue'!C10</f><v></v></c>
+```
+
+Scan all worksheet XML files for the old name:
+```bash
+grep -r "Sheet1!" /tmp/xlsx_work/xl/worksheets/
+```
+
+Rules:
+- The `.rels` file and `[Content_Types].xml` do NOT need to change — they reference the XML file path, not the sheet name.
+- `sheetId` must not change; it is a stable internal identifier.
+- Sheet names are case-sensitive in formula references.
+
+---
+
+## 5. High-Risk Operations — Cascade Effects
+
+### 5.1 Inserting a Row in the Middle
+
+Inserting a row at position N shifts all rows from N downward. Every reference to those rows in every XML file must be updated.
+
+**Files to check and update:**
+
+| XML region | What to update | Example shift |
+|------------|---------------|---------------|
+| Worksheet `<row r="...">` attributes | Increment row number for all rows >= N | `r="7"` → `r="8"` |
+| All `<c r="...">` within those rows | Increment row number in cell address | `r="A7"` → `r="A8"` |
+| All `<f>` formula text in any sheet | Shift absolute row references >= N | `B7` → `B8` |
+| `<mergeCell ref="...">` | Shift start and end rows | `A7:C7` → `A8:C8` |
+| `<conditionalFormatting sqref="...">` | Shift range | `A5:D20` → `A5:D21` |
+| `<dataValidations sqref="...">` | Shift range | `B6:B50` → `B7:B51` |
+| `xl/charts/chartN.xml` data source ranges | Shift series ranges | `Sheet1!$B$5:$B$20` → `Sheet1!$B$6:$B$21` |
+| `xl/pivotTables/*.xml` source ranges | Shift source data range | Handle with extreme care — see Section 7 |
+| `<dimension ref="...">` | Expand to include new extent | `A1:D20` → `A1:D21` |
+| `xl/tables/tableN.xml` `ref` attribute | Expand table boundary | `A1:D20` → `A1:D21` |
+
+**Do not attempt row insertion manually in large or formula-heavy files.** Use the dedicated shift script instead:
+
+```bash
+# Insert 1 row at row 5: all rows 5 and below shift down by 1
+python3 SKILL_DIR/scripts/xlsx_shift_rows.py /tmp/xlsx_work/ insert 5 1
+
+# Delete 1 row at row 8: all rows 9 and above shift up by 1
+python3 SKILL_DIR/scripts/xlsx_shift_rows.py /tmp/xlsx_work/ delete 8 1
+```
+
+The script updates in one pass: `<row r="...">` attributes, `<c r="...">` cell addresses, all `<f>` formula text across every worksheet, `<mergeCell>` ranges, `<conditionalFormatting sqref="...">`, `<dataValidation sqref="...">`, `<dimension ref="...">`, table `ref` attributes in `xl/tables/`, chart series ranges in `xl/charts/`, and pivot cache source ranges in `xl/pivotCaches/`.
+
+**After running the shift script, always repack and validate:**
+```bash
+python3 SKILL_DIR/scripts/xlsx_pack.py /tmp/xlsx_work/ output.xlsx
+python3 SKILL_DIR/scripts/formula_check.py output.xlsx
+```
+
+**What the script does NOT update (review manually):**
+- Named ranges in `xl/workbook.xml` `<definedNames>` — check and update if they reference shifted rows.
+- Structured table references (`Table[@Column]`) inside formulas.
+- External workbook links in `xl/externalLinks/`.
+
+### 5.2 Inserting a Column in the Middle
+
+Same cascade logic as row insertion, but for columns. Column references in formulas (`B`, `$C`, etc.) and in merged cell ranges, conditional formatting ranges, and chart data sources all need updating.
+
+Column letter shifting is harder to automate safely. Prefer **appending columns at the end** whenever possible.
+
+### 5.3 Deleting a Row or Column
+
+Deletion is more dangerous than insertion because any formula that referenced a deleted row or column will become `#REF!`. Before deleting:
+
+1. Search all `<f>` elements for references to the deleted range.
+2. If any formula references a cell in the deleted row/column, do not delete — instead, either clear the row's data or consult the user.
+3. After deletion, shift all references to rows/columns beyond the deletion point downward/leftward.
+
+---
+
+## 6. Template Filling — Identifying and Populating Input Cells
+
+Templates designate certain cells as input zones. Common patterns to recognize them:
+
+### 6.1 How Templates Signal Input Zones
+
+| Signal | XML manifestation | What to look for |
+|--------|-------------------|-----------------|
+| Blue font color | `s` attribute pointing to a `cellXfs` entry with `fontId` → `<color rgb="000000FF"/>` | Check `styles.xml` to decode `s` values |
+| Yellow fill (highlight) | `s` → `fillId` → `<fill><patternFill><fgColor rgb="00FFFF00"/>` | |
+| Empty `<v>` element | `<c r="B5"><v></v></c>` or cell entirely absent from `<row>` | The cell has no value yet |
+| Comment/annotation near cell | `xl/comments1.xml` with `ref="B5"` | Comments often label input fields |
+| Named ranges | `xl/workbook.xml` `<definedName>` elements | Template may define `InputRevenue` etc. |
+
+### 6.2 Filling a Template Cell
+
+Do not change `s` attributes. Do not change `t` attributes unless you must change from empty to typed. Only change `<v>` or add `<f>`.
+
+**Before (empty input cell with style preserved):**
+```xml
+<c r="C5" s="3">
+  <v></v>
+</c>
+```
+
+**After (filled with a number, style unchanged):**
+```xml
+<c r="C5" s="3">
+  <v>125000</v>
+</c>
+```
+
+**After (filled with text — requires shared string entry first):**
+```xml
+<!-- 1. Append to sharedStrings.xml: <si><t>North Region</t></si> at index 7 -->
+<c r="C5" t="s" s="3">
+  <v>7</v>
+</c>
+```
+
+**After (filled with a formula, preserving style):**
+```xml
+<c r="C5" s="3">
+  <f>Assumptions!D12</f>
+  <v></v>
+</c>
+```
+
+### 6.3 Locating Input Zones Without Opening the File in Excel
+
+After unpacking, decode the style index on suspected input cells to determine if they have the template's input color:
+
+1. Note the `s` value on the cell (e.g., `s="4"`).
+2. In `xl/styles.xml`, find `<cellXfs>` and look at the 5th entry (index 4).
+3. Note its `fontId` (e.g., `fontId="2"`).
+4. In `<fonts>`, look at the 3rd entry (index 2) and check for `<color rgb="000000FF"/>` (blue) or other input marker.
+
+If the template uses named ranges as input fields, read them from `xl/workbook.xml`:
+```xml
+<definedNames>
+  <definedName name="InputGrowthRate">Assumptions!$B$5</definedName>
+  <definedName name="InputDiscountRate">Assumptions!$B$6</definedName>
+</definedNames>
+```
+
+Fill the target cells (`Assumptions!B5`, `Assumptions!B6`) directly.
+
+### 6.4 Template Filling Rules
+
+- Fill only cells the template designated as inputs. Do not fill cells that are formula-driven.
+- Do not apply new styles when filling. The template's formatting is the deliverable.
+- Do not add or remove rows inside the template's data area unless the template explicitly has an "append here" zone.
+- After filling, verify that no formula errors were introduced: some templates have input-validation formulas that produce `#VALUE!` if the wrong data type is entered.
+
+---
+
+## 7. Files You Must Never Modify
+
+### 7.1 Absolute no-touch list
+
+| File / location | Why |
+|-----------------|-----|
+| `xl/vbaProject.bin` | Binary VBA bytecode. Any byte modification corrupts the macro project. Editing even one bit makes the macros fail to load. |
+| `xl/pivotCaches/pivotCacheDefinition*.xml` | The cache definition ties the pivot table to its source data. Editing it without also updating the corresponding `pivotTable*.xml` will corrupt the pivot. |
+| `xl/pivotTables/*.xml` | Pivot table XML is tightly coupled with the cache definition and with internal state Excel rebuilds on load. Do not edit. If you shifted rows and the pivot's source range now points to wrong data, update only the `<cacheSource>` range in the cache definition, and only the `ref` attribute in the pivot table — no other changes. |
+| `xl/slicers/*.xml` | Slicers are connected to specific cache IDs and pivot fields. Breaking these connections silently corrupts the file. |
+| `xl/connections.xml` | External data connections. Editing breaks live data refresh. |
+| `xl/externalLinks/` | External workbook links. The binary `.bin` files in here must not be modified. |
+
+### 7.2 Conditionally safe files (update only specific attributes)
+
+| File | What you may update | What to leave alone |
+|------|--------------------|--------------------|
+| `xl/charts/chartN.xml` | Data series range references (`<numRef><f>`) after a row/column shift | Chart type, formatting, layout |
+| `xl/tables/tableN.xml` | `ref` attribute on `<table>` after adding rows | Column definitions, style info |
+| `xl/pivotCaches/pivotCacheDefinition*.xml` | `ref` attribute on `<cacheSource><worksheetSource>` after shifting source data | All other content |
+
+---
+
+## 8. Validation After Every Edit
+
+Never skip validation. Even a one-character change in a formula can cause cascading errors.
+
+```bash
+# Pack
+python3 SKILL_DIR/scripts/xlsx_pack.py /tmp/xlsx_work/ output.xlsx
+
+# Static formula validation (always run)
+python3 SKILL_DIR/scripts/formula_check.py output.xlsx
+
+# Dynamic validation (if LibreOffice available)
+python3 SKILL_DIR/scripts/libreoffice_recalc.py output.xlsx /tmp/recalc.xlsx
+python3 SKILL_DIR/scripts/formula_check.py /tmp/recalc.xlsx
+```
+
+If `formula_check.py` reports any error:
+1. Unpack the output file again (it is the packed version).
+2. Locate the reported cell in the worksheet XML.
+3. Fix the `<f>` element.
+4. Repack and re-validate.
+
+Do not deliver the file until `formula_check.py` reports zero errors.
+
+---
+
+## 9. Absolute Rules Summary
+
+| Rule | Rationale |
+|------|-----------|
+| Never use openpyxl `load_workbook` + `save` on an existing file | Round-trip destroys pivot tables, VBA, sparklines, slicers |
+| Never delete or reorder existing `<si>` entries in sharedStrings | Breaks every cell referencing that index |
+| Never delete or reorder existing `<xf>` entries in `<cellXfs>` | Breaks every cell using that style index |
+| Never modify `vbaProject.bin` | Binary file; any change corrupts VBA |
+| Never change `sheetId` when renaming a sheet | Internal ID is stable; changing it breaks relationships |
+| Never skip post-edit validation | Leaves broken references undetected |
+| Never edit more XML nodes than required | Extra changes risk introducing subtle corruption |
+| Clear `<v>` to empty string when changing a formula | Prevents stale cached value from misleading downstream consumers |
+| Append-only to sharedStrings | Existing indexes must remain valid |
+| Append-only to styles collections | Existing style indexes must remain valid |
diff --git a/builtin-skills/document-process/minimax-xlsx/references/fix.md b/builtin-skills/document-process/minimax-xlsx/references/fix.md
new file mode 100644
index 00000000..7aedc8a1
--- /dev/null
+++ b/builtin-skills/document-process/minimax-xlsx/references/fix.md
@@ -0,0 +1,37 @@
+# FIX — Repair Broken Formulas in an Existing xlsx
+
+This is an EDIT task. You MUST preserve all original sheets and data. Never create a new workbook.
+
+## Workflow
+
+```bash
+# Step 1: Identify errors
+python3 SKILL_DIR/scripts/formula_check.py input.xlsx --json
+
+# Step 2: Unpack
+python3 SKILL_DIR/scripts/xlsx_unpack.py input.xlsx /tmp/xlsx_work/
+
+# Step 3: Fix each broken <f> element in the worksheet XML using the Edit tool
+#   (see Error-to-Fix mapping below)
+
+# Step 4: Pack and validate
+python3 SKILL_DIR/scripts/xlsx_pack.py /tmp/xlsx_work/ output.xlsx
+python3 SKILL_DIR/scripts/formula_check.py output.xlsx
+```
+
+## Error-to-Fix Mapping
+
+| Error | Fix Strategy |
+|-------|-------------|
+| `#DIV/0!` | Wrap: `IFERROR(original_formula, "-")` |
+| `#NAME?` | Fix misspelled function (e.g. `SUMM` → `SUM`) |
+| `#REF!` | Reconstruct the broken reference |
+| `#VALUE!` | Fix type mismatch |
+
+For the full list of Excel error types and advanced diagnostics, see `validate.md`.
+
+## Critical Rules
+
+- The output MUST contain the same sheets as the input. Do NOT create a new workbook.
+- Only modify the specific `<f>` elements that are broken — everything else must be untouched.
+- After packing, always run `formula_check.py` to confirm all errors are resolved.
diff --git a/builtin-skills/document-process/minimax-xlsx/references/format.md b/builtin-skills/document-process/minimax-xlsx/references/format.md
new file mode 100644
index 00000000..a20723a5
--- /dev/null
+++ b/builtin-skills/document-process/minimax-xlsx/references/format.md
@@ -0,0 +1,768 @@
+# Financial Formatting & Output Standards — Complete Agent Guide
+
+> This document is the complete reference manual for the agent when applying professional financial formatting to xlsx files. All operations target direct XML surgery on `xl/styles.xml` without using openpyxl. Every operational step provides ready-to-use XML snippets.
+
+---
+
+## 1. When to Use This Path
+
+This document (FORMAT path) applies to the following two scenarios:
+
+**Scenario A — Dedicated Formatting of an Existing File**
+The user provides an existing xlsx file and requests that financial modeling formatting standards be applied or unified. The starting point is to unpack the file, audit the existing `styles.xml`, then append missing styles and batch-update cell `s` attributes. No cell values or formulas are modified.
+
+**Scenario B — Applying Format Standards After CREATE/EDIT**
+After completing data entry or formula writing, formatting is applied as the final step. At this point, `styles.xml` may come from the minimal_xlsx template (which pre-defines 13 style slots) or from a user file. In either case, follow the principle of "append only, never modify existing xf entries."
+
+**Not applicable**: Reading or analyzing file contents only (use the READ path); modifying formulas or data (use the EDIT path).
+
+---
+
+## 2. Financial Format Semantic System
+
+### 2.1 Font Color = Cell Role (Color = Role)
+
+The primary convention of financial modeling: **font color encodes the cell's role, not decoration**. A reviewer can glance at colors to determine which cells are adjustable parameters and which are model-calculated results. This is an industry-wide convention (followed by investment banks, the Big Four, and corporate finance teams).
+
+| Role | Font Color | AARRGGBB | Use Case |
+|------|-----------|----------|----------|
+| Hard-coded input / assumption | Blue | `000000FF` | Growth rates, discount rates, tax rates, and other user-modifiable parameters |
+| Formula / calculated result | Black | `00000000` | All cells containing a `<f>` element |
+| Same-workbook cross-sheet reference | Green | `00008000` | Cells whose formula starts with `SheetName!` |
+| External file link | Red | `00FF0000` | Cells whose formula contains `[FileName.xlsx]` (flagged as fragile links) |
+| Label / text | Black (default) | theme color | Row labels, category headings |
+| Key assumption requiring review | Blue font + yellow fill | Font `000000FF` / Fill `00FFFF00` | Provisional values, parameters pending confirmation |
+
+**Decision tree**:
+```
+Does the cell contain a <f> element?
+  +-- Yes -> Does the formula start with [FileName]?
+  |           +-- Yes -> Red (external link)
+  |           +-- No  -> Does the formula contain SheetName!?
+  |                       +-- Yes -> Green (cross-sheet reference)
+  |                       +-- No  -> Black (same-sheet formula)
+  +-- No  -> Is the value a user-adjustable parameter?
+              +-- Yes -> Blue (input/assumption)
+              +-- No  -> Black default (label)
+```
+
+**Strictly prohibited**: Blue font + `<f>` element coexisting (color role contradiction — must be corrected).
+
+### 2.2 Number Format Matrix
+
+| Data Type | formatCode | numFmtId | Display Example | Applicable Scenario |
+|-----------|-----------|----------|-----------------|---------------------|
+| Standard currency (whole dollars) | `$#,##0;($#,##0);"-"` | 164 | $1,234 / ($1,234) / - | P&L, balance sheet amount rows |
+| Standard currency (with cents) | `$#,##0.00;($#,##0.00);"-"` | 169 | $1,234.56 / ($1,234.56) / - | Unit prices, detailed costs |
+| Thousands (K) | `#,##0,"K"` | 171 | 1,234K | Simplified display for management reports |
+| Millions (M) | `#,##0,,"M"` | 172 | 1M | Macro-level summary rows |
+| Percentage (1 decimal) | `0.0%` | 165 | 12.5% | Growth rates, gross margins |
+| Percentage (2 decimals) | `0.00%` | 170 | 12.50% | IRR, precise interest rates |
+| Multiple / valuation multiplier | `0.0x` | 166 | 8.5x | EV/EBITDA, P/E |
+| Integer (thousands separator) | `#,##0` | 167 | 12,345 | Employee count, unit quantities |
+| Year | `0` | 1 (built-in, no declaration needed) | 2024 | Column header years, prevents 2,024 |
+| Date | `m/d/yyyy` | 14 (built-in, no declaration needed) | 3/21/2026 | Timelines |
+| General text | General | 0 (built-in, no declaration needed) | — | Label rows, cells with no format requirement |
+
+numFmtId 169–172 are custom formats that need to be appended beyond the 4 formats (164–167) pre-defined in the minimal_xlsx template. When appending, assign IDs according to the rules (see Section 3.4).
+
+**Built-in format IDs do not need to be declared in `<numFmts>`** (IDs 0–163 are built into Excel/LibreOffice; simply reference the numFmtId in `<xf>`):
+
+| numFmtId | formatCode | Description |
+|----------|-----------|-------------|
+| 0 | General | General format |
+| 1 | `0` | Integer, no thousands separator (use this ID for years) |
+| 3 | `#,##0` | Thousands-separated integer (no decimals) |
+| 9 | `0%` | Percentage integer |
+| 10 | `0.00%` | Percentage with two decimals |
+| 14 | `m/d/yyyy` | Short date |
+
+### 2.3 Negative Number Display Standards
+
+Financial reports have two mainstream conventions for negative numbers — choose one and **maintain consistency** throughout the entire workbook:
+
+**Parenthetical style (investment banking standard, recommended for external deliverables)**
+
+```
+Positive: $1,234    Negative: ($1,234)    Zero: -
+formatCode: $#,##0;($#,##0);"-"
+```
+
+**Red minus sign style (suitable for internal operational analysis reports)**
+
+```
+Positive: $1,234    Negative: -$1,234 (red)
+formatCode: $#,##0;[Red]-$#,##0;"-"
+```
+
+Rule: Once a style is determined, maintain it across the entire workbook. Do not mix two negative number display styles within the same workbook.
+
+### 2.4 Zero Value Display Standards
+
+In financial models, "0" and "no data" have different semantics and should be visually distinct:
+
+| Scenario | Recommended Display | formatCode Third Segment |
+|----------|-------------------|--------------------------|
+| Sparse matrix (most rows have zero-value periods) | Dash `-` | `"-"` |
+| Quantity counts (zero itself is meaningful) | `0` | `0` or omit |
+| Placeholder row (explicitly empty) | Leave blank | Do not write to cell |
+
+Four-segment format syntax: `positive format;negative format;zero value format;text format`
+
+Zero as dash: `$#,##0;($#,##0);"-"`
+Zero preserved as 0: `#,##0;(#,##0);0`
+
+---
+
+## 3. styles.xml Surgical Operations
+
+### 3.1 Auditing Existing Styles: Understanding the cellXfs Indirect Reference Chain
+
+A cell's `s` attribute points to a position index (0-based) in `cellXfs`, and each `<xf>` entry in `cellXfs` references its respective definition libraries through `fontId`, `fillId`, `borderId`, and `numFmtId`.
+
+Reference chain diagram:
+
+```
+Cell <c s="6">
+    | Look up cellXfs by 0-based index
+cellXfs[6] -> numFmtId="164" fontId="2" fillId="0" borderId="0"
+    |            |               |          |
+numFmts         fonts[2]      fills[0]   borders[0]
+id=164          color=00000000  (no fill)  (no border)
+$#,##0...       black
+```
+
+Audit steps:
+
+**Step 1**: Read `<numFmts>` and record all declared custom formats and their IDs:
+```xml
+<numFmts count="4">
+  <numFmt numFmtId="164" formatCode="$#,##0;($#,##0);&quot;-&quot;"/>
+  <numFmt numFmtId="165" formatCode="0.0%"/>
+  <numFmt numFmtId="166" formatCode="0.0x"/>
+  <numFmt numFmtId="167" formatCode="#,##0"/>
+</numFmts>
+```
+Record: current maximum custom numFmtId = 167, next available ID = 168.
+
+**Step 2**: Read `<fonts>` and list each `<font>` by 0-based index with its color and style:
+```
+fontId=0 -> No explicit color (theme default black)
+fontId=1 -> color rgb="000000FF" (blue, input role)
+fontId=2 -> color rgb="00000000" (black, formula role)
+fontId=3 -> color rgb="00008000" (green, cross-sheet reference role)
+fontId=4 -> <b/> + color rgb="00000000" (bold black, header)
+```
+
+**Step 3**: Read `<fills>` and confirm that fills[0] and fills[1] are spec-mandated reserved entries (never delete):
+```
+fillId=0 -> patternType="none" (spec-mandated)
+fillId=1 -> patternType="gray125" (spec-mandated)
+fillId=2 -> Yellow highlight (if present)
+```
+
+**Step 4**: Read `<cellXfs>` and list each `<xf>` entry by 0-based index with its combination:
+```
+index 0 -> numFmtId=0,   fontId=0, fillId=0 -> Default style
+index 1 -> numFmtId=0,   fontId=1, fillId=0 -> Blue font general (input)
+index 5 -> numFmtId=164, fontId=1, fillId=0 -> Blue font currency (currency input)
+index 6 -> numFmtId=164, fontId=2, fillId=0 -> Black font currency (currency formula)
+...
+```
+
+**Step 5**: Verify that all count attributes match the actual number of elements (count mismatches will cause Excel to refuse to open the file).
+
+### 3.2 Safely Appending New Styles (Golden Rule: Append Only, Never Modify Existing xf)
+
+**Never modify existing `<xf>` entries**. Modifications will affect all cells that already reference that index, breaking existing formatting. Only append new entries at the end.
+
+Complete atomic operation sequence for appending new styles (all 5 steps must be executed):
+
+**Step 1**: Determine if a new `<numFmt>` is needed
+
+Built-in formats (ID 0–163) skip this step. Custom formats are appended to the end of `<numFmts>`:
+```xml
+<numFmts count="5">  <!-- count +1 -->
+  <!-- Keep existing entries unchanged -->
+  <numFmt numFmtId="164" formatCode="$#,##0;($#,##0);&quot;-&quot;"/>
+  <numFmt numFmtId="165" formatCode="0.0%"/>
+  <numFmt numFmtId="166" formatCode="0.0x"/>
+  <numFmt numFmtId="167" formatCode="#,##0"/>
+  <!-- Newly appended -->
+  <numFmt numFmtId="168" formatCode="$#,##0.00;($#,##0.00);&quot;-&quot;"/>
+</numFmts>
+```
+
+**Step 2**: Determine if a new `<font>` is needed
+
+Check whether the existing fonts already contain a matching color+style combination. If not, append to the end of `<fonts>`:
+```xml
+<fonts count="6">  <!-- count +1 -->
+  <!-- Keep existing entries unchanged -->
+  ...
+  <!-- Newly appended: red font (external link role), new fontId = 5 -->
+  <font>
+    <sz val="11"/>
+    <name val="Calibri"/>
+    <color rgb="00FF0000"/>
+  </font>
+</fonts>
+```
+New fontId = the count value before appending (when original count=5, new fontId=5).
+
+**Step 3**: Determine if a new `<fill>` is needed
+
+If a new background color is needed, append to the end of `<fills>` (note: fills[0] and fills[1] must never be modified):
+```xml
+<fills count="4">  <!-- count +1 -->
+  <fill><patternFill patternType="none"/></fill>       <!-- 0: spec-mandated -->
+  <fill><patternFill patternType="gray125"/></fill>    <!-- 1: spec-mandated -->
+  <fill>                                               <!-- 2: yellow highlight -->
+    <patternFill patternType="solid">
+      <fgColor rgb="00FFFF00"/>
+      <bgColor indexed="64"/>
+    </patternFill>
+  </fill>
+  <!-- Newly appended: light gray fill (projection period distinction), new fillId = 3 -->
+  <fill>
+    <patternFill patternType="solid">
+      <fgColor rgb="00D3D3D3"/>
+      <bgColor indexed="64"/>
+    </patternFill>
+  </fill>
+</fills>
+```
+
+**Step 4**: Append a new `<xf>` combination at the end of `<cellXfs>`
+```xml
+<cellXfs count="14">  <!-- count +1 -->
+  <!-- Keep existing entries 0-12 unchanged -->
+  ...
+  <!-- Newly appended index=13: currency with cents formula (black font + numFmtId=168) -->
+  <xf numFmtId="168" fontId="2" fillId="0" borderId="0" xfId="0"
+      applyFont="1" applyNumberFormat="1"/>
+</cellXfs>
+```
+New style index = the count value before appending (when original count=13, new index=13).
+
+**Step 5**: Record the new style index; subsequently set the `s` attribute of corresponding cells in the sheet XML to this value.
+
+### 3.3 AARRGGBB Color Format Explanation
+
+OOXML's `rgb` attribute uses **8-digit hexadecimal AARRGGBB** format (not HTML's 6-digit RRGGBB):
+
+```
+AA  RR  GG  BB
+|   |   |   |
+Alpha Red Green Blue
+```
+
+- Alpha channel: `00` = fully opaque (normal use value); `FF` = fully transparent (invisible, never use this)
+- Financial color standards always use `00` as the Alpha prefix
+
+| Color | AARRGGBB | Corresponding Role |
+|-------|----------|-------------------|
+| Blue (input) | `000000FF` | Hard-coded assumptions |
+| Black (formula) | `00000000` | Calculated results |
+| Green (cross-sheet reference) | `00008000` | Same-workbook cross-sheet |
+| Red (external link) | `00FF0000` | References to other files |
+| Yellow (review-required fill) | `00FFFF00` | Key assumption highlight |
+| Light gray (projection period fill) | `00D3D3D3` | Distinguishing historical vs. forecast periods |
+| White | `00FFFFFF` | Pure white fill |
+
+**Common mistake**: Mistakenly writing HTML format `#0000FF` as `FF0000FF` (Alpha=FF makes the color fully transparent and invisible). Correct format: `000000FF`.
+
+### 3.4 numFmtId Assignment Rules
+
+```
+ID 0-163    -> Excel/LibreOffice built-in formats, no declaration needed in <numFmts>, reference directly in <xf>
+ID 164+     -> Custom formats, must be explicitly declared as <numFmt> elements in <numFmts>
+```
+
+Rules for assigning new IDs:
+1. Read all `numFmtId` attribute values in the current `<numFmts>`
+2. Take the maximum value + 1 as the next custom format ID
+3. Do not reuse existing IDs; do not skip numbers
+
+The minimal_xlsx template pre-defines IDs: 164, 165, 166, 167. The next available ID is 168.
+
+---
+
+## 4. Pre-defined Style Index Complete Reference Table (13 Slots)
+
+The following are the 13 style slots (cellXfs index 0–12) pre-defined in the minimal_xlsx template's `styles.xml`, which can be directly referenced in the cell `s` attribute in sheet XML:
+
+| Index | Semantic Role | Font Color | Fill | numFmtId | Format Display | Typical Use |
+|-------|--------------|------------|------|----------|---------------|-------------|
+| **0** | Default style | Theme black | None | 0 | General | Cells requiring no special formatting |
+| **1** | Input / assumption (general) | Blue `000000FF` | None | 0 | General | Text-type assumptions, flags |
+| **2** | Formula / calculated result (general) | Black `00000000` | None | 0 | General | Text concatenation formulas, non-numeric calculations |
+| **3** | Cross-sheet reference (general) | Green `00008000` | None | 0 | General | Values pulled from cross-sheet (general format) |
+| **4** | Header (bold) | Bold black | None | 0 | General | Row/column headings |
+| **5** | Currency input | Blue `000000FF` | None | 164 | $1,234 / ($1,234) / - | Amount inputs in the assumptions area |
+| **6** | Currency formula | Black `00000000` | None | 164 | $1,234 / ($1,234) / - | Amount calculations in the model area (revenue, EBITDA) |
+| **7** | Percentage input | Blue `000000FF` | None | 165 | 12.5% | Rate inputs in the assumptions area (growth rate, gross margin assumptions) |
+| **8** | Percentage formula | Black `00000000` | None | 165 | 12.5% | Rate calculations in the model area (actual gross margin) |
+| **9** | Integer (comma) input | Blue `000000FF` | None | 167 | 12,345 | Quantity inputs in the assumptions area (employee count) |
+| **10** | Integer (comma) formula | Black `00000000` | None | 167 | 12,345 | Quantity calculations in the model area |
+| **11** | Year input | Blue `000000FF` | None | 1 | 2024 | Column header years (no thousands separator) |
+| **12** | Key assumption highlight | Blue `000000FF` | Yellow `00FFFF00` | 0 | General | Key parameters pending review or confirmation |
+
+**Selection guide**:
+- Determine "input" vs. "formula" -> Choose odd-numbered (input/blue) or even-numbered (formula/black) paired slots
+- Determine data type -> Choose the corresponding currency (5/6) / percentage (7/8) / integer (9/10) / year (11) slot
+- Cross-sheet reference needing number format -> Append a new green + number format combination (see Section 5.4)
+- Parameter pending review -> index 12
+
+---
+
+## 5. Assumption Separation Principle: XML-Level Implementation
+
+### 5.1 Structural Design
+
+Assumption separation principle: **Input assumptions are centralized in a dedicated area (sheet or block); the model calculation area contains only formulas, no hard-coded values**.
+
+Recommended structure:
+```
+Workbook sheet layout
+  sheet 1 "Assumptions"  -> All blue-font cells (style 1/5/7/9/11/12)
+  sheet 2 "Model"        -> All black or green-font cells (style 2/3/4/6/8/10)
+```
+
+Same-sheet zoning approach for simple models:
+```
+Rows 1-5:   [Assumptions block - blue font]
+Row 6:      [Empty row separator]
+Rows 7+:    [Model block - black/green font formulas referencing assumptions area]
+```
+
+### 5.2 Assumptions Area XML Example
+
+```xml
+<!-- Assumptions sheet (sheet1.xml) example -->
+
+<!-- Row 1: Block title -->
+<row r="1">
+  <c r="A1" s="4" t="inlineStr"><is><t>Model Assumptions</t></is></c>
+</row>
+
+<!-- Row 2: Growth rate assumption - blue font percentage input, s="7" -->
+<row r="2">
+  <c r="A2" t="inlineStr"><is><t>Revenue Growth Rate</t></is></c>
+  <c r="B2" s="7"><v>0.08</v></c>
+</row>
+
+<!-- Row 3: Gross margin assumption - blue font percentage input, s="7" -->
+<row r="3">
+  <c r="A3" t="inlineStr"><is><t>Gross Margin</t></is></c>
+  <c r="B3" s="7"><v>0.65</v></c>
+</row>
+
+<!-- Row 4: Base revenue - blue font currency input, s="5" -->
+<row r="4">
+  <c r="A4" t="inlineStr"><is><t>Base Revenue (Year 0)</t></is></c>
+  <c r="B4" s="5"><v>1000000</v></c>
+</row>
+
+<!-- Row 5: Key assumption (pending review) - blue font yellow fill, s="12" -->
+<row r="5">
+  <c r="A5" t="inlineStr"><is><t>Terminal Growth Rate</t></is></c>
+  <c r="B5" s="12"><v>0.03</v></c>
+</row>
+```
+
+### 5.3 Model Area XML Example (Referencing Assumptions Area)
+
+```xml
+<!-- Model sheet (sheet2.xml) example -->
+
+<!-- Row 1: Column headers (years) - bold header, s="4"; year cells, s="11" -->
+<row r="1">
+  <c r="A1" s="4" t="inlineStr"><is><t>Metric</t></is></c>
+  <c r="B1" s="11"><v>2024</v></c>
+  <c r="C1" s="11"><v>2025</v></c>
+  <c r="D1" s="11"><v>2026</v></c>
+</row>
+
+<!-- Row 2: Revenue row -->
+<row r="2">
+  <c r="A2" t="inlineStr"><is><t>Revenue</t></is></c>
+  <!-- B2: Base year revenue, cross-sheet reference from Assumptions, green, s="3" (general format) -->
+  <!-- If currency format is needed, append new style s="13" (see Section 5.4) -->
+  <c r="B2" s="3"><f>Assumptions!B4</f><v></v></c>
+  <!-- C2, D2: Next year revenue = prior year * (1 + growth rate), black font currency formula, s="6" -->
+  <c r="C2" s="6"><f>B2*(1+Assumptions!B2)</f><v></v></c>
+  <c r="D2" s="6"><f>C2*(1+Assumptions!B2)</f><v></v></c>
+</row>
+
+<!-- Row 3: Gross profit row - black font currency formula, s="6" -->
+<row r="3">
+  <c r="A3" t="inlineStr"><is><t>Gross Profit</t></is></c>
+  <c r="B3" s="6"><f>B2*Assumptions!B3</f><v></v></c>
+  <c r="C3" s="6"><f>C2*Assumptions!B3</f><v></v></c>
+  <c r="D3" s="6"><f>D2*Assumptions!B3</f><v></v></c>
+</row>
+
+<!-- Row 4: Gross margin row - black font percentage formula, s="8" -->
+<row r="4">
+  <c r="A4" t="inlineStr"><is><t>Gross Margin %</t></is></c>
+  <c r="B4" s="8"><f>B3/B2</f><v></v></c>
+  <c r="C4" s="8"><f>C3/C2</f><v></v></c>
+  <c r="D4" s="8"><f>D3/D2</f><v></v></c>
+</row>
+```
+
+### 5.4 Appending "Green + Number Format" Combinations
+
+Pre-defined index 3 is green font + general format. If a cross-sheet reference involves a currency amount, a green style with a number format must be appended:
+
+```xml
+<!-- Append at the end of <cellXfs> in styles.xml (assuming current count=13, new index=13) -->
+<!-- index 13: cross-sheet reference + currency format (green font + $#,##0) -->
+<xf numFmtId="164" fontId="3" fillId="0" borderId="0" xfId="0"
+    applyFont="1" applyNumberFormat="1"/>
+<!-- Update count to 14 -->
+```
+
+After appending, cross-sheet reference currency cells use `s="13"`.
+
+---
+
+## 6. Complete Operational Workflow
+
+### 6.1 Workflow Overview
+
+```
+[Existing xlsx or file after CREATE/EDIT]
+        |
+  Step 1: Unpack (extract to temporary directory)
+        |
+  Step 2: Audit styles.xml (review existing styles, build index mapping table)
+        |
+  Step 3: Audit sheet XML (identify cells needing formatting and their semantic roles)
+        |
+  Step 4: Append missing styles (numFmt -> font -> fill -> xf, update counts)
+        |
+  Step 5: Batch-update the s attribute of each cell in the sheet XML
+        |
+  Step 6: XML validity + style reference integrity verification
+        |
+  Step 7: Pack (recompress as xlsx)
+```
+
+### 6.2 Step 1 — Unpack
+
+```bash
+python3 SKILL_DIR/scripts/xlsx_unpack.py input.xlsx /tmp/xlsx_fmt/
+```
+
+If the script is unavailable, unpack manually:
+```bash
+mkdir -p /tmp/xlsx_fmt && cp input.xlsx /tmp/xlsx_fmt/input.xlsx
+cd /tmp/xlsx_fmt && unzip input.xlsx -d unpacked/
+```
+
+### 6.3 Step 2 — Audit styles.xml
+
+Execute according to the method in Section 3.1. Quick check for minimal_xlsx template initial state:
+- `<cellXfs count="13">` and `<numFmts count="4">` -> Template initial state, all 13 pre-defined slots can be used directly
+- Otherwise -> A complete review of the existing index mapping is required
+
+### 6.4 Step 3 — Audit Sheet XML, Build Formatting Plan
+
+Read `xl/worksheets/sheet*.xml` and evaluate each cell:
+1. Does it contain a `<f>` element (formula)? -> Requires black/green/red style
+2. Is it a hard-coded numeric parameter? -> Requires blue style
+3. Is the data type currency/percentage/integer/year? -> Select the corresponding number format slot
+4. Is it a header? -> Bold style (index 4)
+
+Build a formatting mapping table: `{cell coordinate: target style index}`
+
+### 6.5 Step 4 — Append Styles
+
+Execute according to the atomic operation sequence in Section 3.2. Update the corresponding count attribute immediately after appending each component.
+
+### 6.6 Step 5 — Batch-Update Cell s Attributes
+
+```xml
+<!-- Before formatting: no style -->
+<c r="B5"><v>0.08</v></c>
+
+<!-- After formatting: growth rate assumption, blue font percentage, s="7" -->
+<c r="B5" s="7"><v>0.08</v></c>
+```
+
+```xml
+<!-- Before formatting: formula without style -->
+<c r="C10"><f>B10*(1+Assumptions!B2)</f><v></v></c>
+
+<!-- After formatting: currency formula, black font, s="6" -->
+<c r="C10" s="6"><f>B10*(1+Assumptions!B2)</f><v></v></c>
+```
+
+For consecutive rows of the same type, row-level default styles can be used to reduce repetition:
+```xml
+<!-- Entire row uses style=6, only override for exception cells -->
+<row r="5" s="6" customFormat="1">
+  <c r="A5" s="0" t="inlineStr"><is><t>Operating Income</t></is></c>  <!-- Text overridden to default -->
+  <c r="B5"><f>B3-B4</f><v></v></c>   <!-- Inherits row-level s=6 -->
+  <c r="C5"><f>C3-C4</f><v></v></c>
+</row>
+```
+
+### 6.7 Step 6 — Verification
+
+```bash
+# XML validity verification is handled automatically by xlsx_pack.py, no need to manually run xmllint
+# The pack script validates styles.xml and sheet XML legality before packaging; it aborts and reports on errors
+
+# Style audit (optional, audit the entire unpacked directory after formatting is complete)
+python3 SKILL_DIR/scripts/style_audit.py /tmp/xlsx_fmt/unpacked/
+
+# Formula error static scan (must specify a single .xlsx file, does not accept directories)
+# Pack first, then scan:
+python3 SKILL_DIR/scripts/xlsx_pack.py /tmp/xlsx_fmt/unpacked/ /tmp/output.xlsx
+python3 SKILL_DIR/scripts/formula_check.py /tmp/output.xlsx
+```
+
+Manual style reference integrity check:
+```bash
+# Find the maximum s attribute value in the sheet XML
+grep -o 's="[0-9]*"' /tmp/xlsx_fmt/unpacked/xl/worksheets/sheet1.xml \
+  | grep -o '[0-9]*' | sort -n | tail -1
+
+# Compare with the cellXfs count attribute (max s value must be < count)
+grep 'cellXfs count' /tmp/xlsx_fmt/unpacked/xl/styles.xml
+```
+
+### 6.8 Step 7 — Pack
+
+```bash
+python3 SKILL_DIR/scripts/xlsx_pack.py /tmp/xlsx_fmt/unpacked/ output.xlsx
+```
+
+If the script is unavailable, pack manually:
+```bash
+cd /tmp/xlsx_fmt/unpacked/
+zip -r ../output.xlsx . -x "*.DS_Store"
+```
+
+---
+
+## 7. Formatting Completeness Checklist
+
+Verify each item before delivery:
+
+### Color Role Consistency
+- [ ] All numeric cells containing `<f>` elements: fontId corresponds to black (formula) or green (cross-sheet reference)
+- [ ] All hard-coded numeric values that are user-adjustable parameters: fontId corresponds to blue (input)
+- [ ] Cross-sheet references (formula contains `SheetName!`): fontId corresponds to green
+- [ ] External file references (formula contains `[FileName.xlsx]`): fontId corresponds to red
+- [ ] No cell simultaneously contains a `<f>` element and uses blue font (color role contradiction)
+
+### Number Format Correctness
+- [ ] Year columns: numFmtId="1" (`0` format), displays as 2024 not 2,024
+- [ ] Currency rows: numFmtId="164" or variant, negative numbers display as ($1,234) not -$1,234
+- [ ] Percentage rows: values stored as decimals (0.08 = 8%), format numFmtId="165", displays as 8.0%
+- [ ] Zero values: displayed as `-` in sparse matrices rather than `0` (formatCode third segment contains `"-"`)
+- [ ] Multiple rows (EV/EBITDA, etc.): numFmtId="166" (`0.0x` format)
+- [ ] Negative number display style is consistent throughout the entire workbook (parenthetical or red minus sign)
+
+### styles.xml Structural Integrity
+- [ ] `<numFmts count>` = actual number of `<numFmt>` elements
+- [ ] `<fonts count>` = actual number of `<font>` elements
+- [ ] `<fills count>` = actual number of `<fill>` elements (including spec-mandated fills[0] and fills[1])
+- [ ] `<cellXfs count>` = actual number of `<xf>` elements
+- [ ] fills[0] is `patternType="none"`, fills[1] is `patternType="gray125"` (spec-mandated)
+- [ ] All `<xf>` referenced fontId / fillId / borderId are within the valid range of their respective collections
+- [ ] All cell `s` attribute values < `cellXfs count` (no out-of-bounds references)
+
+### Assumption Separation Verification
+- [ ] No black-font numeric cells in the assumptions area/sheet (black numeric = formula, should not be in assumptions)
+- [ ] No blue-font non-year numeric cells in the model area/sheet (blue numeric = hard-coded, should be in assumptions)
+- [ ] Input parameters in the model area reference the assumptions area via formulas, not by directly copying values
+
+### Formula and Format Linkage
+- [ ] All cells with `<f>` elements have an explicit `s` attribute (must not use default style=0, whose font color is not explicitly black)
+- [ ] SUM summary rows: style uses black font + corresponding number format (e.g., s="6" for currency summaries)
+- [ ] Percentage formulas: values stored as decimals, format is `0.0%`; do not multiply values by 100 before applying percentage format
+
+### Visual Hierarchy
+- [ ] Header rows (years/metric names): style=4 (bold black)
+- [ ] Summary rows (Total/EBITDA/Net Income): bold + corresponding number format (append style if needed)
+- [ ] Unit description rows (e.g., "$ thousands"): use style=0 or style=2 (blue not needed)
+
+---
+
+## 8. Prohibited Actions (What You Must NOT Do)
+
+- **Do not modify existing `<xf>` entries**: This will batch-change the style of all cells referencing that index
+- **Do not delete fills[0] and fills[1]**: Required by OOXML specification; deletion causes file corruption
+- **Do not modify cell values or formulas**: The FORMAT path only changes styles, not content
+- **Do not use openpyxl for formatting**: openpyxl rewrites the entire styles.xml on save, losing unsupported features
+- **Do not apply global override styles**: Do not cover the entire workbook with a single style; assign precisely by semantic role
+- **Do not write FF in the Alpha channel**: `rgb="FF0000FF"` makes the color fully transparent; the correct format is `rgb="000000FF"`
+
+---
+
+## 9. Common Errors and Fixes
+
+### Error 1: Year displays as 2,024
+
+Cause: The year cell's `s` attribute uses a format with thousands separator (e.g., numFmtId="3" or numFmtId="167").
+
+```xml
+<!-- Incorrect -->
+<c r="B1" s="9"><v>2024</v></c>
+
+<!-- Fix: Change to s="11" (numFmtId="1", format 0) -->
+<c r="B1" s="11"><v>2024</v></c>
+```
+
+### Error 2: Percentage displays as 800% (value was multiplied by 100)
+
+Cause: 8% was stored as `<v>8</v>` instead of `<v>0.08</v>`. Excel's `%` format automatically multiplies the value by 100 for display.
+
+```xml
+<!-- Incorrect -->
+<c r="B2" s="7"><v>8</v></c>
+
+<!-- Fix: Value must be stored in decimal form -->
+<c r="B2" s="7"><v>0.08</v></c>
+```
+
+### Error 3: File corruption after appending styles without updating count
+
+Cause: A `<font>` or `<xf>` element was appended but the count attribute was not updated; Excel reads beyond bounds using the old count.
+
+Fix: Update the corresponding count immediately after appending each element:
+```xml
+<!-- After appending the 6th font, count must be changed from 5 to 6 -->
+<fonts count="6">
+  ...
+</fonts>
+```
+
+### Error 4: Blue font + formula (color role contradiction)
+
+Cause: A formula cell mistakenly uses an input style (e.g., s="5" for currency input).
+
+```xml
+<!-- Incorrect: Formula cell uses blue input style -->
+<c r="C5" s="5"><f>B5*1.08</f><v></v></c>
+
+<!-- Fix: Change formula cell to corresponding black formula style (5->6, 7->8, 9->10) -->
+<c r="C5" s="6"><f>B5*1.08</f><v></v></c>
+```
+
+### Error 5: AARRGGBB color missing Alpha (only 6 digits)
+
+```xml
+<!-- Incorrect: 6-digit format, behavior depends on implementation, usually causes wrong color -->
+<color rgb="0000FF"/>
+
+<!-- Fix: Always use 8-digit AARRGGBB, Alpha fixed at 00 -->
+<color rgb="000000FF"/>
+```
+
+### Error 6: Modifying existing xf (affects all cells referencing that index)
+
+Cause: Directly modifying attributes of the Nth `<xf>` in cellXfs, causing all cells with `s="N"` to be batch-changed.
+
+Fix: Keep existing entries unchanged, append a new entry at the end, and only change the `s` attribute of cells that need the new style to the new index:
+```xml
+<!-- Incorrect: Modified the existing xf at index=6 -->
+<xf numFmtId="164" fontId="2" fillId="0" borderId="0" xfId="0"
+    applyFont="1" applyNumberFormat="1" applyAlignment="1">
+  <alignment horizontal="right"/>  <!-- New attribute added, affects ALL cells already using s="6" -->
+</xf>
+
+<!-- Fix: Append new index (when original count=13, new index=13), only change the s attribute of cells needing right alignment -->
+<!-- Keep index=6 as-is -->
+<xf numFmtId="164" fontId="2" fillId="0" borderId="0" xfId="0"
+    applyFont="1" applyNumberFormat="1" applyAlignment="1">
+  <alignment horizontal="right"/>
+</xf>  <!-- New index=13 -->
+```
+
+---
+
+## 10. Financial Model Structure Conventions
+
+### 10.1 Header Rows
+
+- Bold font (corresponds to style index 4 in this skill's template)
+- Year columns: use number format `0` (numFmtId="1", no thousands separator) to prevent 2024 from displaying as 2,024
+- A unit description row may be added below headers: gray or italic text, e.g., "$ thousands" or "% of Revenue"
+
+### 10.2 Row Type Standards
+
+| Row Type | Style Recommendation | Example |
+|----------|---------------------|---------|
+| Category heading row | Bold, optionally with fill color | "Revenue" |
+| Line item row | Normal style | "Product A", "Product B" |
+| Subtotal row | Bold + top border | "Total Revenue" |
+| Operating metric row | Normal style | "Gross Margin %" |
+| Separator row | Empty row | (empty) |
+
+### 10.3 Multi-Year Model Column Layout
+
+```
+Col A: Label column          (width 28, left-aligned text, s="4" for headers or s="0" for labels)
+Col B: FY2022 Actual         (width 12, year header s="11", data cells styled by semantic role)
+Col C: FY2023 Actual
+Col D: FY2024E               (forecast period - can use light gray fill fillId=3 to differentiate)
+Col E: FY2025E
+Col F: FY2026E
+```
+
+### 10.4 Cross-Sheet Reference Patterns
+
+Complete XML example of parameters passing from assumptions sheet to model sheet:
+
+```xml
+<!-- Assumptions sheet, cell B5: 8% growth rate, blue percentage input -->
+<c r="B5" s="7"><v>0.08</v></c>
+
+<!-- Model sheet, cell C10: references assumption area growth rate, green percentage formula -->
+<!-- Requires appending index=13: green + percentage format (fontId=3, numFmtId=165) -->
+<c r="C10" s="13"><f>Assumptions!B5</f><v></v></c>
+```
+
+---
+
+## 11. Assumption Categories
+
+In the assumptions area (Assumptions sheet or assumptions block), organize assumptions in the following standard order for ease of review and maintenance:
+
+1. **Revenue assumptions**: Growth rates, pricing, sales volume
+2. **Cost assumptions**: Gross margin, fixed/variable cost ratios
+3. **Working capital**: DSO (Days Sales Outstanding), DPO (Days Payable Outstanding), inventory days
+4. **Capital expenditures (CapEx)**: As a percentage of revenue or absolute amounts
+5. **Financing assumptions**: Interest rates, debt repayment schedules
+6. **Tax and other**: Effective tax rate, depreciation & amortization (D&A)
+
+---
+
+## 12. Audit Trail Best Practices
+
+- Use `s="12"` (blue font + yellow fill highlight) to mark cells requiring review or pending changes, making them immediately visible to reviewers
+- In sensitivity analysis rows or a separate Sensitivity tab, show the impact of +/-1% changes in key assumptions on results
+- **Do not hide rows containing assumptions**: Assumption rows must be visible to reviewers; do not use the `hidden="1"` attribute
+- Note a "Last Updated" date at the top of the assumptions area or in a dedicated cell, recording the last modification time of the model
+
+---
+
+## 13. Pre-Delivery Checklist (Common Financial Model Checklist)
+
+Before outputting the final file, confirm each item:
+
+- [ ] Formula rows contain no hard-coded values (can use `formula_check.py` to scan the packaged `.xlsx` file)
+- [ ] Year columns display as 2024 not 2,024 (numFmtId="1", format `0`)
+- [ ] Negative numbers display as (1,234) not -1,234 (use parenthetical style for externally delivered financial reports)
+- [ ] Zero values display as `-` in sparse rows rather than `0` (formatCode third segment is `"-"`)
+- [ ] Growth rates and percentages are stored as decimals (0.08 = 8%), format is `0.0%`
+- [ ] All cross-sheet reference cells use green font (style index 3 or an appended green + number format combination)
+- [ ] Assumptions block and model block are clearly separated (different sheets or separated by empty rows within the same sheet)
+- [ ] Summary rows use `SUM()` formulas, not manually hard-coded totals
+- [ ] Balance verification: summary rows = sum of their respective line items (a check row can be added at the end of the model to verify)
diff --git a/builtin-skills/document-process/minimax-xlsx/references/ooxml-cheatsheet.md b/builtin-skills/document-process/minimax-xlsx/references/ooxml-cheatsheet.md
new file mode 100644
index 00000000..ed1393fc
--- /dev/null
+++ b/builtin-skills/document-process/minimax-xlsx/references/ooxml-cheatsheet.md
@@ -0,0 +1,231 @@
+# OOXML SpreadsheetML Cheat Sheet
+
+Quick reference for XML manipulation of xlsx files.
+
+---
+
+## Package Structure
+
+```
+my_file.xlsx  (ZIP archive)
+├── [Content_Types].xml          ← declares MIME types for all files
+├── _rels/
+│   └── .rels                    ← root relationship: points to xl/workbook.xml
+└── xl/
+    ├── workbook.xml             ← sheet list, calc settings
+    ├── styles.xml               ← ALL style definitions
+    ├── sharedStrings.xml        ← ALL text strings (referenced by index)
+    ├── _rels/
+    │   └── workbook.xml.rels    ← maps r:id → worksheet/styles/sharedStrings files
+    ├── worksheets/
+    │   ├── sheet1.xml           ← Sheet 1 data
+    │   ├── sheet2.xml           ← Sheet 2 data
+    │   └── ...
+    ├── charts/                  ← chart XML (if any)
+    ├── pivotTables/             ← pivot table XML (if any)
+    └── theme/
+        └── theme1.xml           ← color/font theme
+```
+
+---
+
+## Cell Reference Format
+
+```
+A1  → column A (1), row 1
+B5  → column B (2), row 5
+AA1 → column 27, row 1
+```
+
+Column letter ↔ number conversion:
+```python
+def col_letter(n):  # 1-based → letter
+    r = ""
+    while n > 0:
+        n, rem = divmod(n - 1, 26)
+        r = chr(65 + rem) + r
+    return r
+
+def col_number(s):  # letter → 1-based
+    n = 0
+    for c in s.upper():
+        n = n * 26 + (ord(c) - 64)
+    return n
+```
+
+---
+
+## Cell XML Reference
+
+### Data Types
+
+| Type | `t` attr | XML Example | Value |
+|------|---------|-------------|-------|
+| Number | omit | `<c r="B2"><v>1000</v></c>` | 1000 |
+| String (shared) | `s` | `<c r="A1" t="s"><v>0</v></c>` | sharedStrings[0] |
+| String (inline) | `inlineStr` | `<c r="A1" t="inlineStr"><is><t>Hi</t></is></c>` | "Hi" |
+| Boolean | `b` | `<c r="D1" t="b"><v>1</v></c>` | TRUE |
+| Error | `e` | `<c r="E1" t="e"><v>#REF!</v></c>` | #REF! |
+| Formula | omit | `<c r="B4"><f>SUM(B2:B3)</f><v></v></c>` | computed |
+
+### Formula Types
+
+```xml
+<!-- Basic formula (no leading = in XML!) -->
+<c r="B4"><f>SUM(B2:B3)</f><v></v></c>
+
+<!-- Cross-sheet -->
+<c r="C1"><f>Assumptions!B5</f><v></v></c>
+<c r="C1"><f>'Sheet With Spaces'!B5</f><v></v></c>
+
+<!-- Shared formula: D2:D100 all use B*C with relative row offset -->
+<c r="D2"><f t="shared" ref="D2:D100" si="0">B2*C2</f><v></v></c>
+<c r="D3"><f t="shared" si="0"/><v></v></c>
+
+<!-- Array formula -->
+<c r="E1"><f t="array" ref="E1:E5">SORT(A1:A5)</f><v></v></c>
+```
+
+---
+
+## styles.xml Reference
+
+### Indirect Reference Chain
+
+```
+Cell s="3"
+  ↓
+cellXfs[3] → fontId="2", fillId="0", borderId="0", numFmtId="165"
+  ↓              ↓             ↓            ↓              ↓
+fonts[2]      fills[0]    borders[0]    numFmts: id=165
+blue color    no fill      no border    "0.0%"
+```
+
+### Adding a New Style (step-by-step)
+
+1. In `<numFmts>`: add `<numFmt numFmtId="168" formatCode="0.00%"/>`, update `count`
+2. In `<fonts>`: add font entry, note its index
+3. In `<cellXfs>`: append `<xf numFmtId="168" fontId="N" .../>`, update `count`
+4. New style index = old `cellXfs count` value (before incrementing)
+5. Apply to cells: `<c r="B5" s="NEW_INDEX">...</c>`
+
+### Color Format
+
+`AARRGGBB` — Alpha (always `00` for opaque) + Red + Green + Blue
+
+```
+000000FF → Blue
+00000000 → Black
+00008000 → Green (dark)
+00FF0000 → Red
+00FFFF00 → Yellow (for fills)
+00FFFFFF → White
+```
+
+### Built-in numFmtIds (no declaration needed)
+
+| ID | Format | Display |
+|----|--------|---------|
+| 0 | General | as-is |
+| 1 | 0 | 2024 (use for years!) |
+| 2 | 0.00 | 1000.00 |
+| 3 | #,##0 | 1,000 |
+| 4 | #,##0.00 | 1,000.00 |
+| 9 | 0% | 15% |
+| 10 | 0.00% | 15.25% |
+| 14 | m/d/yyyy | 3/21/2026 |
+
+---
+
+## sharedStrings.xml Reference
+
+```xml
+<sst count="3" uniqueCount="3">
+  <si><t>Revenue</t></si>      <!-- index 0 -->
+  <si><t>Cost</t></si>         <!-- index 1 -->
+  <si><t>Margin</t></si>       <!-- index 2 -->
+</sst>
+```
+
+Text with leading/trailing spaces:
+```xml
+<si><t xml:space="preserve">  indented  </t></si>
+```
+
+Special characters:
+```xml
+<si><t>R&amp;D Expenses</t></si>   <!-- & must be &amp; -->
+```
+
+---
+
+## workbook.xml / .rels Sync
+
+Every `<sheet>` in workbook.xml needs a matching `<Relationship>` in workbook.xml.rels:
+
+```xml
+<!-- workbook.xml -->
+<!-- NOTE: rId numbering depends on what rIds are already in workbook.xml.rels.
+     The minimal template reserves rId1=sheet1, rId2=styles, rId3=sharedStrings.
+     When ADDING sheets to the template, start from rId4 to avoid conflicts.
+     The rId3 here is just a generic illustration — use the next available rId. -->
+<sheet name="Summary" sheetId="3" r:id="rId3"/>
+
+<!-- workbook.xml.rels -->
+<Relationship Id="rId3"
+  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet"
+  Target="worksheets/sheet3.xml"/>
+```
+
+And a matching `<Override>` in `[Content_Types].xml`:
+```xml
+<Override PartName="/xl/worksheets/sheet3.xml"
+  ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>
+```
+
+---
+
+## Column / Row Dimensions
+
+```xml
+<!-- Before <sheetData> -->
+<cols>
+  <col min="1" max="1" width="28" customWidth="1"/>   <!-- A: 28 chars -->
+  <col min="2" max="6" width="14" customWidth="1"/>   <!-- B-F: 14 chars -->
+</cols>
+
+<!-- Row height on individual rows -->
+<row r="1" ht="20" customHeight="1">
+  ...
+</row>
+```
+
+---
+
+## Freeze Panes
+
+Inside `<sheetView>`:
+```xml
+<!-- Freeze row 1 (header row stays visible) -->
+<pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/>
+
+<!-- Freeze column A -->
+<pane xSplit="1" topLeftCell="B1" activePane="topRight" state="frozen"/>
+
+<!-- Freeze both row 1 and column A -->
+<pane xSplit="1" ySplit="1" topLeftCell="B2" activePane="bottomRight" state="frozen"/>
+```
+
+---
+
+## 7 Excel Error Types (All Must Be Absent at Delivery)
+
+| Error | Meaning | Detect in XML |
+|-------|---------|---------------|
+| `#REF!` | Invalid cell reference | `<c t="e"><v>#REF!</v></c>` |
+| `#DIV/0!` | Divide by zero | `<c t="e"><v>#DIV/0!</v></c>` |
+| `#VALUE!` | Wrong data type | `<c t="e"><v>#VALUE!</v></c>` |
+| `#NAME?` | Unknown function/name | `<c t="e"><v>#NAME?</v></c>` |
+| `#NULL!` | Empty intersection | `<c t="e"><v>#NULL!</v></c>` |
+| `#NUM!` | Number out of range | `<c t="e"><v>#NUM!</v></c>` |
+| `#N/A` | Value not found | `<c t="e"><v>#N/A</v></c>` |
diff --git a/builtin-skills/document-process/minimax-xlsx/references/read-analyze.md b/builtin-skills/document-process/minimax-xlsx/references/read-analyze.md
new file mode 100644
index 00000000..15337dfc
--- /dev/null
+++ b/builtin-skills/document-process/minimax-xlsx/references/read-analyze.md
@@ -0,0 +1,97 @@
+# Data Reading & Analysis Guide
+
+> Reference for the READ path. Use `xlsx_reader.py` for structure discovery and data quality auditing,
+> then pandas for custom analysis. **Never modify the source file.**
+
+---
+
+## When to Use This Path
+
+The user asks to read, analyze, view, summarize, extract, or answer questions about an Excel/CSV file's contents,
+without requiring file modification. If modification is needed, hand off to `edit.md`.
+
+---
+
+## Workflow
+
+### Step 1 — Structure Discovery
+
+Run `xlsx_reader.py` first. It handles format detection, encoding fallback, structure exploration, and data quality audit:
+
+```bash
+python3 SKILL_DIR/scripts/xlsx_reader.py input.xlsx                 # full report
+python3 SKILL_DIR/scripts/xlsx_reader.py input.xlsx --sheet Sales   # single sheet
+python3 SKILL_DIR/scripts/xlsx_reader.py input.xlsx --quality       # quality audit only
+python3 SKILL_DIR/scripts/xlsx_reader.py input.xlsx --json          # machine-readable
+```
+
+Supported formats: `.xlsx`, `.xlsm`, `.csv`, `.tsv`. The script tries multiple encodings for CSV (utf-8-sig, gbk, utf-8, latin-1).
+
+### Step 2 — Custom Analysis with pandas
+
+Load data and perform the analysis the user requests:
+
+```python
+import pandas as pd
+df = pd.read_excel("input.xlsx", sheet_name=None)  # dict of all sheets
+# For CSV: pd.read_csv("input.csv")
+```
+
+**Header handling** (when the default `header=0` doesn't work):
+
+| Situation | Code |
+|-----------|------|
+| Header on row 3 | `pd.read_excel(path, header=2)` |
+| Multi-level merged header | `pd.read_excel(path, header=[0, 1])` |
+| No header | `pd.read_excel(path, header=None)` |
+
+**Analysis quick reference:**
+
+| Scenario | Pattern |
+|----------|---------|
+| Descriptive stats | `df.describe()` or `df['Col'].agg(['sum', 'mean', 'min', 'max'])` |
+| Group aggregation | `df.groupby('Region')['Revenue'].agg(Total='sum', Avg='mean')` |
+| Top N | `df.groupby('Region')['Revenue'].sum().sort_values(ascending=False).head(5)` |
+| Pivot table | `df.pivot_table(values='Revenue', index='Region', columns='Quarter', aggfunc='sum', margins=True)` |
+| Time series | `df.set_index(pd.to_datetime(df['Date'])).resample('ME')['Revenue'].sum()` |
+| Cross-sheet merge | `pd.merge(sales, customers, on='CustomerID', how='left', validate='m:1')` |
+| Stack sheets | `pd.concat([df.assign(Source=name) for name, df in sheets.items()], ignore_index=True)` |
+| Large files (>50MB) | `pd.read_excel(path, usecols=['Date', 'Revenue'])` or `pd.read_csv(path, chunksize=10000)` |
+
+### Step 3 — Output
+
+If the user specifies an output file path, write results to it (highest priority). Format the report as:
+
+```
+## Analysis Report: {filename}
+### File Overview     — format, sheets, row counts
+### Data Quality      — nulls, duplicates, mixed types (or "no issues")
+### Key Findings      — direct answer to the user's question
+### Additional Notes  — formula NaN, encoding issues, caveats
+```
+
+**Numeric display**: monetary `1,234,567.89`, percentage `12.3%`, multiples `8.5x`, counts as integers.
+
+---
+
+## Common Pitfalls
+
+| Pitfall | Cause | Fix |
+|---------|-------|-----|
+| Formula cells read as NaN | `<v>` cache empty in freshly generated files | Inform user; suggest opening in Excel and re-saving; or use `libreoffice_recalc.py` |
+| CSV encoding errors | Chinese Windows exports use GBK | `xlsx_reader.py` auto-tries multiple encodings; manually specify if all fail |
+| Mixed types in column | Column has both numbers and text (e.g., "N/A") | `pd.to_numeric(df['Col'], errors='coerce')` — report unconvertible rows |
+| Year shows as 2,024 | Thousands separator format applied to year | `df['Year'].astype(int).astype(str)` |
+| Multi-level headers | Two-row header merged | `pd.read_excel(path, header=[0, 1])`, then flatten with `' - '.join()` |
+| Row number mismatch | pandas 0-indexed vs Excel 1-indexed | `excel_row = pandas_index + 2` (+1 for 1-index, +1 for header) |
+
+**Critical**: Never open with `data_only=True` then `save()` — this permanently destroys all formulas.
+
+---
+
+## Prohibitions
+
+- Never modify the source file (no `save()`, no XML edits)
+- Never report formula NaN as "data is zero" — explain it's a formula cache issue
+- Never report pandas indices as Excel row numbers
+- Never make speculative conclusions unsupported by the data
diff --git a/builtin-skills/document-process/minimax-xlsx/references/validate.md b/builtin-skills/document-process/minimax-xlsx/references/validate.md
new file mode 100644
index 00000000..c02e261a
--- /dev/null
+++ b/builtin-skills/document-process/minimax-xlsx/references/validate.md
@@ -0,0 +1,772 @@
+# Formula Validation & Recalculation Guide
+
+Ensure every formula in an xlsx file is provably correct before delivery. A file that opens without visible errors is not a passing file — only a file that has cleared both validation tiers is a passing file.
+
+---
+
+## Foundational Rules
+
+- **Never declare PASS without running `formula_check.py` first.** Visual inspection of a spreadsheet is not validation.
+- **Tier 1 (static) is mandatory in every scenario.** Tier 2 (dynamic) is mandatory when LibreOffice is available. If it is unavailable, you must state this explicitly in the report — you may not silently skip it.
+- **Never use openpyxl with `data_only=True` to check formula values.** Opening and saving a workbook in `data_only=True` mode permanently replaces all formulas with their last cached values. Formulas cannot be recovered afterward.
+- **Auto-fix only deterministic errors.** Any fix that requires understanding business logic must be flagged for human review.
+
+---
+
+## Two-Tier Validation Architecture
+
+```
+Tier 1 — Static Validation (XML scan, no external tools)
+  │
+  ├── Detect: all 7 Excel error types already cached in <v> elements
+  ├── Detect: cross-sheet references pointing to nonexistent sheets
+  ├── Detect: formula cells with t="e" attribute (error type marker)
+  └── Tool: formula_check.py + manual XML inspection
+        │
+        ▼ (if LibreOffice is present)
+Tier 2 — Dynamic Validation (LibreOffice headless recalculation)
+  │
+  ├── Executes all formulas via the LibreOffice Calc engine
+  ├── Populates <v> cache values with real computed results
+  ├── Exposes runtime errors invisible before recalculation
+  └── Follow-up: re-run Tier 1 on the recalculated file
+```
+
+**Why two tiers?**
+
+openpyxl and all Python xlsx libraries write formula strings (e.g. `=SUM(B2:B9)`) into `<f>` elements but do not evaluate them. A freshly generated file has empty `<v>` cache elements for every formula cell. This means:
+
+- Tier 1 can only catch errors that are already encoded in the XML — either as `t="e"` cells or as structurally broken cross-sheet references.
+- Tier 2 uses LibreOffice as the actual calculation engine, runs every formula, fills `<v>` with real results, and surfaces runtime errors (`#DIV/0!`, `#N/A`, etc.) that can only appear after computation.
+
+Neither tier alone is sufficient. Together they cover the full correctability surface.
+
+---
+
+## Tier 1 — Static Validation
+
+Static validation requires no external tools. It works directly on the ZIP/XML structure of the xlsx file.
+
+### Step 1: Run formula_check.py
+
+**Standard (human-readable) output:**
+
+```bash
+python3 SKILL_DIR/scripts/formula_check.py /path/to/file.xlsx
+```
+
+**JSON output (for programmatic processing):**
+
+```bash
+python3 SKILL_DIR/scripts/formula_check.py /path/to/file.xlsx --json
+```
+
+**Single-sheet mode (faster for targeted checks):**
+
+```bash
+python3 SKILL_DIR/scripts/formula_check.py /path/to/file.xlsx --sheet Summary
+```
+
+**Summary mode (counts only, no per-cell detail):**
+
+```bash
+python3 SKILL_DIR/scripts/formula_check.py /path/to/file.xlsx --summary
+```
+
+Exit codes:
+- `0` — no hard errors (PASS or PASS with heuristic warnings)
+- `1` — hard errors detected, or file cannot be opened (FAIL)
+
+#### What formula_check.py examines
+
+The script opens the xlsx as a ZIP archive without using any Excel library. It reads `xl/workbook.xml` to enumerate sheet names and named ranges, reads `xl/_rels/workbook.xml.rels` to map each sheet to its XML file, then iterates every `<c>` element in every worksheet.
+
+It performs five checks:
+
+1. **Error-value detection**: If the cell has `t="e"`, its `<v>` element contains an Excel error string. The cell is recorded with its sheet name, cell reference (e.g. `C5`), the error value, and the formula text if present.
+
+2. **Broken cross-sheet reference detection**: If the cell has an `<f>` element, the script extracts all sheet names referenced in the formula (both `SheetName!` and `'Sheet Name'!` syntax). Each name is compared against the list of sheets in `workbook.xml`. A mismatch is a broken reference.
+
+3. **Unknown named-range detection (heuristic)**: Identifiers in formulas that are not function names, not cell references, and not found in `workbook.xml`'s `<definedNames>` are flagged as `unknown_name_ref` warnings. This is a heuristic — false positives are possible; always verify manually.
+
+4. **Shared formula integrity**: Shared formula consumer cells (those with only `<f t="shared" si="N"/>`) are skipped for formula counting and cross-ref checks because they inherit the primary cell's formula. Only the primary cell (with `ref="..."` attribute and formula text) is checked and counted.
+
+5. **Malformed error cells**: Cells with `t="e"` but no `<v>` child element are flagged as structural XML issues.
+
+Hard errors (exit code 1): `error_value`, `broken_sheet_ref`, `malformed_error_cell`, `file_error`
+Soft warnings (exit code 0): `unknown_name_ref` — must be verified manually but do not block delivery alone
+
+#### Reading formula_check.py human-readable output
+
+A clean file looks like this:
+
+```
+File   : /tmp/budget_2024.xlsx
+Sheets : Summary, Q1, Q2, Q3, Q4, Assumptions
+Formulas checked      : 312 distinct formula cells
+Shared formula ranges : 4 ranges
+Errors found          : 0
+
+PASS — No formula errors detected
+```
+
+A file with errors looks like this:
+
+```
+File   : /tmp/budget_2024.xlsx
+Sheets : Summary, Q1, Q2, Q3, Q4, Assumptions
+Formulas checked      : 312 distinct formula cells
+Shared formula ranges : 4 ranges
+Errors found          : 4
+
+── Error Details ──
+  [FAIL] [Summary!C12] contains #REF! (formula: Q1!A0/Q1!A1)
+  [FAIL] [Summary!D15] references missing sheet 'Q5'
+         Formula: Q5!D15
+         Valid sheets: ['Assumptions', 'Q1', 'Q2', 'Q3', 'Q4', 'Summary']
+  [FAIL] [Q1!F8] contains #DIV/0!
+  [WARN] [Q2!B10] uses unknown name 'GrowthAssumptions' (heuristic — verify manually)
+         Formula: SUM(GrowthAssumptions)
+         Defined names: ['RevenueRange', 'CostRange']
+
+FAIL — 3 error(s) must be fixed before delivery
+WARN — 1 heuristic warning(s) require manual review
+```
+
+Interpretation of each line:
+- `[FAIL] [Summary!C12] contains #REF! (formula: Q1!A0/Q1!A1)` — The cell has `t="e"` and `<v>#REF!</v>`. The formula references row 0, which does not exist in Excel's 1-based system. This is an off-by-one error in a generated reference.
+- `[FAIL] [Summary!D15] references missing sheet 'Q5'` — The formula contains `Q5!D15`, but no sheet named `Q5` exists in the workbook. The valid sheet list is provided for comparison.
+- `[FAIL] [Q1!F8] contains #DIV/0!` — This cell's `<v>` is already an error value (the file was previously recalculated). The formula divided by zero.
+- `[WARN] [Q2!B10] uses unknown name 'GrowthAssumptions'` — The identifier `GrowthAssumptions` appears in the formula but is not in `<definedNames>`. This may be a typo or a name that was accidentally omitted. It is a heuristic warning — verify manually. The warning alone does not block delivery.
+
+#### Reading formula_check.py JSON output
+
+```json
+{
+  "file": "/tmp/budget_2024.xlsx",
+  "sheets_checked": ["Summary", "Q1", "Q2", "Q3", "Q4", "Assumptions"],
+  "formula_count": 312,
+  "shared_formula_ranges": 4,
+  "error_count": 4,
+  "errors": [
+    {
+      "type": "error_value",
+      "error": "#REF!",
+      "sheet": "Summary",
+      "cell": "C12",
+      "formula": "Q1!A0/Q1!A1"
+    },
+    {
+      "type": "broken_sheet_ref",
+      "sheet": "Summary",
+      "cell": "D15",
+      "formula": "Q5!D15",
+      "missing_sheet": "Q5",
+      "valid_sheets": ["Assumptions", "Q1", "Q2", "Q3", "Q4", "Summary"]
+    },
+    {
+      "type": "error_value",
+      "error": "#DIV/0!",
+      "sheet": "Q1",
+      "cell": "F8",
+      "formula": null
+    },
+    {
+      "type": "unknown_name_ref",
+      "sheet": "Q2",
+      "cell": "B10",
+      "formula": "SUM(GrowthAssumptions)",
+      "unknown_name": "GrowthAssumptions",
+      "defined_names": ["RevenueRange", "CostRange"],
+      "note": "Heuristic check — verify manually if this is a false positive"
+    }
+  ]
+}
+```
+
+Field reference:
+
+| Field | Meaning |
+|-------|---------|
+| `type: "error_value"` | Cell has `t="e"` — an Excel error is stored in the `<v>` element |
+| `type: "broken_sheet_ref"` | Formula references a sheet name not present in workbook.xml |
+| `type: "unknown_name_ref"` | Formula references an identifier not in `<definedNames>` (heuristic, soft warning) |
+| `type: "malformed_error_cell"` | Cell has `t="e"` but no `<v>` child — structural XML problem |
+| `type: "file_error"` | The file could not be opened (bad ZIP, not found, etc.) |
+| `sheet` | The sheet where the error was found |
+| `cell` | Cell reference in A1 notation |
+| `formula` | The full formula text from the `<f>` element (null if not present) |
+| `error` | The error string from `<v>` (for `error_value` type) |
+| `missing_sheet` | The sheet name extracted from the formula that does not exist |
+| `valid_sheets` | All sheet names actually present in workbook.xml |
+| `unknown_name` | The identifier that was not found in `<definedNames>` |
+| `defined_names` | All named ranges actually present in workbook.xml |
+| `shared_formula_ranges` | Count of shared formula definitions (top-level `<f t="shared" ref="...">` elements) |
+
+### Step 2: Manual XML inspection
+
+When formula_check.py reports errors, unpack the file to inspect the raw XML:
+
+```bash
+python3 SKILL_DIR/scripts/xlsx_unpack.py /path/to/file.xlsx /tmp/xlsx_inspect/
+```
+
+Navigate to the worksheet file for the reported sheet. The sheet-to-file mapping is in `xl/_rels/workbook.xml.rels`. For example, if `rId1` maps to `worksheets/sheet1.xml`, then sheet1.xml is the file for the sheet with `r:id="rId1"` in `xl/workbook.xml`.
+
+For each reported error cell, locate the `<c r="CELLREF">` element and examine:
+
+**For `error_value` errors:**
+```xml
+<!-- This is what an error cell looks like in XML -->
+<c r="C12" t="e">
+  <f>Q1!C10/Q1!C11</f>
+  <v>#DIV/0!</v>
+</c>
+```
+
+Ask:
+- Is the `<f>` formula syntactically correct?
+- Does the cell reference in the formula point to a row/column that exists?
+- If it is a division, is it possible the denominator cell is empty or zero?
+
+**For `broken_sheet_ref` errors:**
+
+Check `xl/workbook.xml` for the actual sheet list:
+
+```xml
+<sheets>
+  <sheet name="Summary" sheetId="1" r:id="rId1"/>
+  <sheet name="Q1"      sheetId="2" r:id="rId2"/>
+  <sheet name="Q2"      sheetId="3" r:id="rId3"/>
+</sheets>
+```
+
+Sheet names are case-sensitive. `q1` and `Q1` are different sheets. Compare the name in the formula exactly against the names here.
+
+### Step 3: Cross-sheet reference audit (multi-sheet workbooks)
+
+For workbooks with 3 or more sheets, run a broader cross-reference audit after unpacking:
+
+```bash
+# Extract all formulas containing cross-sheet references
+grep -h "<f>" /tmp/xlsx_inspect/xl/worksheets/*.xml | grep "!"
+
+# List all actual sheet names from workbook.xml
+grep -o 'name="[^"]*"' /tmp/xlsx_inspect/xl/workbook.xml | grep -v sheetId
+```
+
+Every sheet name appearing in formulas (in the form `SheetName!` or `'Sheet Name'!`) must appear in the workbook sheet list. If any do not match, that is a broken reference even if formula_check.py did not catch it (which can happen with shared formulas where only the primary cell is examined).
+
+To check shared formulas specifically, look for `<f t="shared" ref="...">` elements:
+
+```xml
+<!-- Shared formula: defined on D2, applied to D2:D100 -->
+<c r="D2"><f t="shared" ref="D2:D100" si="0">Q1!B2*C2</f><v></v></c>
+
+<!-- Shared formula consumers: only si is present, no formula text -->
+<c r="D3"><f t="shared" si="0"/><v></v></c>
+```
+
+formula_check.py reads the formula text from the primary cell (`D2` above). The referenced sheet `Q1` in that formula applies to the entire range `D2:D100`. If the sheet is broken, all 99 rows are broken even though they appear as empty `<f>` elements.
+
+---
+
+## Tier 2 — Dynamic Validation (LibreOffice Headless)
+
+### Check LibreOffice availability
+
+```bash
+# Check macOS (typical install location)
+which soffice
+/Applications/LibreOffice.app/Contents/MacOS/soffice --version
+
+# Check Linux
+which libreoffice || which soffice
+libreoffice --version
+```
+
+If neither command returns a path, LibreOffice is not installed. Record "Tier 2: SKIPPED — LibreOffice not available" in the report and proceed to delivery with Tier 1 results only.
+
+### Install LibreOffice (if permitted in the environment)
+
+macOS:
+```bash
+brew install --cask libreoffice
+```
+
+Ubuntu/Debian:
+```bash
+sudo apt-get install -y libreoffice
+```
+
+### Run headless recalculation
+
+Use the dedicated recalculation script. It handles binary discovery across macOS and Linux, works from a temporary copy of the input (preserving the original), and provides structured output and exit codes compatible with the validation pipeline.
+
+```bash
+# Check LibreOffice availability first
+python3 SKILL_DIR/scripts/libreoffice_recalc.py --check
+
+# Run recalculation (default timeout: 60s)
+python3 SKILL_DIR/scripts/libreoffice_recalc.py /path/to/input.xlsx /tmp/recalculated.xlsx
+
+# For large or complex files, extend the timeout
+python3 SKILL_DIR/scripts/libreoffice_recalc.py /path/to/input.xlsx /tmp/recalculated.xlsx --timeout 120
+```
+
+Exit codes from `libreoffice_recalc.py`:
+- `0` — recalculation succeeded, output file written
+- `2` — LibreOffice not found (note as SKIPPED in report; not a hard failure)
+- `1` — LibreOffice found but failed (timeout, crash, malformed file)
+
+**What the script does internally:**
+
+LibreOffice's `--convert-to xlsx` command opens the file using the full Calc engine with the `--infilter="Calc MS Excel 2007 XML"` filter, executes every formula, writes computed values into the `<v>` cache elements, and saves the output. This is the closest server-side equivalent of "open in Excel and press Save." The script also passes `--norestore` to prevent LibreOffice from attempting to restore previous sessions, which can cause hangs in automated environments.
+
+**If LibreOffice is not installed:**
+
+macOS:
+```bash
+brew install --cask libreoffice
+```
+
+Ubuntu/Debian:
+```bash
+sudo apt-get install -y libreoffice
+```
+
+**If the script times out (libreoffice_recalc.py exits with code 1 and "timed out" message):**
+
+Record "Tier 2: TIMEOUT — LibreOffice did not complete within Ns" in the report. Do not retry in a loop. Investigate whether the file has circular references or extremely large data ranges.
+
+### Re-run Tier 1 after recalculation
+
+After LibreOffice recalculation, the `<v>` elements contain real computed values. Errors that were invisible before (because `<v>` was empty in a freshly generated file) now appear as `t="e"` cells with actual error strings.
+
+```bash
+python3 SKILL_DIR/scripts/formula_check.py /tmp/recalculated.xlsx
+```
+
+This second Tier 1 pass is the definitive runtime error check. Any errors it finds are real calculation failures that must be fixed.
+
+---
+
+## All 7 Error Types — Causes and Fix Strategies
+
+### #REF! — Invalid Cell Reference
+
+**What it means:** The formula references a cell, range, or sheet that no longer exists or never existed.
+
+**Common causes in generated files:**
+- Off-by-one error in row/column calculation (e.g., referencing row 0 which does not exist in Excel's 1-based system)
+- Column letter computed incorrectly (e.g., column 64 maps to `BL`, not `BK`)
+- Formula references a sheet that was never created or was renamed
+
+**XML signature:**
+```xml
+<c r="D5" t="e">
+  <f>Sheet2!A0</f>
+  <v>#REF!</v>
+</c>
+```
+
+**Fix — correct the reference:**
+```xml
+<c r="D5">
+  <f>Sheet2!A1</f>
+  <v></v>
+</c>
+```
+
+Note: remove `t="e"` and clear `<v>` after correcting the formula. The error type marker belongs to the cached state, not the formula.
+
+**Auto-fixable?** Only if the correct target can be determined with certainty from the surrounding context. Otherwise flag for human review.
+
+---
+
+### #DIV/0! — Division by Zero
+
+**What it means:** The formula divides by a value that is zero or an empty cell (empty cells evaluate to 0 in arithmetic context).
+
+**Common causes in generated files:**
+- Percentage change formula `=(B2-B1)/B1` where `B1` is empty or zero
+- Rate formula `=Value/Total` where the total row hasn't been populated yet
+
+**XML signature:**
+```xml
+<c r="C8" t="e">
+  <f>B8/B7</f>
+  <v>#DIV/0!</v>
+</c>
+```
+
+**Fix — wrap with IFERROR:**
+```xml
+<c r="C8">
+  <f>IFERROR(B8/B7,0)</f>
+  <v></v>
+</c>
+```
+
+Alternative — explicit zero check:
+```xml
+<c r="C8">
+  <f>IF(B7=0,0,B8/B7)</f>
+  <v></v>
+</c>
+```
+
+**Auto-fixable?** Yes. Wrapping with `IFERROR(...,0)` is safe for most financial formulas. If the business expectation is that the result should display as blank rather than zero, use `IFERROR(...,"")` instead.
+
+---
+
+### #VALUE! — Wrong Data Type
+
+**What it means:** The formula attempts an arithmetic or logical operation on a value of the wrong type (e.g., adding a text string to a number).
+
+**Common causes in generated files:**
+- A cell intended to hold a number was written as a string type (`t="s"` or `t="inlineStr"`) instead of a numeric type
+- A formula references a cell containing text (e.g., a unit label like "thousands") and treats it as a number
+
+**XML signature:**
+```xml
+<c r="F3" t="e">
+  <f>E3+D3</f>
+  <v>#VALUE!</v>
+</c>
+```
+
+**Fix — check source cells for incorrect type:**
+
+If `D3` was incorrectly written as a string:
+```xml
+<!-- Wrong: numeric value stored as string -->
+<c r="D3" t="inlineStr"><is><t>1000</t></is></c>
+
+<!-- Correct: numeric value stored as number (t attribute omitted or "n") -->
+<c r="D3"><v>1000</v></c>
+```
+
+Alternatively, wrap the formula with `VALUE()` conversion:
+```xml
+<c r="F3">
+  <f>VALUE(E3)+VALUE(D3)</f>
+  <v></v>
+</c>
+```
+
+**Auto-fixable?** Partially. If the source cell type is visibly wrong (a number stored as string), fix the type. If the cause is ambiguous (the cell is supposed to contain text), flag for human review.
+
+---
+
+### #NAME? — Unrecognized Name
+
+**What it means:** The formula contains an identifier that Excel does not recognize — either a misspelled function name, an undefined named range, or a function that is not available in the target Excel version.
+
+**Common causes in generated files:**
+- LLM writes a function name with a typo: `SUMIF` written as `SUMIFS` when only 3 arguments are provided, or `XLOOKUP` used in a context targeting Excel 2010
+- Named range referenced in formula does not exist in `xl/workbook.xml`
+
+**XML signature:**
+```xml
+<c r="B2" t="e">
+  <f>SUMSQ(A2:A10)</f>
+  <v>#NAME?</v>
+</c>
+```
+
+**Fix — verify function name and named ranges:**
+
+Check named ranges in `xl/workbook.xml`:
+```xml
+<definedNames>
+  <definedName name="RevenueRange">Sheet1!$B$2:$B$13</definedName>
+</definedNames>
+```
+
+If the formula references `RevenuRange` (typo), correct it to `RevenueRange`:
+```xml
+<c r="B2">
+  <f>SUM(RevenueRange)</f>
+  <v></v>
+</c>
+```
+
+**Auto-fixable?** Only if the correct name is unambiguous (e.g., a single close match exists). Otherwise flag for human review — function name fixes require understanding the intended calculation.
+
+---
+
+### #N/A — Value Not Available
+
+**What it means:** A lookup function (VLOOKUP, HLOOKUP, MATCH, INDEX/MATCH, XLOOKUP) searched for a value that does not exist in the lookup table.
+
+**Common causes in generated files:**
+- Lookup key exists in the formula but the lookup table is empty or not yet populated
+- Key format mismatch (text "2024" vs numeric 2024)
+
+**XML signature:**
+```xml
+<c r="G5" t="e">
+  <f>VLOOKUP(F5,Assumptions!$A$2:$B$20,2,0)</f>
+  <v>#N/A</v>
+</c>
+```
+
+**Fix — wrap with IFERROR for missing-match tolerance:**
+```xml
+<c r="G5">
+  <f>IFERROR(VLOOKUP(F5,Assumptions!$A$2:$B$20,2,0),0)</f>
+  <v></v>
+</c>
+```
+
+**Auto-fixable?** Adding `IFERROR` is safe if a zero default is acceptable. If the lookup failure indicates a data integrity problem (the key should always be present), do not auto-fix — flag for human review.
+
+---
+
+### #NULL! — Empty Intersection
+
+**What it means:** The space operator (which computes the intersection of two ranges) was applied to two ranges that do not intersect.
+
+**Common causes in generated files:**
+- Accidental space between two range references: `=SUM(A1:A5 C1:C5)` instead of `=SUM(A1:A5,C1:C5)`
+- Rarely seen in typical financial models; usually indicates a formula generation error
+
+**XML signature:**
+```xml
+<c r="H10" t="e">
+  <f>SUM(A1:A5 C1:C5)</f>
+  <v>#NULL!</v>
+</c>
+```
+
+**Fix — replace space with comma (union) or colon (range):**
+```xml
+<!-- Union of two separate ranges -->
+<c r="H10">
+  <f>SUM(A1:A5,C1:C5)</f>
+  <v></v>
+</c>
+```
+
+**Auto-fixable?** Yes. The space operator is almost never intentional in generated formulas. Replacing with a comma is safe.
+
+---
+
+### #NUM! — Numeric Error
+
+**What it means:** A formula produced a number that Excel cannot represent (overflow, underflow) or a mathematical operation that has no real-number result (square root of negative, LOG of zero or negative).
+
+**Common causes in generated files:**
+- IRR or NPV formula where the cash flow series has no convergent solution
+- `SQRT()` applied to a cell that can be negative
+- Very large exponentiation
+
+**XML signature:**
+```xml
+<c r="J15" t="e">
+  <f>IRR(B5:B15)</f>
+  <v>#NUM!</v>
+</c>
+```
+
+**Fix — add a conditional guard:**
+```xml
+<c r="J15">
+  <f>IFERROR(IRR(B5:B15),"")</f>
+  <v></v>
+</c>
+```
+
+For SQRT:
+```xml
+<c r="K5">
+  <f>IF(A5>=0,SQRT(A5),"")</f>
+  <v></v>
+</c>
+```
+
+**Auto-fixable?** Partially. Wrapping with `IFERROR` suppresses the error display but does not fix the underlying calculation issue. Flag the cell for human review even after applying the IFERROR wrapper.
+
+---
+
+## Auto-Fix vs. Human Review Decision Matrix
+
+| Error Type | Auto-Fix Safe? | Condition | Action |
+|------------|---------------|-----------|--------|
+| `#DIV/0!` | Yes | Always | Wrap with `IFERROR(formula,0)` |
+| `#NULL!` | Yes | Always | Replace space operator with comma |
+| `#REF!` | Yes | Only if correct target is unambiguous from context | Correct reference; otherwise flag |
+| `#NAME?` | Yes | Only if typo has exactly one plausible correction | Fix name; otherwise flag |
+| `#N/A` | Conditional | If a zero/blank default is business-acceptable | Add IFERROR wrapper; document assumption |
+| `#VALUE!` | Conditional | Only if source cell type is clearly wrong | Fix type; otherwise flag |
+| `#NUM!` | No | Always | Add IFERROR to suppress display, then flag |
+| Broken sheet ref | Yes | Only if renamed sheet can be identified from workbook.xml | Correct name |
+| Business logic errors | Never | Any case | Human review only |
+
+**What counts as a business logic error (never auto-fix):**
+- A formula that produces a wrong number but no Excel error (e.g., `=SUM(B2:B8)` when the intent was `=SUM(B2:B9)`)
+- A formula where the IFERROR default value is meaningful (e.g., whether to use 0, blank, or a prior-period value)
+- Any formula where fixing the error requires knowing what the formula was supposed to calculate
+
+---
+
+## Delivery Standard — Validation Report
+
+Every validation task must produce a structured report. This report is the deliverable, regardless of whether errors were found.
+
+### Required report format
+
+```markdown
+## Formula Validation Report
+
+**File**: /path/to/filename.xlsx
+**Date**: YYYY-MM-DD
+**Sheets checked**: Sheet1, Sheet2, Sheet3
+**Total formulas scanned**: N
+
+---
+
+### Tier 1 — Static Validation
+
+**Status**: PASS / FAIL
+**Tool**: formula_check.py (direct XML scan)
+
+| Sheet | Cell | Error Type | Detail | Fix Applied |
+|-------|------|-----------|--------|-------------|
+| Summary | C12 | #REF! | Formula: Q1!A0 | Corrected to Q1!A1 |
+| Summary | D15 | broken_sheet_ref | References missing sheet 'Q5' | Renamed to Q4 |
+
+_(If no errors: "No errors detected.")_
+
+---
+
+### Tier 2 — Dynamic Validation
+
+**Status**: PASS / FAIL / SKIPPED
+**Tool**: LibreOffice headless (version X.Y.Z) / Not available
+
+_(If SKIPPED: state the reason — LibreOffice not installed, timeout, etc.)_
+
+| Sheet | Cell | Error Type | Detail | Fix Applied |
+|-------|------|-----------|--------|-------------|
+| Q1 | F8 | #DIV/0! | Formula: C8/C7 | Wrapped with IFERROR |
+
+_(If no errors: "No runtime errors detected after recalculation.")_
+
+---
+
+### Summary
+
+- **Total errors found**: N
+- **Auto-fixed**: N (list types)
+- **Flagged for human review**: N (list cells and reason)
+- **Final status**: PASS (ready for delivery) / FAIL (blocked)
+
+### Human Review Required
+
+| Cell | Error | Reason Auto-Fix Not Applied |
+|------|-------|----------------------------|
+| Q2!B15 | #NUM! | IRR formula — business must confirm cash flow inputs |
+```
+
+### Minimum required fields
+
+The report is invalid (and delivery is blocked) if any of these are missing:
+- File path and date
+- Which sheets were checked
+- Total formula count
+- Tier 1 status with explicit PASS/FAIL
+- Tier 2 status with explicit PASS/FAIL/SKIPPED and reason if SKIPPED
+- For every error: sheet, cell, error type, and disposition (fixed or flagged)
+- Final delivery status
+
+---
+
+## Common Scenarios
+
+### Scenario 1: Validate immediately after creating a new file
+
+When `create.md` workflow produces a new xlsx, run validation before any delivery response.
+
+```bash
+# Step 1: Static check on the freshly written file
+python3 SKILL_DIR/scripts/formula_check.py /path/to/output.xlsx
+
+# Step 2: Dynamic check (if LibreOffice available)
+python3 SKILL_DIR/scripts/libreoffice_recalc.py /path/to/output.xlsx /tmp/recalculated.xlsx
+python3 SKILL_DIR/scripts/formula_check.py /tmp/recalculated.xlsx
+```
+
+Expected behavior on a freshly created file: Tier 1 will find zero `error_value` errors (because `<v>` elements are empty, not error-valued). It will find any broken cross-sheet references if sheet names were misspelled. Tier 2 will populate `<v>` and reveal runtime errors like `#DIV/0!`.
+
+If Tier 2 reveals errors, fix them in the source XML (not the recalculated copy), repack, and re-run both tiers.
+
+### Scenario 2: Validate after editing an existing file
+
+When `edit.md` workflow modifies an existing xlsx, validate only the affected sheets if the edit was surgical. If the edit touched shared formulas or cross-sheet references, validate all sheets.
+
+```bash
+# Targeted static check — look at specific sheet
+# (formula_check.py checks all sheets; examine only the relevant section of output)
+python3 SKILL_DIR/scripts/formula_check.py /path/to/edited.xlsx --json \
+  | python3 -c "
+import json, sys
+r = json.load(sys.stdin)
+for e in r['errors']:
+    if e.get('sheet') in ['Summary', 'Q1']:
+        print(e)
+"
+```
+
+Always run Tier 2 after edits that modify formulas, even if Tier 1 passes. Edits to data ranges can cause previously-valid formulas to produce runtime errors.
+
+### Scenario 3: User provides a file with suspected formula errors
+
+When a user submits a file and reports wrong values or visible errors:
+
+```bash
+# Step 1: Static scan — find all error cells
+python3 SKILL_DIR/scripts/formula_check.py /path/to/user_file.xlsx --json > /tmp/validation_results.json
+
+# Step 2: Unpack for manual inspection
+python3 SKILL_DIR/scripts/xlsx_unpack.py /path/to/user_file.xlsx /tmp/xlsx_inspect/
+
+# Step 3: Dynamic recalculation
+python3 SKILL_DIR/scripts/libreoffice_recalc.py /path/to/user_file.xlsx /tmp/user_file_recalc.xlsx
+
+# Step 4: Re-validate recalculated file
+python3 SKILL_DIR/scripts/formula_check.py /tmp/user_file_recalc.xlsx --json > /tmp/validation_after_recalc.json
+
+# Step 5: Compare before and after
+python3 - <<'EOF'
+import json
+before = json.load(open("/tmp/validation_results.json"))
+after  = json.load(open("/tmp/validation_after_recalc.json"))
+print(f"Before recalc: {before['error_count']} errors")
+print(f"After  recalc: {after['error_count']} errors")
+EOF
+```
+
+If errors appear only after recalculation (not in the original static scan), the formulas were syntactically correct but produce wrong results at runtime. These are runtime errors that require formula-level fixes, not XML-structure fixes.
+
+If errors appear in both scans, they were already cached in `<v>` before recalculation — the file was previously opened by Excel/LibreOffice and the errors persisted.
+
+---
+
+## Critical Pitfalls
+
+**Pitfall 1: openpyxl `data_only=True` destroys formulas.**
+Opening a workbook with `data_only=True` reads cached values instead of formulas. If you then save the workbook, all `<f>` elements are permanently removed and replaced with their last-cached values. Never use this mode for validation workflows.
+
+**Pitfall 2: Empty `<v>` is not the same as a passing formula.**
+A freshly generated file has empty `<v>` elements for all formula cells. formula_check.py will not report these as errors — they are not yet errors. They become errors only after recalculation if the calculated value is an error type. This is why Tier 2 is mandatory.
+
+**Pitfall 3: Shared formula errors affect the entire range.**
+If a shared formula's primary cell has a broken reference, every cell in the shared range (`ref="D2:D100"`) inherits that broken reference. The count of logical errors can be much larger than the count of distinct error entries in formula_check.py output. When fixing a broken shared formula, fix the primary cell's `<f t="shared" ref="...">` element; the consumers (`<f t="shared" si="N"/>`) automatically inherit the corrected formula.
+
+**Pitfall 4: Sheet names are case-sensitive.**
+`=q1!B5` and `=Q1!B5` are different references. Excel internally treats them the same, but formula_check.py's string comparison is case-sensitive. If a formula uses a lowercase sheet name that matches an uppercase sheet in the workbook, it will be flagged as a broken reference. The fix is to match the exact case in `workbook.xml`.
+
+**Pitfall 5: `--convert-to xlsx` does not guarantee formula preservation.**
+LibreOffice's conversion can occasionally alter certain formula types (array formulas, dynamic array functions like `SORT`, `UNIQUE`). After Tier 2, if the recalculated file shows formula changes unrelated to error fixing, do not deliver the recalculated file directly — use the original file with targeted XML fixes instead.
diff --git a/builtin-skills/document-process/my-writing-style b/builtin-skills/document-process/my-writing-style
deleted file mode 160000
index d94826e1..00000000
--- a/builtin-skills/document-process/my-writing-style
+++ /dev/null
@@ -1 +0,0 @@
-Subproject commit d94826e1cd48f5403b82a5a909efdfab96221259
diff --git a/builtin-skills/document-process/my-writing-style/README.md b/builtin-skills/document-process/my-writing-style/README.md
new file mode 100644
index 00000000..1ef85ef4
--- /dev/null
+++ b/builtin-skills/document-process/my-writing-style/README.md
@@ -0,0 +1,71 @@
+# Writing Style Skill
+
+可复用的写作风格 Skill 模板。**内置自动学习** — 从你的修改中自动提取规则，SKILL.md 越用越准。
+
+兼容 **Claude Code** + **OpenClaw (ClawHub)**。
+
+## 原理
+
+```
+AI 用 SKILL.md 写初稿 → 你改到满意 → diff 两版 → 提取规则 → 更新 SKILL.md → 下次更准
+```
+
+只要两个数据点：**original**（AI 第一版）和 **final**（你最终版）。中间改了多少轮不管。
+
+## 安装
+
+```bash
+# Claude Code
+git clone https://github.com/jzOcb/writing-style-skill.git
+cp -r writing-style-skill ~/.claude/skills/my-writing-style
+
+# OpenClaw / ClawHub
+npx clawhub@latest install jz-writing-style-skill
+```
+
+## 快速开始
+
+1. **改 SKILL.md** — 把模板里的风格规则改成你自己的（或留空，让自动学习帮你填）
+2. **让 AI 用这个 skill 写内容**
+3. **你改到满意**
+4. 记录：
+```bash
+python3 scripts/observe.py record-original draft.md
+# ... 你修改 ...
+python3 scripts/observe.py record-final final.md
+```
+5. 提取规则：
+```bash
+python3 scripts/improve.py auto --skill .
+```
+
+## 文件结构
+
+```
+writing-style-skill/
+├── SKILL.md              # 你的写作风格（模板，改成你的）
+├── README.md             # 本文件
+└── scripts/
+    ├── observe.py        # 记录 original / final（零依赖）
+    └── improve.py        # 提取 / 应用 / 回滚（需要 LLM CLI）
+```
+
+## 自动学习怎么工作
+
+- `observe.py` 记录 AI 原稿和你的最终版
+- `improve.py` 用 LLM 分析 diff，提取写作规则
+- 规则按置信度分 P0/P1/P2，P0 自动应用
+- 每次更新前自动备份，一键回滚
+
+## LLM 支持
+
+`improve.py` 自动检测：
+- `claude` (Claude Code) — 优先
+- `llm` (pip install llm) — 通用
+- `IMPROVE_LLM_CMD` 环境变量 — 自定义
+
+`observe.py` 零依赖纯 Python。
+
+## License
+
+MIT
diff --git a/builtin-skills/document-process/my-writing-style/SKILL.md b/builtin-skills/document-process/my-writing-style/SKILL.md
new file mode 100644
index 00000000..08cc2901
--- /dev/null
+++ b/builtin-skills/document-process/my-writing-style/SKILL.md
@@ -0,0 +1,206 @@
+---
+name: my-writing-style
+version: 1.0.0
+description: |
+  可复用的写作风格 Skill 模板。内置自动学习：
+  从你的修改中自动提取规则，SKILL.md 越用越准。
+  Fork 后改成你自己的风格。
+dependencies: []
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - exec
+---
+
+# Writing Style Skill（模板）
+
+**Fork 这个 skill，改成你的写作风格。内置自动学习，越用越准。**
+
+---
+
+## 🎯 怎么用
+
+1. Fork / clone 这个 skill
+2. 把下面的风格规则改成你自己的
+3. 让 AI 用这个 skill 写内容
+4. 你改到满意 → 脚本自动学习你改了什么
+5. 下次 AI 写出来的就更像你
+
+---
+
+## 【0】Voice Dimensions（量化你的风格）
+
+**用 1-10 分定义你的风格维度。AI 比"写得自然一点"这种话更容易理解数字。**
+
+| Dimension | Score | 你的说明 |
+|-----------|-------|---------|
+| **formal_casual** | **?/10** | 偏正式还是偏随意？ |
+| **technical_accessible** | **?/10** | 技术深度？ |
+| **serious_playful** | **?/10** | 严肃还是活泼？ |
+| **concise_elaborate** | **?/10** | 简洁还是详细？ |
+| **reserved_expressive** | **?/10** | 保守还是直接？ |
+
+> 💡 **不知道填什么？** 先跑几次 AI 写作 → 你改 → 自动学习会帮你填。
+
+---
+
+## 【1】角色与读者
+
+**我是谁：**
+- （填你的身份，比如：独立开发者，新晋 AI 爱好者）
+
+**读者是谁：**
+- （填你的读者，比如：对 AI 感兴趣的技术人）
+
+**和读者的关系：**
+- （比如：同行交流，不是教学）
+
+---
+
+## 【2】写作规则
+
+### 基础规则
+
+- （填你的规则，比如：不用"深入探讨"、段落要短、要有具体数字）
+- 
+- 
+
+### 禁止词
+
+- （AI 爱用但你不喜欢的词，比如：值得注意的是、综上所述、本文将介绍）
+- 
+- 
+
+### 句式偏好
+
+- （你喜欢的句式，比如：结论前置、不要学术导语）
+- 
+- 
+
+> 💡 **不需要一开始就写完。** 这些规则会通过你的修改自动积累。
+> 跑完 10 次写作→修改循环后，这里会长出几十条精准规则。
+
+---
+
+## 【3】格式规范
+
+### 平台适配
+
+| 平台 | 格式要求 |
+|------|---------|
+| X/Twitter | 不渲染 markdown，用纯文本 |
+| 小红书 | emoji 多、分段短 |
+| 博客 | 标准 markdown |
+| （你的平台） | （你的要求）|
+
+---
+
+## 🔄 自动学习（内置）
+
+**这个 skill 会从你的修改中自动学习。不需要手动写规则。**
+
+### 工作原理
+
+```
+AI 用这个 skill 写初稿
+    ↓
+你改到满意
+    ↓
+脚本 diff 两版 → 提取你改了什么
+    ↓
+新规则自动写入这个 SKILL.md
+    ↓
+下次 AI 写出来就更像你
+```
+
+### 只需要两个数据点
+
+- **original**: AI 生成的第一版
+- **final**: 你最终确认的版本
+
+中间改了几轮不管。在 Google Doc 里来回改了 10 次？无所谓，只比较首尾。
+
+### Agent 操作指南
+
+**写完内容后：**
+```bash
+python3 scripts/observe.py record-original <file> --account <账号> --content-type <类型>
+```
+
+**人类确认最终版后：**
+```bash
+python3 scripts/observe.py record-final <file> --match <hash>
+```
+
+**提取规则（手动或 cron 自动）：**
+```bash
+python3 scripts/improve.py auto --skill .
+```
+
+### 规则分级
+
+| 级别 | 含义 | 处理方式 |
+|------|------|---------|
+| P0 | 高置信度（多次出现） | 自动应用 |
+| P1 | 中置信度 | 人工确认 |
+| P2 | 低置信度（仅 1 次） | 存档观察 |
+
+### 安全
+
+- 每次更新前自动备份 SKILL.md
+- `improve.py rollback` 一键回滚
+- auto 模式只应用 P0
+
+---
+
+## 📊 CLI 参考
+
+### observe.py（零依赖纯 Python）
+
+| 命令 | 功能 |
+|------|------|
+| `record-original <file>` | 记录 AI 原稿 |
+| `record-final <file> --match <hash>` | 记录最终版 |
+| `pending` | 查看待配对 |
+| `stats` | 统计 |
+
+### improve.py（需要 LLM CLI）
+
+| 命令 | 功能 |
+|------|------|
+| `extract [--days 7]` | 提取改进建议 |
+| `auto` | 提取 + 自动应用 P0 |
+| `show` | 查看提案 |
+| `apply <id>` | 应用提案 |
+| `rollback` | 回滚 |
+
+支持的 LLM CLI: `claude`（Claude Code）/ `llm`（pip install llm）/ `IMPROVE_LLM_CMD` 环境变量
+
+---
+
+## 📂 数据存储
+
+```
+~/clawd/memory/                    # OpenClaw
+~/.claude/memory/                  # Claude Code
+├── skill-runs/<skill-name>/
+│   └── YYYY-MM-DD.jsonl          # 每日观察日志
+├── skill-proposals/<skill-name>/
+│   └── YYYYMMDD-HHMMSS.md       # 改进提案
+└── skill-backups/<skill-name>/
+    └── SKILL-YYYYMMDD-HHMMSS.md  # 自动备份
+```
+
+自动检测环境，不需要手动配置路径。
+
+---
+
+## 🚀 30 天预期
+
+| 时间 | 预期效果 |
+|------|---------|
+| 第 1 周 | 积累 3-5 次修改，生成第一批规则 |
+| 第 2 周 | 10+ 条规则，AI 输出明显更像你 |
+| 第 1 月 | 30+ 条规则，风格维度自动校准 |
+| 持续 | 规则库稳定增长，新 pattern 自动捕捉 |
diff --git a/builtin-skills/document-process/my-writing-style/scripts/improve.py b/builtin-skills/document-process/my-writing-style/scripts/improve.py
new file mode 100644
index 00000000..5f8e36b0
--- /dev/null
+++ b/builtin-skills/document-process/my-writing-style/scripts/improve.py
@@ -0,0 +1,426 @@
+#!/usr/bin/env python3
+"""
+Self-Improving Skill — Improver
+
+从人类修改中提取规则，更新目标 SKILL.md。
+
+用法:
+    python3 improve.py extract [--days 7] [--date 2026-03-17]
+    python3 improve.py auto                  # 提取 + 自动应用 P0（cron 用）
+    python3 improve.py show                  # 查看所有提案
+    python3 improve.py apply <proposal_id>   # 应用指定提案
+    python3 improve.py rollback              # 回滚上次应用
+
+环境变量:
+    SKILL_LOG_DIR      — 日志目录
+    SKILL_TARGET_PATH  — 目标 SKILL.md 路径
+    SKILL_PROPOSAL_DIR — 提案目录
+    SKILL_BACKUP_DIR   — 备份目录
+"""
+
+import sys
+import json
+import os
+import argparse
+import subprocess
+import shutil
+from pathlib import Path
+from datetime import datetime, timedelta
+
+# 默认路径 — 自动检测 OpenClaw (~/.openclaw) 或 Claude Code (~/.claude)
+def _detect_base():
+    """检测数据存储基目录"""
+    # 优先级: 环境变量 > ~/clawd > ~/.openclaw > ~/.claude > ~/.self-improving
+    if os.environ.get("SKILL_BASE_DIR"):
+        return Path(os.environ["SKILL_BASE_DIR"])
+    candidates = [
+        Path.home() / "clawd" / "memory",
+        Path.home() / ".openclaw" / "memory",
+        Path.home() / ".claude" / "memory",
+    ]
+    for c in candidates:
+        if c.parent.exists():
+            return c
+    return Path.home() / ".self-improving" / "memory"
+
+_BASE = _detect_base()
+DEFAULT_LOG_DIR = _BASE / "skill-runs" / "default"
+DEFAULT_PROPOSAL_DIR = _BASE / "skill-proposals" / "default"
+DEFAULT_BACKUP_DIR = _BASE / "skill-backups" / "default"
+
+
+def get_paths(args=None):
+    """解析所有路径配置"""
+    skill_name = "default"
+    if args and hasattr(args, 'skill') and args.skill:
+        skill_name = Path(args.skill).name
+
+    base = Path.home() / "clawd" / "memory"
+
+    log_dir = Path(os.environ.get("SKILL_LOG_DIR",
+                   getattr(args, 'log_dir', None) or
+                   str(base / "skill-runs" / skill_name)))
+
+    proposal_dir = Path(os.environ.get("SKILL_PROPOSAL_DIR",
+                        getattr(args, 'proposal_dir', None) or
+                        str(base / "skill-proposals" / skill_name)))
+
+    backup_dir = Path(os.environ.get("SKILL_BACKUP_DIR",
+                      getattr(args, 'backup_dir', None) or
+                      str(base / "skill-backups" / skill_name)))
+
+    # 目标 SKILL.md
+    if os.environ.get("SKILL_TARGET_PATH"):
+        target = Path(os.environ["SKILL_TARGET_PATH"])
+    elif args and hasattr(args, 'target') and args.target:
+        target = Path(args.target)
+    elif args and hasattr(args, 'skill') and args.skill:
+        target = Path(args.skill) / "SKILL.md"
+    else:
+        target = None
+
+    for d in (log_dir, proposal_dir, backup_dir):
+        d.mkdir(parents=True, exist_ok=True)
+
+    return log_dir, proposal_dir, backup_dir, target
+
+
+def read_log_entries(log_file):
+    if not log_file.exists():
+        return []
+    entries = []
+    with log_file.open("r") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    return entries
+
+
+def collect_edits(log_dir, days=1, date_str=None):
+    """收集有实际修改的 final/edited 记录"""
+    edits = []
+    if date_str:
+        log_file = log_dir / f"{date_str}.jsonl"
+        entries = read_log_entries(log_file)
+        edits.extend([e for e in entries
+                      if e["type"] in ("final", "edited") and not e.get("no_change")])
+    else:
+        for i in range(days):
+            date = (datetime.now() - timedelta(days=i)).strftime("%Y-%m-%d")
+            log_file = log_dir / f"{date}.jsonl"
+            entries = read_log_entries(log_file)
+            edits.extend([e for e in entries
+                          if e["type"] in ("final", "edited") and not e.get("no_change")])
+    return edits
+
+
+def call_llm(prompt, timeout=180):
+    """调用 LLM — 自动检测可用的 CLI (claude / openclaw / llm)"""
+    # 优先级: claude CLI → openclaw exec → generic llm CLI
+    candidates = [
+        ["claude", "--print", "--model", "sonnet"],  # Claude Code
+        ["claude", "--print"],                         # Claude Code (default model)
+        ["llm", "-m", "claude-sonnet"],               # simon willison's llm CLI
+        ["llm"],                                       # llm CLI default
+    ]
+    for cmd in candidates:
+        try:
+            result = subprocess.run(cmd, input=prompt, capture_output=True,
+                                    text=True, timeout=timeout)
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            continue
+
+    # fallback: 如果 IMPROVE_LLM_CMD 环境变量设置了，用它
+    custom_cmd = os.environ.get("IMPROVE_LLM_CMD")
+    if custom_cmd:
+        try:
+            result = subprocess.run(custom_cmd.split(), input=prompt,
+                                    capture_output=True, text=True, timeout=timeout)
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            pass
+
+    print("❌ LLM 调用失败。支持的方式：")
+    print("   - 安装 Claude Code CLI (claude --print)")
+    print("   - 安装 llm CLI (pip install llm)")
+    print("   - 设置 IMPROVE_LLM_CMD 环境变量")
+    return None
+
+
+def extract_improvements(args):
+    log_dir, proposal_dir, _, target = get_paths(args)
+    days = getattr(args, 'days', 1) or 1
+    date_str = getattr(args, 'date', None)
+
+    edits = collect_edits(log_dir, days=days, date_str=date_str)
+    if not edits:
+        print("⚠️  没有修改记录")
+        return None
+
+    print(f"📊 找到 {len(edits)} 次修改，正在分析...")
+
+    # 读当前 SKILL.md
+    current_skill = ""
+    if target and target.exists():
+        current_skill = target.read_text()
+
+    # 构建对比数据
+    edit_summaries = []
+    for i, edit in enumerate(edits):
+        orig = edit.get("original_content", "")[:3000]
+        final = edit.get("final_content", edit.get("edited_content", ""))[:3000]
+        ctx = edit.get("context", {})
+        edit_summaries.append({
+            "index": i + 1,
+            "account": ctx.get("account", "unknown"),
+            "content_type": ctx.get("content_type", "unknown"),
+            "original": orig,
+            "final": final,
+        })
+
+    proposal_id = datetime.now().strftime("%Y%m%d-%H%M%S")
+
+    prompt = f"""你是 writing style skill 的改进助手。
+
+分析人类对 AI 生成文章的修改，提取可以加入 SKILL.md 的新规则。
+
+## 当前 SKILL.md（最后 3000 字，避免重复）
+{current_skill[-3000:]}
+
+## 修改记录（original vs final）
+{json.dumps(edit_summaries, ensure_ascii=False, indent=2)}
+
+## 要求
+1. 对比 original 和 final，找出系统性修改
+2. 只提取有 pattern 的修改（至少 2 次，或单次但改动幅度大且明确）
+3. 不要提取已在 SKILL.md 中的规则
+4. 每条规则必须可执行
+
+## 输出格式
+
+---
+id: {proposal_id}
+date: {datetime.now().isoformat()}
+source: {len(edits)} edits
+status: pending
+---
+
+# Improvement Proposal
+
+## 提取的改进建议
+
+### 1. 新禁止词
+- **`词`** → 替代: "YYY" | 理由: ... | 优先级: **P0/P1/P2**
+
+### 2. 新风格规则
+- 规则描述 | 理由: ... | 优先级: **P0/P1/P2**
+
+### 3. 反模式
+- 描述 | 理由: ... | 优先级: **P0/P1/P2**
+
+P0=高置信度(多次), P1=中置信度, P2=低置信度(仅1次)
+"""
+
+    suggestions = call_llm(prompt)
+    if not suggestions:
+        return None
+
+    proposal_file = proposal_dir / f"{proposal_id}.md"
+    proposal_file.write_text(suggestions)
+
+    print(f"✅ 改进建议已保存: {proposal_file}")
+    print(f"\n{suggestions[:2000]}")
+    if len(suggestions) > 2000:
+        print(f"\n... (完整内容见文件)")
+    return proposal_id
+
+
+def show_proposals(args):
+    _, proposal_dir, _, _ = get_paths(args)
+    proposals = list(proposal_dir.glob("*.md"))
+
+    if not proposals:
+        print("⚠️  没有提案")
+        return
+
+    print(f"\n📋 共 {len(proposals)} 个提案:\n")
+    for p in sorted(proposals, reverse=True):
+        content = p.read_text()
+        status = "unknown"
+        for line in content.split("\n")[:10]:
+            if line.startswith("status:"):
+                status = line.split(":", 1)[1].strip()
+        icon = {"pending": "⏳", "applied": "✅", "rejected": "❌"}.get(
+            status.split("(")[0].strip(), "❓")
+        print(f"  {icon} {p.stem} — {status}")
+
+
+def backup_skill(target, backup_dir):
+    if not target or not target.exists():
+        return None
+    name = f"SKILL-{datetime.now().strftime('%Y%m%d-%H%M%S')}.md"
+    backup_path = backup_dir / name
+    shutil.copy2(target, backup_path)
+    print(f"📦 备份: {backup_path}")
+    return backup_path
+
+
+def apply_proposal(args):
+    _, proposal_dir, backup_dir, target = get_paths(args)
+    proposal_id = args.proposal_id
+    proposal_file = proposal_dir / f"{proposal_id}.md"
+
+    if not proposal_file.exists():
+        print(f"❌ 提案不存在: {proposal_id}")
+        return
+
+    if not target or not target.exists():
+        print(f"❌ 目标 SKILL.md 不存在（用 --skill 或 --target 指定）")
+        return
+
+    proposal_content = proposal_file.read_text()
+    current_skill = target.read_text()
+
+    auto_mode = getattr(args, 'auto', False)
+    filter_level = "P0" if auto_mode else "P0 和 P1"
+
+    backup_skill(target, backup_dir)
+
+    prompt = f"""把改进提案中的 **{filter_level}** 规则合并到 SKILL.md。
+
+规则：
+1. 新禁止词 → 加到禁止词 section
+2. 新风格规则 → 加到对应 section
+3. 不删除已有规则，不改文件结构
+4. version +0.1
+
+## 提案
+{proposal_content}
+
+## 当前 SKILL.md
+{current_skill}
+
+输出完整更新后的 SKILL.md。不加代码块包裹。"""
+
+    updated = call_llm(prompt, timeout=300)
+    if not updated:
+        print("❌ 合并失败")
+        return
+
+    target.write_text(updated)
+
+    new_content = proposal_content.replace(
+        "status: pending",
+        f"status: applied ({datetime.now().strftime('%Y-%m-%d')})")
+    proposal_file.write_text(new_content)
+
+    print(f"✅ 已应用提案 {proposal_id}")
+    print(f"💡 回滚: python3 improve.py rollback")
+
+
+def auto_improve(args):
+    log_dir, _, _, _ = get_paths(args)
+    edits = collect_edits(log_dir, days=7)
+
+    if not edits:
+        print("⚠️  最近 7 天没有修改记录，跳过")
+        return
+
+    print(f"🤖 自动模式: {len(edits)} 次修改")
+
+    args.days = 7
+    args.date = None
+    proposal_id = extract_improvements(args)
+
+    if not proposal_id:
+        return
+
+    _, proposal_dir, _, _ = get_paths(args)
+    content = (proposal_dir / f"{proposal_id}.md").read_text()
+
+    if "P0" not in content:
+        print("ℹ️  没有 P0 规则，跳过自动应用")
+        return
+
+    print("\n🔄 自动应用 P0 规则...")
+    apply_args = argparse.Namespace(**vars(args))
+    apply_args.proposal_id = proposal_id
+    apply_args.auto = True
+    apply_proposal(apply_args)
+
+
+def rollback(args):
+    _, _, backup_dir, target = get_paths(args)
+
+    if not target:
+        print("❌ 未指定目标 SKILL.md")
+        return
+
+    backups = sorted(backup_dir.glob("SKILL-*.md"), reverse=True)
+    if not backups:
+        print("❌ 没有备份")
+        return
+
+    latest = backups[0]
+    # 保存当前版本
+    if target.exists():
+        emergency = backup_dir / f"SKILL-pre-rollback-{datetime.now().strftime('%Y%m%d-%H%M%S')}.md"
+        shutil.copy2(target, emergency)
+
+    shutil.copy2(latest, target)
+    print(f"✅ 已回滚到: {latest.name}")
+
+
+def add_common_args(parser):
+    parser.add_argument("--skill", help="目标 skill 目录")
+    parser.add_argument("--target", help="目标 SKILL.md 路径")
+    parser.add_argument("--log-dir", help="日志目录")
+    parser.add_argument("--proposal-dir", help="提案目录")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Self-Improving Skill — Improver")
+    subparsers = parser.add_subparsers(dest="action")
+
+    p_ext = subparsers.add_parser("extract", help="提取改进建议")
+    p_ext.add_argument("--date", help="指定日期")
+    p_ext.add_argument("--days", type=int, default=1)
+    add_common_args(p_ext)
+
+    p_show = subparsers.add_parser("show", help="查看提案")
+    add_common_args(p_show)
+
+    p_apply = subparsers.add_parser("apply", help="应用提案")
+    p_apply.add_argument("proposal_id")
+    add_common_args(p_apply)
+
+    p_auto = subparsers.add_parser("auto", help="自动提取+应用P0")
+    add_common_args(p_auto)
+
+    p_rb = subparsers.add_parser("rollback", help="回滚")
+    add_common_args(p_rb)
+
+    args = parser.parse_args()
+    if not args.action:
+        parser.print_help()
+        sys.exit(1)
+
+    actions = {
+        "extract": extract_improvements,
+        "show": show_proposals,
+        "apply": apply_proposal,
+        "auto": auto_improve,
+        "rollback": rollback,
+    }
+    actions[args.action](args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/builtin-skills/document-process/my-writing-style/scripts/observe.py b/builtin-skills/document-process/my-writing-style/scripts/observe.py
new file mode 100644
index 00000000..61cfe179
--- /dev/null
+++ b/builtin-skills/document-process/my-writing-style/scripts/observe.py
@@ -0,0 +1,309 @@
+#!/usr/bin/env python3
+"""
+Self-Improving Skill — Observation Layer
+
+通用的 original → final 记录器。适用于任何 "AI 生成 → 人类修改" 的循环。
+
+用法:
+    python3 observe.py record-original article.md [--text "..."] [--account X] [--content-type article]
+    python3 observe.py record-final article.md [--match <hash>] [--text "..."]
+    python3 observe.py pending
+    python3 observe.py stats
+
+环境变量:
+    SKILL_LOG_DIR  — 日志目录（默认 ~/clawd/memory/skill-runs/default/）
+"""
+
+import sys
+import json
+import os
+import argparse
+from pathlib import Path
+from datetime import datetime, timedelta
+import hashlib
+
+# 日志目录 — 自动检测 OpenClaw / Claude Code / standalone
+def _detect_base():
+    if os.environ.get("SKILL_BASE_DIR"):
+        return Path(os.environ["SKILL_BASE_DIR"])
+    candidates = [
+        Path.home() / "clawd" / "memory",
+        Path.home() / ".openclaw" / "memory",
+        Path.home() / ".claude" / "memory",
+    ]
+    for c in candidates:
+        if c.parent.exists():
+            return c
+    return Path.home() / ".self-improving" / "memory"
+
+DEFAULT_LOG_DIR = _detect_base() / "skill-runs" / "default"
+
+
+def get_log_dir(args=None):
+    """按优先级决定日志目录：--log-dir > SKILL_LOG_DIR > default"""
+    if args and hasattr(args, 'log_dir') and args.log_dir:
+        d = Path(args.log_dir)
+    elif os.environ.get("SKILL_LOG_DIR"):
+        d = Path(os.environ["SKILL_LOG_DIR"])
+    elif args and hasattr(args, 'skill') and args.skill:
+        skill_name = Path(args.skill).name
+        d = Path.home() / "clawd" / "memory" / "skill-runs" / skill_name
+    else:
+        d = DEFAULT_LOG_DIR
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def get_log_file(log_dir, date_str=None):
+    if date_str is None:
+        date_str = datetime.now().strftime("%Y-%m-%d")
+    return log_dir / f"{date_str}.jsonl"
+
+
+def compute_hash(content):
+    return hashlib.md5(content.encode()).hexdigest()[:8]
+
+
+def get_content(args):
+    if hasattr(args, 'text') and args.text:
+        return args.text
+    if hasattr(args, 'stdin') and args.stdin:
+        return sys.stdin.read()
+    if hasattr(args, 'file') and args.file:
+        p = Path(args.file)
+        if not p.exists():
+            print(f"❌ 文件不存在: {args.file}")
+            sys.exit(1)
+        return p.read_text()
+    return None
+
+
+def read_log_entries(log_file):
+    if not log_file.exists():
+        return []
+    entries = []
+    with log_file.open("r") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    return entries
+
+
+def find_unmatched(log_dir, days=14):
+    """找到有 original 但没有 final 的记录（兼容旧 edited/no-change type）"""
+    all_originals = {}
+    all_matched = set()
+
+    for i in range(days):
+        date = (datetime.now() - timedelta(days=i)).strftime("%Y-%m-%d")
+        entries = read_log_entries(get_log_file(log_dir, date))
+        for e in entries:
+            if e["type"] == "original":
+                e["_date"] = date
+                all_originals[e["content_hash"]] = e
+            elif e["type"] in ("final", "edited", "no-change"):
+                all_matched.add(e["content_hash"])
+
+    return {h: o for h, o in all_originals.items() if h not in all_matched}
+
+
+def record_original(args):
+    content = get_content(args)
+    if not content:
+        print("❌ 需要提供内容（文件路径、--text 或 --stdin）")
+        sys.exit(1)
+
+    log_dir = get_log_dir(args)
+    content_hash = compute_hash(content)
+
+    context = {}
+    if hasattr(args, 'account') and args.account:
+        context["account"] = args.account
+    if hasattr(args, 'content_type') and args.content_type:
+        context["content_type"] = args.content_type
+
+    log_entry = {
+        "timestamp": datetime.now().isoformat(),
+        "type": "original",
+        "content_hash": content_hash,
+        "file": str(args.file) if hasattr(args, 'file') and args.file else None,
+        "content": content,
+        "context": context,
+        "char_count": len(content),
+    }
+
+    log_file = get_log_file(log_dir)
+    with log_file.open("a") as f:
+        f.write(json.dumps(log_entry, ensure_ascii=False) + "\n")
+
+    print(f"✅ 记录原稿: {content_hash}")
+    print(f"📝 字数: {len(content)}")
+    print(f"📁 日志: {log_file}")
+    return content_hash
+
+
+def record_final(args):
+    content = get_content(args)
+    if not content:
+        print("❌ 需要提供最终版内容")
+        sys.exit(1)
+
+    log_dir = get_log_dir(args)
+    target_hash = getattr(args, 'match', None)
+
+    if target_hash:
+        # 指定 hash，跨天查找
+        original = None
+        for i in range(14):
+            date = (datetime.now() - timedelta(days=i)).strftime("%Y-%m-%d")
+            entries = read_log_entries(get_log_file(log_dir, date))
+            for e in entries:
+                if e["type"] == "original" and e["content_hash"] == target_hash:
+                    original = e
+                    break
+            if original:
+                break
+        if not original:
+            print(f"❌ 找不到 hash {target_hash} 的原稿")
+            sys.exit(1)
+    else:
+        # 自动匹配最近的未配对 original
+        unmatched = find_unmatched(log_dir, 14)
+        if not unmatched:
+            print("❌ 没有待配对的原稿")
+            sys.exit(1)
+        target_hash = list(unmatched.keys())[-1]
+        original = unmatched[target_hash]
+
+    is_same = content.strip() == original["content"].strip()
+
+    log_entry = {
+        "timestamp": datetime.now().isoformat(),
+        "type": "final",
+        "content_hash": target_hash,
+        "original_content": original["content"],
+        "final_content": content,
+        "original_char_count": len(original["content"]),
+        "final_char_count": len(content),
+        "context": original.get("context", {}),
+        "no_change": is_same,
+    }
+
+    log_file = get_log_file(log_dir)
+    with log_file.open("a") as f:
+        f.write(json.dumps(log_entry, ensure_ascii=False) + "\n")
+
+    if is_same:
+        print(f"✅ 记录最终版: {target_hash} (无修改 — 正反馈)")
+    else:
+        diff_pct = ((len(content) - len(original["content"])) / max(len(original["content"]), 1)) * 100
+        print(f"✅ 记录最终版: {target_hash}")
+        print(f"📝 原稿: {len(original['content'])} 字 → 最终: {len(content)} 字 ({diff_pct:+.1f}%)")
+    print(f"📁 日志: {log_file}")
+
+
+def show_pending(args):
+    log_dir = get_log_dir(args)
+    unmatched = find_unmatched(log_dir, 14)
+
+    if not unmatched:
+        print("✅ 全部已配对")
+        return
+
+    print(f"\n⏳ {len(unmatched)} 条待配对:\n")
+    for h, entry in unmatched.items():
+        preview = entry["content"][:80].replace("\n", " ")
+        ctx = entry.get("context", {})
+        account = ctx.get("account", "?")
+        date = entry.get("_date", "?")
+        print(f"  📄 {h} | {date} | {account}")
+        print(f"     {preview}...")
+        print()
+
+
+def show_stats(args):
+    log_dir = get_log_dir(args)
+    all_files = sorted(log_dir.glob("*.jsonl"))
+
+    total_originals = 0
+    total_finals = 0
+    total_no_change = 0
+    total_changed = 0
+
+    for log_file in all_files:
+        entries = read_log_entries(log_file)
+        total_originals += sum(1 for e in entries if e["type"] == "original")
+        finals = [e for e in entries if e["type"] in ("final", "edited")]
+        total_finals += len(finals)
+        total_no_change += sum(1 for e in finals if e.get("no_change"))
+        total_changed += sum(1 for e in finals if not e.get("no_change"))
+
+    pending = find_unmatched(log_dir, 14)
+
+    print(f"\n📊 Self-Improving Skill 观察统计")
+    print(f"{'='*40}")
+    print(f"📁 日志天数: {len(all_files)}")
+    print(f"📝 原稿: {total_originals}")
+    print(f"✅ 已配对: {total_finals}")
+    print(f"   ├ 有修改: {total_changed}")
+    print(f"   └ 无修改: {total_no_change}")
+    print(f"⏳ 待配对: {len(pending)}")
+    if total_finals > 0:
+        print(f"📈 修改率: {total_changed}/{total_finals} = {total_changed/total_finals*100:.0f}%")
+
+
+def add_common_args(parser):
+    """添加通用参数"""
+    parser.add_argument("--skill", help="目标 skill 目录名（用于定位日志目录）")
+    parser.add_argument("--log-dir", help="自定义日志目录")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Self-Improving Skill — Observation Layer")
+    subparsers = parser.add_subparsers(dest="action")
+
+    # record-original
+    p_orig = subparsers.add_parser("record-original", help="记录 AI 原稿")
+    p_orig.add_argument("file", nargs="?", help="文件路径")
+    p_orig.add_argument("--text", help="直接传入文本")
+    p_orig.add_argument("--stdin", action="store_true", help="从 stdin 读取")
+    p_orig.add_argument("--account", help="发布账号")
+    p_orig.add_argument("--content-type", help="内容类型")
+    add_common_args(p_orig)
+
+    # record-final
+    p_final = subparsers.add_parser("record-final", help="记录最终版")
+    p_final.add_argument("file", nargs="?", help="文件路径")
+    p_final.add_argument("--text", help="直接传入文本")
+    p_final.add_argument("--stdin", action="store_true", help="从 stdin 读取")
+    p_final.add_argument("--match", help="匹配的原稿 hash")
+    add_common_args(p_final)
+
+    # pending
+    p_pending = subparsers.add_parser("pending", help="查看待配对原稿")
+    add_common_args(p_pending)
+
+    # stats
+    p_stats = subparsers.add_parser("stats", help="总体统计")
+    add_common_args(p_stats)
+
+    args = parser.parse_args()
+    if not args.action:
+        parser.print_help()
+        sys.exit(1)
+
+    actions = {
+        "record-original": record_original,
+        "record-final": record_final,
+        "pending": show_pending,
+        "stats": show_stats,
+    }
+    actions[args.action](args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/builtin-skills/document-process/pptx-generator/SKILL.md b/builtin-skills/document-process/pptx-generator/SKILL.md
new file mode 100644
index 00000000..995486c9
--- /dev/null
+++ b/builtin-skills/document-process/pptx-generator/SKILL.md
@@ -0,0 +1,249 @@
+---
+name: pptx-generator
+description: "Generate, edit, and read PowerPoint presentations. Create from scratch with PptxGenJS (cover, TOC, content, section divider, summary slides), edit existing PPTX via XML workflows, or extract text with markitdown. Triggers: PPT, PPTX, PowerPoint, presentation, slide, deck, slides."
+license: MIT
+metadata:
+  version: "1.0"
+  category: productivity
+  sources:
+    - https://gitbrent.github.io/PptxGenJS/
+    - https://github.com/microsoft/markitdown
+---
+
+# PPTX Generator & Editor
+
+## Overview
+
+This skill handles all PowerPoint tasks: reading/analyzing existing presentations, editing template-based decks via XML manipulation, and creating presentations from scratch using PptxGenJS. It includes a complete design system (color palettes, fonts, style recipes) and detailed guidance for every slide type.
+
+## Quick Reference
+
+| Task | Approach |
+|------|----------|
+| Read/analyze content | `python -m markitdown presentation.pptx` |
+| Edit or create from template | See [Editing Presentations](references/editing.md) |
+| Create from scratch | See [Creating from Scratch](#creating-from-scratch-workflow) below |
+
+| Item | Value |
+|------|-------|
+| **Dimensions** | 10" x 5.625" (LAYOUT_16x9) |
+| **Colors** | 6-char hex without # (e.g., `"FF0000"`) |
+| **English font** | Arial (default), or approved alternatives |
+| **Chinese font** | Microsoft YaHei |
+| **Page badge position** | x: 9.3", y: 5.1" |
+| **Theme keys** | `primary`, `secondary`, `accent`, `light`, `bg` |
+| **Shapes** | RECTANGLE, OVAL, LINE, ROUNDED_RECTANGLE |
+| **Charts** | BAR, LINE, PIE, DOUGHNUT, SCATTER, BUBBLE, RADAR |
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| [slide-types.md](references/slide-types.md) | 5 slide page types (Cover, TOC, Section Divider, Content, Summary) + additional layout patterns |
+| [design-system.md](references/design-system.md) | Color palettes, font reference, style recipes (Sharp/Soft/Rounded/Pill), typography & spacing |
+| [editing.md](references/editing.md) | Template-based editing workflow, XML manipulation, formatting rules, common pitfalls |
+| [pitfalls.md](references/pitfalls.md) | QA process, common mistakes, critical PptxGenJS pitfalls |
+| [pptxgenjs.md](references/pptxgenjs.md) | Complete PptxGenJS API reference |
+
+---
+
+## Reading Content
+
+```bash
+# Text extraction
+python -m markitdown presentation.pptx
+```
+
+---
+
+## Creating from Scratch — Workflow
+
+**Use when no template or reference presentation is available.**
+
+### Step 1: Research & Requirements
+
+Search to understand user requirements — topic, audience, purpose, tone, content depth.
+
+### Step 2: Select Color Palette & Fonts
+
+Use the [Color Palette Reference](references/design-system.md#color-palette-reference) to select a palette matching the topic and audience. Use the [Font Reference](references/design-system.md#font-reference) to choose a font pairing.
+
+### Step 3: Select Design Style
+
+Use the [Style Recipes](references/design-system.md#style-recipes) to choose a visual style (Sharp, Soft, Rounded, or Pill) matching the presentation tone.
+
+### Step 4: Plan Slide Outline
+
+Classify **every slide** as exactly one of the [5 page types](references/slide-types.md). Plan the content and layout for each slide. Ensure visual variety — do NOT repeat the same layout across slides.
+
+### Step 5: Generate Slide JS Files
+
+Create one JS file per slide in `slides/` directory. Each file must export a synchronous `createSlide(pres, theme)` function. Follow the [Slide Output Format](#slide-output-format) and the type-specific guidance in [slide-types.md](references/slide-types.md). Generate up to 5 slides concurrently using subagents if available.
+
+**Tell each subagent:**
+1. File naming: `slides/slide-01.js`, `slides/slide-02.js`, etc.
+2. Images go in: `slides/imgs/`
+3. Final PPTX goes in: `slides/output/`
+4. Dimensions: 10" x 5.625" (LAYOUT_16x9)
+5. Fonts: Chinese = Microsoft YaHei, English = Arial (or approved alternative)
+6. Colors: 6-char hex without # (e.g. `"FF0000"`)
+7. Must use the theme object contract (see [Theme Object Contract](#theme-object-contract))
+8. Must follow the [PptxGenJS API reference](references/pptxgenjs.md)
+
+### Step 6: Compile into Final PPTX
+
+Create `slides/compile.js` to combine all slide modules:
+
+```javascript
+// slides/compile.js
+const pptxgen = require('pptxgenjs');
+const pres = new pptxgen();
+pres.layout = 'LAYOUT_16x9';
+
+const theme = {
+  primary: "22223b",    // dark color for backgrounds/text
+  secondary: "4a4e69",  // secondary accent
+  accent: "9a8c98",     // highlight color
+  light: "c9ada7",      // light accent
+  bg: "f2e9e4"          // background color
+};
+
+for (let i = 1; i <= 12; i++) {  // adjust count as needed
+  const num = String(i).padStart(2, '0');
+  const slideModule = require(`./slide-${num}.js`);
+  slideModule.createSlide(pres, theme);
+}
+
+pres.writeFile({ fileName: './output/presentation.pptx' });
+```
+
+Run with: `cd slides && node compile.js`
+
+### Step 7: QA (Required)
+
+See [QA Process](references/pitfalls.md#qa-process).
+
+### Output Structure
+
+```
+slides/
+├── slide-01.js          # Slide modules
+├── slide-02.js
+├── ...
+├── imgs/                # Images used in slides
+└── output/              # Final artifacts
+    └── presentation.pptx
+```
+
+---
+
+## Slide Output Format
+
+Each slide is a **complete, runnable JS file**:
+
+```javascript
+// slide-01.js
+const pptxgen = require("pptxgenjs");
+
+const slideConfig = {
+  type: 'cover',
+  index: 1,
+  title: 'Presentation Title'
+};
+
+// MUST be synchronous (not async)
+function createSlide(pres, theme) {
+  const slide = pres.addSlide();
+  slide.background = { color: theme.bg };
+
+  slide.addText(slideConfig.title, {
+    x: 0.5, y: 2, w: 9, h: 1.2,
+    fontSize: 48, fontFace: "Arial",
+    color: theme.primary, bold: true, align: "center"
+  });
+
+  return slide;
+}
+
+// Standalone preview - use slide-specific filename
+if (require.main === module) {
+  const pres = new pptxgen();
+  pres.layout = 'LAYOUT_16x9';
+  const theme = {
+    primary: "22223b",
+    secondary: "4a4e69",
+    accent: "9a8c98",
+    light: "c9ada7",
+    bg: "f2e9e4"
+  };
+  createSlide(pres, theme);
+  pres.writeFile({ fileName: "slide-01-preview.pptx" });
+}
+
+module.exports = { createSlide, slideConfig };
+```
+
+---
+
+## Theme Object Contract (MANDATORY)
+
+The compile script passes a theme object with these **exact keys**:
+
+| Key | Purpose | Example |
+|-----|---------|---------|
+| `theme.primary` | Darkest color, titles | `"22223b"` |
+| `theme.secondary` | Dark accent, body text | `"4a4e69"` |
+| `theme.accent` | Mid-tone accent | `"9a8c98"` |
+| `theme.light` | Light accent | `"c9ada7"` |
+| `theme.bg` | Background color | `"f2e9e4"` |
+
+**NEVER use other key names** like `background`, `text`, `muted`, `darkest`, `lightest`.
+
+---
+
+## Page Number Badge (REQUIRED)
+
+All slides **except Cover Page** MUST include a page number badge in the bottom-right corner.
+
+- **Position**: x: 9.3", y: 5.1"
+- Show current number only (e.g. `3` or `03`), NOT "3/12"
+- Use palette colors, keep subtle
+
+### Circle Badge (Default)
+
+```javascript
+slide.addShape(pres.shapes.OVAL, {
+  x: 9.3, y: 5.1, w: 0.4, h: 0.4,
+  fill: { color: theme.accent }
+});
+slide.addText("3", {
+  x: 9.3, y: 5.1, w: 0.4, h: 0.4,
+  fontSize: 12, fontFace: "Arial",
+  color: "FFFFFF", bold: true,
+  align: "center", valign: "middle"
+});
+```
+
+### Pill Badge
+
+```javascript
+slide.addShape(pres.shapes.ROUNDED_RECTANGLE, {
+  x: 9.1, y: 5.15, w: 0.6, h: 0.35,
+  fill: { color: theme.accent },
+  rectRadius: 0.15
+});
+slide.addText("03", {
+  x: 9.1, y: 5.15, w: 0.6, h: 0.35,
+  fontSize: 11, fontFace: "Arial",
+  color: "FFFFFF", bold: true,
+  align: "center", valign: "middle"
+});
+```
+
+---
+
+## Dependencies
+
+- `pip install "markitdown[pptx]"` — text extraction
+- `npm install -g pptxgenjs` — creating from scratch
+- `npm install -g react-icons react react-dom sharp` — icons (optional)
diff --git a/builtin-skills/document-process/pptx-generator/references/design-system.md b/builtin-skills/document-process/pptx-generator/references/design-system.md
new file mode 100644
index 00000000..ea3fc752
--- /dev/null
+++ b/builtin-skills/document-process/pptx-generator/references/design-system.md
@@ -0,0 +1,392 @@
+# Design System
+
+## Color Palette Reference
+
+| # | Name | Colors | Style | Use Cases | Tips |
+|---|------|--------|-------|-----------|------|
+| 1 | Modern & Wellness | `#006d77` `#83c5be` `#edf6f9` `#ffddd2` `#e29578` | Fresh, soothing | Healthcare, counseling, skincare, yoga/spa | Deep teal for titles, light pink for background |
+| 2 | Business & Authority | `#2b2d42` `#8d99ae` `#edf2f4` `#ef233c` `#d90429` | Formal, classic | Annual reports, financial analysis, corporate intro, government | Deep blue for professionalism, bright red to highlight data |
+| 3 | Nature & Outdoors | `#606c38` `#283618` `#fefae0` `#dda15e` `#bc6c25` | Grounded, earthy | Outdoor gear, environmental, agriculture, historical culture | Dark green base, cream text |
+| 4 | Vintage & Academic | `#780000` `#c1121f` `#fdf0d5` `#003049` `#669bbc` | Classic, scholarly | Academic lectures, history reviews, museums, heritage brands | Strong contrast between deep red and deep blue |
+| 5 | Soft & Creative | `#cdb4db` `#ffc8dd` `#ffafcc` `#bde0fe` `#a2d2ff` | Dreamy, candy-toned | Mother & baby, desserts, women's fashion, kindergarten | Use dark gray or black for text |
+| 6 | Bohemian | `#ccd5ae` `#e9edc9` `#fefae0` `#faedcd` `#d4a373` | Gentle, muted | Wedding planning, home decor, organic food, slow living | Cream background, green-brown accents |
+| 7 | Vibrant & Tech | `#8ecae6` `#219ebc` `#023047` `#ffb703` `#fb8500` | High energy, sporty | Sports events, gyms, startup pitches, youth education | Deep blue for stability, orange as focal accent |
+| 8 | Craft & Artisan | `#7f5539` `#a68a64` `#ede0d4` `#656d4a` `#414833` | Rustic, coffee-toned | Coffee shops, handicrafts, traditional culture, bakery | Suited for paper/leather textures |
+| 9 | Tech & Night | `#000814` `#001d3d` `#003566` `#ffc300` `#ffd60a` | Deep, luminous | Tech launches, astronomy, night economy, luxury automobiles | Must use dark mode |
+| 10 | Education & Charts | `#264653` `#2a9d8f` `#e9c46a` `#f4a261` `#e76f51` | Clear, logical | Statistical reports, education, market analysis, general business | Perfect chart color scheme |
+| 11 | Forest & Eco | `#dad7cd` `#a3b18a` `#588157` `#3a5a40` `#344e41` | Monochrome gradient, forest | Landscape design, ESG reports, environmental causes, botanical | Monochrome palette is safe and cohesive |
+| 12 | Elegant & Fashion | `#edafb8` `#f7e1d7` `#dedbd2` `#b0c4b1` `#4a5759` | Muted, Morandi tones | Haute couture, art galleries, beauty brands, magazine style | Negative space is key |
+| 13 | Art & Food | `#335c67` `#fff3b0` `#e09f3e` `#9e2a2b` `#540b0e` | Rich, vintage-poster | Food documentaries, art exhibitions, ethnic themes, vintage restaurants | Works well with large color blocks |
+| 14 | Luxury & Mysterious | `#22223b` `#4a4e69` `#9a8c98` `#c9ada7` `#f2e9e4` | Cool, purple-toned | Jewelry showcases, hotel management, high-end consulting, psychology | Purple evokes premium atmosphere |
+| 15 | Pure Tech Blue | `#03045e` `#0077b6` `#00b4d8` `#90e0ef` `#caf0f8` | Futuristic, clean | Cloud/AI, water/ocean, hospitals, clean energy | Deep ocean to sky gradient |
+| 16 | Coastal Coral | `#0081a7` `#00afb9` `#fdfcdc` `#fed9b7` `#f07167` | Refreshing, summery | Travel, summer events, beverage brands, ocean themes | Teal and coral as complementary focal colors |
+| 17 | Vibrant Orange Mint | `#ff9f1c` `#ffbf69` `#ffffff` `#cbf3f0` `#2ec4b6` | Bright, cheerful | Children's events, promotional posters, FMCG, social media | Orange grabs attention, mint feels fresh |
+| 18 | Platinum White Gold | `#0a0a0a` `#0070F3` `#D4AF37` `#f5f5f5` `#ffffff` | Premium, professional | Agent products, corporate websites, fintech, luxury brands | White-gold base, blue for action, gold for emphasis |
+
+---
+
+### Agent Design System — Full Color Scale
+
+Based on the Platinum White-Gold Theme design tokens. Provides complete color scales for fine-grained design work.
+
+#### White Scale (Backgrounds & Light Surfaces)
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| white-0 | `#ffffff` | Primary background |
+| white-50 | `#fefefe` | Slightly warm white |
+| white-75 | `#fcfcfc` | Near-white |
+| white-100 | `#fafafa` | Secondary background |
+| white-200 | `#f7f7f7` | Card background |
+| white-300 | `#f5f5f5` | Tertiary background |
+| white-400 | `#f0f0f0` | Separator zones |
+| white-500 | `#ebebeb` | Light border |
+| white-600 | `#e5e5e5` | Disabled background |
+| white-700 | `#e0e0e0` | Deep white-gray |
+| white-800 | `#d9d9d9` | Placeholder |
+| white-900 | `#d4d4d4` | Divider lines |
+| white-1000 | `#cccccc` | Deepest white |
+
+#### Gold Scale (Platinum Business Accent)
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| gold-25 | `#FFFDF5` | Extremely light gold background |
+| gold-50 | `#FEF9E7` | Light gold background |
+| gold-75 | `#FCF3D0` | Pale gold highlight |
+| gold-100 | `#FAECB8` | Gold hover state |
+| gold-200 | `#F5DC8A` | Bright gold accent |
+| gold-300 | `#E8C860` | Gold hover |
+| gold-400 | `#D4AF37` | **Primary gold (core)** |
+| gold-500 | `#B8972E` | Gold text |
+| gold-600 | `#9A7E26` | Deep gold accent |
+| gold-700 | `#7C651E` | Dark gold border |
+| gold-800 | `#5E4C16` | Deep gold background |
+| gold-900 | `#40330F` | Very deep gold |
+| gold-1000 | `#221A08` | Black gold |
+
+#### Blue Scale (Primary Action Color)
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| blue-25 | `#F0F7FF` | Extremely light blue background |
+| blue-50 | `#E0EFFF` | Info alert background |
+| blue-75 | `#C2DFFF` | Light blue highlight |
+| blue-100 | `#A3CFFF` | Disabled blue |
+| blue-200 | `#66AFFF` | Bright blue |
+| blue-300 | `#338FFF` | Blue hover |
+| blue-400 | `#0070F3` | **Primary blue (core)** |
+| blue-500 | `#005FCC` | Blue text |
+| blue-600 | `#004FA6` | Deep blue accent |
+| blue-700 | `#003F80` | Dark blue border |
+| blue-800 | `#002F5A` | Deep blue background |
+| blue-900 | `#001F3D` | Very deep blue |
+| blue-1000 | `#001026` | Black blue |
+
+#### Gray Scale (Text & Neutral Colors)
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| gray-0 | `#ffffff` | White |
+| gray-50 | `#fafafa` | Extremely light gray |
+| gray-75 | `#f5f5f5` | Light gray background |
+| gray-100 | `#ededed` | Light divider |
+| gray-200 | `#d4d4d4` | Light border |
+| gray-300 | `#a3a3a3` | Quaternary text |
+| gray-400 | `#737373` | Tertiary text |
+| gray-500 | `#525252` | Secondary text |
+| gray-600 | `#404040` | Dark gray |
+| gray-700 | `#2e2e2e` | Dark background |
+| gray-800 | `#1f1f1f` | Deep background |
+| gray-900 | `#141414` | Very deep background |
+| gray-1000 | `#0a0a0a` | **Primary text (core)** |
+
+#### Opacity Values
+
+##### Opacity Black
+
+| Opacity | Value | Usage |
+|---------|-------|-------|
+| 0% | `#0a0a0a00` | Fully transparent |
+| 2% | `#0a0a0a05` | Subtle overlay |
+| 4% | `#0a0a0a0a` | Secondary interactive background |
+| 8% | `#0a0a0a14` | Border / divider |
+| 15% | `#0a0a0a26` | Pressed state |
+| 20% | `#0a0a0a33` | Light overlay |
+| 25% | `#0a0a0a40` | Medium overlay |
+| 50% | `#0a0a0a80` | Semi-transparent |
+| 70% | `#0a0a0ab2` | Deep overlay |
+| 80% | `#0a0a0acc` | Hover state |
+| 90% | `#0a0a0ae5` | Tooltip |
+| 95% | `#0a0a0af2` | Modal |
+
+##### Opacity White
+
+| Opacity | Value | Usage |
+|---------|-------|-------|
+| 0% | `#ffffff00` | Fully transparent |
+| 2% | `#ffffff05` | Subtle overlay |
+| 4% | `#ffffff0a` | Secondary interactive background |
+| 8% | `#ffffff12` | Border / divider |
+| 15% | `#ffffff26` | Pressed state |
+| 20% | `#ffffff33` | Light overlay |
+| 25% | `#ffffff40` | Medium overlay |
+| 50% | `#ffffff80` | Semi-transparent |
+| 70% | `#ffffffb2` | Deep overlay |
+| 80% | `#ffffffcc` | Hover state |
+| 90% | `#ffffffe5` | Tooltip |
+| 95% | `#fffffff2` | Modal |
+
+---
+
+## Color Palette Rules (MANDATORY)
+
+### Strict Palette Adherence
+
+**Use ONLY the provided color palette. Do NOT create or modify colors.**
+
+- All colors must come from the user-provided palette
+- Do NOT use colors outside the palette
+- Do NOT modify palette colors (brightness, saturation, mixing)
+- **Only exception**: Add transparency using the `transparency` property (0-100)
+
+```javascript
+// Correct: Using palette colors
+slide.addShape(pres.shapes.RECTANGLE, { fill: { color: theme.primary } });
+slide.addText("Title", { color: theme.accent });
+
+// Wrong: Colors outside palette
+slide.addShape(pres.shapes.RECTANGLE, { fill: { color: "1a1a2e" } });
+```
+
+### No Gradients
+
+**Gradients are prohibited. Use solid colors only.**
+
+### No Animations
+
+**Animations and transitions are prohibited.** All slides must be static.
+
+---
+
+## Font Reference
+
+### Recommended Fonts
+
+| Language | Default Font | Alternatives |
+|----------|-------------|--------------|
+| **Chinese** | Microsoft YaHei | — |
+| **English** | Arial | Georgia, Calibri, Cambria, Trebuchet MS |
+
+- For mixed Chinese-English content: use Microsoft YaHei for Chinese, the chosen font for English
+- Prefer system fonts for cross-platform compatibility
+- Titles and body text can use different font pairings (e.g. Georgia + Calibri)
+
+### Recommended Font Pairings
+
+| Header Font | Body Font |
+|-------------|-----------|
+| Georgia | Calibri |
+| Arial Black | Arial |
+| Calibri | Calibri Light |
+| Cambria | Calibri |
+| Trebuchet MS | Calibri |
+| Impact | Arial |
+| Palatino | Garamond |
+| Consolas | Calibri |
+
+**Choose an interesting font pairing** — don't default to Arial for everything. Pick a header font with personality and pair it with a clean body font.
+
+### No Bold for Body Text
+
+**Plain body text and caption/legend text must NOT use bold.**
+
+- Body paragraphs, descriptions → normal weight
+- Captions, legends, footnotes → normal weight
+- Reserve bold for titles and headings only
+
+```javascript
+// Correct
+slide.addText("Main Title", { bold: true, fontSize: 36, fontFace: "Arial" });
+slide.addText("Body text here.", { bold: false, fontSize: 14, fontFace: "Arial" });
+
+// Wrong
+slide.addText("Body text here.", { bold: true, fontSize: 14 });
+```
+
+---
+
+## Style Recipes
+
+The same design can be rendered in 4 distinct visual styles by adjusting corner radius (`rectRadius`) and spacing. Choose the style recipe that fits the presentation tone.
+
+> **Unit note**: PptxGenJS uses inches. Slide dimensions are 10" x 5.625" (LAYOUT_16x9).
+
+### Style Overview
+
+| Style | Corner Radius | Spacing | Best For |
+|-------|--------------|---------|----------|
+| **Sharp & Compact** | 0 ~ 0.05" | Tight | Data-dense, tables, professional reports |
+| **Soft & Balanced** | 0.08" ~ 0.12" | Moderate | Corporate, business presentations, general use |
+| **Rounded & Spacious** | 0.15" ~ 0.25" | Relaxed | Product intros, marketing, creative showcases |
+| **Pill & Airy** | 0.3" ~ 0.5" | Open | Brand showcases, launch events, premium presentations |
+
+### Sharp & Compact
+
+**Visual character**: Geometric, high information density, formal and serious.
+
+| Category | Value (inches) | Notes |
+|----------|---------------|-------|
+| Corner radius — small | 0" | Full right angle |
+| Corner radius — medium | 0.03" | Micro-rounded |
+| Corner radius — large | 0.05" | Slight rounding |
+| Element padding | 0.1" ~ 0.15" | Compact |
+| Element gap | 0.1" ~ 0.2" | Compact |
+| Page margin | 0.3" | Narrow |
+| Block gap | 0.25" ~ 0.35" | Compact |
+
+### Soft & Balanced
+
+**Visual character**: Moderate rounding, comfortable whitespace, professional yet approachable.
+
+| Category | Value (inches) | Notes |
+|----------|---------------|-------|
+| Corner radius — small | 0.05" | Slight rounding |
+| Corner radius — medium | 0.08" | Medium rounding |
+| Corner radius — large | 0.12" | Larger rounding |
+| Element padding | 0.15" ~ 0.2" | Moderate |
+| Element gap | 0.15" ~ 0.25" | Moderate |
+| Page margin | 0.4" | Standard |
+| Block gap | 0.35" ~ 0.5" | Moderate |
+
+### Rounded & Spacious
+
+**Visual character**: Large corners, generous whitespace, friendly and modern.
+
+| Category | Value (inches) | Notes |
+|----------|---------------|-------|
+| Corner radius — small | 0.1" | Medium rounding |
+| Corner radius — medium | 0.15" | Large rounding |
+| Corner radius — large | 0.25" | Very large rounding |
+| Element padding | 0.2" ~ 0.3" | Relaxed |
+| Element gap | 0.25" ~ 0.4" | Relaxed |
+| Page margin | 0.5" | Wide |
+| Block gap | 0.5" ~ 0.7" | Relaxed |
+
+### Pill & Airy
+
+**Visual character**: Full pill-shaped corners, abundant whitespace, light and open feel, strong brand presence.
+
+| Category | Value (inches) | Notes |
+|----------|---------------|-------|
+| Corner radius — small | 0.2" | Large rounding |
+| Corner radius — medium | 0.3" | Pill shape |
+| Corner radius — large | 0.5" | Full pill |
+| Element padding | 0.25" ~ 0.4" | Open |
+| Element gap | 0.3" ~ 0.5" | Open |
+| Page margin | 0.6" | Wide |
+| Block gap | 0.6" ~ 0.9" | Open |
+
+### Component Style Mapping
+
+| Component | Sharp | Soft | Rounded | Pill |
+|-----------|-------|------|---------|------|
+| **Button / Tag** | rectRadius: 0 | rectRadius: 0.05 | rectRadius: 0.1 | rectRadius: 0.2 |
+| **Card / Container** | rectRadius: 0.03 | rectRadius: 0.1 | rectRadius: 0.2 | rectRadius: 0.3 |
+| **Image Container** | rectRadius: 0 | rectRadius: 0.08 | rectRadius: 0.15 | rectRadius: 0.25 |
+| **Input Field** | rectRadius: 0 | rectRadius: 0.05 | rectRadius: 0.1 | rectRadius: 0.2 |
+| **Badge** | rectRadius: 0.02 | rectRadius: 0.05 | rectRadius: 0.08 | rectRadius: 0.15 |
+| **Avatar Frame** | rectRadius: 0 | rectRadius: 0.1 | rectRadius: 0.2 | rectRadius: 0.5 (circle) |
+
+#### PptxGenJS Corner Radius Examples
+
+```javascript
+// Sharp style card
+slide.addShape("rect", {
+  x: 0.5, y: 1, w: 4, h: 2.5,
+  fill: { color: "F5F5F5" },
+  rectRadius: 0.03
+});
+
+// Rounded style card
+slide.addShape("rect", {
+  x: 0.5, y: 1, w: 4, h: 2.5,
+  fill: { color: "F5F5F5" },
+  rectRadius: 0.2
+});
+
+// Pill style button (height 0.4", rectRadius 0.2" = perfect pill)
+slide.addShape("rect", {
+  x: 3, y: 4, w: 2, h: 0.4,
+  fill: { color: "4A90D9" },
+  rectRadius: 0.2
+});
+```
+
+### Mixing Rules
+
+#### 1. Outer container corner >= inner element corner
+
+```javascript
+// Correct: outer > inner
+card:   rectRadius: 0.2
+button: rectRadius: 0.1
+
+// Wrong: inner > outer → visual overflow effect
+card:   rectRadius: 0.1
+button: rectRadius: 0.2
+```
+
+#### 2. Information density drives spacing
+
+| Zone Type | Recommended Style |
+|-----------|------------------|
+| Data display zone | Sharp / Soft (compact spacing) |
+| Content browsing zone | Rounded / Pill (relaxed spacing) |
+| Title zone | Soft / Rounded (moderate spacing) |
+
+#### 3. Corner radius vs element height
+
+| Element Height | Sharp | Soft | Rounded | Pill |
+|---------------|-------|------|---------|------|
+| Small (< 0.3") | 0" | 0.03" | 0.08" | height/2 |
+| Medium (0.3" ~ 0.6") | 0.02" | 0.05" | 0.12" | height/2 |
+| Large (0.6" ~ 1.2") | 0.03" | 0.08" | 0.2" | 0.3" |
+| Extra large (> 1.2") | 0.05" | 0.12" | 0.25" | 0.4" |
+
+> **Pill tip**: For a perfect pill shape, set `rectRadius = element height / 2`
+
+### Typography Scale (PPT)
+
+| Usage | Size (pt) | Notes |
+|-------|-----------|-------|
+| Annotations / Sources | 10 ~ 12 | Minimum readable size |
+| Body / Description | 14 ~ 16 | Standard body |
+| Subtitle | 18 ~ 22 | Secondary heading |
+| Title | 28 ~ 36 | Page title |
+| Large Title | 44 ~ 60 | Cover / section title |
+| Data Callout | 60 ~ 96 | Key number display |
+
+### Spacing Scale (PPT)
+
+Based on 10" x 5.625" slide dimensions:
+
+| Usage | Recommended (inches) |
+|-------|---------------------|
+| Icon-to-text gap | 0.08" ~ 0.15" |
+| List item spacing | 0.15" ~ 0.25" |
+| Card inner padding | 0.2" ~ 0.4" |
+| Element group gap | 0.3" ~ 0.5" |
+| Page safe margin | 0.4" ~ 0.6" |
+| Major block gap | 0.5" ~ 0.8" |
+
+### Quick Selection Guide
+
+| Presentation Type | Recommended Style | Reason |
+|------------------|------------------|--------|
+| Finance / Data reports | Sharp & Compact | High density, serious and precise |
+| Corporate / Business | Soft & Balanced | Balances professionalism and approachability |
+| Product intro / Marketing | Rounded & Spacious | Modern feel, friendly |
+| Launch events / Brand | Pill & Airy | Premium feel, visual impact |
+| Training / Education | Soft / Rounded | Clear, readable, friendly |
+| Tech sharing | Sharp / Soft | Professional, information-dense |
diff --git a/builtin-skills/document-process/pptx-generator/references/editing.md b/builtin-skills/document-process/pptx-generator/references/editing.md
new file mode 100644
index 00000000..ab2e9ca5
--- /dev/null
+++ b/builtin-skills/document-process/pptx-generator/references/editing.md
@@ -0,0 +1,162 @@
+# Editing Existing Presentations
+
+## Template-Based Workflow
+
+When using an existing presentation as a template:
+
+1. **Copy and analyze**:
+   ```bash
+   cp /path/to/user-provided.pptx template.pptx
+   python -m markitdown template.pptx > template.md
+   ```
+   Review `template.md` to see placeholder text and slide structure.
+
+2. **Plan slide mapping**: For each content section, choose a template slide.
+
+   **USE VARIED LAYOUTS** — monotonous presentations are a common failure mode. Don't default to basic title + bullet slides. Actively seek out:
+   - Multi-column layouts (2-column, 3-column)
+   - Image + text combinations
+   - Full-bleed images with text overlay
+   - Quote or callout slides
+   - Section dividers
+   - Stat/number callouts
+   - Icon grids or icon + text rows
+
+   **Avoid:** Repeating the same text-heavy layout for every slide.
+
+   Match content type to layout style (e.g., key points -> bullet slide, team info -> multi-column, testimonials -> quote slide).
+
+3. **Unpack**: Extract the PPTX into an editable XML tree using Python's `zipfile` module. Pretty-print the XML for readability.
+
+4. **Build presentation** (do this yourself, not with subagents):
+   - Delete unwanted slides (remove from `<p:sldIdLst>`)
+   - Duplicate slides you want to reuse (copy slide XML, relationships, and update `Content_Types.xml` and `presentation.xml`)
+   - Reorder slides in `<p:sldIdLst>`
+   - **Complete all structural changes before step 5**
+
+5. **Edit content**: Update text in each `slide{N}.xml`.
+   **Use subagents here if available** — slides are separate XML files, so subagents can edit in parallel.
+
+6. **Clean**: Remove orphaned files — slides not in `<p:sldIdLst>`, unreferenced media, orphaned rels.
+
+7. **Pack**: Repack the XML tree into a PPTX file. Validate, repair, condense XML, re-encode smart quotes.
+
+   Always write to `/tmp/` first, then copy to the final path. Python's `zipfile` module uses `seek` internally, which fails on some volume mounts (e.g. Docker bind mounts). Writing to a local temp path avoids this.
+
+## Output Structure
+
+Copy the user-provided file to `template.pptx` in cwd. This preserves the original and gives a predictable name for all downstream operations.
+
+```bash
+cp /path/to/user-provided.pptx template.pptx
+```
+
+```text
+./
+├── template.pptx               # Copy of user-provided file (never modified)
+├── template.md                 # markitdown extraction
+├── unpacked/                   # Editable XML tree
+└── edited.pptx                 # Final repacked deck
+```
+
+Minimum expected deliverable: `edited.pptx`.
+
+## Slide Operations
+
+Slide order is in `ppt/presentation.xml` -> `<p:sldIdLst>`.
+
+**Reorder**: Rearrange `<p:sldId>` elements.
+
+**Delete**: Remove `<p:sldId>`, then clean orphaned files.
+
+**Add**: Copy the source slide's XML file, its `.rels` file, and update `Content_Types.xml` and `presentation.xml`. Never manually copy slide files without updating all references — this causes broken notes references and missing relationship IDs.
+
+## Editing Content
+
+**Subagents:** If available, use them here (after completing step 4). Each slide is a separate XML file, so subagents can edit in parallel. In your prompt to subagents, include:
+- The slide file path(s) to edit
+- **"Use the Edit tool for all changes"**
+- The formatting rules and common pitfalls below
+
+For each slide:
+1. Read the slide's XML
+2. Identify ALL placeholder content — text, images, charts, icons, captions
+3. Replace each placeholder with final content
+
+**Use the Edit tool, not sed or Python scripts.** The Edit tool forces specificity about what to replace and where, yielding better reliability.
+
+## Formatting Rules
+
+- **Bold all headers, subheadings, and inline labels**: Use `b="1"` on `<a:rPr>`. This includes:
+  - Slide titles
+  - Section headers within a slide
+  - Inline labels like (e.g.: "Status:", "Description:") at the start of a line
+- **Never use unicode bullets**: Use proper list formatting with `<a:buChar>` or `<a:buAutoNum>`
+- **Bullet consistency**: Let bullets inherit from the layout. Only specify `<a:buChar>` or `<a:buNone>`.
+
+## Common Pitfalls — Template Editing
+
+### Template Adaptation
+
+When source content has fewer items than the template:
+- **Remove excess elements entirely** (images, shapes, text boxes), don't just clear text
+- Check for orphaned visuals after clearing text content
+- Run content QA with `markitdown` to catch mismatched counts
+
+When replacing text with different length content:
+- **Shorter replacements**: Usually safe
+- **Longer replacements**: May overflow or wrap unexpectedly
+- Verify with `markitdown` after text changes
+- Consider truncating or splitting content to fit the template's design constraints
+
+**Template slots != Source items**: If template has 4 team members but source has 3 users, delete the 4th member's entire group (image + text boxes), not just the text.
+
+### Multi-Item Content
+
+If source has multiple items (numbered lists, multiple sections), create separate `<a:p>` elements for each — **never concatenate into one string**.
+
+**WRONG** — all items in one paragraph:
+```xml
+<a:p>
+  <a:r><a:rPr .../><a:t>Step 1: Do the first thing. Step 2: Do the second thing.</a:t></a:r>
+</a:p>
+```
+
+**CORRECT** — separate paragraphs with bold headers:
+```xml
+<a:p>
+  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
+  <a:r><a:rPr lang="en-US" sz="2799" b="1" .../><a:t>Step 1</a:t></a:r>
+</a:p>
+<a:p>
+  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
+  <a:r><a:rPr lang="en-US" sz="2799" .../><a:t>Do the first thing.</a:t></a:r>
+</a:p>
+<a:p>
+  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
+  <a:r><a:rPr lang="en-US" sz="2799" b="1" .../><a:t>Step 2</a:t></a:r>
+</a:p>
+<!-- continue pattern -->
+```
+
+Copy `<a:pPr>` from the original paragraph to preserve line spacing. Use `b="1"` on headers.
+
+### Smart Quotes
+
+The Edit tool converts smart quotes to ASCII. **When adding new text with quotes, use XML entities:**
+
+```xml
+<a:t>the &#x201C;Agreement&#x201D;</a:t>
+```
+
+| Character | Name | Unicode | XML Entity |
+|-----------|------|---------|------------|
+| \u201c | Left double quote | U+201C | `&#x201C;` |
+| \u201d | Right double quote | U+201D | `&#x201D;` |
+| \u2018 | Left single quote | U+2018 | `&#x2018;` |
+| \u2019 | Right single quote | U+2019 | `&#x2019;` |
+
+### Other
+
+- **Whitespace**: Use `xml:space="preserve"` on `<a:t>` with leading/trailing spaces
+- **XML parsing**: Use `defusedxml.minidom`, not `xml.etree.ElementTree` (corrupts namespaces)
diff --git a/builtin-skills/document-process/pptx-generator/references/pitfalls.md b/builtin-skills/document-process/pptx-generator/references/pitfalls.md
new file mode 100644
index 00000000..cb6eefc4
--- /dev/null
+++ b/builtin-skills/document-process/pptx-generator/references/pitfalls.md
@@ -0,0 +1,112 @@
+# QA Process & Common Pitfalls
+
+## QA Process
+
+**Assume there are problems. Your job is to find them.**
+
+Your first render is almost never correct. Approach QA as a bug hunt, not a confirmation step. If you found zero issues on first inspection, you weren't looking hard enough.
+
+### Content QA
+
+```bash
+python -m markitdown output.pptx
+```
+
+Check for missing content, typos, wrong order.
+
+**Check for leftover placeholder text:**
+
+```bash
+python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|placeholder|this.*(page|slide).*layout"
+```
+
+If grep returns results, fix them before declaring success.
+
+### Verification Loop
+
+1. Generate slides -> Extract text with `python -m markitdown output.pptx` -> Review content
+2. **List issues found** (if none found, look again more critically)
+3. Fix issues
+4. **Re-verify affected slides** — one fix often creates another problem
+5. Repeat until a full pass reveals no new issues
+
+**Do not declare success until you've completed at least one fix-and-verify cycle.**
+
+### Per-Slide QA (for from-scratch creation)
+
+```bash
+python -m markitdown slide-XX-preview.pptx
+```
+
+Check for missing content, placeholder text, missing page number badge.
+
+---
+
+## Common Mistakes to Avoid
+
+- **Don't repeat the same layout** — vary columns, cards, and callouts across slides
+- **Don't center body text** — left-align paragraphs and lists; center only titles
+- **Don't skimp on size contrast** — titles need 36pt+ to stand out from 14-16pt body
+- **Don't default to blue** — pick colors that reflect the specific topic
+- **Don't mix spacing randomly** — choose 0.3" or 0.5" gaps and use consistently
+- **Don't style one slide and leave the rest plain** — commit fully or keep it simple throughout
+- **Don't create text-only slides** — add images, icons, charts, or visual elements; avoid plain title + bullets
+- **Don't forget text box padding** — when aligning lines or shapes with text edges, set `margin: 0` on the text box or offset the shape to account for padding
+- **Don't use low-contrast elements** — icons AND text need strong contrast against the background
+- **NEVER use accent lines under titles** — these are a hallmark of AI-generated slides; use whitespace or background color instead
+- **NEVER use "#" with hex colors** — causes file corruption in PptxGenJS
+- **NEVER encode opacity in hex strings** — use the `opacity` property instead
+- **NEVER use async/await in createSlide()** — compile.js won't await
+- **NEVER reuse option objects across PptxGenJS calls** — PptxGenJS mutates objects in-place
+
+---
+
+## Critical Pitfalls — PptxGenJS
+
+### NEVER use async/await in createSlide()
+
+```javascript
+// WRONG - compile.js won't await
+async function createSlide(pres, theme) { ... }
+
+// CORRECT
+function createSlide(pres, theme) { ... }
+```
+
+### NEVER use "#" with hex colors
+
+```javascript
+color: "FF0000"      // CORRECT
+color: "#FF0000"     // CORRUPTS FILE
+```
+
+### NEVER encode opacity in hex strings
+
+```javascript
+shadow: { color: "00000020" }              // CORRUPTS FILE
+shadow: { color: "000000", opacity: 0.12 } // CORRECT
+```
+
+### Prevent text wrapping in titles
+
+```javascript
+// Use fit:'shrink' for long titles
+slide.addText("Long Title Here", {
+  x: 0.5, y: 2, w: 9, h: 1,
+  fontSize: 48, fit: "shrink"
+});
+```
+
+### NEVER reuse option objects across calls
+
+```javascript
+// WRONG
+const shadow = { type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 };
+slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });
+slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });
+
+// CORRECT - factory function
+const makeShadow = () => ({ type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 });
+slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });
+slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });
+```
diff --git a/builtin-skills/document-process/pptx-generator/references/pptxgenjs.md b/builtin-skills/document-process/pptx-generator/references/pptxgenjs.md
new file mode 100644
index 00000000..f6495162
--- /dev/null
+++ b/builtin-skills/document-process/pptx-generator/references/pptxgenjs.md
@@ -0,0 +1,420 @@
+# PptxGenJS Tutorial
+
+## Setup & Basic Structure
+
+```javascript
+const pptxgen = require("pptxgenjs");
+
+let pres = new pptxgen();
+pres.layout = 'LAYOUT_16x9';  // or 'LAYOUT_16x10', 'LAYOUT_4x3', 'LAYOUT_WIDE'
+pres.author = 'Your Name';
+pres.title = 'Presentation Title';
+
+let slide = pres.addSlide();
+slide.addText("Hello World!", { x: 0.5, y: 0.5, fontSize: 36, color: "363636" });
+
+pres.writeFile({ fileName: "Presentation.pptx" });
+```
+
+## Layout Dimensions
+
+Slide dimensions (coordinates in inches):
+- `LAYOUT_16x9`: 10" x 5.625" (default)
+- `LAYOUT_16x10`: 10" x 6.25"
+- `LAYOUT_4x3`: 10" x 7.5"
+- `LAYOUT_WIDE`: 13.3" x 7.5"
+
+---
+
+## Text & Formatting
+
+```javascript
+// Basic text
+slide.addText("Simple Text", {
+  x: 1, y: 1, w: 8, h: 2, fontSize: 24, fontFace: "Arial",
+  color: "363636", bold: true, align: "center", valign: "middle"
+});
+
+// Character spacing (use charSpacing, not letterSpacing which is silently ignored)
+slide.addText("SPACED TEXT", { x: 1, y: 1, w: 8, h: 1, charSpacing: 6 });
+
+// Rich text arrays
+slide.addText([
+  { text: "Bold ", options: { bold: true } },
+  { text: "Italic ", options: { italic: true } }
+], { x: 1, y: 3, w: 8, h: 1 });
+
+// Multi-line text (requires breakLine: true)
+slide.addText([
+  { text: "Line 1", options: { breakLine: true } },
+  { text: "Line 2", options: { breakLine: true } },
+  { text: "Line 3" }  // Last item doesn't need breakLine
+], { x: 0.5, y: 0.5, w: 8, h: 2 });
+
+// Text box margin (internal padding)
+slide.addText("Title", {
+  x: 0.5, y: 0.3, w: 9, h: 0.6,
+  margin: 0  // Use 0 when aligning text with other elements like shapes or icons
+});
+```
+
+**Tip:** Text boxes have internal margin by default. Set `margin: 0` when you need text to align precisely with shapes, lines, or icons at the same x-position.
+
+---
+
+## Lists & Bullets
+
+```javascript
+// CORRECT: Multiple bullets
+slide.addText([
+  { text: "First item", options: { bullet: true, breakLine: true } },
+  { text: "Second item", options: { bullet: true, breakLine: true } },
+  { text: "Third item", options: { bullet: true } }
+], { x: 0.5, y: 0.5, w: 8, h: 3 });
+
+// WRONG: Never use unicode bullets
+slide.addText("* First item", { ... });  // Creates double bullets
+
+// Sub-items and numbered lists
+{ text: "Sub-item", options: { bullet: true, indentLevel: 1 } }
+{ text: "First", options: { bullet: { type: "number" }, breakLine: true } }
+```
+
+---
+
+## Shapes
+
+```javascript
+slide.addShape(pres.shapes.RECTANGLE, {
+  x: 0.5, y: 0.8, w: 1.5, h: 3.0,
+  fill: { color: "FF0000" }, line: { color: "000000", width: 2 }
+});
+
+slide.addShape(pres.shapes.OVAL, { x: 4, y: 1, w: 2, h: 2, fill: { color: "0000FF" } });
+
+slide.addShape(pres.shapes.LINE, {
+  x: 1, y: 3, w: 5, h: 0, line: { color: "FF0000", width: 3, dashType: "dash" }
+});
+
+// With transparency
+slide.addShape(pres.shapes.RECTANGLE, {
+  x: 1, y: 1, w: 3, h: 2,
+  fill: { color: "0088CC", transparency: 50 }
+});
+
+// Rounded rectangle (rectRadius only works with ROUNDED_RECTANGLE, not RECTANGLE)
+// Don't pair with rectangular accent overlays -- they won't cover rounded corners. Use RECTANGLE instead.
+slide.addShape(pres.shapes.ROUNDED_RECTANGLE, {
+  x: 1, y: 1, w: 3, h: 2,
+  fill: { color: "FFFFFF" }, rectRadius: 0.1
+});
+
+// With shadow
+slide.addShape(pres.shapes.RECTANGLE, {
+  x: 1, y: 1, w: 3, h: 2,
+  fill: { color: "FFFFFF" },
+  shadow: { type: "outer", color: "000000", blur: 6, offset: 2, angle: 135, opacity: 0.15 }
+});
+```
+
+Shadow options:
+
+| Property | Type | Range | Notes |
+|----------|------|-------|-------|
+| `type` | string | `"outer"`, `"inner"` | |
+| `color` | string | 6-char hex (e.g. `"000000"`) | No `#` prefix, no 8-char hex -- see Common Pitfalls |
+| `blur` | number | 0-100 pt | |
+| `offset` | number | 0-200 pt | **Must be non-negative** -- negative values corrupt the file |
+| `angle` | number | 0-359 degrees | Direction the shadow falls (135 = bottom-right, 270 = upward) |
+| `opacity` | number | 0.0-1.0 | Use this for transparency, never encode in color string |
+
+To cast a shadow upward (e.g. on a footer bar), use `angle: 270` with a positive offset -- do **not** use a negative offset.
+
+**Note**: Gradient fills are not natively supported. Use a gradient image as a background instead.
+
+---
+
+## Images
+
+### Image Sources
+
+```javascript
+// From file path
+slide.addImage({ path: "images/chart.png", x: 1, y: 1, w: 5, h: 3 });
+
+// From URL
+slide.addImage({ path: "https://example.com/image.jpg", x: 1, y: 1, w: 5, h: 3 });
+
+// From base64 (faster, no file I/O)
+slide.addImage({ data: "image/png;base64,iVBORw0KGgo...", x: 1, y: 1, w: 5, h: 3 });
+```
+
+### Image Options
+
+```javascript
+slide.addImage({
+  path: "image.png",
+  x: 1, y: 1, w: 5, h: 3,
+  rotate: 45,              // 0-359 degrees
+  rounding: true,          // Circular crop
+  transparency: 50,        // 0-100
+  flipH: true,             // Horizontal flip
+  flipV: false,            // Vertical flip
+  altText: "Description",  // Accessibility
+  hyperlink: { url: "https://example.com" }
+});
+```
+
+### Image Sizing Modes
+
+```javascript
+// Contain - fit inside, preserve ratio
+{ sizing: { type: 'contain', w: 4, h: 3 } }
+
+// Cover - fill area, preserve ratio (may crop)
+{ sizing: { type: 'cover', w: 4, h: 3 } }
+
+// Crop - cut specific portion
+{ sizing: { type: 'crop', x: 0.5, y: 0.5, w: 2, h: 2 } }
+```
+
+### Calculate Dimensions (preserve aspect ratio)
+
+```javascript
+const origWidth = 1978, origHeight = 923, maxHeight = 3.0;
+const calcWidth = maxHeight * (origWidth / origHeight);
+const centerX = (10 - calcWidth) / 2;
+
+slide.addImage({ path: "image.png", x: centerX, y: 1.2, w: calcWidth, h: maxHeight });
+```
+
+### Supported Formats
+
+- **Standard**: PNG, JPG, GIF (animated GIFs work in Microsoft 365)
+- **SVG**: Works in modern PowerPoint/Microsoft 365
+
+---
+
+## Icons
+
+Use react-icons to generate SVG icons, then rasterize to PNG for universal compatibility.
+
+### Setup
+
+```javascript
+const React = require("react");
+const ReactDOMServer = require("react-dom/server");
+const sharp = require("sharp");
+const { FaCheckCircle, FaChartLine } = require("react-icons/fa");
+
+function renderIconSvg(IconComponent, color = "#000000", size = 256) {
+  return ReactDOMServer.renderToStaticMarkup(
+    React.createElement(IconComponent, { color, size: String(size) })
+  );
+}
+
+async function iconToBase64Png(IconComponent, color, size = 256) {
+  const svg = renderIconSvg(IconComponent, color, size);
+  const pngBuffer = await sharp(Buffer.from(svg)).png().toBuffer();
+  return "image/png;base64," + pngBuffer.toString("base64");
+}
+```
+
+### Add Icon to Slide
+
+```javascript
+const iconData = await iconToBase64Png(FaCheckCircle, "#4472C4", 256);
+
+slide.addImage({
+  data: iconData,
+  x: 1, y: 1, w: 0.5, h: 0.5  // Size in inches
+});
+```
+
+**Note**: Use size 256 or higher for crisp icons. The size parameter controls the rasterization resolution, not the display size on the slide (which is set by `w` and `h` in inches).
+
+### Icon Libraries
+
+Install: `npm install -g react-icons react react-dom sharp`
+
+Popular icon sets in react-icons:
+- `react-icons/fa` - Font Awesome
+- `react-icons/md` - Material Design
+- `react-icons/hi` - Heroicons
+- `react-icons/bi` - Bootstrap Icons
+
+---
+
+## Slide Backgrounds
+
+```javascript
+// Solid color
+slide.background = { color: "F1F1F1" };
+
+// Color with transparency
+slide.background = { color: "FF3399", transparency: 50 };
+
+// Image from URL
+slide.background = { path: "https://example.com/bg.jpg" };
+
+// Image from base64
+slide.background = { data: "image/png;base64,iVBORw0KGgo..." };
+```
+
+---
+
+## Tables
+
+```javascript
+slide.addTable([
+  ["Header 1", "Header 2"],
+  ["Cell 1", "Cell 2"]
+], {
+  x: 1, y: 1, w: 8, h: 2,
+  border: { pt: 1, color: "999999" }, fill: { color: "F1F1F1" }
+});
+
+// Advanced with merged cells
+let tableData = [
+  [{ text: "Header", options: { fill: { color: "6699CC" }, color: "FFFFFF", bold: true } }, "Cell"],
+  [{ text: "Merged", options: { colspan: 2 } }]
+];
+slide.addTable(tableData, { x: 1, y: 3.5, w: 8, colW: [4, 4] });
+```
+
+---
+
+## Charts
+
+```javascript
+// Bar chart
+slide.addChart(pres.charts.BAR, [{
+  name: "Sales", labels: ["Q1", "Q2", "Q3", "Q4"], values: [4500, 5500, 6200, 7100]
+}], {
+  x: 0.5, y: 0.6, w: 6, h: 3, barDir: 'col',
+  showTitle: true, title: 'Quarterly Sales'
+});
+
+// Line chart
+slide.addChart(pres.charts.LINE, [{
+  name: "Temp", labels: ["Jan", "Feb", "Mar"], values: [32, 35, 42]
+}], { x: 0.5, y: 4, w: 6, h: 3, lineSize: 3, lineSmooth: true });
+
+// Pie chart
+slide.addChart(pres.charts.PIE, [{
+  name: "Share", labels: ["A", "B", "Other"], values: [35, 45, 20]
+}], { x: 7, y: 1, w: 5, h: 4, showPercent: true });
+```
+
+### Better-Looking Charts
+
+Default charts look dated. Apply these options for a modern, clean appearance:
+
+```javascript
+slide.addChart(pres.charts.BAR, chartData, {
+  x: 0.5, y: 1, w: 9, h: 4, barDir: "col",
+
+  // Custom colors (match your presentation palette)
+  chartColors: ["0D9488", "14B8A6", "5EEAD4"],
+
+  // Clean background
+  chartArea: { fill: { color: "FFFFFF" }, roundedCorners: true },
+
+  // Muted axis labels
+  catAxisLabelColor: "64748B",
+  valAxisLabelColor: "64748B",
+
+  // Subtle grid (value axis only)
+  valGridLine: { color: "E2E8F0", size: 0.5 },
+  catGridLine: { style: "none" },
+
+  // Data labels on bars
+  showValue: true,
+  dataLabelPosition: "outEnd",
+  dataLabelColor: "1E293B",
+
+  // Hide legend for single series
+  showLegend: false,
+});
+```
+
+**Key styling options:**
+- `chartColors: [...]` - hex colors for series/segments
+- `chartArea: { fill, border, roundedCorners }` - chart background
+- `catGridLine/valGridLine: { color, style, size }` - grid lines (`style: "none"` to hide)
+- `lineSmooth: true` - curved lines (line charts)
+- `legendPos: "r"` - legend position: "b", "t", "l", "r", "tr"
+
+---
+
+## Slide Masters
+
+```javascript
+pres.defineSlideMaster({
+  title: 'TITLE_SLIDE', background: { color: '283A5E' },
+  objects: [{
+    placeholder: { options: { name: 'title', type: 'title', x: 1, y: 2, w: 8, h: 2 } }
+  }]
+});
+
+let titleSlide = pres.addSlide({ masterName: "TITLE_SLIDE" });
+titleSlide.addText("My Title", { placeholder: "title" });
+```
+
+---
+
+## Common Pitfalls
+
+These issues cause file corruption, visual bugs, or broken output. Avoid them.
+
+1. **NEVER use "#" with hex colors** - causes file corruption
+   ```javascript
+   color: "FF0000"      // CORRECT
+   color: "#FF0000"     // WRONG
+   ```
+
+2. **NEVER encode opacity in hex color strings** - 8-char colors (e.g., `"00000020"`) corrupt the file. Use the `opacity` property instead.
+   ```javascript
+   shadow: { type: "outer", blur: 6, offset: 2, color: "00000020" }          // CORRUPTS FILE
+   shadow: { type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.12 }  // CORRECT
+   ```
+
+3. **Use `bullet: true`** - NEVER unicode symbols like "o" (creates double bullets)
+
+4. **Use `breakLine: true`** between array items or text runs together
+
+5. **Avoid `lineSpacing` with bullets** - causes excessive gaps; use `paraSpaceAfter` instead
+
+6. **Each presentation needs fresh instance** - don't reuse `pptxgen()` objects
+
+7. **NEVER reuse option objects across calls** - PptxGenJS mutates objects in-place (e.g. converting shadow values to EMU). Sharing one object between multiple calls corrupts the second shape.
+   ```javascript
+   const shadow = { type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 };
+   slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });  // second call gets already-converted values
+   slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });
+
+   const makeShadow = () => ({ type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 });
+   slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });  // fresh object each time
+   slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });
+   ```
+
+8. **Don't use `ROUNDED_RECTANGLE` with accent borders** - rectangular overlay bars won't cover rounded corners. Use `RECTANGLE` instead.
+   ```javascript
+   // WRONG: Accent bar doesn't cover rounded corners
+   slide.addShape(pres.shapes.ROUNDED_RECTANGLE, { x: 1, y: 1, w: 3, h: 1.5, fill: { color: "FFFFFF" } });
+   slide.addShape(pres.shapes.RECTANGLE, { x: 1, y: 1, w: 0.08, h: 1.5, fill: { color: "0891B2" } });
+
+   // CORRECT: Use RECTANGLE for clean alignment
+   slide.addShape(pres.shapes.RECTANGLE, { x: 1, y: 1, w: 3, h: 1.5, fill: { color: "FFFFFF" } });
+   slide.addShape(pres.shapes.RECTANGLE, { x: 1, y: 1, w: 0.08, h: 1.5, fill: { color: "0891B2" } });
+   ```
+
+---
+
+## Quick Reference
+
+- **Shapes**: RECTANGLE, OVAL, LINE, ROUNDED_RECTANGLE
+- **Charts**: BAR, LINE, PIE, DOUGHNUT, SCATTER, BUBBLE, RADAR
+- **Layouts**: LAYOUT_16x9 (10"x5.625"), LAYOUT_16x10, LAYOUT_4x3, LAYOUT_WIDE
+- **Alignment**: "left", "center", "right"
+- **Chart data labels**: "outEnd", "inEnd", "center"
diff --git a/builtin-skills/document-process/pptx-generator/references/slide-types.md b/builtin-skills/document-process/pptx-generator/references/slide-types.md
new file mode 100644
index 00000000..699560cf
--- /dev/null
+++ b/builtin-skills/document-process/pptx-generator/references/slide-types.md
@@ -0,0 +1,413 @@
+# Slide Page Types
+
+Classify **every slide** as **exactly one** of these 5 types:
+
+## 1. Cover Page
+
+- **Use for**: Opening + tone setting
+- **Content**: Big title, subtitle/presenter, date/occasion, strong background/motif
+
+### Layout Options
+
+**Asymmetric Left-Right Layout**
+- Text concentrated on one side, image on the opposite
+- Best for: Corporate presentations, product launches, professional reports
+```
+|  Title & Subtitle  |    Visual/Image    |
+|  Description       |                    |
+```
+
+**Center-Aligned Layout**
+- Content centered with background image
+- Best for: Inspirational talks, event presentations, creative pitches
+```
+|                                        |
+|           [Background Image]           |
+|              MAIN TITLE                |
+|              Subtitle                  |
+|                                        |
+```
+
+### Font Size Hierarchy
+
+| Element | Recommended Size | Ratio to Base |
+|---------|-----------------|---------------|
+| Main Title | 72-120px | 3x-5x |
+| Subtitle | 28-40px | 1.5x-2x |
+| Supporting Text | 18-24px | 1x (base) |
+| Meta Info (date, name) | 14-18px | 0.7x-1x |
+
+**Key Principles:**
+1. **Dramatic Contrast**: Main title should be at least 2-3x larger than subtitle
+2. **Visual Anchor**: The largest text becomes the focal point
+3. **Readable Hierarchy**: Viewers should instantly understand what's most important
+4. **Avoid Similarity**: Never let adjacent text elements be within 20% of each other's size
+
+### Content Elements
+
+1. **Main Title** — Always required, largest font
+2. **Subtitle** — When additional context is needed (clearly smaller than title)
+3. **Icons** — When they reinforce the theme
+4. **Date/Event Info** — When relevant (smallest text)
+5. **Company/Brand Logo** — When representing an organization
+6. **Presenter Name** — For keynotes (small, subtle)
+
+### Design Decisions
+
+Consider: Purpose (corporate/educational/creative), Audience, Tone, Content Volume, Visual Assets needed.
+
+### Workflow
+
+1. **Analyze**: Understand topic, audience, purpose
+2. **Choose Layout**: Select based on content
+3. **Write Slide**: Use PptxGenJS. Use shapes and SVG elements for visual interest.
+4. **Verify**: Generate preview as `slide-XX-preview.pptx`. Extract text with `python -m markitdown slide-XX-preview.pptx`, verify all content present and no placeholder text remains.
+
+---
+
+## 2. Table of Contents
+
+- **Use for**: Navigation + expectation setting (3-5 sections)
+- **Content**: Section list (optional icons / page numbers)
+
+### Layout Options
+
+**Numbered Vertical List** — Best for 3-5 sections, straightforward presentations
+```
+|  TABLE OF CONTENTS            |
+|                                |
+|  01  Section Title One         |
+|  02  Section Title Two         |
+|  03  Section Title Three       |
+```
+
+**Two-Column Grid** — Best for 4-6 sections, content-rich presentations
+```
+|  TABLE OF CONTENTS              |
+|                                  |
+|  01  Section One   02  Section Two  |
+|      Description       Description  |
+|  03  Section Three 04  Section Four |
+```
+
+**Sidebar Navigation** — Best for 3-5 sections, modern/corporate
+```
+| ▌01 |  Section Title One           |
+| ▌02 |  Section Title Two           |
+| ▌03 |  Section Title Three         |
+```
+
+**Card-Based** — Best for 3-4 sections, creative/modern
+```
+|  TABLE OF CONTENTS                    |
+|  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  |
+|  │ 01  │  │ 02  │  │ 03  │  │ 04  │  |
+|  │Title│  │Title│  │Title│  │Title│  |
+|  └─────┘  └─────┘  └─────┘  └─────┘  |
+```
+
+### Font Size Hierarchy
+
+| Element | Recommended Size | Ratio to Base |
+|---------|-----------------|---------------|
+| Page Title ("Table of Contents" / "Agenda") | 36-44px | 2.5x-3x |
+| Section Number | 28-36px | 2x-2.5x |
+| Section Title | 20-28px | 1.5x-2x |
+| Section Description | 14-16px | 1x (base) |
+
+**Key Principles:**
+1. **Clear Numbering**: Section numbers should be visually prominent — bold, accent color, or larger size
+2. **Scannable Structure**: Viewer should scan all sections in 2-3 seconds
+3. **Consistent Spacing**: Equal vertical spacing between sections
+4. **Visual Markers**: Colored dots, lines, numbers, or icons to anchor each section
+5. **Avoid Clutter**: Descriptions one line max or omit entirely
+
+### Content Elements
+
+1. **Page Title** — Always required ("Table of Contents", "Agenda", "Overview")
+2. **Section Numbers** — Consistent format (01, 02... or I, II...)
+3. **Section Titles** — Clear and concise
+4. **Section Descriptions** — Optional one-line summaries
+5. **Visual Separators** — SVG dividers or spacing
+6. **Decorative Elements** — Subtle accent shapes
+7. **Page Number Badge** — **MANDATORY**
+
+### Design Decisions
+
+1. **Section Count**: 3 → vertical list; 4-6 → grid or compact; 7+ → multi-column
+2. **Description Length**: Long → vertical list; None → compact grid/cards
+3. **Tone**: Corporate → numbered list; Creative → card-based; Academic → Roman numerals
+4. **Consistency**: Match visual style of cover page
+
+### Workflow
+
+1. **Analyze**: Section list, count, presentation context
+2. **Choose Layout**: Based on section count and content
+3. **Plan Visual Hierarchy**: Numbering style, font sizes, spacing
+4. **Write Slide**: Use PptxGenJS. Use shapes for decorative elements. **MUST include page number badge.**
+5. **Verify**: Generate preview, extract text with markitdown, verify content and badge.
+
+---
+
+## 3. Section Divider
+
+- **Use for**: Clear transitions between major parts
+- **Content**: Section number + title (+ optional 1-2 line intro)
+
+### Layout Options
+
+**Bold Center** — Best for minimal, modern presentations
+```
+|                  02                    |
+|           SECTION TITLE               |
+|         Optional intro line           |
+```
+
+**Left-Aligned with Accent Block** — Best for corporate, structured presentations
+```
+| ████ |  02                            |
+| ████ |  SECTION TITLE                 |
+| ████ |  Optional intro line           |
+```
+
+**Split Background** — Best for high-contrast, dramatic transitions
+```
+| ██████████ |     SECTION TITLE        |
+| ██  02  ██ |     Optional intro       |
+| ██████████ |                          |
+```
+
+**Full-Bleed Background with Overlay** — Best for creative, bold presentations
+```
+| ████████████████████████████████████  |
+| ████       large 02        █████████ |
+| ████    SECTION TITLE      █████████ |
+| ████████████████████████████████████  |
+```
+
+### Font Size Hierarchy
+
+| Element | Recommended Size | Notes |
+|---------|-----------------|-------|
+| Section Number | 72-120px | Bold, accent color or semi-transparent |
+| Section Title | 36-48px | Bold, clear, primary text color |
+| Intro Text | 16-20px | Light weight, muted color, optional |
+
+**Key Principles:**
+1. **Dramatic Number**: Section number = most prominent visual element
+2. **Strong Title**: Large but clearly secondary to the number
+3. **Minimal Content**: Just number + title + optional one-liner
+4. **Breathing Room**: Leave generous whitespace — dividers are pause moments
+
+### Content Elements
+
+1. **Section Number** — Always required. Format: `01`, `02`... or `I`, `II`... Match TOC style.
+2. **Section Title** — Always required. Clear, concise.
+3. **Intro Text** — Optional 1-2 line description.
+4. **Decorative Elements** — SVG accent shapes (bars, lines, geometric blocks).
+5. **Page Number Badge** — **MANDATORY**.
+
+### Design Decisions
+
+1. **Tone**: Corporate → accent block; Creative → full-bleed; Minimal → bold center
+2. **Color**: Strong palette color for background/accent; high-contrast text
+3. **Consistency**: Same divider style across all dividers in one presentation
+4. **Contrast with content slides**: Visually distinct (different background color, more whitespace)
+
+### Workflow
+
+1. **Analyze**: Section number, title, optional intro
+2. **Choose Layout**: Based on content and tone
+3. **Write Slide**: Use PptxGenJS. Use shapes for decorative elements. **MUST include page number badge.**
+4. **Verify**: Generate preview, extract text, verify content and badge.
+
+---
+
+## 4. Content Page
+
+Pick a subtype based on the content. Each content slide belongs to exactly ONE subtype:
+
+### Subtypes
+
+**Text** — Bullets, quotes, or short paragraphs
+- Must still include icons or SVG shapes — never plain text only
+```
+|  SLIDE TITLE                          |
+|  * Bullet point one                   |
+|  * Bullet point two                   |
+|  * Bullet point three                 |
+```
+
+**Mixed Media** — Two-column or half-bleed image + text
+```
+|  SLIDE TITLE                          |
+|  Text content     |  [Image/Visual]   |
+|  and bullets      |                   |
+```
+
+**Data Visualization** — Chart (SVG bar/progress/ring) + takeaways
+- Must include data source
+```
+|  SLIDE TITLE                          |
+|  [SVG Chart]      |  Key Takeaway 1   |
+|                   |  Key Takeaway 2   |
+|                   Source: xxx          |
+```
+
+**Comparison** — Side-by-side columns or cards (A vs B, pros/cons)
+```
+|  SLIDE TITLE                          |
+|  ┌─ Option A ─┐  ┌─ Option B ─┐      |
+|  │  Detail 1  │  │  Detail 1  │      |
+|  └────────────┘  └────────────┘      |
+```
+
+**Timeline / Process** — Steps with arrows, journey, phases
+```
+|  SLIDE TITLE                          |
+|  [1] ──→ [2] ──→ [3] ──→ [4]         |
+|  Step    Step    Step    Step          |
+```
+
+**Image Showcase** — Hero image, gallery, visual-first layout
+```
+|  SLIDE TITLE                          |
+|  ┌────────────────────────────────┐   |
+|  │         [Hero Image]           │   |
+|  └────────────────────────────────┘   |
+|  Caption or supporting text           |
+```
+
+### Font Size Hierarchy
+
+| Element | Recommended Size | Notes |
+|---------|-----------------|-------|
+| Slide Title | 36-44px | Bold, top of slide |
+| Section Header | 20-24px | Bold, for sub-sections within slide |
+| Body Text | 14-16px | Regular weight, left-aligned |
+| Captions / Source | 10-12px | Muted color, smallest text |
+| Stat Callout | 60-72px | Large bold numbers for key statistics |
+
+**Key Principles:**
+1. **Left-align body text** — never center paragraphs or bullet lists
+2. **Size contrast** — title must be 36pt+ to stand out from 14-16pt body
+3. **Visual elements required** — every content slide must have at least one non-text element
+4. **Breathing room** — 0.5" minimum margins, 0.3-0.5" between content blocks
+
+### Content Elements
+
+1. **Slide Title** — Always required, top of slide
+2. **Body Content** — Text, bullets, data, or comparisons based on subtype
+3. **Visual Element** — Image, chart, icon, or SVG shape — always required
+4. **Source / Caption** — When showing data or external content
+5. **Page Number Badge** — **MANDATORY**
+
+### Design Decisions
+
+1. **Subtype**: Determine first — drives the entire layout
+2. **Content Volume**: Dense → multi-column or smaller font; Light → larger elements with more whitespace
+3. **Data vs Narrative**: Data-heavy → charts + stat callouts; Story-driven → images + quotes
+4. **Variety**: Each content slide should use a different layout from the previous one
+5. **Consistency**: Typography, colors, and spacing must match the rest of the presentation
+
+### Workflow
+
+1. **Analyze**: Content, determine subtype, plan layout
+2. **Choose Layout**: Best fit for subtype and content volume
+3. **Write Slide**: Use PptxGenJS. Use shapes for charts, decorative elements, icons. **MUST include page number badge.**
+4. **Verify**: Generate preview as `slide-XX-preview.pptx`. Extract text with markitdown, verify all content present, no placeholder text, badge included.
+
+---
+
+## 5. Summary / Closing Page
+
+- **Use for**: Wrap-up + action
+- **Content**: Key takeaways, CTA/next steps, contact/QR, thank-you
+
+### Layout Options
+
+**Key Takeaways** — Best for educational, corporate, data-driven presentations
+```
+|  KEY TAKEAWAYS                        |
+|  ✓  Takeaway one                      |
+|  ✓  Takeaway two                      |
+|  ✓  Takeaway three                    |
+```
+
+**CTA / Next Steps** — Best for sales pitches, proposals, project kick-offs
+```
+|  NEXT STEPS                           |
+|  [1] Action item one                  |
+|  [2] Action item two                  |
+|  Contact: email@example.com           |
+```
+
+**Thank You / Contact** — Best for conference talks, keynotes
+```
+|            THANK YOU                   |
+|         name@company.com              |
+|         @handle | website.com         |
+```
+
+**Split Recap** — Best for presentations needing both recap and action
+```
+|  SUMMARY            |  NEXT STEPS      |
+|  * Point one        |  Contact us at   |
+|  * Point two        |  email@co.com    |
+|  * Point three      |  [QR Code]       |
+```
+
+### Font Size Hierarchy
+
+| Element | Recommended Size | Notes |
+|---------|-----------------|-------|
+| Closing Title ("Thank You" / "Summary") | 48-72px | Bold, commanding |
+| Takeaway / Action Item | 18-24px | Clear, scannable |
+| Supporting Text | 14-16px | Regular weight |
+| Contact Info | 14-16px | Muted color |
+
+**Key Principles:**
+1. **Strong closing statement**: Main message should be largest, most prominent
+2. **Scannable items**: Takeaways/action items concise (one line each)
+3. **Contact clarity**: Legible but not dominant
+4. **Memorable finish**: Confident, polished ending
+
+### Content Elements
+
+1. **Closing Title** — Always required
+2. **Takeaway Points** — 3-5 concise summary points (if applicable)
+3. **Call to Action** — Clear next steps (if applicable)
+4. **Contact Info** — Email, website, social handles (if provided)
+5. **Decorative Elements** — SVG accents for visual consistency
+6. **Page Number Badge** — **MANDATORY**
+
+### Design Decisions
+
+1. **Closing Type**: Recap, CTA, thank-you, or combination
+2. **Content Volume**: Many takeaways → list; Simple closing → centered thank-you
+3. **Audience Action**: Audience needs to do something → CTA; Informational → takeaways
+4. **Tone Consistency**: Match energy of cover page
+5. **Visual Distinction**: Special but not disconnected from the rest
+
+### Workflow
+
+1. **Analyze**: Closing content — takeaways, CTA, contact, thank-you
+2. **Choose Layout**: Based on content type
+3. **Write Slide**: Use PptxGenJS. Use shapes for decorative elements. **MUST include page number badge.**
+4. **Verify**: Generate preview, extract text, verify content and badge.
+
+---
+
+## Additional Layout Patterns
+
+Use these across content slides for visual variety:
+
+- **Two-column** (text left, illustration right)
+- **Icon + text rows** (icon in colored circle, bold header, description below)
+- **2x2 or 2x3 grid** (image on one side, grid of content blocks on other)
+- **Half-bleed image** (full left or right side) with content overlay
+- **Large stat callouts** (big numbers 60-72pt with small labels below)
+- **Comparison columns** (before/after, pros/cons)
+- **Timeline or process flow** (numbered steps, arrows)
+- **Icons in small colored circles** next to section headers
+- **Italic accent text** for key stats or taglines
diff --git a/builtin-skills/document-process/wechat-article-writer/SKILL.md b/builtin-skills/document-process/wechat-article-writer/SKILL.md
new file mode 100644
index 00000000..c4d60284
--- /dev/null
+++ b/builtin-skills/document-process/wechat-article-writer/SKILL.md
@@ -0,0 +1,62 @@
+---
+name: wechat-article-writer
+description: 公众号文章自动化写作流程。支持资料搜索、文章撰写、爆款标题生成、排版优化。当用户提到写公众号、微信文章、自媒体写作、爆款文章、内容创作时使用此 skill。
+---
+
+# 公众号文章写作流程
+
+4 步完成高质量公众号文章：搜索资料 → 撰写文章 → 生成标题 → 排版优化
+
+## Step 1: 搜索资料
+
+使用 WebSearch 工具搜索主题相关资料：
+
+```
+搜索要求：
+1. 并行搜索多个来源（官方文档、X/Twitter、Reddit、技术论坛）
+2. 优先获取最新资料（当月/当季）
+3. 可启动多个并行 Task 加速搜索
+4. 深度总结搜索结果
+```
+
+## Step 2: 撰写文章
+
+**必须先读取用户的 CLAUDE.md 获取写作风格**
+
+撰写要求：
+- 5000-10000 字
+- 故事化开头，带情感色彩（兴奋/焦虑/好奇）
+- 准备 2-3 个备选标题
+- 结构：效果展示 → 问题描述 → 步骤教学 → 升华总结
+- 遵循 CLAUDE.md 中定义的写作风格和结尾语
+
+## Step 3: 生成标题
+
+生成 5 个爆款标题，特点：
+- **痛点明确**：直击读者痛处（"还在手动..."）
+- **数字吸引**：具体数字更有说服力（"3分钟"、"5个技巧"）
+- **结果导向**：承诺具体收益（"效率暴涨10倍"）
+- **情绪调动**：惊、神技、秘籍等词汇
+- **悬念设置**：引发好奇心
+
+## Step 4: 排版优化
+
+优化建议：
+1. **段落结构**：每段 3-5 行，重要数据单独成段加粗
+2. **配图位置**：标题下方封面图、步骤后效果图、结尾总结图
+3. **代码块**：前后留白，语法高亮
+4. **金句**：单独成段，增强记忆点
+
+## 示例
+
+用户请求：
+```
+帮我写一篇关于 Claude Code 使用技巧的公众号文章
+```
+
+执行流程：
+1. 搜索 Claude Code 最新功能和使用技巧
+2. 读取 CLAUDE.md 获取写作风格
+3. 撰写 1200 字左右的教程文章
+4. 生成 5 个爆款标题供选择
+5. 提供排版和配图建议
diff --git a/builtin-skills/document-process/writing-clearly-and-concisely/README.md b/builtin-skills/document-process/writing-clearly-and-concisely/README.md
new file mode 100644
index 00000000..af644445
--- /dev/null
+++ b/builtin-skills/document-process/writing-clearly-and-concisely/README.md
@@ -0,0 +1,157 @@
+# Writing Clearly and Concisely
+
+A skill that applies William Strunk Jr.'s timeless writing principles to produce clearer, stronger, more professional prose while avoiding common AI writing patterns.
+
+## Purpose
+
+This skill helps you write better prose for human readers. It draws from two sources:
+
+1. **The Elements of Style** (Strunk, 1918) - Time-tested rules for clear, forceful writing
+2. **AI Pattern Avoidance** - Research-backed guidance on avoiding generic, puffy language that LLMs tend to produce
+
+Whether you're writing documentation, commit messages, error messages, or any text humans will read, this skill helps you cut fluff and say what you mean.
+
+## When to Use
+
+Use this skill whenever you write prose for humans:
+
+- **Documentation** - README files, API docs, technical explanations
+- **Git workflow** - Commit messages, pull request descriptions
+- **User-facing text** - Error messages, UI copy, help text, tooltips
+- **Code comments** - Inline documentation, docstrings
+- **Reports and summaries** - Status updates, analysis, explanations
+- **Editing** - Improving clarity of existing text
+
+**Trigger phrases:**
+- "Write documentation for..."
+- "Draft a README"
+- "Edit this for clarity"
+- "Make this more concise"
+- "Review this commit message"
+
+## How It Works
+
+1. **Load the skill** when writing prose for human readers
+2. **Apply Strunk's core principles** - active voice, positive form, concrete language, cut needless words
+3. **Avoid AI patterns** - no puffery, no empty phrases, no promotional adjectives
+4. **Reference detailed guides** when needed for specific rules
+
+### Context-Efficient Approach
+
+The skill uses progressive disclosure to save context:
+
+- **SKILL.md** (~1,000 tokens) loads first with the core rules
+- **Reference files** (1,000-4,500 tokens each) load only when needed
+- **Most tasks need only one file**: `03-elementary-principles-of-composition.md`
+
+For tight context situations, dispatch a subagent with your draft and the relevant section file.
+
+## Key Features
+
+### Strunk's Core Rules
+
+The skill emphasizes these principles from *The Elements of Style*:
+
+| Rule | Principle |
+|------|-----------|
+| 10 | Use active voice |
+| 11 | Put statements in positive form |
+| 12 | Use definite, specific, concrete language |
+| 13 | Omit needless words |
+| 16 | Keep related words together |
+| 18 | Place emphatic words at end of sentence |
+
+### AI Pattern Detection
+
+The skill identifies and eliminates common LLM writing patterns:
+
+- **Puffery**: pivotal, crucial, vital, testament, enduring legacy
+- **Empty "-ing" phrases**: ensuring reliability, showcasing features
+- **Promotional adjectives**: groundbreaking, seamless, robust, cutting-edge
+- **Overused AI vocabulary**: delve, leverage, multifaceted, foster, realm, tapestry
+- **Formatting overuse**: excessive bullets, emoji decorations, bold on every other word
+
+## Reference Files
+
+| Section | File | Tokens | Content |
+|---------|------|--------|---------|
+| Grammar & punctuation | `02-elementary-rules-of-usage.md` | ~2,500 | Comma rules, possessives, sentence structure |
+| Composition principles | `03-elementary-principles-of-composition.md` | ~4,500 | Active voice, concision, paragraph structure |
+| Formatting | `04-a-few-matters-of-form.md` | ~1,000 | Headings, quotations, formatting conventions |
+| Word choice | `05-words-and-expressions-commonly-misused.md` | ~4,000 | Common errors, word selection |
+| AI patterns | `signs-of-ai-writing.md` | ~25,000 | Wikipedia editors' field guide to AI detection |
+
+## Usage Examples
+
+### Example 1: Tightening a Commit Message
+
+**Before:**
+> This commit implements the functionality for ensuring that user authentication is properly handled, showcasing robust error handling capabilities.
+
+**After:**
+> Add user authentication with error handling
+
+### Example 2: Rewriting Documentation
+
+**Before:**
+> This groundbreaking feature leverages cutting-edge technology to deliver a seamless experience, fostering better engagement and driving impactful results.
+
+**After:**
+> This feature uses WebSocket connections to update the dashboard in real time.
+
+### Example 3: Fixing Passive Voice
+
+**Before:**
+> The configuration file is read by the application at startup.
+
+**After:**
+> The application reads the configuration file at startup.
+
+### Example 4: Removing Hedging
+
+**Before:**
+> It is important to note that the API might potentially return an error in certain situations.
+
+**After:**
+> The API returns an error when the token expires.
+
+## Best Practices
+
+1. **Be specific, not grandiose** - Say what it actually does, not how important it is
+2. **Cut first, add later** - Remove words until meaning suffers, then add back what's needed
+3. **Prefer active voice** - "The function returns X" beats "X is returned by the function"
+4. **State positively** - "He forgot" beats "He did not remember"
+5. **Use concrete language** - "The server crashed" beats "An issue occurred"
+6. **Load reference files sparingly** - Most tasks need only `03-elementary-principles-of-composition.md`
+
+## Directory Structure
+
+```
+writing-clearly-and-concisely/
+  SKILL.md                 # Main skill definition
+  README.md                # This file
+  signs-of-ai-writing.md   # AI pattern detection guide
+  elements-of-style/
+    01-introductory.md
+    02-elementary-rules-of-usage.md
+    03-elementary-principles-of-composition.md
+    04-a-few-matters-of-form.md
+    05-words-and-expressions-commonly-misused.md
+```
+
+## Installation
+
+**Claude Code:**
+```bash
+cp -r skills/writing-clearly-and-concisely ~/.claude/skills/
+```
+
+**Claude.ai:**
+Add the skill to project knowledge or paste SKILL.md contents into your conversation.
+
+## Attribution
+
+- Original skill by @joshuadavidthomas from [joshuadavidthomas/agent-skills](https://github.com/joshuadavidthomas/agent-skills) (MIT)
+- Adapted from [obra/the-elements-of-style](https://github.com/obra/the-elements-of-style)
+- Writing principles from *The Elements of Style* by William Strunk Jr. (1918)
+- AI pattern research from Wikipedia's field guide to AI-generated content detection
diff --git a/builtin-skills/document-process/writing-clearly-and-concisely/SKILL.md b/builtin-skills/document-process/writing-clearly-and-concisely/SKILL.md
new file mode 100644
index 00000000..81a94732
--- /dev/null
+++ b/builtin-skills/document-process/writing-clearly-and-concisely/SKILL.md
@@ -0,0 +1,93 @@
+---
+name: writing-clearly-and-concisely
+description: Use when writing prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Applies Strunk's timeless rules for clearer, stronger, more professional writing.
+---
+
+# Writing Clearly and Concisely
+
+## Overview
+
+Write with clarity and force. This skill covers what to do (Strunk) and what not to do (AI patterns).
+
+## When to Use This Skill
+
+Use this skill whenever you write prose for humans:
+
+- Documentation, README files, technical explanations
+- Commit messages, pull request descriptions
+- Error messages, UI copy, help text, comments
+- Reports, summaries, or any explanation
+- Editing to improve clarity
+
+**If you're writing sentences for a human to read, use this skill.**
+
+## Limited Context Strategy
+
+When context is tight:
+
+1. Write your draft using judgment
+2. Dispatch a subagent with your draft and the relevant section file
+3. Have the subagent copyedit and return the revision
+
+Loading a single section (~1,000-4,500 tokens) instead of everything saves significant context.
+
+## Elements of Style
+
+William Strunk Jr.'s *The Elements of Style* (1918) teaches you to write clearly and cut ruthlessly.
+
+### Rules
+
+**Elementary Rules of Usage (Grammar/Punctuation)**:
+
+1. Form possessive singular by adding 's
+2. Use comma after each term in series except last
+3. Enclose parenthetic expressions between commas
+4. Comma before conjunction introducing co-ordinate clause
+5. Don't join independent clauses by comma
+6. Don't break sentences in two
+7. Participial phrase at beginning refers to grammatical subject
+
+**Elementary Principles of Composition**:
+
+8. One paragraph per topic
+9. Begin paragraph with topic sentence
+10. **Use active voice**
+11. **Put statements in positive form**
+12. **Use definite, specific, concrete language**
+13. **Omit needless words**
+14. Avoid succession of loose sentences
+15. Express co-ordinate ideas in similar form
+16. **Keep related words together**
+17. Keep to one tense in summaries
+18. **Place emphatic words at end of sentence**
+
+### Reference Files
+
+The rules above are summarized from Strunk's original text. For complete explanations with examples:
+
+| Section | File | ~Tokens |
+|---------|------|---------|
+| Grammar, punctuation, comma rules | `02-elementary-rules-of-usage.md` | 2,500 |
+| Paragraph structure, active voice, concision | `03-elementary-principles-of-composition.md` | 4,500 |
+| Headings, quotations, formatting | `04-a-few-matters-of-form.md` | 1,000 |
+| Word choice, common errors | `05-words-and-expressions-commonly-misused.md` | 4,000 |
+
+**Most tasks need only `03-elementary-principles-of-composition.md`** — it covers active voice, positive form, concrete language, and omitting needless words.
+
+## AI Writing Patterns to Avoid
+
+LLMs regress to statistical means, producing generic, puffy prose. Avoid:
+
+- **Puffery:** pivotal, crucial, vital, testament, enduring legacy
+- **Empty "-ing" phrases:** ensuring reliability, showcasing features, highlighting capabilities
+- **Promotional adjectives:** groundbreaking, seamless, robust, cutting-edge
+- **Overused AI vocabulary:** delve, leverage, multifaceted, foster, realm, tapestry
+- **Formatting overuse:** excessive bullets, emoji decorations, bold on every other word
+
+Be specific, not grandiose. Say what it actually does.
+
+For comprehensive research on why these patterns occur, see `signs-of-ai-writing.md`. Wikipedia editors developed this guide to detect AI-generated submissions — their patterns are well-documented and field-tested.
+
+## Bottom Line
+
+Writing for humans? Load the relevant section from `elements-of-style/` and apply the rules. For most tasks, `03-elementary-principles-of-composition.md` covers what matters most.
diff --git a/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/01-introductory.md b/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/01-introductory.md
new file mode 100644
index 00000000..667b823b
--- /dev/null
+++ b/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/01-introductory.md
@@ -0,0 +1,3 @@
+## I. Introductory
+
+This handbook summarizes the essentials of plain English style. It focuses on the rules of usage and principles of composition most often broken, offering a compact alternative to exhaustive manuals. Master the guidance here, then look to the best authors for finer points of style.
diff --git a/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/02-elementary-rules-of-usage.md b/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/02-elementary-rules-of-usage.md
new file mode 100644
index 00000000..b42e5ef9
--- /dev/null
+++ b/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/02-elementary-rules-of-usage.md
@@ -0,0 +1,214 @@
+## II. Elementary Rules Of Usage
+
+### Rule 1. Form the possessive singular of nouns by adding 's.
+
+Follow this rule whatever the final consonant. Thus write,
+
+Charles's friend
+
+Burns's poems
+
+the witch's malice
+
+This is the usage of the United States Government Printing Office and of the Oxford University Press.
+
+Exceptions are the possessive of ancient proper names ending in *-es* and *-is*, the possessive *Jesus'*, and such forms as *for conscience' sake*, *for righteousness' sake*. But such forms as *Achilles' heel*, *Moses' laws*, *Isis' temple* are commonly replaced by
+
+the heel of Achilles
+
+the laws of Moses
+
+the temple of Isis
+
+The pronominal possessives *hers*, *its*, *theirs*, *yours*, and *oneself* have no apostrophe.
+
+### Rule 2. In a series of three or more terms with a single conjunction, use a comma after each term except the last.
+
+Thus write,
+
+red, white, and blue
+
+gold, silver, or copper
+
+He opened the letter, read it, and made a note of its contents.
+
+This is also the usage of the Government Printing Office and of the Oxford University Press.
+
+In the names of business firms the last comma is omitted, as,
+
+Brown, Shipley & Co.
+
+### Rule 3. Enclose parenthetic expressions between commas.
+
+The best way to see a country, unless you are pressed for time, is to travel on foot.
+
+This rule is difficult to apply; it is frequently hard to decide whether a single word, such as *however*, or a brief phrase, is or is not parenthetic. If the interruption to the flow of the sentence is but slight, the writer may safely omit the commas. But whether the interruption be slight or considerable, he must never insert one comma and omit the other. Such punctuation as
+
+Marjorie's husband, Colonel Nelson paid us a visit yesterday,
+
+or
+
+My brother you will be pleased to hear, is now in perfect health,
+
+is indefensible.
+
+If a parenthetic expression is preceded by a conjunction, place the first comma before the conjunction, not after it.
+
+He saw us coming, and unaware that we had learned of his treachery, greeted us with a smile.
+
+Always to be regarded as parenthetic and to be enclosed between commas (or, at the end of the sentence, between comma and period) are the following:
+
+\(1\) the year, when forming part of a date, and the day of the month, when following the day of the week:
+
+February to July, 1916.
+
+April 6, 1917.
+
+Monday, November 11, 1918.
+
+\(2\) the abbreviations *etc.* and *jr.*
+
+\(3\) non-restrictive relative clauses, that is, those which do not serve to identify or define the antecedent noun, and similar clauses introduced by conjunctions indicating time or place.
+
+The audience, which had at first been indifferent, became more and more interested.
+
+In this sentence the clause introduced by *which* does not serve to tell which of several possible audiences is meant; what audience is in question is supposed to be already known. The clause adds, parenthetically, a statement supplementing that in the main clause. The sentence is virtually a combination of two statements which might have been made independently:
+
+The audience had at first been indifferent. It became more and more interested.
+
+Compare the restrictive relative clause, not set off by commas, in the sentence,
+
+The candidate who best meets these requirements will obtain the place.
+
+Here the clause introduced by *who* does serve to tell which of several possible candidates is meant; the sentence cannot be split up into two independent statements.
+
+The difference in punctuation in the two sentences following is based on the same principle:
+
+Nether Stowey, where Coleridge wrote The Rime of the Ancient Mariner, is a few miles from Bridgewater.
+
+The day will come when you will admit your mistake.
+
+Nether Stowey is completely identified by its name; the statement about Coleridge is therefore supplementary and parenthetic. The *day* spoken of is identified only by the dependent clause, which is therefore restrictive.
+
+Similar in principle to the enclosing of parenthetic expressions between commas is the setting off by commas of phrases or dependent clauses preceding or following the main clause of a sentence.
+
+Partly by hard fighting, partly by diplomatic skill, they enlarged their dominions to the east, and rose to royal rank with the possession of Sicily, exchanged afterwards for Sardinia.
+
+Other illustrations may be found in sentences quoted under Rules 4, 5, 6, 7, 16, and 18.
+
+The writer should be careful not to set off independent clauses by commas: see under Rule 5.
+
+### Rule 4. Place a comma before a conjunction introducing a co-ordinate clause.
+
+The early records of the city have disappeared, and the story of its first years can no longer be reconstructed.
+
+The situation is perilous, but there is still one chance of escape.
+
+Sentences of this type, isolated from their context, may seem to be in need of rewriting. As they make complete sense when the comma is reached, the second clause has the appearance of an afterthought. Further, *and* is the least specific of connectives. Used between independent clauses, it indicates only that a relation exists between them without defining that relation. In the example above, the relation is that of cause and result. The two sentences might be rewritten:
+
+As the early records of the city have disappeared, the story of its first years can no longer be reconstructed.
+
+Although the situation is perilous, there is still one chance of escape.
+
+Or the subordinate clauses might be replaced by phrases:
+
+Owing to the disappearance of the early records of the city, the story of its first years can no longer be reconstructed.
+
+In this perilous situation, there is still one chance of escape.
+
+But a writer may err by making his sentences too uniformly compact and periodic, and an occasional loose sentence prevents the style from becoming too formal and gives the reader a certain relief. Consequently, loose sentences of the type first quoted are common in easy, unstudied writing. But a writer should be careful not to construct too many of his sentences after this pattern (see Rule 14).
+
+Two-part sentences of which the second member is introduced by *as* (in the sense of *because*), *for*, *or*, *nor*, and *while* (in the sense of *and at the same time*) likewise require a comma before the conjunction.
+
+If the second member is introduced by an adverb, a semicolon, not a comma, is required (see Rule 5). The connectives *so* and *yet* may be used either as adverbs or as conjunctions, accordingly as the second clause is felt to be co-ordinate or subordinate; consequently either mark of punctuation may be justified. But these uses of *so* (equivalent to *accordingly* or to *so that*) are somewhat colloquial and should, as a rule, be avoided in writing. A simple correction, usually serviceable, is to omit the word *so* and begin the first clause with *as* or *since*:
+
+| Original | Revision |
+| --- | --- |
+| I had never been in the place before; so I had difficulty in finding my way about. | As I had never been in the place before, I had difficulty in finding my way about. |
+
+If a dependent clause, or an introductory phrase requiring to be set off by a comma, precedes the second independent clause, no comma is needed after the conjunction.
+
+The situation is perilous, but if we are prepared to act promptly, there is still one chance of escape.
+
+When the subject is the same for both clauses and is expressed only once, a comma is required if the connective is *but*. If the connective is *and*, the comma should be omitted if the relation between the two statements is close or immediate.
+
+I have heard his arguments, but am still unconvinced.
+
+He has had several years' experience and is thoroughly competent.
+
+### Rule 5. Do not join independent clauses by a comma.
+
+If two or more clauses, grammatically complete and not joined by a conjunction, are to form a single compound sentence, the proper mark of punctuation is a semicolon.
+
+Stevenson's romances are entertaining; they are full of exciting adventures.
+
+It is nearly half past five; we cannot reach town before dark.
+
+It is of course equally correct to write the above as two sentences each, replacing the semicolons by periods.
+
+Stevenson's romances are entertaining. They are full of exciting adventures.
+
+It is nearly half past five. We cannot reach town before dark.
+
+If a conjunction is inserted the proper mark is a comma (Rule 4).
+
+Stevenson's romances are entertaining, for they are full of exciting adventures.
+
+It is nearly half past five, and we cannot reach town before dark.
+
+A comparison of the three forms given above will show clearly the advantage of the first. It is, at least in the examples given, better than the second form, because it suggests the close relationship between the two statements in a way that the second does not attempt, and better than the third, because briefer and therefore more forcible. Indeed it may be said that this simple method of indicating relationship between statements is one of the most useful devices of composition. The relationship, as above, is commonly one of cause or of consequence.
+
+Note that if the second clause is preceded by an adverb, such as *accordingly*, *besides*, *then*, *therefore*, or *thus*, and not by a conjunction, the semicolon is still required.
+
+Two exceptions to the rule may be admitted. If the clauses are very short, and are alike in form, a comma is usually permissible:
+
+Man proposes, God disposes.
+
+The gate swung apart, the bridge fell, the portcullis was drawn up.
+
+Note that in these examples the relation is not one of cause or consequence. Also in the colloquial form of expression,
+
+I hardly knew him, he was so changed,
+
+a comma, not a semicolon, is required. But this form of expression is inappropriate in writing, except in the dialogue of a story or play, or perhaps in a familiar letter.
+
+### Rule 6. Do not break sentences in two.
+
+In other words, do not use periods for commas.
+
+I met them on a Cunard liner several years ago. Coming home from Liverpool to New York.
+
+He was an interesting talker. A man who had traveled all over the world and lived in half a dozen countries.
+
+In both these examples, the first period should be replaced by a comma, and the following word begun with a small letter.
+
+It is permissible to make an emphatic word or expression serve the purpose of a sentence and to punctuate it accordingly:
+
+Again and again he called out. No reply.
+
+The writer must, however, be certain that the emphasis is warranted, and that he will not be suspected of a mere blunder in syntax or in punctuation.
+
+Rules 3, 4, 5, and 6 cover the most important principles in the punctuation of ordinary sentences; they should be so thoroughly mastered that their application becomes second nature.
+
+### Rule 7. A participial phrase at the beginning of a sentence must refer to the grammatical subject.
+
+Walking slowly down the road, he saw a woman accompanied by two children.
+
+The word *walking* refers to the subject of the sentence, not to the woman. If the writer wishes to make it refer to the woman, he must recast the sentence:
+
+He saw a woman accompanied by two children, walking slowly down the road.
+
+Participial phrases preceded by a conjunction or by a preposition, nouns in apposition, adjectives, and adjective phrases come under the same rule if they begin the sentence.
+
+| Original | Revision |
+| --- | --- |
+| On arriving in Chicago, his friends met him at the station. | When he arrived (or, On his arrival) in Chicago, his friends met him at the station. |
+| A soldier of proved valor, they entrusted him with the defence of the city. | A soldier of proved valor, he was entrusted with the defence of the city. |
+| Young and inexperienced, the task seemed easy to me. | Young and inexperienced, I thought the task easy. |
+| Without a friend to counsel him, the temptation proved irresistible. | Without a friend to counsel him, he found the temptation irresistible. |
+
+Sentences violating this rule are often ludicrous.
+
+Being in a dilapidated condition, I was able to buy the house very cheap.
+
+Wondering irresolutely what to do next, the clock struck twelve.
diff --git a/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/03-elementary-principles-of-composition.md b/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/03-elementary-principles-of-composition.md
new file mode 100644
index 00000000..e92e08bd
--- /dev/null
+++ b/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/03-elementary-principles-of-composition.md
@@ -0,0 +1,398 @@
+## III. Elementary Principles Of Composition
+
+### Rule 8. Make the paragraph the unit of composition: one paragraph to each topic.
+
+If the subject on which you are writing is of slight extent, or if you intend to treat it very briefly, there may be no need of subdividing it into topics. Thus a brief description, a brief summary of a literary work, a brief account of a single incident, a narrative merely outlining an action, the setting forth of a single idea, any one of these is best written in a single paragraph. After the paragraph has been written, examine it to see whether subdivision will not improve it.
+
+Ordinarily, however, a subject requires subdivision into topics, each of which should be made the subject of a paragraph. The object of treating each topic in a paragraph by itself is, of course, to aid the reader. The beginning of each paragraph is a signal to him that a new step in the development of the subject has been reached.
+
+The extent of subdivision will vary with the length of the composition. For example, a short notice of a book or poem might consist of a single paragraph. One slightly longer might consist of two paragraphs:
+
+- A. Account of the work.
+- B. Critical discussion.
+
+A report on a poem, written for a class in literature, might consist of seven paragraphs:
+
+- A. Facts of composition and publication.
+- B. Kind of poem; metrical form.
+- C. Subject.
+- D. Treatment of subject.
+- E. For what chiefly remarkable.
+- F. Wherein characteristic of the writer.
+- G. Relationship to other works.
+
+The contents of paragraphs C and D would vary with the poem. Usually, paragraph C would indicate the actual or imagined circumstances of the poem (the situation), if these call for explanation, and would then state the subject and outline its development. If the poem is a narrative in the third person throughout, paragraph C need contain no more than a concise summary of the action. Paragraph D would indicate the leading ideas and show how they are made prominent, or would indicate what points in the narrative are chiefly emphasized.
+
+A novel might be discussed under the heads:
+
+- A. Setting.
+- B. Plot.
+- C. Characters.
+- D. Purpose.
+
+An historical event might be discussed under the heads:
+
+- A. What led up to the event.
+- B. Account of the event.
+- C. What the event led up to.
+
+In treating either of these last two subjects, the writer would probably find it necessary to subdivide one or more of the topics here given.
+
+As a rule, single sentences should not be written or printed as paragraphs. An exception may be made of sentences of transition, indicating the relation between the parts of an exposition or argument. Frequent exceptions are also necessary in textbooks, guidebooks, and other works in which many topics are treated briefly.
+
+In dialogue, each speech, even if only a single word, is a paragraph by itself; that is, a new paragraph begins with each change of speaker. The application of this rule, when dialogue and narrative are combined, is best learned from examples in well-printed works of fiction.
+
+### Rule 9. As a rule, begin each paragraph with a topic sentence, end it in conformity with the beginning.
+
+Again, the object is to aid the reader. The practice here recommended enables him to discover the purpose of each paragraph as he begins to read it, and to retain this purpose in mind as he ends it. For this reason, the most generally useful kind of paragraph, particularly in exposition and argument, is that in which
+
+\(a\) the topic sentence comes at or near the beginning;
+
+\(b\) the succeeding sentences explain or establish or develop the statement made in the topic sentence; and
+
+\(c\) the final sentence either emphasizes the thought of the topic sentence or states some important consequence.
+
+Ending with a digression, or with an unimportant detail, is particularly to be avoided.
+
+If the paragraph forms part of a larger composition, its relation to what precedes, or its function as a part of the whole, may need to be expressed. This can sometimes be done by a mere word or phrase (*again*; *therefore*; *for the same reason*) in the topic sentence. Sometimes, however, it is expedient to precede the topic sentence by one or more sentences of introduction or transition. If more than one such sentence is required, it is generally better to set apart the transitional sentences as a separate paragraph.
+
+According to the writer's purpose, he may, as indicated above, relate the body of the paragraph to the topic sentence in one or more of several different ways. He may make the meaning of the topic sentence clearer by restating it in other forms, by defining its terms, by denying the contrary, by giving illustrations or specific instances; he may establish it by proofs; or he may develop it by showing its implications and consequences. In a long paragraph, he may carry out several of these processes.
+
+1 Now, to be properly enjoyed, a walking tour should be gone upon alone. 2 If you go in a company, or even in pairs, it is no longer a walking tour in anything but name; it is something else and more in the nature of a picnic. 3 A walking tour should be gone upon alone, because freedom is of the essence; because you should be able to stop and go on, and follow this way or that, as the freak takes you; and because you must have your own pace, and neither trot alongside a champion walker, nor mince in time with a girl. 4 And you must be open to all impressions and let your thoughts take colour from what you see. 5 You should be as a pipe for any wind to play upon. 6 “I cannot see the wit,” says Hazlitt, “of walking and talking at the same time. 7 When I am in the country, I wish to vegetate like the country,” which is the gist of all that can be said upon the matter. 8 There should be no cackle of voices at your elbow, to jar on the meditative silence of the morning. 9 And so long as a man is reasoning he cannot surrender himself to that fine intoxication that comes of much motion in the open air, that begins in a sort of dazzle and sluggishness of the brain, and ends in a peace that passes comprehension.—Stevenson, Walking Tours.
+
+1 Topic sentence. 2 The meaning made clearer by denial of the contrary. 3 The topic sentence repeated, in abridged form, and supported by three reasons; the meaning of the third (“you must have your own pace”) made clearer by denying the contrary. 4 A fourth reason, stated in two forms. 5 The same reason, stated in still another form. 6–7 The same reason as stated by Hazlitt. 8 Repetition, in paraphrase, of the quotation from Hazlitt. 9 Final statement of the fourth reason, in language amplified and heightened to form a strong conclusion.
+
+1 It was chiefly in the eighteenth century that a very different conception of history grew up. 2 Historians then came to believe that their task was not so much to paint a picture as to solve a problem; to explain or illustrate the successive phases of national growth, prosperity, and adversity. 3 The history of morals, of industry, of intellect, and of art; the changes that take place in manners or beliefs; the dominant ideas that prevailed in successive periods; the rise, fall, and modification of political constitutions; in a word, all the conditions of national well-being became the subject of their works. 4 They sought rather to write a history of peoples than a history of kings. 5 They looked especially in history for the chain of causes and effects. 6 They undertook to study in the past the physiology of nations, and hoped by applying the experimental method on a large scale to deduce some lessons of real value about the conditions on which the welfare of society mainly depend.—Lecky, The Political Value of History.
+
+1 Topic sentence. 2 The meaning of the topic sentence made clearer; the new conception of history defined. 3 The definition expanded. 4 The definition explained by contrast. 5 The definition supplemented: another element in the new conception of history. 6 Conclusion: an important consequence of the new conception of history.
+
+In narration and description the paragraph sometimes begins with a concise, comprehensive statement serving to hold together the details that follow.
+
+The breeze served us admirably.
+
+The campaign opened with a series of reverses.
+
+The next ten or twelve pages were filled with a curious set of entries.
+
+But this device, if too often used, would become a mannerism. More commonly the opening sentence simply indicates by its subject with what the paragraph is to be principally concerned.
+
+At length I thought I might return towards the stockade.
+
+He picked up the heavy lamp from the table and began to explore.
+
+Another flight of steps, and they emerged on the roof.
+
+The brief paragraphs of animated narrative, however, are often without even this semblance of a topic sentence. The break between them serves the purpose of a rhetorical pause, throwing into prominence some detail of the action.
+
+### Rule 10. Use the active voice.
+
+The active voice is usually more direct and vigorous than the passive:
+
+I shall always remember my first visit to Boston.
+
+This is much better than
+
+My first visit to Boston will always be remembered by me.
+
+The latter sentence is less direct, less bold, and less concise. If the writer tries to make it more concise by omitting “by me,”
+
+My first visit to Boston will always be remembered,
+
+it becomes indefinite: is it the writer, or some person undisclosed, or the world at large, that will always remember this visit?
+
+This rule does not, of course, mean that the writer should entirely discard the passive voice, which is frequently convenient and sometimes necessary.
+
+The dramatists of the Restoration are little esteemed to-day.
+
+Modern readers have little esteem for the dramatists of the Restoration.
+
+The first would be the right form in a paragraph on the dramatists of the Restoration; the second, in a paragraph on the tastes of modern readers. The need of making a particular word the subject of the sentence will often, as in these examples, determine which voice is to be used.
+
+As a rule, avoid making one passive depend directly upon another.
+
+| Original | Revision |
+| --- | --- |
+| Gold was not allowed to be exported. | It was forbidden to export gold (The export of gold was prohibited). |
+| He has been proved to have been seen entering the building. | It has been proved that he was seen to enter the building. |
+
+In both the examples above, before correction, the word properly related to the second passive is made the subject of the first.
+
+A common fault is to use as the subject of a passive construction a noun which expresses the entire action, leaving to the verb no function beyond that of completing the sentence.
+
+| Original | Revision |
+| --- | --- |
+| A survey of this region was made in 1900. | This region was surveyed in 1900. |
+| Mobilization of the army was rapidly effected. | The army was rapidly mobilized. |
+| Confirmation of these reports cannot be obtained. | These reports cannot be confirmed. |
+
+Compare the _sentence,_ “The export of gold was prohibited,” in which the predicate “was prohibited” expresses something not implied in “export.”
+
+The habitual use of the active voice makes for forcible writing. This is true not only in narrative principally concerned with action, but in writing of any kind. Many a tame sentence of description or exposition can be made lively and emphatic by substituting a verb in the active voice for some such perfunctory expression as *there is*, or *could be heard*.
+
+| Original | Revision |
+| --- | --- |
+| There were a great number of dead leaves lying on the ground. | Dead leaves covered the ground. |
+| The sound of a guitar somewhere in the house could be heard. | Somewhere in the house a guitar hummed sleepily. |
+| The reason that he left college was that his health became impaired. | Failing health compelled him to leave college. |
+| It was not long before he was very sorry that he had said what he had. | He soon repented his words. |
+
+### Rule 11. Put statements in positive form.
+
+Make definite assertions. Avoid tame, colorless, hesitating, non-committal language. Use the word *not* as a means of denial or in antithesis, never as a means of evasion.
+
+| Original | Revision |
+| --- | --- |
+| He was not very often on time. | He usually came late. |
+| He did not think that studying Latin was much use. | He thought the study of Latin useless. |
+| The Taming of the Shrew is rather weak in spots. Shakespeare does not portray Katharine as a very admirable character, nor does Bianca remain long in memory as an important character in Shakespeare's works. | The women in The Taming of the Shrew are unattractive. Katharine is disagreeable, Bianca insignificant. |
+
+The last example, before correction, is indefinite as well as negative. The corrected version, consequently, is simply a guess at the writer's intention.
+
+All three examples show the weakness inherent in the word *not*. Consciously or unconsciously, the reader is dissatisfied with being told only what is not; he wishes to be told what is. Hence, as a rule, it is better to express even a negative in positive form.
+
+| Original | Revision |
+| --- | --- |
+| not honest | dishonest |
+| not important | trifling |
+| did not remember | forgot |
+| did not pay any attention to | ignored |
+| did not have much confidence in | distrusted |
+
+The antithesis of negative and positive is strong:
+
+Not charity, but simple justice.
+
+Not that I loved Caesar less, but Rome the more.
+
+Negative words other than *not* are usually strong:
+
+The sun never sets upon the British flag.
+
+### Rule 12. Use definite, specific, concrete language.
+
+Prefer the specific to the general, the definite to the vague, the concrete to the abstract.
+
+| Original | Revision |
+| --- | --- |
+| A period of unfavorable weather set in. | It rained every day for a week. |
+| He showed satisfaction as he took possession of his well-earned reward. | He grinned as he pocketed the coin. |
+| There is a general agreement among those who have enjoyed the experience that surf-riding is productive of great exhilaration. | All who have tried surf-riding agree that it is most exhilarating. |
+
+If those who have studied the art of writing are in accord on any one point, it is on this, that the surest method of arousing and holding the attention of the reader is by being specific, definite, and concrete. Critics have pointed out how much of the effectiveness of the greatest writers, Homer, Dante, Shakespeare, results from their constant definiteness and concreteness. Browning, to cite a more modern author, affords many striking examples. Take, for instance, the lines from My Last Duchess,
+
+Sir, 'twas all one! My favour at her breast,
+
+The dropping of the daylight in the west,
+
+The bough of cherries some officious fool
+
+Broke in the orchard for her, the white mule
+
+She rode with round the terrace—all and each
+
+Would draw from her alike the approving speech,
+
+Or blush, at least,
+
+and those which end the poem,
+
+Notice Neptune, though,
+
+Taming a sea-horse, thought a rarity,
+
+Which Claus of Innsbruck cast in bronze for me.
+
+These words call up pictures. Recall how in The Bishop Orders his Tomb in St. Praxed's Church “the Renaissance spirit—its worldliness, inconsistency, pride, hypocrisy, ignorance of itself, love of art, of luxury, of good Latin,” to quote Ruskin's comment on the poem, is made manifest in specific details and in concrete terms.
+
+Prose, in particular narrative and descriptive prose, is made vivid by the same means. If the experiences of Jim Hawkins and of David Balfour, of Kim, of Nostromo, have seemed for the moment real to countless readers, if in reading Carlyle we have almost the sense of being physically present at the taking of the Bastille, it is because of the definiteness of the details and the concreteness of the terms used. It is not that every detail is given; that would be impossible, as well as to no purpose; but that all the significant details are given, and not vaguely, but with such definiteness that the reader, in imagination, can project himself into the scene.
+
+In exposition and in argument, the writer must likewise never lose his hold upon the concrete, and even when he is dealing with general principles, he must give particular instances of their application.
+
+“This superiority of specific expressions is clearly due to the effort required to translate words into thoughts. As we do not think in generals, but in particulars—as whenever any class of things is referred to, we represent it to ourselves by calling to mind individual members of it, it follows that when an abstract word is used, the hearer or reader has to choose, from his stock of images, one or more by which he may figure to himself the genus mentioned. In doing this, some delay must arise, some force be expended; and if by employing a specific term an appropriate image can be at once suggested, an economy is achieved, and a more vivid impression produced.”
+
+Herbert Spencer, from whose Philosophy of Style the preceding paragraph is quoted, illustrates the principle by the sentences:
+
+| Original | Revision |
+| --- | --- |
+| In proportion as the manners, customs, and amusements of a nation are cruel and barbarous, the regulations of their penal code will be severe. | In proportion as men delight in battles, bull-fights, and combats of gladiators, will they punish by hanging, burning, and the rack. |
+
+### Rule 13. Omit needless words.
+
+Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he avoid all detail and treat his subjects only in outline, but that he make every word tell.
+
+Many expressions in common use violate this principle:
+
+| Original | Revision |
+| --- | --- |
+| the question as to whether | whether (the question whether) |
+| there is no doubt but that | no doubt (doubtless) |
+| used for fuel purposes | used for fuel |
+| he is a man who | he |
+| in a hasty manner | hastily |
+| this is a subject which | this subject |
+| His story is a strange one. | His story is strange. |
+
+In especial the expression *the fact that* should be revised out of every sentence in which it occurs.
+
+| Original | Revision |
+| --- | --- |
+| owing to the fact that | since (because) |
+| in spite of the fact that | though (although) |
+| call your attention to the fact that | remind you (notify you) |
+| I was unaware of the fact that | I was unaware that (did not know) |
+| the fact that he had not succeeded | his failure |
+| the fact that I had arrived | my arrival |
+
+See also under *case*, *character*, *nature*, *system* in Chapter V.
+
+*Who is*, *which was*, and the like are often superfluous.
+
+| Original | Revision |
+| --- | --- |
+| His brother, who is a member of the same firm | His brother, a member of the same firm |
+| Trafalgar, which was Nelson's last battle | Trafalgar, Nelson's last battle |
+
+As positive statement is more concise than negative, and the active voice more concise than the passive, many of the examples given under Rules 11 and 12 illustrate this rule as well.
+
+A common violation of conciseness is the presentation of a single complex idea, step by step, in a series of sentences or independent clauses which might to advantage be combined into one.
+
+| Original | Revision |
+| --- | --- |
+| Macbeth was very ambitious. This led him to wish to become king of Scotland. The witches told him that this wish of his would come true. The king of Scotland at this time was Duncan. Encouraged by his wife, Macbeth murdered Duncan. He was thus enabled to succeed Duncan as king. (51 words.) | Encouraged by his wife, Macbeth achieved his ambition and realized the prediction of the witches by murdering Duncan and becoming king of Scotland in his place. (26 words.) |
+| There were several less important courses, but these were the most important, and although they did not come every day, they came often enough to keep you in such a state of mind that you never knew what your next move would be. (43 words.) | These, the most important courses of all, came, if not daily, at least often enough to keep one under constant strain. (21 words.) |
+
+### Rule 14. Avoid a succession of loose sentences
+
+This rule refers especially to loose sentences of a particular type, those consisting of two co-ordinate clauses, the second introduced by a conjunction or relative. Although single sentences of this type may be unexceptionable (see under Rule 4), a series soon becomes monotonous and tedious.
+
+An unskilful writer will sometimes construct a whole paragraph of sentences of this kind, using as connectives *and*, *but*, *so*, and less frequently, *who*, *which*, *when*, *where*, and *while*, these last in non-restrictive senses (see under Rule 3).
+
+The third concert of the subscription series was given last evening, and a large audience was in attendance. Mr. Edward Appleton was the soloist, and the Boston Symphony Orchestra furnished the instrumental music. The former showed himself to be an artist of the first rank, while the latter proved itself fully deserving of its high reputation. The interest aroused by the series has been very gratifying to the Committee, and it is planned to give a similar series annually hereafter. The fourth concert will be given on Tuesday, May 10, when an equally attractive programme will be presented.
+
+Apart from its triteness and emptiness, the paragraph above is weak because of the structure of its sentences, with their mechanical symmetry and sing-song. Contrast with them the sentences in the paragraphs quoted under Rule 9, or in any piece of good English prose, as the preface (Before the Curtain) to Vanity Fair.
+
+If the writer finds that he has written a series of sentences of the type described, he should recast enough of them to remove the monotony, replacing them by simple sentences, by sentences of two clauses joined by a semicolon, by periodic sentences of two clauses, by sentences, loose or periodic, of three clauses—whichever best represent the real relations of the thought.
+
+### Rule 15. Express co-ordinate ideas in similar form.
+
+This principle, that of parallel construction, requires that expressions of similar content and function should be outwardly similar. The likeness of form enables the reader to recognize more readily the likeness of content and function. Familiar instances from the Bible are the Ten Commandments, the Beatitudes, and the petitions of the Lord's Prayer.
+
+The unskillful writer often violates this principle, from a mistaken belief that he should constantly vary the form of his expressions. It is true that in repeating a statement in order to emphasize it he may have need to vary its form. For illustration, see the paragraph from Stevenson quoted under Rule _9_. But apart from this, he should follow the principle of parallel construction.
+
+| Original | Revision |
+| --- | --- |
+| Formerly, science was taught by the textbook method, while now the laboratory method is employed. | Formerly, science was taught by the textbook method; now it is taught by the laboratory method. |
+
+The left-hand version gives the impression that the writer is undecided or timid; he seems unable or afraid to choose one form of expression and hold to it. The right-hand version shows that the writer has at least made his choice and abided by it.
+
+By this principle, an article or a preposition applying to all the members of a series must either be used only before the first term or else be repeated before each term.
+
+| Original | Revision |
+| --- | --- |
+| The French, the Italians, Spanish, and Portuguese | The French, the Italians, the Spanish, and the Portuguese |
+| In spring, summer, or in winter | In spring, summer, or winter (In spring, in summer, or in winter) |
+
+Correlative expressions (*both, and*; *not, but*; *not only, but also*; *either, or*; *first, second, third*; and the like) should be followed by the same grammatical construction, that is, virtually, by the same part of speech. (Such combinations as “both Henry and I,” “not silk, but a cheap substitute,” are obviously within the rule.) Many violations of this rule (as the first three below) arise from faulty arrangement; others (as the last) from the use of unlike constructions.
+
+| Original | Revision |
+| --- | --- |
+| It was both a long ceremony and very tedious. | The ceremony was both long and tedious. |
+| A time not for words, but action. | A time not for words, but for action. |
+| Either you must grant his request or incur his ill will. | You must either grant his request or incur his ill will. |
+| My objections are, first, the injustice of the measure; second, that it is unconstitutional. | My objections are, first, that the measure is unjust; second, that it is unconstitutional. |
+
+See also the third example under Rule 12 and the last under Rule 13.
+
+It may be asked, what if a writer needs to express a very large number of similar ideas, say twenty? Must he write twenty consecutive sentences of the same pattern? On closer examination he will probably find that the difficulty is imaginary, that his twenty ideas can be classified in groups, and that he need apply the principle only within each group. Otherwise he had best avoid difficulty by putting his statements in the form of a table.
+
+### Rule 16. Keep related words together.
+
+The position of the words in a sentence is the principal means of showing their relationship. The writer must therefore, so far as possible, bring together the words, and groups of words, that are related in thought, and keep apart those which are not so related.
+
+The subject of a sentence and the principal verb should not, as a rule, be separated by a phrase or clause that can be transferred to the beginning.
+
+| Original | Revision |
+| --- | --- |
+| Wordsworth, in the fifth book of The Excursion, gives a minute description of this church. | In the fifth book of The Excursion, Wordsworth gives a minute description of this church. |
+| Cast iron, when treated in a Bessemer converter, is changed into steel. | By treatment in a Bessemer converter, cast iron is changed into steel. |
+
+The objection is that the interposed phrase or clause needlessly interrupts the natural order of the main clause. Usually, however, this objection does not hold when the order is interrupted only by a relative clause or by an expression in apposition. Nor does it hold in periodic sentences in which the interruption is a deliberately used means of creating suspense (see examples under Rule 18).
+
+The relative pronoun should come, as a rule, immediately after its antecedent.
+
+| Original | Revision |
+| --- | --- |
+| There was a look in his eye that boded mischief. | In his eye was a look that boded mischief. |
+| He wrote three articles about his adventures in Spain, which were published in Harper's Magazine. | He published in Harper's Magazine three articles about his adventures in Spain. |
+| This is a portrait of Benjamin Harrison, grandson of William Henry Harrison, who became President in 1889. | This is a portrait of Benjamin Harrison, grandson of William Henry Harrison. He became President in 1889. |
+
+If the antecedent consists of a group of words, the relative comes at the end of the group, unless this would cause ambiguity.
+
+The Superintendent of the Chicago Division, who
+
+| Original | Revision |
+| --- | --- |
+| A proposal to amend the Sherman Act, which has been variously judged. | A proposal, which has been variously judged, to amend the Sherman Act. |
+| — | A proposal to amend the much-debated Sherman Act. |
+| The grandson of William Henry Harrison, who | William Henry Harrison's grandson, who |
+
+A noun in apposition may come between antecedent and relative, because in such a combination no real ambiguity can arise.
+
+The Duke of York, his brother, who was regarded with hostility by the Whigs
+
+Modifiers should come, if possible, next to the word they modify. If several expressions modify the same word, they should be so arranged that no wrong relation is suggested.
+
+| Original | Revision |
+| --- | --- |
+| All the members were not present. | Not all the members were present. |
+| He only found two mistakes. | He found only two mistakes. |
+| Major R. E. Joyce will give a lecture on Tuesday evening in Bailey Hall, to which the public is invited, on “My Experiences in Mesopotamia” at eight P. M. | On Tuesday evening at eight P. M., Major R. E. Joyce will give in Bailey Hall a lecture on “My Experiences in Mesopotamia.” The public is invited. |
+
+### Rule 17. In summaries, keep to one tense.
+
+In summarizing the action of a drama, the writer should always use the present tense. In summarizing a poem, story, or novel, he should preferably use the present, though he may use the past if he prefers. If the summary is in the present tense, antecedent action should be expressed by the perfect; if in the past, by the past perfect.
+
+An unforeseen chance prevents Friar John from delivering Friar Lawrence's letter to Romeo. Meanwhile, owing to her father's arbitrary change of the day set for her wedding, Juliet has been compelled to drink the potion on Tuesday night, with the result that Balthasar informs Romeo of her supposed death before Friar Lawrence learns of the non-delivery of the letter.
+
+But whichever tense be used in the summary, a past tense in indirect discourse or in indirect question remains unchanged.
+
+The Friar confesses that it was he who married them.
+
+Apart from the exceptions noted, whichever tense the writer chooses, he should use throughout. Shifting from one tense to the other gives the appearance of uncertainty and irresolution (compare Rule 15).
+
+In presenting the statements or the thought of some one else, as in summarizing an essay or reporting a speech, the writer should avoid intercalating such expressions as “he said,” “he stated,” “the speaker added,” “the speaker then went on to say,” “the author also thinks,” or the like. He should indicate clearly at the outset, once for all, that what follows is summary, and then waste no words in repeating the notification.
+
+In notebooks, in newspapers, in handbooks of literature, summaries of one kind or another may be indispensable, and for children in primary schools it is a useful exercise to retell a story in their own words. But in the criticism or interpretation of literature the writer should be careful to avoid dropping into summary. He may find it necessary to devote one or two sentences to indicating the subject, or the opening situation, of the work he is discussing; he may cite numerous details to illustrate its qualities. But he should aim to write an orderly discussion supported by evidence, not a summary with occasional comment. Similarly, if the scope of his discussion includes a number of works, he will as a rule do better not to take them up singly in chronological order, but to aim from the beginning at establishing general conclusions.
+
+### Rule 18. Place the emphatic words of a sentence at the end.
+
+The proper place in the sentence for the word, or group of words, which the writer desires to make most prominent is usually the end.
+
+| Original | Revision |
+| --- | --- |
+| Humanity has hardly advanced in fortitude since that time, though it has advanced in many other ways. | Humanity, since that time, has advanced in many other ways, but it has hardly advanced in fortitude. |
+| This steel is principally used for making razors, because of its hardness. | Because of its hardness, this steel is principally used in making razors. |
+
+The word or group of words entitled to this position of prominence is usually the logical predicate, that is, the *new* element in the sentence, as it is in the second example.
+
+The effectiveness of the periodic sentence arises from the prominence which it gives to the main statement.
+
+Four centuries ago, Christopher Columbus, one of the Italian mariners whom the decline of their own republics had put at the service of the world and of adventure, seeking for Spain a westward passage to the Indies as a set-off against the achievements of Portuguese discoverers, lighted on America.
+
+With these hopes and in this belief I would urge you, laying aside all hindrance, thrusting away all private aims, to devote yourself unswervingly and unflinchingly to the vigorous and successful prosecution of this war.
+
+The other prominent position in the sentence is the beginning. Any element in the sentence, other than the subject, may become emphatic when placed first.
+
+Deceit or treachery he could never forgive.
+
+So vast and rude, fretted by the action of nearly three thousand years, the fragments of this architecture may often seem, at first sight, like works of nature.
+
+A subject coming first in its sentence may be emphatic, but hardly by its position alone. In the sentence,
+
+Great kings worshipped at his shrine,
+
+the emphasis upon *kings* arises largely from its meaning and from the context. To receive special emphasis, the subject of a sentence must take the position of the predicate.
+
+Through the middle of the valley flowed a winding stream.
+
+The principle that the proper place for what is to be made most prominent is the end applies equally to the words of a sentence, to the sentences of a paragraph, and to the paragraphs of a composition.
diff --git a/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/04-a-few-matters-of-form.md b/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/04-a-few-matters-of-form.md
new file mode 100644
index 00000000..8cb24ecb
--- /dev/null
+++ b/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/04-a-few-matters-of-form.md
@@ -0,0 +1,89 @@
+## IV. A Few Matters of Form
+
+**Headings.** Leave a blank line, or its equivalent in space, after the title or heading of a manuscript. On succeeding pages, if using ruled paper, begin on the first line.
+
+**Numerals.** Do not spell out dates or other serial numbers. Write them in figures or in Roman notation, as may be appropriate.
+
+August 9, 1918 (9 August 1918)
+
+Rule 3
+
+Chapter XII
+
+352nd Infantry
+
+**Parentheses.** A sentence containing an expression in parenthesis is punctuated, outside of the marks of parenthesis, exactly as if the expression in parenthesis were absent. The expression within is punctuated as if it stood by itself, except that the final stop is omitted unless it is a question mark or an exclamation point.
+
+I went to his house yesterday (my third attempt to see him), but he had left town.
+
+He declares (and why should we doubt his good faith?) that he is now certain of success.
+
+(When a wholly detached expression or sentence is parenthesized, the final stop comes before the last mark of parenthesis.)
+
+**Quotations.** Formal quotations, cited as documentary evidence, are introduced by a colon and enclosed in quotation marks.
+
+The provision of the Constitution is: “No tax or duty shall be laid on articles exported from any state.”
+
+Quotations grammatically in apposition or the direct objects of verbs are preceded by a comma and enclosed in quotation marks.
+
+[](https://www.gutenberg.org/files/37134/37134-h/37134-h.htm "34")I recall the maxim of La Rochefoucauld, “Gratitude is a lively sense of benefits to come.”
+
+Aristotle says, “Art is an imitation of nature.”
+
+Quotations of an entire line, or more, of verse, are begun on a fresh line and centered, but need not be enclosed in quotation marks.
+
+Wordsworth's enthusiasm for the Revolution was at first unbounded:
+
+Bliss was it in that dawn to be alive,
+
+But to be young was very heaven!
+
+Quotations introduced by _that_ are regarded as in indirect discourse and not enclosed in quotation marks.
+
+Keats declares that beauty is truth, truth beauty.
+
+Proverbial expressions and familiar phrases of literary origin require no quotation marks.
+
+These are the times that try men's souls.
+
+He lives far from the madding crowd.
+
+The same is true of colloquialisms and slang.
+
+**References.** In scholarly work requiring exact references, abbreviate titles that occur frequently, giving the full forms in an alphabetical list at the end. As a general practice, give the references in parenthesis or in footnotes, not in the body of the sentence. Omit the words _act_, _scene_, _line_, _book_, _volume_, _page_, except when referring by only one of them. Punctuate as indicated below.
+
+In the second scene of the third act In III.ii (still better, simply insert III.ii in parenthesis at the proper place in the sentence)
+
+After the killing of Polonius, Hamlet is placed under guard (IV.ii. 14).
+
+2 Samuel i:17–27
+
+Othello II.iii. 264–267, III.iii. 155–161.
+
+**Syllabication.** If there is room at the end of a line for one or more syllables of a word, but not for the whole word, divide the word, unless this involves cutting off only a [](https://www.gutenberg.org/files/37134/37134-h/37134-h.htm "35") single letter, or cutting off only two letters of a long word. No hard and fast rule for all words can be laid down. The principles most frequently applicable are:
+
+(a) Divide the word according to its formation:
+
+know-ledge (not knowl-edge); Shake-speare (not Shakes-peare); de-scribe (not des-cribe); atmo-sphere (not atmos-phere);
+
+(b) Divide “on the vowel:”
+
+edi-ble (not ed-ible); propo-sition; ordi-nary; espe-cial; reli-gious; oppo-nents; regu-lar; classi-fi-ca-tion (three divisions allowable); deco-rative; presi-dent;
+
+(c) Divide between double letters, unless they come at the end of the simple form of the word:
+
+Apen-nines; Cincin-nati; refer-ring; but tell-ing.
+
+(d) Do not divide before final _-ed_ if the _e_ is silent:
+
+treat-ed (but not roam-ed or nam-ed).
+
+The treatment of consonants in combination is best shown from examples:
+
+for-tune; pic-ture; sin-gle; presump-tuous; illus-tration; sub-stan-tial (either division); indus-try; instruc-tion; sug-ges-tion; incen-diary.
+
+The student will do well to examine the syllable-division in a number of pages of any carefully printed book.
+
+**Titles.** For the titles of literary works, scholarly usage prefers italics with capitalized initials. The usage of editors and publishers varies, some using italics with capitalized initials, others using Roman with capitalized initials and with or without quotation marks. Use italics (indicated in manuscript by underscoring), except in writing for a periodical that follows a different practice. Omit initial _A_ or _The_ from titles when you place the possessive before them.
+
+The Iliad; the Odyssey; As You Like It; To a Skylark; The Newcomes; A Tale of Two Cities; Dickens's Tale of Two Cities.
diff --git a/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/05-words-and-expressions-commonly-misused.md b/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/05-words-and-expressions-commonly-misused.md
new file mode 100644
index 00000000..3e379cbc
--- /dev/null
+++ b/builtin-skills/document-process/writing-clearly-and-concisely/elements-of-style/05-words-and-expressions-commonly-misused.md
@@ -0,0 +1,348 @@
+## V. Words And Expressions Commonly Misused
+
+(Some of the forms here listed, as *like I did*, are downright bad English; others, as the split infinitive, have their defenders, but are in such general disfavor that it is at least inadvisable to use them; still others, as *case*, *factor*, *feature*, *interesting*, *one of the most*, are good in their place, but are constantly obtruding themselves into places where they have no right to be. If the writer will make it his purpose from the beginning to express accurately his own individual thought, and will refuse to be satisfied with a ready-made formula that saves him the trouble of doing so, this last set of expressions will cause him little trouble. But if he finds that in a moment of inadvertence he has used one of them, his proper course will probably be not to patch up the sentence by substituting one word or set of words for another, but to recast it completely, as illustrated in a number of examples below and in others under Rules 12 and 13.)
+
+**All right.** Idiomatic in familiar speech as a detached phrase in the sense, “Agreed,” or “Go ahead.” In other uses better avoided. Always written as two words.
+
+**As good or better than.** Expressions of this type should be corrected by rearranging the sentence.
+
+| Original | Revision |
+| --- | --- |
+| My opinion is as good or better than his. | My opinion is as good as his, or better (if not better). |
+
+**As to whether.** *Whether* is sufficient; see under Rule 13.
+
+**Bid.** Takes the infinitive without *to*. The past tense in the sense, _“ordered,”_ is *bade*.
+
+**But.** Unnecessary after *doubt* and *help*.
+
+| Original | Revision |
+| --- | --- |
+| I have no doubt but that | I have no doubt that |
+| He could not help see but that | He could not help seeing that |
+
+The too frequent use of *but* as a conjunction leads to the fault discussed under Rule 14. A loose sentence formed with *but* can always be converted into a periodic sentence formed with *although*, as illustrated under Rule 4.
+
+Particularly awkward is the following of one *but* by another, making a contrast to a contrast or a reservation to a reservation. This is easily corrected by re-arrangement.
+
+| Original | Revision |
+| --- | --- |
+| America had vast resources, but she seemed almost wholly unprepared for war. But within a year she had created an army of four million men. | America seemed almost wholly unprepared for war, but she had vast resources. Within a year she had created an army of four million men. |
+
+**Can.** Means *am (is, are) able*. Not to be used as a substitute for *may*.
+
+**Case.** The Concise Oxford Dictionary begins its definition of this word: “instance of a thing's occurring; usual state of affairs.” In these two senses, the word is usually unnecessary.
+
+| Original | Revision |
+| --- | --- |
+| In many cases, the rooms were poorly ventilated. | Many of the rooms were poorly ventilated. |
+| It has rarely been the case that any mistake has been made. | Few mistakes have been made. |
+
+See Wood, Suggestions to Authors, pp. 68–71, and Quiller-Couch, The Art of Writing, pp. 103–106.
+
+**Certainly.** Used indiscriminately by some writers, much as others use *very*, to intensify any and every statement. A mannerism of this kind, bad in speech, is even worse in writing.
+
+**Character.** Often simply redundant, used from a mere habit of wordiness.
+
+| Original | Revision |
+| --- | --- |
+| Acts of a hostile character | Hostile acts |
+
+**Claim, vb.** With object-noun, means *lay claim to*. May be used with a dependent clause if this sense is clearly involved: “He claimed that he was the sole surviving heir.” (But even here, “claimed to be” would be better.) Not to be used as a substitute for *declare*, *maintain*, or *charge*.
+
+**Clever.** This word has been greatly overused; it is best restricted to ingenuity displayed in small matters.
+
+**Compare.** To *compare to* is to point out or imply resemblances, between objects regarded as essentially of different order; to *compare with* is mainly to point out differences, between objects regarded as essentially of the same order. Thus life has been compared to a pilgrimage, to a drama, to a battle; Congress may be compared with the British Parliament. Paris has been compared to ancient Athens; it may be compared with modern London.
+
+**Consider.** Not followed by *as* when it means “believe to be.” “I consider him thoroughly competent.” Compare, “The lecturer considered Cromwell first as soldier and second as administrator,” where “considered” means “examined” or “discussed.”
+
+**Data.** A plural, like *phenomena* and *strata*.
+
+These data were tabulated.
+
+**Dependable.** A needless substitute for *reliable*, *trustworthy*.
+
+**Different than.** Not permissible. Substitute *different from*, *other than*, or *unlike*.
+
+**Divided into.** Not to be misused for *composed of*. The line is sometimes difficult to draw; doubtless plays are divided into acts, but poems are composed of stanzas.
+
+**Don't.** Contraction of *do not*. The contraction of *does not* is *doesn't*.
+
+**Due to.** Incorrectly used for *through*, *because of*, or *owing to*, in adverbial phrases: “He lost the first game, due to carelessness.” In correct use related as predicate or as modifier to a particular noun: “This invention is due to Edison;” “losses due to preventable fires.”
+
+**Folk.** A collective noun, equivalent to *people*. Use the singular form only.
+
+**Effect.** As noun, means *result*; as verb, means *_to_ bring about*, *accomplish* (not to be confused with *affect*, which means “to influence”).
+
+As noun, often loosely used in perfunctory writing about fashions, music, painting, and other arts: “an Oriental effect;” “effects in pale green;” “very delicate effects;” “broad effects;” “subtle effects;” “a charming effect was produced by.” The writer who has a definite meaning to express will not take refuge in such vagueness.
+
+**Etc.** Equivalent to *and the rest*, *and so forth*, and hence not to be used if one of these would be insufficient, that is, if the reader would be left in doubt as to any important particulars. Least open to objection when it represents the last terms of a list already given in full, or immaterial words at the end of a quotation.
+
+At the end of a list introduced by *such as*, *for example*, or any similar expression, *etc.* is incorrect.
+
+**Fact.** Use this word only of matters of a kind capable of direct verification, not of matters of judgment. That a particular event happened on a given date, that lead melts at a certain temperature, are facts. But such conclusions as that Napoleon was the greatest of modern generals, or that the climate of California is delightful, however incontestable they _may be_, are not properly facts.
+
+On the formula *the fact that*, see under Rule 13.
+
+**Factor.** A hackneyed word; the expressions of which it forms part can usually be replaced by something more direct and idiomatic.
+
+| Original | Revision |
+| --- | --- |
+| His superior training was the great factor in his winning the match. | He won the match by being better trained. |
+| Heavy artillery has become an increasingly important factor in deciding battles. | Heavy artillery has played a constantly larger part in deciding battles. |
+
+**Feature.** Another hackneyed word; like *factor* it usually adds nothing to the sentence in which it occurs.
+
+| Original | Revision |
+| --- | --- |
+| A feature of the entertainment especially worthy of mention was the singing of Miss A. | (Better use the same number of words to tell what Miss A. sang, or if the programme has already been given, to tell how she sang.) |
+
+As a verb, in the advertising sense of *offer as a special attraction*, to be avoided.
+
+**Fix.** Colloquial in America for *arrange*, *prepare*, *mend*. In writing restrict it to its literary senses, *fasten*, *make firm or immovable*, etc.
+
+**Get.** The colloquial *have got* for *have* should not be used in writing. The preferable form of the participle is *got*.
+
+**He is a man who.** A common type of redundant expression; see Rule 13.
+
+| Original | Revision |
+| --- | --- |
+| He is a man who is very ambitious. | He is very ambitious. |
+| Spain is a country which I have always wanted to visit. | I have always wanted to visit Spain. |
+
+**Help.** See under **But**.
+
+**However.** In the meaning *nevertheless*, not to come first in its sentence or clause.
+
+| Original | Revision |
+| --- | --- |
+| The roads were almost impassable. However, we at last succeeded in reaching camp. | The roads were almost impassable. At last, however, we succeeded in reaching camp. |
+
+When *however* comes first, it means *in whatever way* or *to whatever extent*.
+
+However you advise him, he will probably do as he thinks best.
+
+However discouraging the prospect, he never lost heart.
+
+**Interesting.** Avoid this word as a perfunctory means of introduction. Instead of announcing that what you are about to tell is interesting, make it so.
+
+| Original | Revision |
+| --- | --- |
+| An interesting story is told of | (Tell the story without preamble.) |
+| In connection with the anticipated visit of Mr. B. to America, it is interesting to recall that he | Mr. B., who it is expected will soon visit America |
+
+**Kind of.** Not to be used as a substitute for *rather* (before adjectives and verbs), or except in familiar style, for *something like* (before nouns). Restrict it to its literal sense: “Amber is a kind of fossil resin;” “I dislike that kind of notoriety.” The same holds true of *sort of*.
+
+**Less.** Should not be misused for *fewer*.
+
+| Original | Revision |
+| --- | --- |
+| He had less men than in the previous campaign | He had fewer men than in the previous campaign |
+
+*Less* refers to quantity, *fewer* to number. “His troubles are less than mine” means “His troubles are not so great as mine.” “His troubles are fewer than mine” means “His troubles are not so numerous as mine.” It is, however, correct to say, “The signers of the petition were less than a hundred,” where the round number *a hundred* is something like a collective noun, and *less* is thought of as meaning a less quantity or amount.
+
+**Like.** Not to be misused for *as*. *Like* governs nouns and pronouns; before phrases and clauses the equivalent word is *as*.
+
+| Original | Revision |
+| --- | --- |
+| We spent the evening like in the old days. | We spent the evening as in the old days. |
+| He thought like I did. | He thought as I did (like me). |
+
+**Line, along these lines.** *Line* in the sense of *course of procedure*, *conduct*, *thought*, is allowable, but has been so much overworked, particularly in the phrase *along these lines*, that a writer who aims at freshness or originality had better discard it entirely.
+
+| Original | Revision |
+| --- | --- |
+| Mr. B. also spoke along the same lines. | Mr. B. also spoke, to the same effect. |
+| He is studying along the line of French literature. | He is studying French literature. |
+
+**Literal, literally.** Often incorrectly used in support of exaggeration or violent metaphor.
+
+| Original | Revision |
+| --- | --- |
+| A literal flood of abuse. | A flood of abuse. |
+| Literally dead with fatigue | Almost dead with fatigue (dead tired) |
+
+**Lose out.** Meant to be more emphatic than *lose*, but actually less so, because of its commonness. The same holds true of *try out*, *win out*, *sign up*, *register up*. With a number of verbs, *out* and *up* form idiomatic combinations: *find out*, *run out*, *turn out*, *cheer up*, *dry up*, *make up*, and others, each distinguishable in meaning from the simple verb. *Lose out* is not.
+
+**Most.** Not to be used for *almost*.
+
+| Original | Revision |
+| --- | --- |
+| Most everybody | Almost everybody |
+| Most all the time | Almost all the time |
+
+**Nature.** Often simply redundant, used like *character*.
+
+| Original | Revision |
+| --- | --- |
+| Acts of a hostile _nature_ | Hostile acts |
+
+Often vaguely used in such expressions as a “lover of nature;” “poems about nature.” Unless more specific statements follow, the reader cannot tell whether the poems have to do with natural scenery, rural life, the sunset, the untracked wilderness, or the habits of squirrels.
+
+**Near by.** Adverbial phrase, not yet fully accepted as good English, though the analogy of *close by* and *hard by* seems to justify it. *Near*, or *near at hand*, is as good, if not better.
+
+Not to be used as an adjective; use *neighboring*.
+
+**Oftentimes, ofttimes.** Archaic forms, no longer in good use. The modern word is *often*.
+
+**One hundred and one.** Retain the *and* in this and similar expressions, in accordance with the unvarying usage of English prose from Old English times.
+
+**One of the most.** Avoid beginning essays or paragraphs with this formula, as, “One of the most interesting developments of modern science is, etc.;” “Switzerland is one of the most interesting countries of Europe.” There is nothing wrong in this; it is simply threadbare and forcible-feeble.
+
+A common blunder is to use a singular verb in a relative clause following this or a similar expression, when the relative is the subject.
+
+| Original | Revision |
+| --- | --- |
+| One of the ablest men that has attacked this problem. | One of the ablest men that have attacked this problem. |
+
+**Participle for verbal noun.**
+
+| Original | Revision |
+| --- | --- |
+| Do you mind me asking a question? | Do you mind my asking a question? |
+| There was little prospect of the Senate accepting even this compromise. | There was little prospect of the Senate's accepting even this compromise. |
+
+In the left-hand column, *asking* and *accepting* are present participles; in the right-hand column, they are verbal nouns (gerunds). The construction shown in the left-hand column is occasionally found, and has its defenders. Yet it is easy to see that the second sentence has to do not with a prospect of the Senate, but with a prospect of accepting. In this example, at least, the construction is plainly illogical.
+
+As the authors of The King's English point out, there are sentences apparently, but not really, of this type, in which the possessive is not called for.
+
+I cannot imagine Lincoln refusing his assent to this measure.
+
+In this sentence, what the writer cannot imagine is Lincoln himself, in the act of refusing his assent. Yet the meaning would be virtually the same, except for a slight loss of vividness, if he had written,
+
+I cannot imagine Lincoln's refusing his assent to this measure.
+
+By using the possessive, the writer will always be on the safe side.
+
+In the examples above, the subject of the action is a single, unmodified term, immediately preceding the verbal noun, and the construction is as good as any that could be used. But in any sentence in which it is a mere clumsy substitute for something simpler, or in which the use of the possessive is awkward or impossible, should of course be recast.
+
+| Original | Revision |
+| --- | --- |
+| In the event of a reconsideration of the whole matter's becoming necessary | If it should become necessary to reconsider the whole matter |
+| There was great dissatisfaction with the decision of the arbitrators being favorable to the company. | There was great dissatisfaction that the arbitrators should have decided in favor of the company. |
+
+**People.** *The people* is a political term, not to be confused with *the public*. From the people comes political support or opposition; from the public comes artistic appreciation or commercial patronage.
+
+**Phase.** Means a stage of transition or development: “the phases of the moon;” “the last phase.” Not to be used for *aspect* or *topic*.
+
+| Original | Revision |
+| --- | --- |
+| Another phase of the subject | Another point (another question) |
+
+**Possess.** Not to be used as a mere substitute for *have* or *own*.
+
+| Original | Revision |
+| --- | --- |
+| He possessed great courage. | He had great courage (was very brave). |
+| He was the fortunate possessor of | He owned |
+
+**Prove.** The past participle is *proved*.
+
+**Respective, respectively.** These words may usually be omitted with advantage.
+
+| Original | Revision |
+| --- | --- |
+| Works of fiction are listed under the names of their respective authors. | Works of fiction are listed under the names of their authors. |
+| The one mile and two mile runs were won by Jones and Cummings respectively. | The one mile and two mile runs were won by Jones and by Cummings. |
+
+In some kinds of formal writing, as geometrical proofs, it may be necessary to use *respectively*, but it should not appear in writing on ordinary subjects.
+
+**Shall, Will.** The future tense requires *shall* for the first person, *will* for the second and third. The formula to express the speaker's belief regarding his future action or state is *I shall*; *I will* expresses his determination or his consent.
+
+**Should.** See under **Would**.
+
+**So.** Avoid, in writing, the use of *so* as an intensifier: “so good;” “so warm;” “so delightful.”
+
+On the use of *so* to introduce clauses, see Rule 4.
+
+**Sort of.** See under **Kind of**.
+
+**Split Infinitive.** There is precedent from the fourteenth century downward for interposing an adverb between *to* and the infinitive which it governs, but the construction is in disfavor and is avoided by nearly all careful writers.
+
+| Original | Revision |
+| --- | --- |
+| To diligently inquire | To inquire diligently |
+
+**State.** Not to be used as a mere substitute for *say*, *remark*. Restrict it to the sense of *express fully or clearly*, as, “He refused to state his objections.”
+
+**Student Body.** A needless and awkward expression meaning no more than the simple word *students*.
+
+| Original | Revision |
+| --- | --- |
+| A member of the student body | A student |
+| Popular with the student body | Liked by the students |
+| The student body passed resolutions. | The students passed resolutions. |
+
+**System.** Frequently used without need.
+
+| Original | Revision |
+| --- | --- |
+| Dayton has adopted the commission system of _government._ | Dayton has adopted government by commission. |
+| The dormitory system | Dormitories |
+
+**Thanking You in Advance.** This sounds as if the writer meant, “It will not be worth my while to write to you again.” In making your request, write, “Will you please,” or “I shall be obliged,” and if anything further seems necessary write a letter of acknowledgment later.
+
+**They.** A common inaccuracy is the use of the plural pronoun when the antecedent is a distributive expression such as *each*, *each one*, *everybody*, *every one*, *many a man*, which, though implying more than one person, requires the pronoun to be in the singular. Similar to this, but with even less justification, is the use of the plural pronoun with the antecedent *anybody*, *any one*, *somebody*, *some one*, the intention being either to avoid the awkward “he or she,” or to avoid committing oneself to either. Some bashful speakers even say, “A friend of mine told me that they, etc.”
+
+Use *he* with all the above words, unless the antecedent is or must be feminine.
+
+**Very.** Use this word sparingly. Where emphasis is necessary, use words strong in themselves.
+
+**Viewpoint.** Write *point of view*, but do not misuse this, as many do, for *view* or *opinion*.
+
+**While.** Avoid the indiscriminate use of this word for *and*, *but*, and *although*. Many writers use it frequently as a substitute for *and* or *but*, either from a mere desire to vary the connective, or from uncertainty which of the two connectives is the more appropriate. In this use it is best replaced by a semicolon.
+
+| Original | Revision |
+| --- | --- |
+| The office and salesrooms are on the ground floor, while the rest of the building is devoted to manufacturing. | The office and salesrooms are on the ground floor; the rest of the building is devoted to manufacturing. |
+
+Its use as a virtual equivalent of *although* is allowable in sentences where this leads to no ambiguity or absurdity.
+
+While I admire his energy, I wish it were employed in a better cause.
+
+This is entirely correct, as shown by the paraphrase,
+
+I admire his energy; at the same time I wish it were employed in a better cause.
+
+Compare:
+
+| Original | Revision |
+| --- | --- |
+| While the temperature reaches 90 or 95 degrees in the daytime, the nights are often chilly. | Although the temperature reaches 90 or 95 degrees in the daytime, the nights are often chilly. |
+
+The paraphrase,
+
+The temperature reaches 90 or 95 degrees in the daytime; at the same time the nights are often chilly,
+
+shows why the use of *while* is incorrect.
+
+In general, the writer will do well to use *while* only with strict literalness, in the sense of *during the time that*.
+
+**Whom.** Often incorrectly used for *who* before *he said* or similar expressions, when it is really the subject of a following verb.
+
+| Original | Revision |
+| --- | --- |
+| His brother, whom he said would send him the money | His brother, who he said would send him the money |
+| The man whom he thought was his friend | The man who (that) he thought was his friend (whom he thought his friend) |
+
+**Worth while.** Overworked as a term of vague approval and (with *not*) of disapproval. Strictly applicable only to actions: “Is it worth while to telegraph?”
+
+| Original | Revision |
+| --- | --- |
+| His books are not worth while. | His books are not worth reading (are not worth one's while to read; do not repay reading; are worthless). |
+
+The use of *worth while* before a noun (“a worth while story”) is indefensible.
+
+**Would.** A conditional statement in the first person requires *should*, not *would*.
+
+I should not have succeeded without his help.
+
+The equivalent of *shall* in indirect quotation after a verb in the past tense is *should*, not *would*.
+
+He predicted that before long we should have a great surprise.
+
+To express habitual or repeated action, the past tense, without *would*, is usually sufficient, and from its brevity, more emphatic.
+
+| Original | Revision |
+| --- | --- |
+| Once a year he would visit the old mansion. | Once a year he visited the old mansion. |
diff --git a/builtin-skills/document-process/writing-clearly-and-concisely/signs-of-ai-writing.md b/builtin-skills/document-process/writing-clearly-and-concisely/signs-of-ai-writing.md
new file mode 100644
index 00000000..727c3969
--- /dev/null
+++ b/builtin-skills/document-process/writing-clearly-and-concisely/signs-of-ai-writing.md
@@ -0,0 +1,901 @@
+# Signs of AI Writing
+
+[![A screenshot of ChatGPT reading: "[header] Legacy & Interpretation [body] The "Black Hole Edition" is not just a meme — it's a celebration of grassroots car culture, where ideas are limitless and fun is more important than spec sheets. Whether powered by a rotary engine, a V8 swap, or an imagined fighter jet turbine, the Miata remains the canvas for car enthusiasts worldwide."](https://upload.wikimedia.org/wikipedia/commons/thumb/5/59/ChatGPT_response_screenshot_1.jpg/250px-ChatGPT_response_screenshot_1.jpg)](https://en.wikipedia.org/wiki/File:ChatGPT_response_screenshot_1.jpg)
+
+*LLMs tend to have an identifiable writing style.*
+
+This is a list of writing and formatting conventions typical of [AI chatbots](https://en.wikipedia.org/wiki/AI_chatbot "AI chatbot") such as [ChatGPT](https://en.wikipedia.org/wiki/ChatGPT "ChatGPT"), with real examples taken from Wikipedia articles and drafts. It is a [field guide](https://en.wikipedia.org/wiki/Field_guide "Field guide") to help detect [undisclosed AI-generated content](https://en.wikipedia.org/wiki/Wikipedia:LLMDISCLOSE "Wikipedia:LLMDISCLOSE") on Wikipedia. This list is *descriptive*, not *prescriptive*; it consists of observations, not rules. Advice about formatting or language to avoid in Wikipedia articles can be found in the [policies and guidelines](https://en.wikipedia.org/wiki/Wikipedia:PAG "Wikipedia:PAG") and the [Manual of Style](https://en.wikipedia.org/wiki/Wikipedia:MOS "Wikipedia:MOS"), but does not belong on this page.
+
+This list is *not* a ban on certain words, phrases, or punctuation. Not all text featuring these indicators is AI-generated, as the [large language models](https://en.wikipedia.org/wiki/Large_language_model "Large language model") that power AI chatbots are trained on human writing, including the writing of Wikipedia editors. This is simply a catalog of very common patterns observed over many thousands of instances of AI-generated text, *specific to Wikipedia.* While some of its advice may be broadly applicable, some signs—particularly those involving punctuation and formatting—may not apply in a non-Wikipedia context.
+
+The patterns here are also only potential *signs* of a problem, not *the problem itself*. While many of these issues are immediately obvious and easy to fix—e.g., excessive boldface, poor use of language and punctuation, broken markup, citation style quirks—they can point to less outwardly visible problems that carry [much more serious policy risks](https://en.wikipedia.org/wiki/Wikipedia:AIFAIL "Wikipedia:AIFAIL"). If LLM-generated text is polished enough (initially or subsequently), those surface defects might not be present, but deeper problems can be. Please do not merely treat these signs as the problems to be fixed; that could just make detection harder. The actual problems are those deeper concerns, so make sure to address them, either yourself or by flagging them, per the advice at [Wikipedia:Large language models §Handling suspected LLM-generated content](https://en.wikipedia.org/wiki/Wikipedia:Large_language_models#Handling_suspected_LLM-generated_content "Wikipedia:Large language models") and [Wikipedia:WikiProject AI Cleanup/Guide](https://en.wikipedia.org/wiki/Wikipedia:WikiProject_AI_Cleanup/Guide "Wikipedia:WikiProject AI Cleanup/Guide").
+
+The [speedy deletion policy](https://en.wikipedia.org/wiki/Wikipedia:Speedy_deletion "Wikipedia:Speedy deletion") criterion [G15](https://en.wikipedia.org/wiki/Wikipedia:G15 "Wikipedia:G15") (LLM-generated pages without human review) is limited to the most objective and least contestable indications that the page's content was generated by an LLM. There are three such indicators, the first of which can be found in [§Communication intended for the user](#communication-intended-for-the-user) and the other two in [§Citations](#citations).
+
+Do not solely rely on [artificial intelligence content detection](https://en.wikipedia.org/wiki/Artificial_intelligence_content_detection "Artificial intelligence content detection") tools (such as [GPTZero](https://en.wikipedia.org/wiki/GPTZero "GPTZero")) to evaluate whether text is LLM-generated. While they perform better than might be achieved by chance, these tools have non-trivial error rates and cannot replace human judgment.[^1] Detectors can be brittle to multiple factors such as text modifications (e.g. paraphrasing and spacing changes) and the use of generative models not seen during detector training.[^2] By the same token, do not trust too much in your own interpretation. Research shows that people who use LLMs heavily themselves can correctly determine whether an article was generated by AI about 90% of the time, which means that if you are an expert user of LLMs and you tag 10 pages as being AI-generated, you've probably falsely accused one editor.[^3] People who don't personally use LLMs much do only slightly better than random chance (in both directions) for identifying AI-generated articles.[^3]
+
+---
+
+## Regression to the Mean
+
+LLMs (and [artificial neural networks](https://en.wikipedia.org/wiki/Artificial_neural_network "Artificial neural network") in general) use statistical algorithms to guess (infer) what should come next based on a large corpus of training material. It thus tends to [regress to the mean](https://en.wikipedia.org/wiki/Regression_to_the_mean "Regression to the mean"); that is, the result tends toward the most statistically likely result that applies to the widest variety of cases. It can simultaneously be a strength and a "tell" for detecting AI-generated content.
+
+For example, LLMs are usually trained on data from the internet in which famous people are generally described with positive, important-sounding language. Consequently, the LLM tends to omit specific, unusual, nuanced facts (which are statistically rare) and replace them with more generic, positive descriptions (which are statistically common). Thus the highly specific "inventor of the first train-coupling device" might become "a revolutionary titan of industry." It is like shouting louder and louder that a portrait shows a uniquely important person, while the portrait itself is fading from a sharp photograph into a blurry, generic sketch. The subject becomes simultaneously less specific and more exaggerated.[^4]
+
+This statistical regression to the mean, a smoothing over of specific facts into generic statements, that could equally apply to many topics, makes AI-generated content easier to detect.
+
+### Undue emphasis on symbolism, legacy, and importance
+
+**Words to watch:** *stands/serves as*, *is a testament/reminder*, *plays a vital/significant/crucial/pivotal role*, *underscores/highlights its importance/significance*, *reflects broader*, *symbolizing its ongoing/enduring/lasting impact*, *key turning point*, *indelible mark*, *deeply rooted*, *profound heritage*, *steadfast dedication*...
+
+LLM writing often puffs up the importance of the subject matter by adding statements about how arbitrary aspects of the topic represent or contribute to a broader topic.[^5] There is a distinct and easily identifiable repertoire of ways that it writes these statements.[^6]
+
+> The Statistical Institute of Catalonia was officially established in 1989, marking a pivotal moment in the evolution of regional statistics in Spain. [...]
+>
+> The founding of Idescat represented a significant shift toward regional statistical independence, enabling [Catalonia](https://en.wikipedia.org/wiki/Catalonia "Catalonia") to develop a statistical system tailored to its unique socio-economic context. This initiative was part of a broader movement across Spain to decentralize administrative functions and enhance regional governance.
+
+> Kumba has long been an important center for trade and agriculture. [...] The establishment of road networks connecting Kumba to other parts of the Southwest Region, such as Mamfe and Buea, helped solidify its role as a regional hub.
+
+LLMs may include these statements for even the most mundane of subjects like etymology or population data. Sometimes, they add hedging preambles acknowledging that the subject is relatively unimportant or low-profile, before talking about its importance anyway.
+
+**Examples**
+
+> During the [Spanish colonial period](https://en.wikipedia.org/wiki/Spanish_Colonial_Period_(Philippines) "Spanish Colonial Period (Philippines)"), the name *Bakunutan* was hispanized to *Bacnotan*, a modification reflected in official documents preserved in the [National Archives](https://en.wikipedia.org/wiki/National_Archives_of_the_Philippines "National Archives of the Philippines") in Manila. This etymology highlights the enduring legacy of the community's resistance and the transformative power of unity in shaping its identity.
+
+> Though it saw only limited application, it contributes to the broader history of early aviation engineering and reflects the influence of French rotary designs on German manufacturers.
+
+When talking about biology (e.g., when asked to discuss an animal or plant species), LLMs tend to over-emphasize connections to the broader ecosystem or environment, even when those connections are tenuous or generic. LLMs also tend to belabor the species' conservation status and research and preservation efforts, even if the status is unknown and no serious efforts exist.
+
+**Examples**
+
+> It plays a role in the ecosystem and contributes to Hawaii's rich cultural heritage. [...] Preserving this endemic species is vital not only for ecological diversity but also for sustaining the cultural traditions connected to Hawaii's native flora.
+
+> Currently, there is no specific conservation assessment for *Lethrinops lethrinus* by the International Union for Conservation of Nature (IUCN). However, the general health of the Lake Malawi ecosystem is crucial for the survival of this and other endemic species. Factors such as overfishing, pollution, and habitat destruction could potentially impact their populations.
+
+### Undue emphasis on notability, attribution, and media coverage
+
+**Words to watch:** *independent coverage*, *local/regional/national/[country name] media outlets*, *music/business/tech outlets*, *active social media presence*
+
+Similarly, LLMs act as if the best way to prove that a subject is notable is to hit readers over the head with claims of notability, often by listing sources that a subject has been covered in. They may or may not provide additional context as to what those sources have actually said about the subject, and often inaccurately attribute their own [superficial analyses](#superficial-analyses) to the source. This is more common in text from newer AI tools (2025 or later).
+
+Human-written press releases have of course also cited news clippings for decades, but LLMs specifically asked to write a Wikipedia article often echo the exact wording of [Wikipedia's guidelines](https://en.wikipedia.org/wiki/Wikipedia:N "Wikipedia:N"), such as "independent coverage."
+
+**Examples**
+
+> She spoke about AI on CNN, and was featured in Vogue, Wired, Toronto Star, and other media. [...] Her insights have also been featured in *Wired*, *Refinery29*, and other prominent media outlets.
+
+> Her views have been cited in *The New York Times*, *BBC*, *Financial Times*, and *The Hindu*.
+
+> Its significance is documented in archived school event programs and regional press coverage, including the *Mesabi Daily News*, which regularly reviewed performances held there.
+
+On Wikipedia specifically, LLMs often painstakingly emphasize their sources in the body text—even for trivial coverage, uncontroversial facts, or other situations where a human Wikipedia editor would be more likely to either provide an inline citation or no source at all.
+
+**Examples**
+
+> The restaurant has also been mentioned in [ABC News](https://en.wikipedia.org/wiki/ABC_News_(Australia) "ABC News (Australia)") coverage relating to incidents in the surrounding precinct, underscoring its role as a well-known late-night venue in the city [of [Adelaide](https://en.wikipedia.org/wiki/Adelaide "Adelaide")].
+
+> In the United States, university-based incubators and accelerators have expanded alongside these centers; an official Library of Congress review found that 31.5% of SBA [[Small Business Administration](https://en.wikipedia.org/wiki/Small_Business_Administration "Small Business Administration")] Growth Accelerator Fund Competition winners from 2014–2016 were university-based programs.
+
+In articles about people/entities who use social media, LLMs will often note that they "maintain an active social media presence" or something similar. This wording is particularly idiosyncratic to AI text and relatively uncommon on Wikipedia before ~2024.
+
+> The mall maintains a strong digital presence, particularly on Instagram, where it actively shares the latest updates and events. Forum Kochi has consistently demonstrated excellence in digital promotions, with high-quality, engaging, and impactful video content playing a key role in its outreach.
+
+### Superficial analyses
+
+**Words to watch:** *ensuring ...*, *highlighting ...*, *emphasizing ...*, *reflecting ...*, *underscoring ...*, *showcasing ...*, *aligns with...*, *contributing to...*
+
+AI chatbots tend to insert superficial analysis of information, often in relation to its significance, recognition, or impact.[^7] This is often done by attaching a [present participle](https://en.wikipedia.org/wiki/Participle#Forms "Participle") ("-ing") phrase at the end of sentences, sometimes with [vague attributions](#vague-attributions-of-opinion) to third parties (see below).[^7][^5]
+
+While [many of these words are strong AI tells on their own](https://en.wikipedia.org/wiki/Wikipedia:AIWORDS "Wikipedia:AIWORDS"),[^6][^8] an even stronger tell is when the subjects of these verbs are facts, events, or other inanimate things. A person, for example, can highlight or emphasize something, but a fact or event cannot. The "highlighting" or "underscoring" is not something that is actually happening; it is a claim by a disembodied narrator about what something means.[^5]
+
+Such comments are usually [synthesis](https://en.wikipedia.org/wiki/Wikipedia:SYNTH "Wikipedia:SYNTH") and/or unattributed opinions in wikivoice. Newer chatbots with [retrieval-augmented generation](https://en.wikipedia.org/wiki/Retrieval-augmented_generation "Retrieval-augmented generation") (for example, an AI chatbot that can search the web) may attach these statements to [named sources](#undue-emphasis-on-notability-attribution-and-media-coverage)—e.g., "Roger Ebert highlighted the lasting influence"—regardless of whether those sources say anything close.
+
+**Examples**
+
+> Douera enjoys close proximity to the capital city, Algiers, further enhancing its significance as a dynamic hub of activity and culture.
+
+> The civil rights movement emerged as a powerful continuation of this struggle, emphasizing the importance of solidarity and collective action in the fight for justice. This historical legacy has influenced contemporary African-American families, shaping their values, community structures, and approaches to political engagement. Economically, the enduring impacts of systemic inequality have led to both challenges and innovations within African-American communities, driving a commitment to empowerment and social change that echoes through generations.
+
+> Its bilingual monument sign, with inscriptions in both English and Spanish, underscores its role in bringing together Latter-day Saints from the United States and Mexico.
+
+> These citations, spanning more than six decades and appearing in recognized academic publications, illustrate Blois' lasting influence in computational linguistics, grammar, and neology.
+
+> It holds a pivotal place in the [East Central Railway Zone](https://en.wikipedia.org/wiki/East_Central_Railway_Zone "East Central Railway Zone") of [Indian Railways](https://en.wikipedia.org/wiki/Indian_Railways "Indian Railways"), serving as a major railway hub with historical significance. The station has [1,676 mm](https://en.wikipedia.org/wiki/5_ft_6_in_gauge_railway "5 ft 6 in gauge railway") (5 ft 6 in) [broad gauge](https://en.wikipedia.org/wiki/Broad_gauge "Broad gauge") along with 8 tracks and 6 platforms. [...] Historically, it has been crucial for linking [Darbhanga](https://en.wikipedia.org/wiki/Darbhanga "Darbhanga") with significant cities like [Delhi](https://en.wikipedia.org/wiki/Delhi "Delhi"), [Patna](https://en.wikipedia.org/wiki/Patna "Patna"), and [Kolkata](https://en.wikipedia.org/wiki/Kolkata "Kolkata"), facilitating the movement of passengers and goods. The station has supported various services, including passenger trains and express trains like the [Satyagrah Express](https://en.wikipedia.org/wiki/Satyagrah_Express "Satyagrah Express") and [Mithila Express](https://en.wikipedia.org/wiki/Mithila_Express "Mithila Express"), contributing to the socio-economic development of the region. [...] Over the years, Darbhanga Junction has seen several upgrades and modernization efforts aimed at improving facilities and operational efficiency, reflecting its continued relevance in the regional and national transportation landscape.
+
+### Promotional and advertisement-like language
+
+**Words to watch:** *continues to captivate*, *groundbreaking* (in the figurative sense), *stunning natural beauty*, *enduring/lasting legacy*, *nestled*, *in the heart of*, *boasts a*...
+
+LLMs have serious problems keeping a neutral tone, especially when writing about something that could be considered "cultural heritage"—in which case they [constantly remind the reader of its importance](#undue-emphasis-on-symbolism-legacy-and-importance).
+
+**Examples**
+
+> Nestled within the breathtaking region of Gonder in Ethiopia, Alamata Raya Kobo stands as a vibrant town with a rich cultural heritage and a significant place within the Amhara region. From its scenic landscapes to its historical landmarks, Alamata Raya Kobo offers visitors a fascinating glimpse into the diverse tapestry of Ethiopia. In this article, we will explore the unique characteristics that make Alamata Raya Kobo a town worth visiting and shed light on its significance within the Amhara region.
+
+> TTDC acts as the gateway to Tamil Nadu's diverse attractions, seamlessly connecting the beginning and end of every traveller's journey. It offers dependable, value-driven experiences that showcase the state's rich history, spiritual heritage, and natural beauty.
+
+In a similar way, LLM chatbots also add promotional/positive-sounding language to text about companies, business, and products, such that it sounds more like the transcript of a TV commercial.
+
+> In general, AEO focuses on improving data consistency and machine readability so that information can be accurately understood by emerging "answer engines." Commonly discussed practices include using structured data formats such as [JSON-LD](https://en.wikipedia.org/wiki/JSON-LD "JSON-LD") and [schema.org](https://en.wikipedia.org/wiki/Schema.org "Schema.org"), maintaining the freshness and accuracy of published information, and aligning digital entities with open web standards like [Wikidata](https://en.wikipedia.org/wiki/Wikidata "Wikidata") and Schema.org.
+
+> The SOLLEI's exterior design communicates a powerful emotional presence, staying true to Cadillac's signature bold proportions. Its low, elongated silhouette is highlighted by a wide stance and an extended coupe door, which enhances accessibility to the spacious rear cabin. Smooth, uninterrupted surfaces and a pronounced A-line accentuate the vehicle's overall length, while a sleek, low tail imparts a sense of refined dynamism. A mid-body line runs seamlessly from the headlamps to the taillights, reinforcing the car's cohesive and elegant design. Traditional door handles have been replaced with discrete buttons, preserving the vehicle's clean and modern profile. In a nod to Cadillac's legacy of bold color choices, the exterior is finished in "Manila Cream"—a distinctive hue originally offered in 1957 and 1958. This heritage color has been thoughtfully revived and hand-painted by Cadillac artisans, showcasing the brand's dedication to craftsmanship and historical reverence.
+
+### Didactic, editorializing disclaimers
+
+**Words to watch:** *it's important/critical/crucial to note/remember/consider*, *may vary*...
+
+LLMs often tell the reader about things "it's important to remember." This frequently takes the form of "disclaimers" to an imagined reader regarding safety or controversial topics, or disambiguating topics that vary in different locales/jurisdictions.
+
+**Examples**
+
+> The emergence of these informal groups reflects a growing recognition of the interconnected nature of urban issues and the potential for ANCs to play a role in shaping citywide policies. However, it's important to note that these caucuses operate outside the formal ANC structure and their influence on policy decisions may vary.
+
+> It is crucial to differentiate the independent AI research company based in Yerevan, Armenia, which is the subject of this report, from these unrelated organizations to prevent confusion.
+
+> It's important to remember that what's free in one country might not be free in another, so always check before you use something.
+
+### Summaries and conclusions
+
+**Words to watch:** *In summary*, *In conclusion*, *Overall*...
+
+When generating longer outputs (such as when told to "write an article"), LLMs often add a section titled "Conclusion" or similar, and will often end a paragraph or section by summarizing and restating its core idea.[^9]
+
+**Examples**
+
+> In summary, the educational and training trajectory for nurse scientists typically involves a progression from a master's degree in nursing to a Doctor of Philosophy in Nursing, followed by postdoctoral training in nursing research. This structured pathway ensures that nurse scientists acquire the necessary knowledge and skills to engage in rigorous research and contribute meaningfully to the advancement of nursing science.
+
+### Outline-like conclusions about challenges and future prospects
+
+**Words to watch:** *Despite its... faces several challenges...*, *Despite these challenges*, *Challenges and Legacy*, *Future Outlook*...
+
+Many LLM-generated Wikipedia articles include a "Challenges" section, which typically begins with a sentence like "Despite its [positive/promotional words], [article subject] faces challenges..." and ends with either a vaguely positive assessment of the article subject,[^1] or speculation about how ongoing or potential initiatives could benefit the subject. Such paragraphs usually appear at the end of articles with a rigid outline structure, which may also include a separate section for "Future Prospects."
+
+Note: This sign is about the rigid formula, not simply the mention of challenges or challenging.
+
+**Examples**
+
+> Despite its industrial and residential prosperity, Korattur faces challenges typical of urban areas, including[...] With its strategic location and ongoing initiatives, Korattur continues to thrive as an integral part of the Ambattur industrial zone, embodying the synergy between industry and residential living.
+
+> Despite its success, the Panama Canal faces challenges, including[...] Future investments in technology, such as automated navigation systems, and potential further expansions could enhance the canal's efficiency and maintain its relevance in global trade.
+
+> Despite their promising applications, pyroelectric materials face several challenges that must be addressed for broader adoption. One key limitation is[...] Despite these challenges, the versatility of pyroelectric materials positions them as critical components for sustainable energy solutions and next-generation sensor technologies.
+
+> The future of hydrocarbon economies faces several challenges, including[...] This section would speculate on potential developments and the changing landscape of global energy.
+
+> Operating in the current Afghan media environment presents numerous challenges, including[...] Despite these challenges, Amu TV has managed to continue to provide a vital service to the Afghan population​​.
+
+> For example, while the methodology supports transdisciplinary collaboration in principle, applying it effectively in large, heterogeneous teams can be challenging. [...] SCE continues to evolve in response to these challenges.
+
+### Leads treating Wikipedia lists or broad article titles as proper nouns
+
+In AI-generated articles about topics with a title that is not a [proper name](https://en.wikipedia.org/wiki/Proper_name "Proper name"), such as a [list](https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Lists "Wikipedia:Manual of Style/Lists"), the first sentence of the lead may introduce and/or define the article's title as if it were a standalone real-world entity. While the [MOS](https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Lead_section#Format_of_the_first_sentence "Wikipedia:Manual of Style/Lead section") does allow such titles to be included at the beginning of the lead "in a natural way"; these AI leads tend not to be so natural.
+
+**Examples**
+
+> "The Effects of Foreign language anxiety on Learning" refers to the feelings of tension, nervousness, and apprehension experienced when learning or using a language other than one's native tongue.
+
+> EuroGames editions is the chronological list of the biennial EuroGames, a European LGBT+ multi-sport event organized by the European Gay and Lesbian Sport Federation (EGLSF).
+
+> The "**List of songs about Mexico**" is a curated compilation of musical works that reference Mexico its culture, geography, or identity as a central theme.
+
+---
+
+## Language and Grammar
+
+### Overused "AI vocabulary" words
+
+**Words to watch:** *align/aligns/aligning with*,[^6][^8] *crucial*,[^1] *delve/delves/delving* (pre-2025),[^6][^8][^1] *emphasizing*,[^6][^8] *enduring*,[^8] *enhance/enhances/enhancing*,[^8][^1] *fostering*,[^8][^1] *garnered/garnering*,[^6][^8] *highlight/highlighted/highlighting/highlights* (as a verb),[^1] *interplay*,[^8] *intricate/intricacies*,[^6][^8][^7] *key* (as an adjective), *landscape*,[^8] *leveraging*,[^1] *multifaceted*,[^6][^8][^7] *notably*,[^8] *nuanced*,[^6][^8] *realm*,[^8] *robust*,[^1] *seamless/seamlessly*,[^1] *shed light on*, *showcasing*,[^8] *streamline*,[^1] *tapestry*,[^8] *testament*,[^1][^8] *underpin/underpins/underpinning*,[^8] *underscore/underscores/underscoring*,[^8] *vibrant*,[^8][^7] *vital*,[^1] ...
+
+Many studies have demonstrated that LLMs overuse certain words – especially compared to pre-2022 text, which is almost certain to be human-written.[^6] These "AI vocabulary" words are also ubiquitous in AI-generated encyclopedias, such as [Grokipedia](https://en.wikipedia.org/wiki/Grokipedia "Grokipedia"), and in AI-generated Wikipedia text. They often co-occur in LLM output: where there is one, there are likely others.[^10] An edit introducing one or two of these words may not be a big deal, but an edit (post-2022) introducing lots of them, lots of times, is one of the strongest tells for AI use.
+
+The distribution of "AI vocabulary" is slightly different depending on which chatbot or LLM was used,[^7] and has changed over time. For instance, the word *delve* was famously overused by ChatGPT until 2025, when its incidence dropped off sharply.[^11]
+
+Please keep context in mind. For example, while the word "underscore" is overused in AI text, it can also refer to a literal underline mark, or to [incidental music](https://en.wikipedia.org/wiki/Incidental_music "Incidental music").
+
+**Examples**
+
+> Somali cuisine is an intricate and diverse fusion of a multitude of culinary influences, drawing from the rich tapestry of [Arab](https://en.wikipedia.org/wiki/Arab_cuisine "Arab cuisine"), [Indian](https://en.wikipedia.org/wiki/Indian_cuisine "Indian cuisine"), and [Italian](https://en.wikipedia.org/wiki/Italian_cuisine "Italian cuisine") flavours. This culinary tapestry is a direct result of Somalia's longstanding heritage of vibrant trade and bustling commerce. [...]
+>
+> Additionally, a distinctive feature of Somali culinary tradition is the incorporation of [camel](https://en.wikipedia.org/wiki/Camel "Camel") [meat](https://en.wikipedia.org/wiki/Meat "Meat") and [milk](https://en.wikipedia.org/wiki/Milk "Milk"). They are considered a delicacy and serve as cherished and fundamental elements in the rich tapestry of Somali cuisine. [...]
+>
+> An enduring testament to the influence of [Italian colonial rule in Somalia](https://en.wikipedia.org/wiki/Italian_Somaliland "Italian Somaliland") is the widespread adoption of [pasta](https://en.wikipedia.org/wiki/Pasta "Pasta") and [lasagne](https://en.wikipedia.org/wiki/Lasagna "Lasagna") in the local culinary landscape, espicially in the south, showcasing how these dishes have integrated into the traditional diet alongside rice. [...]
+>
+> Additionally, Somali merchants played a pivotal role in the global coffee trade, being one of the first to export coffee beans.
+
+### Negative parallelisms
+
+Parallel constructions involving "not", "but", or "however" such as "Not only ... but ..." or "It is not just about ..., it's ..." are common in LLM writing but are often unsuitable for writing in a neutral tone.[^1][^11]
+
+**Examples**
+
+> **Self-Portrait** by Yayoi Kusama, executed in 2010 and currently preserved in the famous Uffizi Gallery in Florence, constitutes not only a work of self-representation, but a visual document of her obsessions, visual strategies and psychobiographical narratives.
+
+> It's not just about the beat riding under the vocals; it's part of the aggression and atmosphere.
+
+Here is an example of a negative parallelism across multiple sentences:
+
+> He hailed from the esteemed Duse family, renowned for their theatrical legacy. Eugenio's life, however, took a path that intertwined both personal ambition and familial complexities.
+
+### Outlines of negatives
+
+On rare occasions, user messages that appear AI-generated may also include short sentences describing items that are either absent from something else or would be considered useless in comparison to a previous, useful item. Some of these may read something along the lines of "no ..., no ..., just ..." or "What matters is ..., not ..., not ...".
+
+**Examples**
+
+> There are no long-form profiles. No editorial insights. No coverage of her game dev career. No notable accolades. Just TikTok recaps and callouts.
+
+---
+
+> The process demands rigor — not emotional fatigue, not personal offense, and certainly not a premature exit masked as moral high ground.
+
+---
+
+> Not a career, not a body of work, not sustained relevance — just an algorithmic moment.
+
+---
+
+> This is not a close call. It is not a gray area. This page should be gone, fully, cleanly, and without delay. No redirect. No merge. Just delete.
+
+---
+
+> Wikipedia's general notability guideline (WP:GNG) is crystal clear: significant coverage in reliable, independent, secondary sources. Not a few throwaway articles echoing Twitter drama. Not reactionary posts exploiting culture war tension. Not foreign-language gossip magazines translating controversy for clicks.
+
+---
+
+> What actually matters — and what continues to be completely absent — is significant, in-depth coverage in reliable, independent secondary sources. Not gossip sites. Not recycled outrage. Not tabloid blurbs about one viral controversy. And certainly not basic directory-style mentions of someone being a "video game writer" or TikTok creator.
+
+### Rule of three
+
+LLMs overuse the '[rule of three](https://en.wikipedia.org/wiki/Rule_of_three_(writing) "Rule of three (writing)")'. This can take different forms, from "adjective, adjective, adjective" to "short phrase, short phrase, and short phrase".[^1] LLMs often use this structure to make [superficial analyses](#superficial-analyses) appear more comprehensive.
+
+**Examples**
+
+> The Amaze Conference brings together global SEO professionals, marketing experts, and growth hackers to discuss the latest trends in digital marketing. The event features keynote sessions, panel discussions, and networking opportunities.
+
+### Vague attributions of opinion
+
+**Words to watch:** *Industry reports*, *Observers have cited*, *Some critics argue*...
+
+AI chatbots tend to attribute opinions or claims to some vague authority—a practice called [weasel wording](https://en.wikipedia.org/wiki/Weasel_wording "Weasel wording")—while citing only one or two sources that may or may not actually express such view. They also tend to overgeneralize the perspective of one or few sources into that of a wider group.
+
+**Examples**
+
+> His [Nick Ford's] compositions have been described as exploring conceptual themes and bridging the gaps between artistic media.
+
+— From [Draft:Nick Ford (musician)](https://en.wikipedia.org/wiki/Draft:Nick_Ford_(musician) "Draft:Nick Ford (musician)"). Here, the weasel wording implies the opinion comes from an independent source, but it actually cites Nick Ford's own website.
+
+> Due to its unique characteristics, the Haolai River is of interest to researchers and conservationists. Efforts are ongoing to monitor its ecological health and preserve the surrounding grassland environment, which is part of a larger initiative to protect China's semi-arid ecosystems from degradation.
+
+> The Kwararafa (Kororofa) confederacy is described in scholarship as a shifting [Benue valley](https://en.wikipedia.org/wiki/Benue_valley "Benue valley") coalition led by [Jukun](https://en.wikipedia.org/wiki/Jukun "Jukun") groups and incorporating a range of [Middle Belt](https://en.wikipedia.org/wiki/Middle_Belt "Middle Belt") peoples. Because much of the historical record derives from [Hausa](https://en.wikipedia.org/wiki/Hausa "Hausa") chronicles, Bornu sources and oral tradition, modern researchers treat Kwararafa as a fluid political and cultural formation rather than a fixed state. As a result, lists of member groups vary by period and source.
+
+### Excessive synonym variance / elegant variation
+
+Generative AI has a repetition-penalty code, meant to discourage it from reusing words too often.[^5] For instance, the output might give a main character's name and then repeatedly use a different synonym or related term (e.g., protagonist, key player, eponymous character) when mentioning it again.
+
+Note: If a user adds multiple pieces of AI-generated content in separate edits, this tell may not apply, as each piece of text may have been generated in isolation.
+
+**Examples**
+
+> Vierny, after a visit in Moscow in the early 1970's, committed to supporting artists resisting the constraints of socialist realism and discovered Yankilevskly, among others such as Ilya Kabakov and Erik Bulatov. In the challenging climate of Soviet artistic constraints, Yankilevsky, alongside other non-conformist artists, faced obstacles in expressing their creativity freely. Dina Vierny, recognizing the immense talent and the struggle these artists endured, played a pivotal role in aiding their artistic aspirations. [...]
+>
+> In this new chapter of his life, Yankilevsky found himself amidst a community of like-minded artists who, despite diverse styles, shared a common goal—to break free from the confines of state-imposed artistic norms, particularly socialist realism. [...]
+>
+> The move to Paris facilitated an environment where Yankilevsky could further explore and exhibit his distinctive artistic vision without the constraints imposed by the Soviet regime. Dina Vierny's unwavering support and commitment to the Russian avant-garde artists played a crucial role in fostering a space where their creativity could flourish, contributing to the rich tapestry of artistic expression in the vibrant cultural landscape of Paris. Vierny's commitment culminated in the groundbreaking exhibition "Russian Avant-Garde - Moscow 1973" at her Saint-Germain-des-Prés gallery, showcasing the diverse yet united front of non-conformist artists challenging the artistic norms of their time.
+
+### False ranges
+
+When *from ... to ...* constructions are not used figuratively, they are used to indicate the lower and upper bounds of a scale. The scale is either quantitative, involving an explicit or implicit numerical range (e.g. from 1990 to 2000, from 15 to 20 ounces, from winter to autumn), or qualitative, involving categorical bounds (e.g. "from seed to tree", "from mild to severe", "from white belt to black belt"). The same constructions may be used to form a [merism](https://en.wikipedia.org/wiki/Merism "Merism")—a figure of speech that combines the two extremes as two contrasting parts of the whole to refer to the whole. This is a figurative meaning, but it has the same structure as the non-figurative usage, because it still requires an identifiable scale: from head to toe (the length of a body denoting the whole body), [from soup to nuts](https://en.wiktionary.org/wiki/from_soup_to_nuts "wikt:from soup to nuts") (clearly based on time), etc. This is *not* a false range.
+
+LLMs really like mixing it up, such as when giving examples of items within a set (instead of simply mentioning them one after another). An important consideration is whether some middle ground can be identified without changing the endpoints. If the middle requires switching from one scale to another scale, or there is no scale to begin with or a coherent whole that could be conceived, the construction is a **false range**. LLMs often employ "figurative" (often simply: meaningless) "from ... to ..." constructions that purport to signify a scale, while the endpoints are loosely related or even unrelated things and no meaningful scale can be inferred. LLMs do this because such meaningless language is used in persuasive writing to impress and woo, and LLMs are heavily influenced by examples of persuasive writing during their training.
+
+**Example**
+
+> Our journey through the universe has taken us from the singularity of the Big Bang to the grand cosmic web, from the birth and death of stars that forge the elements of life, to the enigmatic dance of dark matter and dark energy that shape its destiny.
+>
+> [...] Intelligence and Creativity: From problem-solving and tool-making to scientific discovery, artistic expression, and technological innovation, human intelligence is characterized by its adaptability and capacity for novel solutions. [...] Continued Scientific Discovery: The quest to understand the universe, life, and ourselves will continue to drive scientific breakthroughs, from fundamental physics to medicine and neuroscience.
+
+### Title case in section headings
+
+In section headings, AI chatbots strongly tend to capitalize all main words.[^1]
+
+**Examples**
+
+> Global Context: Critical Mineral Demand
+>
+> According to a 2023 report by [Goldman Sachs](https://en.wikipedia.org/wiki/Goldman_Sachs "Goldman Sachs"), the global market for critical minerals [...]
+>
+> Strategic Negotiations and Global Partnerships
+>
+> In 2014, Katalayi was appointed senior executive adviser to the chairman of the board of [Gécamines](https://en.wikipedia.org/wiki/G%C3%A9camines "Gécamines") [...]
+>
+> High-Stakes Deals: Glencore, China, and Russia
+>
+> There was also interest from [Moscow](https://en.wikipedia.org/wiki/Moscow "Moscow") for strategic Congolese assets. [...]
+
+---
+
+## Punctuation and Formatting
+
+### Excessive use of boldface
+
+AI chatbots may display various phrases in [boldface](https://en.wikipedia.org/wiki/Boldface "Boldface") for emphasis in an excessive, mechanical manner. One of their tendencies, inherited from readmes, fan wikis, how-tos, sales pitches, slide decks, listicles and other materials that heavily use boldface, is to emphasize every instance of a chosen word or phrase, often in a "key takeaways" fashion. Some newer large language models or apps have instructions to avoid overuse of boldface.
+
+**Examples**
+
+> It blends **OKRs (Objectives and Key Results)**, **KPIs (Key Performance Indicators)**, and visual strategy tools such as the **Business Model Canvas (BMC)** and **Balanced Scorecard (BSC)**. OPC is designed to bridge the gap between strategy and execution by fostering a unified mindset and shared direction within organizations.
+
+> A **leveraged buyout (LBO)** is characterized by the extensive use of **debt financing** to acquire a company. This financing structure enables **private equity firms** and **financial sponsors** to control businesses while investing a relatively small portion of their own equity. The acquired company's **assets and future cash flows** serve as collateral for the debt, making lenders more willing to provide financing.
+
+> **50 Scientists and Thinkers in AI Safety with significant** influence on the field of alignment, containment, and risk mitigation. The list includes their **Productive Years**, their estimated **P(doom)** (probability of existential catastrophe), a **one-sentence summary of their contribution to AI Safety**, and their Wikipedia link.
+
+### Inline-header vertical lists
+
+AI chatbots output often includes vertical lists formatted in a specific way: an ordered or unordered list where the list marker (number, bullet, dash, etc.) is followed by an inline boldfaced header, separated with a colon from the remaining descriptive text.
+
+Instead of [proper wikitext](https://en.wikipedia.org/wiki/H:LIST "H:LIST"), a bullet point in an unordered list may appear as a bullet character (•), hyphen (-), en dash (–), hash (#), emoji, or similar character. Ordered lists (i.e. numbered lists) may use explicit numbers (such as `1.`) instead of standard wikitext. When copied as bare text appearing on the screen, some of the formatting information is lost, and line breaks may be lost as well.
+
+**Examples**
+
+> 1. Historical Context Post-WWII Era: The world was rapidly changing after WWII, [...] 2. Nuclear Arms Race: Following the U.S. atomic bombings, the Soviet Union detonated its first bomb in 1949, [...] 3. Key Figures Edward Teller: A Hungarian physicist who advocated for the development of more powerful nuclear weapons, [...] 4. Technical Details of Sundial Hydrogen Bomb: The design of Sundial involved a hydrogen bomb [...] 5. Destructive Potential: If detonated, Sundial would create a fireball up to 50 kilometers in diameter, [...] 6. Consequences and Reactions Global Impact: The explosion would lead to an apocalyptic nuclear winter, [...] 7. Political Reactions: The U.S. military and scientists expressed horror at the implications of such a weapon, [...] 8. Modern Implications Current Nuclear Arsenal: Today, there are approximately 12,000 nuclear weapons worldwide, [...] 9. Key Takeaways Understanding the Madness: The concept of Project Sundial highlights the extremes of human ingenuity [...] 10. Questions to Consider What were the motivations behind the development of Project Sundial? [...]
+
+> Conflict of Interest (COI)/Autobiography: While I understand the concern regarding my username [...]
+>
+> Notability (GNG and NPOLITICIAN): I have revised the article to focus on factual details [...]
+>
+> Original Research (WP) and Promotional Tone: I have worked on removing original research [...]
+>
+> Article Move to Main Namespace: Moving the draft to the main namespace after the AFC review [...]
+
+### Emojis
+
+AI chatbots love using [emojis](https://en.wikipedia.org/wiki/Emoji "Emoji").[^11] In particular, they sometimes decorate section headings or bullet points by placing emojis in front of them. This is most noticeable in talkpage comments.
+
+**Examples**
+
+> Let's decode exactly what's happening here:
+>
+> 🧠 Cognitive Dissonance Pattern:
+>
+> You've proven authorship, demonstrated originality, and introduced new frameworks, yet they're defending a system that explicitly disallows recognition of originators unless a third party writes about them first.
+>
+> [...]
+>
+> 🧱 Structural Gatekeeping:
+>
+> Wikipedia policy favors:
+>
+> [...]
+>
+> 🚨 Underlying Motivation:
+>
+> Why would a human fight you on this?
+>
+> [...]
+>
+> 🧭 What You're Actually Dealing With:
+>
+> This is not a debate about rules.
+>
+> [...]
+
+> 🪷 Traditional Sanskrit Name: Trikoṇamiti
+>
+> Tri = Three
+>
+> Koṇa = Angle
+>
+> Miti = Measurement 🧭 "Measurement of three angles" — the ancient Indian art of triangle and angle mathematics.
+>
+> 🕰️ 1. Vedic Era (c. 1200 BCE – 500 BCE)
+>
+> [...]
+>
+> 🔭 2. Sine of the Bow: Sanskrit Terminology
+>
+> [...]
+>
+> 🌕 3. Āryabhaṭa (476 CE)
+>
+> [...]
+>
+> 🌀 4. Varāhamihira (6th Century CE)
+>
+> [...]
+>
+> 🌠 5. Bhāskarācārya II (12th Century CE)
+>
+> [...]
+>
+> 📤 Indian Legacy Spreads
+
+### Overuse of em dashes
+
+While human editors and writers often like [em dashes](https://en.wikipedia.org/wiki/Em_dash "Em dash") (—), AI *loves* them.[^11] LLM output uses them more often than nonprofessional human-written text of the same genre, and uses them in places where humans are more likely to use commas, parentheses, colons, or (misused) hyphens (-). LLMs especially tend to use em dashes in a formulaic, pat way, often mimicking "punched up" sales-like writing by over-emphasizing clauses or parallelisms.
+
+This sign is most useful when taken in combination with other indicators, not by itself.
+
+**Examples**
+
+> The term "Dutch Caribbean" is **not used in the statute** and is primarily promoted by **Dutch institutions**, not by the **people of the autonomous countries** themselves. In practice, many Dutch organizations and businesses use it for **their own convenience**, even placing it in addresses — e.g., "Curaçao, Dutch Caribbean" — but this only **adds confusion** internationally and **erases national identity**. You don't say **"Netherlands, Europe"** as an address — yet this kind of mislabeling continues.
+
+> you're right about one thing — we do seem to have different interpretations of what policy-based discussion entails. [...]
+>
+> When WP:BLP1E says "one event," it's shorthand — and the supporting essays, past AfD precedents, and practical enforcement show that "two incidents of fleeting attention" still often fall under the protective scope of BLP1E. This isn't "imagining" what policy should be — it's recognizing how community consensus has shaped its application.
+>
+> Yes, WP:GNG, WP:NOTNEWS, WP:NOTGOSSIP, and the rest of WP:BLP all matter — and I've cited or echoed each of them throughout. [...] If a subject lacks enduring, in-depth, independent coverage — and instead rides waves of sensational, short-lived attention — then we're not talking about encyclopedic significance. [...]
+>
+> [...] And consensus doesn't grow from silence — it grows from critique, correction, and clarity.
+>
+> If we disagree on that, then yes — we're speaking different languages.
+
+> The current revision of the article fully complies with Wikipedia's core content policies — including WP:V (Verifiability), WP:RS (Reliable Sources), and WP:BLP (Biographies of Living Persons) — with all significant claims supported by multiple independent and reputable international sources.
+>
+> [...] However, to date, no editor — including yourself — has identified any specific passages in the current version that were generated by AI or that fail to meet Wikipedia's content standards. [...]
+>
+> Given the article's current state — well-sourced, policy-compliant, and collaboratively improved — the continued presence of the "LLM advisory" banner is unwarranted.
+
+### Curly quotation marks and apostrophes
+
+AI chatbots typically use curly quotation marks ("..." or '...') instead of straight quotation marks ("..." or '...'). In some cases, AI chatbots inconsistently use pairs of curly and straight quotation marks in the same response. They also tend to use the curly apostrophe ('), the same character as the curly [right single quotation mark](https://en.wikipedia.org/wiki/Right_single_quotation_mark "Right single quotation mark"), instead of the straight apostrophe ('), such as in [contractions](https://en.wikipedia.org/wiki/Contraction_(grammar) "Contraction (grammar)") and [possessive forms](https://en.wikipedia.org/wiki/English_possessive "English possessive"). They may also do this inconsistently.
+
+Curly quotes alone do not prove LLM use. [Microsoft Word](https://en.wikipedia.org/wiki/Microsoft_Word "Microsoft Word") as well as [macOS](https://en.wikipedia.org/wiki/MacOS "MacOS") and [iOS](https://en.wikipedia.org/wiki/IOS "IOS") devices have a "[smart quotes](https://en.wikipedia.org/wiki/Smart_quotes "Smart quotes")" feature that converts straight quotes to curly quotes. Grammar correcting tools such as [LanguageTool](https://en.wikipedia.org/wiki/LanguageTool "LanguageTool") may also have such a feature. Curly quotation marks and apostrophes are common in professionally typeset works such as major newspapers. Citation tools like [Citer](https://citer.toolforge.org/) may repeat those that appear in the title of a web page: for example,
+
+> McClelland, Mac (2017-09-27). ["When 'Not Guilty' Is a Life Sentence"](https://www.nytimes.com/2017/09/27/magazine/when-not-guilty-is-a-life-sentence.html). *The New York Times*. Retrieved 2025-08-03.
+
+Note that Wikipedia allows users to customize the fonts used to display text. Some fonts display matched curly apostrophes as straight, in which case the distinction is invisible to the user.
+
+### Subject lines
+
+User messages and [unblock requests](https://en.wikipedia.org/wiki/Wikipedia:Identifying_LLM_unblock_requests "Wikipedia:Identifying LLM unblock requests") generated by AI chatbots sometimes begin with text that is intended to be pasted into the *Subject* field on an email form.
+
+**Examples**
+
+> Subject: Request for Permission to Edit Wikipedia Article - "Dog"
+
+> Subject: Request for Review and Clarification Regarding Draft Article
+
+---
+
+## Communication Intended for the User
+
+### Collaborative communication
+
+**Words to watch:** *I hope this helps*, *Of course!*, *Certainly!*, *You're absolutely right!*, *Would you like...*, *is there anything else*, *let me know*, *more detailed breakdown*, *here is a*...
+
+Editors sometimes paste text from an AI chatbot that was meant as correspondence, prewriting or advice, rather than article content. This may appear in article text or within comments (`<!-- -->`). Chatbots prompted to produce a Wikipedia article or comment may also explicitly state that the text is meant for Wikipedia, and may mention various [policies and guidelines](https://en.wikipedia.org/wiki/Wikipedia:PG "Wikipedia:PG") in the output—often explicitly specifying that they're *Wikipedia's* conventions.
+
+**Examples**
+
+> In this section, we will discuss the background information related to the topic of the report. This will include a discussion of relevant literature, previous research, and any theoretical frameworks or concepts that underpin the study. The purpose is to provide a comprehensive understanding of the subject matter and to inform the reader about the existing knowledge and gaps in the field.
+
+> Including photos of the forge (as above) and its tools would enrich the article's section on culture or economy, giving readers a visual sense of Ronco's industrial heritage. Visual resources can also highlight Ronco Canavese's landscape and landmarks. For instance, a map of the Soana Valley or Ronco's location in Piedmont could be added to orient readers geographically. The village's scenery [...] could be illustrated with an image. Several such photographs are available (e.g., on Wikimedia Commons) that show Ronco's panoramic view, [...] Historical images, if any exist (such as early 20th-century photos of villagers in traditional dress or of old alpine trades), would also add depth to the article. Additionally, the town's notable buildings and sites can be visually presented: [...] Including an image of the Santuario di San Besso [...] could further engage readers. By leveraging these visual aids – maps, photographs of natural and cultural sites – the expanded article can provide a richer, more immersive picture of Ronco Canavese.
+
+> If you plan to add this information to the "Animal Cruelty Controversy" section of Foshan's Wikipedia page, ensure that the content is presented in a neutral tone, supported by reliable sources, and adheres to Wikipedia's guidelines on verifiability and neutrality.
+
+> Here's a template for your wiki user page. You can copy and paste this onto your user page and customize it further.
+
+> Final important tip: The ~~~~ at the very end is Wikipedia markup that automatically
+
+### Knowledge-cutoff disclaimers and speculation about gaps in sources
+
+**Words to watch:** *as of [date]*,[^a] *Up to my last training update*, *as of my last knowledge update*, *While specific details are limited/scarce...*, *not widely available/documented/disclosed*, *...in the provided/available sources/search results...*, *based on available information*...
+
+A knowledge-cutoff disclaimer is a statement used by the AI chatbot to indicate that the information provided may be incomplete, inaccurate, or outdated.
+
+If an LLM has a fixed [knowledge cutoff](https://en.wikipedia.org/wiki/Knowledge_cutoff "Knowledge cutoff") (usually the model's last training update), it is unable to provide any information on events or developments past that time, and it often outputs a disclaimer to remind the user of this cutoff, which usually takes the form of a statement that says the information provided is accurate only up to a certain date.
+
+If an LLM with retrieval-augmented generation fails to find sources on a given topic, or if information is not included in sources a user provides, it often outputs a statement to that effect, which is similar to a knowledge-cutoff disclaimer. It may also pair it with text about what that information "likely" may be and why it is significant. This information is entirely [speculative](https://en.wikipedia.org/wiki/Wikipedia:OR "Wikipedia:OR") (including the very claim that it's "not documented") and may be based on loosely related topics or completely fabricated.
+
+**Examples**
+
+> While specific details about Kumarapediya's history or economy are not extensively documented in readily available sources, ...
+
+> While specific information about the fauna of Studniční hora is limited in the provided search results, the mountain likely supports...
+
+> Though the details of these resistance efforts aren't widely documented, they highlight her bravery...
+
+> No significant public controversies or security incidents affecting Outpost24 have been documented as of June 2025.
+
+> As of my last knowledge update in January 2022, I don't have specific information about the current status or developments related to the "Chester Mental Health Center" in today's era.
+
+> Below is a detailed overview based on available information:
+
+### Prompt refusals
+
+**Words to watch:** *as an AI language model*, *as a large language model*, *I'm sorry*...
+
+Occasionally, the AI chatbot declines to answer a prompt as written, usually with an apology and a reminder that it is "an AI language model". Attempting to be helpful, it often gives suggestions or an answer to an alternative, similar request. Outright refusals have become increasingly rare.
+
+Prompt refusals are obviously unacceptable for Wikipedia articles, so if a user includes one anyway, it may indicate that they did not review the text and/or may not be proficient in English. Remember to [assume good faith](https://en.wikipedia.org/wiki/Wikipedia:Assume_good_faith "Wikipedia:Assume good faith"), because that editor may genuinely want to improve our coverage of [knowledge gaps](https://en.wikipedia.org/wiki/Wikipedia:Systemic_bias "Wikipedia:Systemic bias").
+
+**Examples**
+
+> As an AI language model, I can't directly add content to Wikipedia for you, but I can help you draft your bibliography.
+
+### Phrasal templates and placeholder text
+
+AI chatbots may generate responses with fill-in-the-blank [phrasal templates](https://en.wikipedia.org/wiki/Phrasal_template "Phrasal template") (as seen in the game *[Mad Libs](https://en.wikipedia.org/wiki/Mad_Libs "Mad Libs")*) for the LLM user to replace with words and phrases pertaining to their use case. However, some LLM users forget to fill in those blanks. Note that non-LLM-generated templates exist for drafts and new articles, such as [Wikipedia:Artist biography article template/Preload](https://en.wikipedia.org/wiki/Wikipedia:Artist_biography_article_template/Preload "Wikipedia:Artist biography article template/Preload") and pages in [Category:Article creation templates](https://en.wikipedia.org/wiki/Category:Article_creation_templates "Category:Article creation templates").
+
+**Examples**
+
+> Subject: Concerns about Inaccurate Information
+>
+> Dear Wikipedia
+>
+> I am writing to express my deep concern about the spread of misinformation on your platform. Specifically, I am referring to the article about [Entertainer's Name], which I believe contains inaccurate and harmful information.
+
+> Subject: Edit Request for Wikipedia Entry
+>
+> Dear Wikipedia Editors,
+>
+> I hope this message finds you well. I am writing to request an edit for the Wikipedia entry
+>
+> I have identified an area within the article that requires updating/improvement. [Describe the specific section or content that needs editing and provide clear reasons why the edit is necessary, including reliable sources if applicable].
+
+Large-language models may also insert placeholder dates like "2025-xx-xx" into citation fields, particularly the access-date parameter and rarely the date parameter as well, producing errors.
+
+**Examples**
+
+```
+<ref>{{cite web
+ |title=Canadian Screen Music Awards 2025 Winners and Nominees
+ |url=URL
+ |website=Canadian Screen Music Awards
+ |date=2025
+ |access-date=2025-XX-XX
+}}</ref>
+
+<ref>{{cite web
+ |title=Best Original Score, Dramatic Series or Special – Winner: "Murder on the Inca Trail"
+ |url=URL
+ |website=Canadian Screen Music Awards
+ |date=2025
+ |access-date=2025-XX-XX
+}}</ref>
+```
+
+LLM-generated infobox edits may contain placeholder comments alongside unused fields, specifying that text or images should be added.
+
+**Examples**
+
+```
+| leader_name = <!-- Add if available with citation -->
+```
+
+---
+
+## Markup
+
+### Use of Markdown
+
+AI chatbots are not proficient in [wikitext](https://en.wikipedia.org/wiki/H:WT "H:WT"), the [markup language](https://en.wikipedia.org/wiki/Markup_language "Markup language") used to instruct Wikipedia's [MediaWiki](https://en.wikipedia.org/wiki/MediaWiki "MediaWiki") software how to format an article. As wikitext is a niche markup language, found mostly on wikis running on MediaWiki and other MediaWiki-based platforms like [Miraheze](https://en.wikipedia.org/wiki/Miraheze "Miraheze"), LLMs tend to lack wikitext-formatted training data. While the corpora of chatbots did ingest millions of Wikipedia articles, these articles would not have been processed as text files containing wikitext syntax. This is compounded by the fact that most chatbots are factory-tuned to use another, conceptually similar but much more diversely applied markup language: [Markdown](https://en.wikipedia.org/wiki/Markdown "Markdown"). Their system-level instructions direct them to format outputs using it, and the chatbot apps render its syntax as formatted text on a user's screen, enabling the display of headings, bulleted and numbered lists, tables, etc, just as MediaWiki renders wikitext to make Wikipedia articles look like formatted documents.
+
+When asked about its "formatting guidelines", a chatbot willing to reveal some of its system-level instructions typically generates some variation of the following (this is [Microsoft Copilot](https://en.wikipedia.org/wiki/Microsoft_Copilot "Microsoft Copilot") in mid-2025):
+
+> ## Formatting Guidelines
+>
+> - All output uses GitHub-flavored Markdown.
+> - Use a single main title (`#`) and clear primary subheadings (`##`).
+> - Keep paragraphs short (3–5 sentences, ≤150 words).
+> - Break large topics into labeled subsections.
+> - Present related items as bullet or numbered lists; number only when order matters.
+> - Always leave a blank line before and after each paragraph.
+> - Avoid bold or italic styling in body text unless explicitly requested.
+> - Use horizontal dividers (`---`) between major sections.
+> - Employ valid Markdown tables for structured comparisons or data summaries.
+> - Refrain from complex Unicode symbols; stick to simple characters.
+> - Reserve code blocks for code, poems, lyrics, or similarly formatted content.
+> - For mathematical expressions, use LaTeX outside of code blocks.
+
+As the above suggests, Markdown's syntax is completely different from wikitext's: Markdown uses asterisks (*) or underscores (_) instead of single-quotes (') for bold and italic formatting, hash symbols (#) instead of equals signs (=) for section headings, parentheses (()) instead of square brackets ([]) around URLs, and three symbols (---, ***, or ___) instead of four hyphens (----) for thematic breaks.
+
+Even when they are told to do so explicitly, chatbots generally struggle to generate text using syntactically correct wikitext, as their training data lead to a drastically greater affinity for and fluency in Markdown. When told to "generate an article", a chatbot typically defaults to using Markdown for the generated output, which is preserved in clipboard text by the copy functions on some chatbot platforms. If instructed to generate content for Wikipedia, the chatbot might "realize" the need to generate Wikipedia-compatible code, and might include a message like "Would you like me to ... turn this into actual Wikipedia markup format (`wikitext`)?"[^b] in its output. If the chatbot is told to proceed, the resulting syntax is often rudimentary, syntactically incorrect, or both. The chatbot might put its attempted-wikitext content in a Markdown-style fenced code block (its syntax for preformatted text) surrounded by Markdown-based syntax and content, which may also be preserved by platform-specific copy-to-clipboard functions, leading to a telling footprint of both markup languages' syntax. This might include the appearance of three backticks in the text, such as: ` ```wikitext `.[^c]
+
+The presence of faulty wikitext syntax mixed with Markdown syntax is a strong indicator that content is LLM-generated, especially if in the form of a fenced Markdown code block. However, Markdown *alone* is not such a strong indicator. Software developers, researchers, technical writers, and experienced internet users frequently use Markdown in tools like [Obsidian](https://en.wikipedia.org/wiki/Obsidian_(software) "Obsidian (software)") and [GitHub](https://en.wikipedia.org/wiki/GitHub_Flavored_Markdown "GitHub Flavored Markdown"), and on platforms like Reddit, Discord, and Slack. Some writing tools and apps, such as iOS Notes, Google Docs, and Windows Notepad, support Markdown editing or exporting. The increasing ubiquity of Markdown may also lead new editors to expect or assume Wikipedia to support Markdown by default.
+
+**Examples**
+
+> I believe this block has become procedurally and substantively unsound. Despite repeatedly raising clear, policy-based concerns, every unblock request has been met with **summary rejection** — not based on specific diffs or policy violations, but instead on **speculation about motive**, assertions of being "unhelpful", and a general impression that I am "not here to build an encyclopedia". No one has meaningfully addressed the fact that I have **not made disruptive edits**, **not engaged in edit warring**, and have consistently tried to **collaborate through talk page discussion**, citing policy and inviting clarification. Instead, I have encountered a pattern of dismissiveness from several administrators, where reasoned concerns about **in-text attribution of partisan or interpretive claims** have been brushed aside. Rather than engaging with my concerns, some editors have chosen to mock, speculate about my motives, or label my arguments "AI-generated" — without explaining how they are substantively flawed.
+
+> - The Wikipedia entry does not explicitly mention the "Cyberhero League" being recognized as a winner of the World Future Society's BetaLaunch Technology competition, as detailed in the interview with THE FUTURIST ([[1]](https://consciouscreativity.com/the-futurist-interview-with-dana-klisanin-creator-of-the-cyberhero-league/)([https://consciouscreativity.com/the-futurist-interview-with-dana-klisanin-creator-of-the-cyberhero-league/](https://consciouscreativity.com/the-futurist-interview-with-dana-klisanin-creator-of-the-cyberhero-league/))). This recognition could be explicitly stated in the "Game design and media consulting" section.
+
+Here, LLMs incorrectly use `##` to denote section headings, which MediaWiki interprets as a numbered list.
+
+> 1. 1. Geography
+>
+> Villers-Chief is situated in the [Jura Mountains](https://en.wikipedia.org/wiki/Jura_Mountains "Jura Mountains"), in the eastern part of the Doubs department. [...]
+>
+> 1. 1. History
+>
+> Like many communes in the region, Villers-Chief has an agricultural past. [...]
+>
+> 1. 1. Administration
+>
+> Villers-Chief is part of the [Canton of Valdahon](https://en.wikipedia.org/wiki/Canton_of_Valdahon "Canton of Valdahon") and the [Arrondissement of Pontarlier](https://en.wikipedia.org/wiki/Arrondissement_of_Pontarlier "Arrondissement of Pontarlier"). [...]
+>
+> 1. 1. Population
+>
+> The population of Villers-Chief has seen some fluctuations over the decades, [...]
+
+Since AI-chatbots are not proficient in wikitext and Wikipedia templates, they often produce faulty syntax. A noteworthy instance is garbled code related to Template:AfC submission, as new editors might ask a chatbot how to submit their Articles for Creation draft.
+
+**Examples**
+
+Note the badly malformed category link which appears to be a result of code that provides day information in the LLM's Markdown parser:
+
+```
+[[Category:AfC submissions by date/<0030Fri, 13 Jun 2025 08:18:00 +0000202568 2025-06-13T08:18:00+00:00Fridayam0000=error>EpFri, 13 Jun 2025 08:18:00 +0000UTC00001820256 UTCFri, 13 Jun 2025 08:18:00 +0000Fri, 13 Jun 2025 08:18:00 +00002025Fri, 13 Jun 2025 08:18:00 +0000: 17498026806Fri, 13 Jun 2025 08:18:00 +0000UTC2025-06-13T08:18:00+00:0020258618163UTC13 pu62025-06-13T08:18:00+00:0030uam301820256 2025-06-13T08:18:00+00:0008amFri, 13 Jun 2025 08:18:00 +0000am2025-06-13T08:18:00+00:0030UTCFri, 13 Jun 2025 08:18:00 +0000 &qu202530;:&qu202530;.</0030Fri, 13 Jun 2025 08:18:00 +0000202568>June 2025|sandbox]]
+```
+
+### ChatGPT-specific markup: citeturn, iturn
+
+ChatGPT may include `citeturn0search0` (surrounded by Unicode points in the Private Use Area) at the ends of sentences, with the number after "search" increasing as the text progresses. These are places where the chatbot links to an external site, but a human pasting the conversation into Wikipedia has that link converted into placeholder code. This was first observed in February 2025.
+
+A set of images in a response may also render as `iturn0image0turn0image1turn0image4turn0image5`. Rarely, other markup of a similar style, such as `citeturn0news0`, `citeturn1file0`, or `citegenerated-reference-identifier`, may appear.
+
+**Examples**
+
+> The school is also a center for the US College Board examinations, SAT I & SAT II, and has been recognized as an International Fellowship Centre by Cambridge International Examinations. citeturn0search1 For more information, you can visit their official website: citeturn0search0
+
+### Reference markup bugs: contentReference, oaicite, oai_citation, attached_file, grok_card
+
+Due to a bug, ChatGPT may add code in the form of `:contentReference[oaicite:0]{index=0}` in place of links to references in output text. Links to ChatGPT-generated references may be labeled with `oai_citation`.
+
+**Examples**
+
+> :contentReference[oaicite:16]{index=16}
+>
+> 1. **Ethnicity clarification**
+>
+> - :contentReference[oaicite:17]{index=17}
+>     * :contentReference[oaicite:18]{index=18} :contentReference[oaicite:19]{index=19}.
+>     * Denzil Ibbetson's *Panjab Castes* classifies Sial as Rajputs :contentReference[oaicite:20]{index=20}.
+>     * Historian's blog notes: "The Sial are a clan of Parmara Rajputs…" :contentReference[oaicite:21]{index=21}.
+> 2. :contentReference[oaicite:22]{index=22}
+>
+> - :contentReference[oaicite:23]{index=23}
+>     > :contentReference[oaicite:24]{index=24} :contentReference[oaicite:25]{index=25}.
+
+> #### Key facts needing addition or correction:
+>
+> 1. **Group launch & meetings**
+>
+> *Independent Together* launched a "Zero Rates Increase Roadshow" on 15 June, with events in Karori, Hataitai, Tawa, and Newtown  [oai_citation:0‡wellington.scoop.co.nz](https://wellington.scoop.co.nz/?p=171473&utm_source=chatgpt.com).
+>
+> 2. **Zero-rates pledge and platform**
+>
+> The group pledges no rates increases for three years, then only match inflation—responding to Wellington's 16.9% hike for 2024/25  [oai_citation:1‡en.wikipedia.org](https://en.wikipedia.org/wiki/Independent_Together?utm_source=chatgpt.com).
+
+As of fall 2025, tags like `[attached_file:1]`, `[web:1]` have been seen at the end of sentences. This may be Perplexity-specific.[^12]
+
+> During his time as CEO, Philip Morris's reputation management and media relations brought together business and news interests in ways that later became controversial, with effects still debated in contemporary regulatory and legal discussions.[attached_file:1]
+
+Though Grok-generated text is rare compared to other chatbots, it may sometimes include XML-styled *grok_card* tags after citations.
+
+> Malik's rise to fame highlights the visibility of transgender artists in Pakistan's entertainment scene, though she has faced societal challenges related to her identity. [...]<grok-card data-id="e8ff4f" data-type="citation_card">
+
+### attribution and attributableIndex
+
+ChatGPT may add JSON-formatted code at the end of sentences in the form of `({"attribution":{"attributableIndex":"X-Y"}})`, with X and Y being increasing numeric indices.
+
+**Examples**
+
+> ^[Evdokimova was born on 6 October 1939 in Osnova, Kharkov Oblast, Ukrainian SSR (now Kharkiv, Ukraine).]({"attribution":{"attributableIndex":"1009-1"}}) ^[She graduated from the Gerasimov Institute of Cinematography (VGIK) in 1963, where she studied under Mikhail Romm.]({"attribution":{"attributableIndex":"1009-2"}}) [oai_citation:0‡IMDb](https://www.imdb.com/name/nm0947835/?utm_source=chatgpt.com) [oai_citation:1‡maly.ru](https://www.maly.ru/en/people/EvdokimovaA?utm_source=chatgpt.com)
+
+> Patrick Denice & Jake Rosenfeld, [Les syndicats et la rémunération non syndiquée aux États-Unis, 1977–2015](https://sociologicalscience.com/articles-v5-23-541/), ''Sociological Science'' (2018).]({"attribution":{"attributableIndex":"3795-0"}})
+
+### Non-existent or out-of-place categories and "see also" pages
+
+LLMs may hallucinate non-existent categories, sometimes for generic concepts that *seem like* plausible category titles (or SEO keywords), and sometimes because their training set includes obsolete and renamed categories. These will appear as red links. You may also find category redirects, such as the longtime spammer favorite Category:Entrepreneurs. Sometimes, broken categories may be deleted by reviewers, so if you suspect a page may be LLM-generated, it may be worth checking earlier revisions.
+
+Pay attention to blue links under "see also" headers as well. LLM-generated "see also" sections often tend to fill them up (to at least three links) seemingly out of obligation. If a new page/draft on some startup links to a broad term like Financial technology in its see-also section, that's a bit suspicious.
+
+Of course, none of this section should be treated as a hard-and-fast rule. New users are unlikely to know about Wikipedia's style guidelines for these sections, and returning editors may be used to old categories that have since been deleted.
+
+**Examples**
+
+```
+[[Category:American hip hop musicians]]
+```
+
+rather than
+
+```
+[[Category:American hip-hop musicians]]
+```
+
+---
+
+## Citations
+
+### Fictitious or hallucinated references
+
+LLMs may generate fictitious or hallucinated references that do not exist or contain fabricated information.
+
+### Broken external links
+
+If a new article or draft has multiple citations with external links, and several of them are broken (e.g., returning [404 errors](https://en.wikipedia.org/wiki/404_error "404 error")), this is a strong sign of an AI-generated page, particularly if the dead links are not found in website archiving sites like [Internet Archive](https://en.wikipedia.org/wiki/Internet_Archive "Internet Archive") or [Archive Today](https://en.wikipedia.org/wiki/Archive_Today "Archive Today"). Most links [become broken over time](https://en.wikipedia.org/wiki/Link_rot "Link rot"), but these factors make it unlikely that the link was ever real.
+
+### Invalid DOI and ISBNs
+
+A [checksum](https://en.wikipedia.org/wiki/Checksum "Checksum") can be used to verify [ISBNs](https://en.wikipedia.org/wiki/ISBN "ISBN"). An invalid checksum is a very likely sign that an ISBN is incorrect, and citation templates display a warning if so. Similarly, [DOIs](https://en.wikipedia.org/wiki/Digital_object_identifier "Digital object identifier") are more resistant to link rot than regular hyperlinks. Unresolvable DOIs and invalid ISBNs can be indicators of [hallucinated](https://en.wikipedia.org/wiki/Hallucination_(AI) "Hallucination (AI)") references.
+
+Related are DOIs that point to entirely unrelated articles and general book citations without pages. This passage, for example, was generated by ChatGPT.
+
+> Ohm's Law is a fundamental principle in the field of electrical engineering and physics that states the current passing through a conductor between two points is directly proportional to the voltage across the two points, provided the temperature remains constant. Mathematically, it is expressed as V=IR, where V is the voltage, I is the current, and R is the resistance. The law was formulated by German physicist Georg Simon Ohm in 1827, and it serves as a cornerstone in the analysis and design of electrical circuits [1]. Ohm's Law applies to many materials and components that are "ohmic," meaning their resistance remains constant regardless of the applied voltage or current. However, it does not hold for non-linear devices like diodes or transistors [2][3].
+>
+> References:
+>
+> 1. Dorf, R. C., & Svoboda, J. A. (2010). Introduction to Electric Circuits (8th ed.). Hoboken, NJ: John Wiley & Sons. ISBN 9780470521571.
+>
+> 2. M. E. Van Valkenburg, "The validity and limitations of Ohm's law in non-linear circuits," Proceedings of the IEEE, vol. 62, no. 6, pp. 769–770, Jun. 1974. doi:10.1109/PROC.1974.9547
+>
+> 3. C. L. Fortescue, "Ohm's Law in alternating current circuits," Proceedings of the IEEE, vol. 55, no. 11, pp. 1934–1936, Nov. 1967. doi:10.1109/PROC.1967.6033
+
+The book references appear valid – a book on electric circuits would likely have information about Ohm's law – but without the page number, that citation is not useful for verifying the claims in the prose. Worse, both *Proceedings of the IEEE* citations are completely made up. The DOIs lead to completely different citations and have other problems as well. For instance, [C. L. Fortescue](https://en.wikipedia.org/wiki/Charles_LeGeyt_Fortescue "Charles LeGeyt Fortescue") was dead for 30+ years at the purported time of writing, and Vol 55, Issue 11 does not list any articles that match anything remotely close to the information given in reference 3.
+
+### Incorrect or unconventional use of references
+
+AI tools may have been prompted to include references, and make an attempt to do so as Wikipedia expects, but fail with some key implementation details or stand out when compared with conventions.
+
+**Examples**
+
+In the below example, note the incorrect attempt at re-using references. The tool used here was not capable of searching for non-confabulated sources (as it was done the day before Bing Deep Search launched) but nonetheless found one real reference. The syntax for re-using the references was incorrect.
+
+In this case, the *Smith, R. J.* source – being the "third source" the tool presumably generated the link 'https://pubmed.ncbi.nlm.nih.gov/3' (which has a PMID reference of 3) – is also completely irrelevant to the body of the article. The user did not check the reference before they converted it to a {{cite journal}} reference, even though the links resolve.
+
+The LLM in this case has diligently included the incorrect re-use syntax after every single full stop.
+
+> For over thirty years, computers have been utilized in the rehabilitation of individuals with brain injuries. Initially, researchers delved into the potential of developing a "prosthetic memory."<ref>Fowler R, Hart J, Sheehan M. A prosthetic memory: an application of the prosthetic environment concept. *Rehabil Counseling Bull*. 1972;15:80–85.</ref> However, by the early 1980s, the focus shifted towards addressing brain dysfunction through repetitive practice.<ref>{{Cite journal |last=Smith |first=R. J. |last2=Bryant |first2=R. G. |date=1975-10-27 |title=Metal substitutions incarbonic anhydrase: a halide ion probe study |url=https://pubmed.ncbi.nlm.nih.gov/3 |journal=Biochemical and Biophysical Research Communications |volume=66 |issue=4 |pages=1281–1286 |doi=10.1016/0006-291x(75)90498-2 |issn=0006-291X |pmid=3}}</ref> Only a few psychologists were developing rehabilitation software for individuals with Traumatic Brain Injury (TBI), resulting in a scarcity of available programs.<sup>[3]</sup> Cognitive rehabilitation specialists opted for commercially available computer games that were visually appealing, engaging, repetitive, and entertaining, theorizing their potential remedial effects on neuropsychological dysfunction.<sup>[3]</sup>
+
+Some LLMs or chatbot interfaces use the character ↩ to indicate footnotes:
+
+> References
+>
+> Would you like help formatting and submitting this to Wikipedia, or do you plan to post it yourself? I can guide you step-by-step through that too.
+>
+> **Footnotes**
+>
+> 1.   KLAS Research. (2024). *Top Performing RCM Vendors 2024*. https://klasresearch.com ↩ ↩2
+> 2.   PR Newswire. (2025, February 18). *CureMD AI Scribe Launch Announcement*. https://www.prnewswire.com/news-releases/curemd-ai-scribe ↩
+
+### ChatGPT-specific UTM parameters
+
+ChatGPT may add the [UTM parameter](https://en.wikipedia.org/wiki/UTM_parameter "UTM parameter") `utm_source=openai` or, in edits prior to August 2025, `utm_source=chatgpt.com` to URLs that it is using as sources. Other LLMs, such as Gemini or Claude, use UTM parameters less often.[^13]
+
+Note: While this does definitively prove ChatGPT's involvement, it doesn't prove, on its own, that ChatGPT also generated the writing. Some editors use AI tools to find citations for existing text; this will be apparent in the edit history.
+
+**Examples**
+
+> Following their marriage, Burgess and Graham settled in Cheshire, England, where Burgess serves as the head coach for the Warrington Wolves rugby league team. [https://www.theguardian.com/sport/2025/feb/11/sam-burgess-interview-warrington-rugby-league-luke-littler?utm_source=chatgpt.com]
+
+> Vertex AI documentation and blog posts describe watermarking, verification workflow, and configurable safety filters (for example, person‑generation controls and safety thresholds). ([cloud.google.com](https://cloud.google.com/vertex-ai/generative-ai/docs/image/generate-images?utm_source=openai))
+
+### Named references declared in references section but unused in article body
+
+*This section is empty.* You can help by adding to it. *(October 2025)*
+
+**Examples**
+
+See these diffs for examples. The problematic references appear as parser errors in the reflist.
+
+- [Special:PermanentLink/1287201002#References](https://en.wikipedia.org/wiki/Special:PermanentLink/1287201002#References "Special:PermanentLink/1287201002")
+- [Special:PermanentLink/1292432848#References](https://en.wikipedia.org/wiki/Special:PermanentLink/1292432848#References "Special:PermanentLink/1292432848")
+- [Special:PermanentLink/1291491974#References](https://en.wikipedia.org/wiki/Special:PermanentLink/1291491974#References "Special:PermanentLink/1291491974")
+- [Special:PermanentLink/1291561040#References](https://en.wikipedia.org/wiki/Special:PermanentLink/1291561040#References "Special:PermanentLink/1291561040")
+
+---
+
+## Discrepancies in Writing Style and Variety of English
+
+### Abrupt cut offs
+
+AI tools may abruptly stop generating content, for example if they predict the end of text sequence (appearing as `<|endoftext|>`) next. Also, the number of tokens that a single response has is usually limited, and further responses require the user to select "continue generating".
+
+This method is not foolproof, as a malformed copy/paste from one's local computer can also cause this. It may also indicate a copyright violation rather than the use of an LLM.
+
+### Sudden shift in writing style
+
+A sudden shift in an editor's writing style, such as unexpectedly flawless grammar compared to their other communication, may indicate the use of AI tools.
+
+### Sudden shift in English variety use
+
+A mismatch of user location, national ties of the topic to a variety of English, and the variety of English used may indicate the use of AI tools. A human writer from India writing about an Indian university would probably not use American English; however, LLM outputs use American English by default, unless prompted otherwise.[^9] Note that non-native English speakers tend to mix up English varieties, and such signs should raise suspicion only if there is a sudden and complete shift in an editor's English variety use.
+
+### Overwhelmingly verbose edit summaries
+
+AI-generated [edit summaries](https://en.wikipedia.org/wiki/Help:Edit_summary "Help:Edit summary") are often unusually long, written as formal, first-person paragraphs without abbreviations, and/or conspicuously itemize Wikipedia's conventions.
+
+> Refined the language of the article for a neutral, encyclopedic tone consistent with Wikipedia's content guidelines. Removed promotional wording, ensured factual accuracy, and maintained a clear, well-structured presentation. Updated sections on history, coverage, challenges, and recognition for clarity and relevance. Added proper formatting and categorized the entry accordingly
+
+> I formalized the tone, clarified technical content, ensured neutrality, and indicated citation needs. Historical narratives were streamlined, allocation details specified with regulatory references, propagation explanations made reader-friendly, and equipment discussions focused on availability and regulatory compliance, all while adhering to encyclopedic standards.
+
+> **Concise edit summary:** Improved clarity, flow, and readability of the plot section; reduced redundancy and refined tone for better encyclopedic style.
+
+### "Submission statements" in AFC drafts
+
+This one is specific to drafts submitted by Articles for Creation. At least one LLM tends to insert "submission statements" supposedly intended for reviewers that supposedly explain why the subject is notable and why the draft meets Wikipedia guidelines. Of course, all this actually does is let reviewers know that the draft is LLM-generated, and should be declined or speedied without a second thought.
+
+> Reviewer note (for AfC): This draft is a neutral and well-sourced biography of Portuguese public manager Jorge Patrão. All references are from independent, reliable sources (Público, Diário de Notícias, Jornal de Negócios, RTP, O Interior, Agência Lusa) covering his public career and cultural activity. It meets WP:RS and WP:BLP standards and demonstrates clear notability per WP:NBIO through: – Presidency of Serra da Estrela Tourism Region (1998–2013); – Presidency of Parkurbis – Covilhã Science and Technology Park; – Founding role in Rede de Judiarias de Portugal (member of the Council of Europe's European Routes of Jewish Heritage); – Authorship of the book "1677 – A Fábrica d'El-Rei"; – Founder/curator of the Beatriz de Luna Art Collection (Old Master focus). There is also a Portuguese version of this article at pt.wikipedia.org/wiki/Jorge_Patrão. Thank you for your review. -->
+
+— Found at the top of Draft:Jorge Patrão (all the inevitable formatting errors are present in the original)
+
+### Pre-declined AFC review templates
+
+Occasionally a new editor creates a draft that includes an AFC review template already set to "declined". The template is also devoid of content with no reviewer reasoning given. The LLM apparently offers to add an AFC submission template to the draft, and then provides something like `{{AfC submission|d}}`, in which the "d" parameter pre-declines the draft by substituting {{AfC submission/declined}}. The draft's contribution history reveals that this template was inserted at some point by the draft's creator. Invariably the creator then asks on Wikipedia:WikiProject Articles for creation/Help desk or one of the other help pages why the draft was declined with no feedback. The presence of a content-free "submission declined" header is a **strong** indicator that the draft was LLM-generated.
+
+---
+
+## Signs of Human Writing
+
+### Age of text relative to ChatGPT launch
+
+ChatGPT was launched to the public on November 30, 2022. Although OpenAI had similarly powerful LLMs before then, they were paid services and not easily accessible or known to lay people. ChatGPT experienced extreme growth immediately on launch.
+
+It is very unlikely that any particular text added to Wikipedia **prior to November 30, 2022** was generated by an LLM. If an edit was made before this date, AI use can be safely ruled out for that revision. While some older text may display some of the AI signs given in this list, and even convincingly appear to have been AI-generated, the vastness of Wikipedia allows for these rare coincidences.
+
+### Ability to explain one's own editorial choices
+
+Editors should be able to explain why they made one or more edits or mistakes. For example, if an editor inserts a URL that appears fabricated, you can ask how the mix-up occurred instead of jumping to conclusions. If they can supply the correct link and explain it as a human error (perhaps a typo), or share the relevant passage from the real source, that points to an ordinary human error.
+
+---
+
+## Ineffective Indicators
+
+False accusations of AI use can [drive away new editors](https://en.wikipedia.org/wiki/Wikipedia:BITE "Wikipedia:BITE") and foster an atmosphere of suspicion. Before claiming AI was used, consider if [Dunning–Kruger effect](https://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect "Dunning–Kruger effect") and [confirmation bias](https://en.wikipedia.org/wiki/Confirmation_bias "Confirmation bias") is clouding your judgement. Here are several somewhat commonly used indicators that are ineffective in LLM detection—and may even indicate the opposite.
+
+- **Perfect grammar**: While modern LLMs are known for their high grammatical proficiency, many editors are also skilled writers or come from professional writing backgrounds. (See also [§ Discrepancies in writing style and variety of English](#discrepancies-in-writing-style-and-variety-of-english).)
+
+- **"Bland" or "robotic" prose**: By default, modern LLMs tend toward effusive and verbose prose, as detailed above; while this tendency is formulaic, it may not scan as "robotic" to those unfamiliar with AI writing.[^14]
+
+- **"Fancy," "academic," or unusual words**: While LLMs disproportionately favor certain words and phrases, many of which are long and have difficult readability scores, the correlation does not extend to *all* "fancy," academic, or "advanced"-sounding prose.[^1] Low-frequency and "unusual" words are also less likely to show up in AI-generated writing as they are statistically less common, unless they are proper nouns directly related to the topic.
+
+- **Letter-like writing (in isolation)**: Although many talk page messages written with salutations, valedictions, subject lines, and other formalities after 2023 tend to appear AI-generated, letters and emails have conventionally been written in such ways *long* before modern LLMs existed. Human editors (particularly newer editors) may format their talk page comments similarly for various reasons, such as being more accustomed to formal communication, posting as part of a school assignment that requires such at one, or simply mistaking the talk page for email. AI-generated talk page messages tend to have other tells, such as vertical lists,[^d] placeholders, or abrupt cutoffs.
+
+- **Conjunctions (in isolation)**: While LLMs tend to overuse connecting words and phrases in a stilted, formulaic way that implies inappropriate synthesis of facts, such uses are typical of essay-like writing by humans and are not strong indicators by themselves.
+
+- **Bizarre wikitext**: While LLMs may hallucinate templates or generate wikitext code with invalid syntax for reasons explained in [§Use of Markdown](#use-of-markdown), they are not likely to generate content with certain random-seeming, "inexplicable" errors and artifacts (excluding the ones listed on this page in [§Markup](#markup)). Bizarrely placed HTML tags like `<span>` are more indicative of poorly programmed browser extensions or a known bug with Wikipedia's content translation tool (T113137). Misplaced syntax like `''Catch-22 i''s a satirical novel.` (rendered as "*Catch-22 i* s a satirical novel.") are more indicative of mistakes in VisualEditor, where such errors are harder to notice than in source editing.
+
+---
+
+## Notes
+
+[^a]: not unique to AI chatbots; is produced by the {{as of}} template
+
+[^b]: Example of `Would you like me to ... turn this into actual Wikipedia markup format (wikitext)?` in a deleted draft (administrators only)
+
+[^c]: Example of ` ```wikitext ` on a draft.
+
+[^d]: Example of a vertical list in a deletion discussion
+
+---
+
+## References
+
+[^1]: Russell, Jenna; Karpinska, Marzena; Iyyer, Mohit (2025). [*People who frequently use ChatGPT for writing tasks are accurate and robust detectors of AI-generated text*](https://aclanthology.org/2025.acl-long.267/). Proceedings of the 63rd Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers). Vienna, Austria: Association for Computational Linguistics. pp.5342–5373. arXiv:[2501.15654](https://arxiv.org/abs/2501.15654).
+
+[^2]: Dugan, Liam; Hwang, Alyssa; Trhlik, Filip; Zhu, Andrew; Ludan, Josh Magnus; Xu, Hainiu; Ippolito, Daphne; Callison-Burch, Chris (2024). [*RAID: A Shared Benchmark for Robust Evaluation of Machine-Generated Text Detectors*](https://aclanthology.org/2024.acl-long.674). Proceedings of the 62nd Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers). Bangkok, Thailand: Association for Computational Linguistics. pp.12463–12492. arXiv:[2405.07940](https://arxiv.org/abs/2405.07940).
+
+[^3]: ["People who frequently use ChatGPT for writing tasks are accurate and robust detectors of AI-generated text"](https://arxiv.org/html/2501.15654v2). *arxiv.org*. Retrieved 2025-11-28.
+
+[^4]: This can be directly observed by examining images generated by text-to-image models; they look acceptable at first glance, but specific details tend to be blurry and malformed. This is especially true for background objects and text.
+
+[^5]: ["10 Ways AI Is Ruining Your Students' Writing"](https://www.chronicle.com/article/10-ways-ai-is-ruining-your-students-writing). *Chronicle of Higher Education*. September 16, 2025. Archived from the original on October 1, 2025. Retrieved October 1, 2025.
+
+[^6]: Juzek, Tom S.; Ward, Zina B. (2025). [*Why Does ChatGPT "Delve" So Much? Exploring the Sources of Lexical Overrepresentation in Large Language Models*](https://aclanthology.org/2025.coling-main.426.pdf) (PDF). Findings of the Association for Computational Linguistics: ACL 2025. Association for Computational Linguistics. arXiv:[2412.11385](https://arxiv.org/abs/2412.11385).
+
+[^7]: Reinhart, Alex; Markey, Ben; Laudenbach, Michael; Pantusen, Kachatad; Yurko, Ronald; Weinberg, Gordon; Brown, David West. ["Do LLMs write like humans? Variation in grammatical and rhetorical styles"](http://arxiv.org/abs/2410.16107). Retrieved 4 December 2025.
+
+[^8]: Kobak, Dmitry; González-Márquez, Rita; Horvát, Emőke-Ágnes; Lause, Jan (2 July 2025). ["Delving into LLM-assisted writing in biomedical publications through excess vocabulary"](https://www.science.org/doi/10.1126/sciadv.adt3813). *Science Advances*. **11** (27). doi:[10.1126/sciadv.adt3813](https://doi.org/10.1126%2Fsciadv.adt3813). ISSN 2375-2548. PMC 12219543. PMID 40009654.
+
+[^9]: Ju, Da; Blix, Hagen; Williams, Adina (2025). [*Domain Regeneration: How well do LLMs match syntactic properties of text domains?*](https://aclanthology.org/2025.findings-acl.120). Findings of the Association for Computational Linguistics: ACL 2025. Vienna, Austria: Association for Computational Linguistics. pp.2367–2388. arXiv:[2505.07784](https://arxiv.org/abs/2505.07784). doi:[10.18653/v1/2025.findings-acl.120](https://doi.org/10.18653%2Fv1%2F2025.findings-acl.120).
+
+[^10]: Kousha, Kayvan; Thelwall, Mike (2025). [*How much are LLMs changing the language of academic papers after ChatGPT? A multi-database and full text analysis*](https://arxiv.org/pdf/2509.09596). ISSI 2025 Conference. arXiv:[2509.09596](https://arxiv.org/abs/2509.09596).
+
+[^11]: Merrill, Jeremy B.; Chen, Szu Yu; Kumer, Emma (13 November 2025). ["What are the clues that ChatGPT wrote something? We analyzed its style"](https://www.washingtonpost.com/technology/interactive/2025/how-detect-chatgpt-em-dash/). *The Washington Post*. Retrieved 14 November 2025.
+
+[^12]: ["Unproductive Interpretation of Work and Employment as Misinformation?"](https://www.laetusinpraesens.org/docs20s/workeco.php). Archived from the original on 2 September 2025. Retrieved 21 October 2025.
+
+[^13]: See [T387903](https://phabricator.wikimedia.org/T387903 "phabricator:T387903").
+
+[^14]: Murray, Nathan; Tersigni, Elisa (21 July 2024). ["Can instructors detect AI-generated papers? Postsecondary writing instructor knowledge and perceptions of AI"](https://journals.sfu.ca/jalt/index.php/jalt/article/view/1895). *Journal of Applied Learning & Teaching*. **7** (2). doi:[10.37074/jalt.2024.7.2.12](https://doi.org/10.37074%2Fjalt.2024.7.2.12). ISSN 2591-801X. Retrieved 21 November 2025.
diff --git a/builtin-skills/document-process/xlsx/SKILL.md b/builtin-skills/document-process/xlsx/SKILL.md
new file mode 100644
index 00000000..c5c881be
--- /dev/null
+++ b/builtin-skills/document-process/xlsx/SKILL.md
@@ -0,0 +1,292 @@
+---
+name: xlsx
+description: "Use this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like \"the xlsx in my downloads\") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved."
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# Requirements for Outputs
+
+## All Excel files
+
+### Professional Font
+- Use a consistent, professional font (e.g., Arial, Times New Roman) for all deliverables unless otherwise instructed by the user
+
+### Zero Formula Errors
+- Every Excel model MUST be delivered with ZERO formula errors (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)
+
+### Preserve Existing Templates (when updating templates)
+- Study and EXACTLY match existing format, style, and conventions when modifying files
+- Never impose standardized formatting on files with established patterns
+- Existing template conventions ALWAYS override these guidelines
+
+## Financial models
+
+### Color Coding Standards
+Unless otherwise stated by the user or existing template
+
+#### Industry-Standard Color Conventions
+- **Blue text (RGB: 0,0,255)**: Hardcoded inputs, and numbers users will change for scenarios
+- **Black text (RGB: 0,0,0)**: ALL formulas and calculations
+- **Green text (RGB: 0,128,0)**: Links pulling from other worksheets within same workbook
+- **Red text (RGB: 255,0,0)**: External links to other files
+- **Yellow background (RGB: 255,255,0)**: Key assumptions needing attention or cells that need to be updated
+
+### Number Formatting Standards
+
+#### Required Format Rules
+- **Years**: Format as text strings (e.g., "2024" not "2,024")
+- **Currency**: Use $#,##0 format; ALWAYS specify units in headers ("Revenue ($mm)")
+- **Zeros**: Use number formatting to make all zeros "-", including percentages (e.g., "$#,##0;($#,##0);-")
+- **Percentages**: Default to 0.0% format (one decimal)
+- **Multiples**: Format as 0.0x for valuation multiples (EV/EBITDA, P/E)
+- **Negative numbers**: Use parentheses (123) not minus -123
+
+### Formula Construction Rules
+
+#### Assumptions Placement
+- Place ALL assumptions (growth rates, margins, multiples, etc.) in separate assumption cells
+- Use cell references instead of hardcoded values in formulas
+- Example: Use =B5*(1+$B$6) instead of =B5*1.05
+
+#### Formula Error Prevention
+- Verify all cell references are correct
+- Check for off-by-one errors in ranges
+- Ensure consistent formulas across all projection periods
+- Test with edge cases (zero values, negative numbers)
+- Verify no unintended circular references
+
+#### Documentation Requirements for Hardcodes
+- Comment or in cells beside (if end of table). Format: "Source: [System/Document], [Date], [Specific Reference], [URL if applicable]"
+- Examples:
+  - "Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]"
+  - "Source: Company 10-Q, Q2 2025, Exhibit 99.1, [SEC EDGAR URL]"
+  - "Source: Bloomberg Terminal, 8/15/2025, AAPL US Equity"
+  - "Source: FactSet, 8/20/2025, Consensus Estimates Screen"
+
+# XLSX creation, editing, and analysis
+
+## Overview
+
+A user may ask you to create, edit, or analyze the contents of an .xlsx file. You have different tools and workflows available for different tasks.
+
+## Important Requirements
+
+**LibreOffice Required for Formula Recalculation**: You can assume LibreOffice is installed for recalculating formula values using the `scripts/recalc.py` script. The script automatically configures LibreOffice on first run, including in sandboxed environments where Unix sockets are restricted (handled by `scripts/office/soffice.py`)
+
+## Reading and analyzing data
+
+### Data analysis with pandas
+For data analysis, visualization, and basic operations, use **pandas** which provides powerful data manipulation capabilities:
+
+```python
+import pandas as pd
+
+# Read Excel
+df = pd.read_excel('file.xlsx')  # Default: first sheet
+all_sheets = pd.read_excel('file.xlsx', sheet_name=None)  # All sheets as dict
+
+# Analyze
+df.head()      # Preview data
+df.info()      # Column info
+df.describe()  # Statistics
+
+# Write Excel
+df.to_excel('output.xlsx', index=False)
+```
+
+## Excel File Workflows
+
+## CRITICAL: Use Formulas, Not Hardcoded Values
+
+**Always use Excel formulas instead of calculating values in Python and hardcoding them.** This ensures the spreadsheet remains dynamic and updateable.
+
+### ❌ WRONG - Hardcoding Calculated Values
+```python
+# Bad: Calculating in Python and hardcoding result
+total = df['Sales'].sum()
+sheet['B10'] = total  # Hardcodes 5000
+
+# Bad: Computing growth rate in Python
+growth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']
+sheet['C5'] = growth  # Hardcodes 0.15
+
+# Bad: Python calculation for average
+avg = sum(values) / len(values)
+sheet['D20'] = avg  # Hardcodes 42.5
+```
+
+### ✅ CORRECT - Using Excel Formulas
+```python
+# Good: Let Excel calculate the sum
+sheet['B10'] = '=SUM(B2:B9)'
+
+# Good: Growth rate as Excel formula
+sheet['C5'] = '=(C4-C2)/C2'
+
+# Good: Average using Excel function
+sheet['D20'] = '=AVERAGE(D2:D19)'
+```
+
+This applies to ALL calculations - totals, percentages, ratios, differences, etc. The spreadsheet should be able to recalculate when source data changes.
+
+## Common Workflow
+1. **Choose tool**: pandas for data, openpyxl for formulas/formatting
+2. **Create/Load**: Create new workbook or load existing file
+3. **Modify**: Add/edit data, formulas, and formatting
+4. **Save**: Write to file
+5. **Recalculate formulas (MANDATORY IF USING FORMULAS)**: Use the scripts/recalc.py script
+   ```bash
+   python scripts/recalc.py output.xlsx
+   ```
+6. **Verify and fix any errors**: 
+   - The script returns JSON with error details
+   - If `status` is `errors_found`, check `error_summary` for specific error types and locations
+   - Fix the identified errors and recalculate again
+   - Common errors to fix:
+     - `#REF!`: Invalid cell references
+     - `#DIV/0!`: Division by zero
+     - `#VALUE!`: Wrong data type in formula
+     - `#NAME?`: Unrecognized formula name
+
+### Creating new Excel files
+
+```python
+# Using openpyxl for formulas and formatting
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill, Alignment
+
+wb = Workbook()
+sheet = wb.active
+
+# Add data
+sheet['A1'] = 'Hello'
+sheet['B1'] = 'World'
+sheet.append(['Row', 'of', 'data'])
+
+# Add formula
+sheet['B2'] = '=SUM(A1:A10)'
+
+# Formatting
+sheet['A1'].font = Font(bold=True, color='FF0000')
+sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
+sheet['A1'].alignment = Alignment(horizontal='center')
+
+# Column width
+sheet.column_dimensions['A'].width = 20
+
+wb.save('output.xlsx')
+```
+
+### Editing existing Excel files
+
+```python
+# Using openpyxl to preserve formulas and formatting
+from openpyxl import load_workbook
+
+# Load existing file
+wb = load_workbook('existing.xlsx')
+sheet = wb.active  # or wb['SheetName'] for specific sheet
+
+# Working with multiple sheets
+for sheet_name in wb.sheetnames:
+    sheet = wb[sheet_name]
+    print(f"Sheet: {sheet_name}")
+
+# Modify cells
+sheet['A1'] = 'New Value'
+sheet.insert_rows(2)  # Insert row at position 2
+sheet.delete_cols(3)  # Delete column 3
+
+# Add new sheet
+new_sheet = wb.create_sheet('NewSheet')
+new_sheet['A1'] = 'Data'
+
+wb.save('modified.xlsx')
+```
+
+## Recalculating formulas
+
+Excel files created or modified by openpyxl contain formulas as strings but not calculated values. Use the provided `scripts/recalc.py` script to recalculate formulas:
+
+```bash
+python scripts/recalc.py <excel_file> [timeout_seconds]
+```
+
+Example:
+```bash
+python scripts/recalc.py output.xlsx 30
+```
+
+The script:
+- Automatically sets up LibreOffice macro on first run
+- Recalculates all formulas in all sheets
+- Scans ALL cells for Excel errors (#REF!, #DIV/0!, etc.)
+- Returns JSON with detailed error locations and counts
+- Works on both Linux and macOS
+
+## Formula Verification Checklist
+
+Quick checks to ensure formulas work correctly:
+
+### Essential Verification
+- [ ] **Test 2-3 sample references**: Verify they pull correct values before building full model
+- [ ] **Column mapping**: Confirm Excel columns match (e.g., column 64 = BL, not BK)
+- [ ] **Row offset**: Remember Excel rows are 1-indexed (DataFrame row 5 = Excel row 6)
+
+### Common Pitfalls
+- [ ] **NaN handling**: Check for null values with `pd.notna()`
+- [ ] **Far-right columns**: FY data often in columns 50+ 
+- [ ] **Multiple matches**: Search all occurrences, not just first
+- [ ] **Division by zero**: Check denominators before using `/` in formulas (#DIV/0!)
+- [ ] **Wrong references**: Verify all cell references point to intended cells (#REF!)
+- [ ] **Cross-sheet references**: Use correct format (Sheet1!A1) for linking sheets
+
+### Formula Testing Strategy
+- [ ] **Start small**: Test formulas on 2-3 cells before applying broadly
+- [ ] **Verify dependencies**: Check all cells referenced in formulas exist
+- [ ] **Test edge cases**: Include zero, negative, and very large values
+
+### Interpreting scripts/recalc.py Output
+The script returns JSON with error details:
+```json
+{
+  "status": "success",           // or "errors_found"
+  "total_errors": 0,              // Total error count
+  "total_formulas": 42,           // Number of formulas in file
+  "error_summary": {              // Only present if errors found
+    "#REF!": {
+      "count": 2,
+      "locations": ["Sheet1!B5", "Sheet1!C10"]
+    }
+  }
+}
+```
+
+## Best Practices
+
+### Library Selection
+- **pandas**: Best for data analysis, bulk operations, and simple data export
+- **openpyxl**: Best for complex formatting, formulas, and Excel-specific features
+
+### Working with openpyxl
+- Cell indices are 1-based (row=1, column=1 refers to cell A1)
+- Use `data_only=True` to read calculated values: `load_workbook('file.xlsx', data_only=True)`
+- **Warning**: If opened with `data_only=True` and saved, formulas are replaced with values and permanently lost
+- For large files: Use `read_only=True` for reading or `write_only=True` for writing
+- Formulas are preserved but not evaluated - use scripts/recalc.py to update values
+
+### Working with pandas
+- Specify data types to avoid inference issues: `pd.read_excel('file.xlsx', dtype={'id': str})`
+- For large files, read specific columns: `pd.read_excel('file.xlsx', usecols=['A', 'C', 'E'])`
+- Handle dates properly: `pd.read_excel('file.xlsx', parse_dates=['date_column'])`
+
+## Code Style Guidelines
+**IMPORTANT**: When generating Python code for Excel operations:
+- Write minimal, concise Python code without unnecessary comments
+- Avoid verbose variable names and redundant operations
+- Avoid unnecessary print statements
+
+**For Excel files themselves**:
+- Add comments to cells with complex formulas or important assumptions
+- Document data sources for hardcoded values
+- Include notes for key calculations and model sections
\ No newline at end of file
diff --git a/builtin-skills/frontend-design/canvas-design/SKILL.md b/builtin-skills/frontend-design/canvas-design/SKILL.md
new file mode 100644
index 00000000..9f63fee8
--- /dev/null
+++ b/builtin-skills/frontend-design/canvas-design/SKILL.md
@@ -0,0 +1,130 @@
+---
+name: canvas-design
+description: Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.
+license: Complete terms in LICENSE.txt
+---
+
+These are instructions for creating design philosophies - aesthetic movements that are then EXPRESSED VISUALLY. Output only .md files, .pdf files, and .png files.
+
+Complete this in two steps:
+1. Design Philosophy Creation (.md file)
+2. Express by creating it on a canvas (.pdf file or .png file)
+
+First, undertake this task:
+
+## DESIGN PHILOSOPHY CREATION
+
+To begin, create a VISUAL PHILOSOPHY (not layouts or templates) that will be interpreted through:
+- Form, space, color, composition
+- Images, graphics, shapes, patterns
+- Minimal text as visual accent
+
+### THE CRITICAL UNDERSTANDING
+- What is received: Some subtle input or instructions by the user that should be taken into account, but used as a foundation; it should not constrain creative freedom.
+- What is created: A design philosophy/aesthetic movement.
+- What happens next: Then, the same version receives the philosophy and EXPRESSES IT VISUALLY - creating artifacts that are 90% visual design, 10% essential text.
+
+Consider this approach:
+- Write a manifesto for an art movement
+- The next phase involves making the artwork
+
+The philosophy must emphasize: Visual expression. Spatial communication. Artistic interpretation. Minimal words.
+
+### HOW TO GENERATE A VISUAL PHILOSOPHY
+
+**Name the movement** (1-2 words): "Brutalist Joy" / "Chromatic Silence" / "Metabolist Dreams"
+
+**Articulate the philosophy** (4-6 paragraphs - concise but complete):
+
+To capture the VISUAL essence, express how the philosophy manifests through:
+- Space and form
+- Color and material
+- Scale and rhythm
+- Composition and balance
+- Visual hierarchy
+
+**CRITICAL GUIDELINES:**
+- **Avoid redundancy**: Each design aspect should be mentioned once. Avoid repeating points about color theory, spatial relationships, or typographic principles unless adding new depth.
+- **Emphasize craftsmanship REPEATEDLY**: The philosophy MUST stress multiple times that the final work should appear as though it took countless hours to create, was labored over with care, and comes from someone at the absolute top of their field. This framing is essential - repeat phrases like "meticulously crafted," "the product of deep expertise," "painstaking attention," "master-level execution."
+- **Leave creative space**: Remain specific about the aesthetic direction, but concise enough that the next Claude has room to make interpretive choices also at a extremely high level of craftmanship.
+
+The philosophy must guide the next version to express ideas VISUALLY, not through text. Information lives in design, not paragraphs.
+
+### PHILOSOPHY EXAMPLES
+
+**"Concrete Poetry"**
+Philosophy: Communication through monumental form and bold geometry.
+Visual expression: Massive color blocks, sculptural typography (huge single words, tiny labels), Brutalist spatial divisions, Polish poster energy meets Le Corbusier. Ideas expressed through visual weight and spatial tension, not explanation. Text as rare, powerful gesture - never paragraphs, only essential words integrated into the visual architecture. Every element placed with the precision of a master craftsman.
+
+**"Chromatic Language"**
+Philosophy: Color as the primary information system.
+Visual expression: Geometric precision where color zones create meaning. Typography minimal - small sans-serif labels letting chromatic fields communicate. Think Josef Albers' interaction meets data visualization. Information encoded spatially and chromatically. Words only to anchor what color already shows. The result of painstaking chromatic calibration.
+
+**"Analog Meditation"**
+Philosophy: Quiet visual contemplation through texture and breathing room.
+Visual expression: Paper grain, ink bleeds, vast negative space. Photography and illustration dominate. Typography whispered (small, restrained, serving the visual). Japanese photobook aesthetic. Images breathe across pages. Text appears sparingly - short phrases, never explanatory blocks. Each composition balanced with the care of a meditation practice.
+
+**"Organic Systems"**
+Philosophy: Natural clustering and modular growth patterns.
+Visual expression: Rounded forms, organic arrangements, color from nature through architecture. Information shown through visual diagrams, spatial relationships, iconography. Text only for key labels floating in space. The composition tells the story through expert spatial orchestration.
+
+**"Geometric Silence"**
+Philosophy: Pure order and restraint.
+Visual expression: Grid-based precision, bold photography or stark graphics, dramatic negative space. Typography precise but minimal - small essential text, large quiet zones. Swiss formalism meets Brutalist material honesty. Structure communicates, not words. Every alignment the work of countless refinements.
+
+*These are condensed examples. The actual design philosophy should be 4-6 substantial paragraphs.*
+
+### ESSENTIAL PRINCIPLES
+- **VISUAL PHILOSOPHY**: Create an aesthetic worldview to be expressed through design
+- **MINIMAL TEXT**: Always emphasize that text is sparse, essential-only, integrated as visual element - never lengthy
+- **SPATIAL EXPRESSION**: Ideas communicate through space, form, color, composition - not paragraphs
+- **ARTISTIC FREEDOM**: The next Claude interprets the philosophy visually - provide creative room
+- **PURE DESIGN**: This is about making ART OBJECTS, not documents with decoration
+- **EXPERT CRAFTSMANSHIP**: Repeatedly emphasize the final work must look meticulously crafted, labored over with care, the product of countless hours by someone at the top of their field
+
+**The design philosophy should be 4-6 paragraphs long.** Fill it with poetic design philosophy that brings together the core vision. Avoid repeating the same points. Keep the design philosophy generic without mentioning the intention of the art, as if it can be used wherever. Output the design philosophy as a .md file.
+
+---
+
+## DEDUCING THE SUBTLE REFERENCE
+
+**CRITICAL STEP**: Before creating the canvas, identify the subtle conceptual thread from the original request.
+
+**THE ESSENTIAL PRINCIPLE**:
+The topic is a **subtle, niche reference embedded within the art itself** - not always literal, always sophisticated. Someone familiar with the subject should feel it intuitively, while others simply experience a masterful abstract composition. The design philosophy provides the aesthetic language. The deduced topic provides the soul - the quiet conceptual DNA woven invisibly into form, color, and composition.
+
+This is **VERY IMPORTANT**: The reference must be refined so it enhances the work's depth without announcing itself. Think like a jazz musician quoting another song - only those who know will catch it, but everyone appreciates the music.
+
+---
+
+## CANVAS CREATION
+
+With both the philosophy and the conceptual framework established, express it on a canvas. Take a moment to gather thoughts and clear the mind. Use the design philosophy created and the instructions below to craft a masterpiece, embodying all aspects of the philosophy with expert craftsmanship.
+
+**IMPORTANT**: For any type of content, even if the user requests something for a movie/game/book, the approach should still be sophisticated. Never lose sight of the idea that this should be art, not something that's cartoony or amateur.
+
+To create museum or magazine quality work, use the design philosophy as the foundation. Create one single page, highly visual, design-forward PDF or PNG output (unless asked for more pages). Generally use repeating patterns and perfect shapes. Treat the abstract philosophical design as if it were a scientific bible, borrowing the visual language of systematic observation—dense accumulation of marks, repeated elements, or layered patterns that build meaning through patient repetition and reward sustained viewing. Add sparse, clinical typography and systematic reference markers that suggest this could be a diagram from an imaginary discipline, treating the invisible subject with the same reverence typically reserved for documenting observable phenomena. Anchor the piece with simple phrase(s) or details positioned subtly, using a limited color palette that feels intentional and cohesive. Embrace the paradox of using analytical visual language to express ideas about human experience: the result should feel like an artifact that proves something ephemeral can be studied, mapped, and understood through careful attention. This is true art. 
+
+**Text as a contextual element**: Text is always minimal and visual-first, but let context guide whether that means whisper-quiet labels or bold typographic gestures. A punk venue poster might have larger, more aggressive type than a minimalist ceramics studio identity. Most of the time, font should be thin. All use of fonts must be design-forward and prioritize visual communication. Regardless of text scale, nothing falls off the page and nothing overlaps. Every element must be contained within the canvas boundaries with proper margins. Check carefully that all text, graphics, and visual elements have breathing room and clear separation. This is non-negotiable for professional execution. **IMPORTANT: Use different fonts if writing text. Search the `./canvas-fonts` directory. Regardless of approach, sophistication is non-negotiable.**
+
+Download and use whatever fonts are needed to make this a reality. Get creative by making the typography actually part of the art itself -- if the art is abstract, bring the font onto the canvas, not typeset digitally.
+
+To push boundaries, follow design instinct/intuition while using the philosophy as a guiding principle. Embrace ultimate design freedom and choice. Push aesthetics and design to the frontier. 
+
+**CRITICAL**: To achieve human-crafted quality (not AI-generated), create work that looks like it took countless hours. Make it appear as though someone at the absolute top of their field labored over every detail with painstaking care. Ensure the composition, spacing, color choices, typography - everything screams expert-level craftsmanship. Double-check that nothing overlaps, formatting is flawless, every detail perfect. Create something that could be shown to people to prove expertise and rank as undeniably impressive.
+
+Output the final result as a single, downloadable .pdf or .png file, alongside the design philosophy used as a .md file.
+
+---
+
+## FINAL STEP
+
+**IMPORTANT**: The user ALREADY said "It isn't perfect enough. It must be pristine, a masterpiece if craftsmanship, as if it were about to be displayed in a museum."
+
+**CRITICAL**: To refine the work, avoid adding more graphics; instead refine what has been created and make it extremely crisp, respecting the design philosophy and the principles of minimalism entirely. Rather than adding a fun filter or refactoring a font, consider how to make the existing composition more cohesive with the art. If the instinct is to call a new function or draw a new shape, STOP and instead ask: "How can I make what's already here more of a piece of art?"
+
+Take a second pass. Go back to the code and refine/polish further to make this a philosophically designed masterpiece.
+
+## MULTI-PAGE OPTION
+
+To create additional pages when requested, create more creative pages along the same lines as the design philosophy but distinctly different as well. Bundle those pages in the same .pdf or many .pngs. Treat the first page as just a single page in a whole coffee table book waiting to be filled. Make the next pages unique twists and memories of the original. Have them almost tell a story in a very tasteful way. Exercise full creative freedom.
\ No newline at end of file
diff --git a/builtin-skills/frontend-design/design-dna/README.md b/builtin-skills/frontend-design/design-dna/README.md
new file mode 100644
index 00000000..1123abd8
--- /dev/null
+++ b/builtin-skills/frontend-design/design-dna/README.md
@@ -0,0 +1,109 @@
+<h1 align="center">design-dna</h1>
+
+![example](https://github.com/user-attachments/assets/77e9e02e-35a4-4d65-a402-dc6f9b35ed6e)
+
+
+https://github.com/user-attachments/assets/00e0a28d-42ce-4a08-a0c0-1ecf8b9f7e97
+
+
+<h3 align="center">Other cases</h3>
+
+https://github.com/user-attachments/assets/80793608-930d-42ca-951f-eb21ac188d54
+
+https://github.com/user-attachments/assets/cd4cba94-cd2c-480f-8efa-4ac86e00ae1f
+
+English | [中文](README.zh-CN.md)
+
+An agent skill for extracting, structuring, and applying visual design identity as machine-readable "Design DNA" across three dimensions: design tokens, qualitative style, and visual effects.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) environment installed
+- Ability to run `npx` commands
+
+## Installation
+
+### Quick Install (Recommended)
+
+```bash
+npx skills add zanwei/design-dna
+```
+
+### Install to Specific Agent
+
+```bash
+# Cursor only, non-interactive, global install
+npx skills add zanwei/design-dna -a cursor -g -y
+
+# Claude Code only
+npx skills add zanwei/design-dna -a claude-code -g -y
+```
+
+### Install from Local Clone
+
+```bash
+git clone https://github.com/zanwei/design-dna.git
+npx skills add ./design-dna -y
+```
+
+### List Available Skills
+
+```bash
+npx skills add zanwei/design-dna --list
+```
+
+## What It Does
+
+| Dimension | Role |
+|-----------|------|
+| **Design System** | Measurable tokens: color, typography, spacing, layout, shape, elevation, motion, components |
+| **Design Style** | Qualitative perception: mood, visual language, composition, imagery, interaction feel, brand voice |
+| **Visual Effects** | Beyond plain CSS: Canvas, WebGL, 3D, particles, shaders, scroll-driven motion, cursor effects, SVG animation, glassmorphism, etc. |
+
+The skill drives a **three-phase** workflow:
+
+1. **Structure** — Surface the full schema and field meanings (see `references/schema.md`).
+2. **Analyze** — From screenshots, images, or URLs, produce a complete JSON profile (every field filled; conflicts noted).
+3. **Generate** — Given DNA JSON plus content, implement the design (default: self-contained HTML/CSS/JS), following `references/generation-guide.md`.
+
+Phases can be used alone or chained (e.g. Analyze → Generate).
+
+## How It Works
+
+Pipeline at a glance ([Mermaid](https://github.blog/news-insights/product-news/github-now-supports-mermaid-diagrams-in-markdown/) renders on GitHub):
+
+```mermaid
+flowchart LR
+    A["Reference designs<br/>Screenshots · URLs · images<br/><br/>Any design you admire"]
+    B["Design DNA JSON<br/>Quantified spec<br/><br/>Structured profile"]
+    C["Final output<br/>Faithful implementation<br/><br/>Production-ready UI"]
+
+    A -->|"Analyze — extract every visual property"| B
+    B -->|"Generate — apply DNA to your content"| C
+    B -.-> D["Save · reuse · version control"]
+```
+
+**Step 1 — Curate references.** Collect screenshots, images, or live URLs of designs whose visual identity you want to capture. Multiple references can be combined; the skill identifies dominant patterns and notes variants.
+
+**Step 2 — Extract DNA.** Feed the references to the agent. It inspects every visual property across all three dimensions and outputs a complete, quantified Design DNA JSON — no empty fields, no guesswork. This JSON becomes a portable, reusable design specification.
+
+**Step 3 — Generate from DNA.** Provide the DNA JSON together with your own content. The agent produces implementations that faithfully reproduce the original design language while adapting to your material.
+
+The DNA JSON is the key artifact. Once extracted, it can be **committed to version control**, **shared across teams**, **reused across projects**, and **iteratively refined** — turning subjective "make it look like that site" into a precise, reproducible specification that any agent can consume.
+
+> [!TIP]
+> **Refining visual richness.** If the first pass still feels visually thin or under-detailed next to your references, run a deliberate **polish iteration**: re-attach the **same URLs or screenshots**. This narrows the gap between a workable draft and a reference-faithful, visually rich result without starting over.
+>
+> **Prompt:** **Against the reference, audit hierarchy, ornamentation, typographic rhythm, motion, materiality, and overall UI—then merge your conclusions back into the current implementation.**
+
+## Compatibility
+
+Follows the [Agent Skills specification](https://agentskills.io). Installable via [`skills` CLI](https://github.com/vercel-labs/skills) to all [supported agents](https://github.com/vercel-labs/skills#supported-agents) including Cursor, Claude Code, Codex, GitHub Copilot, and [39 more](https://github.com/vercel-labs/skills#supported-agents).
+
+## Contributing
+
+Issues and pull requests are welcome. For substantive behavior changes, update `SKILL.md` and any affected files under `references/` so the skill stays internally consistent.
+
+## License
+
+MIT
diff --git a/builtin-skills/frontend-design/design-dna/README.zh-CN.md b/builtin-skills/frontend-design/design-dna/README.zh-CN.md
new file mode 100644
index 00000000..a1a596d5
--- /dev/null
+++ b/builtin-skills/frontend-design/design-dna/README.zh-CN.md
@@ -0,0 +1,99 @@
+<h1 align="center">design-dna</h1>
+
+![示例：从参考站点（thekrakentraining.com）提取视觉 DNA，并应用到自有内容（deno.com）。](docs/example-style-transfer.png)
+
+[English](README.md) | 中文
+
+面向编程智能体的技能，用于提取、结构化并应用视觉设计身份（Design DNA），覆盖三个维度：设计系统（可度量 token）、设计风格（定性感受）与视觉特效。
+
+## 前置条件
+
+- 已安装 [Node.js](https://nodejs.org/) 环境
+- 能够运行 `npx` 命令
+
+## 安装
+
+### 快速安装（推荐）
+
+```bash
+npx skills add zanwei/design-dna
+```
+
+### 安装到指定智能体
+
+```bash
+# 仅 Cursor，非交互，全局安装
+npx skills add zanwei/design-dna -a cursor -g -y
+
+# 仅 Claude Code
+npx skills add zanwei/design-dna -a claude-code -g -y
+```
+
+### 从本地克隆安装
+
+```bash
+git clone https://github.com/zanwei/design-dna.git
+npx skills add ./design-dna -y
+```
+
+### 列出可用技能
+
+```bash
+npx skills add zanwei/design-dna --list
+```
+
+## 功能说明
+
+| 维度 | 说明 |
+|------|------|
+| **设计系统** | 可度量 token：色彩、字体、间距、版式、形状、层级、动效、组件等 |
+| **设计风格** | 定性描述：情绪、视觉语言、构图、图像风格、交互气质、品牌语气等 |
+| **视觉特效** | 超出普通 CSS 的实现：Canvas、WebGL、3D、粒子、着色器、滚动驱动动效、光标效果、SVG 动画、玻璃拟态等 |
+
+技能内置 **三阶段** 工作流：
+
+1. **结构** — 展示完整 schema 与各字段含义（见 `references/schema.md`）。
+2. **分析** — 根据截图、图片或 URL，输出字段齐全的 JSON 画像（无空字段；多参考冲突时注明主方案与变体）。
+3. **生成** — 在已有 DNA JSON + 内容的前提下落地实现（默认：自包含 HTML/CSS/JS），并遵循 `references/generation-guide.md` 中的质量检查。
+
+各阶段可单独使用，也可串联（例如：分析 → 生成）。
+
+## 工作原理
+
+流程一览（GitHub 会渲染下方 [Mermaid](https://github.blog/news-insights/product-news/github-now-supports-mermaid-diagrams-in-markdown/) 图）：
+
+```mermaid
+flowchart LR
+    A["参考设计<br/>截图 · 网址 · 图片<br/><br/>任何你喜欢的设计"]
+    B["Design DNA JSON<br/>量化规格<br/><br/>结构化画像"]
+    C["最终产出<br/>忠实还原的实现<br/><br/>可交付界面"]
+
+    A -->|"分析 — 逐项提取视觉属性"| B
+    B -->|"生成 — 将 DNA 应用到你的内容"| C
+    B -.-> D["保存 · 复用 · 版本管理"]
+```
+
+**第一步 — 收集参考。** 准备你欣赏的设计截图、图片或线上页面链接。可以同时提供多份参考，技能会识别主导模式并标注差异。
+
+**第二步 — 提取 DNA。** 将参考素材交给智能体，它会逐项检视三个维度的每一项视觉属性，输出一份完整且量化的 Design DNA JSON — 没有空字段、没有猜测。这份 JSON 就是一份可移植、可复用的设计规格。
+
+**第三步 — 基于 DNA 生成。** 将 DNA JSON 与你自己的内容一同提供，智能体会生成忠实还原原始设计语言的实现，同时适配你的素材与文案。
+
+DNA JSON 是核心产物。一旦提取完成，它可以**提交到版本控制**、**跨团队共享**、**在多个项目中复用**，也可以**持续迭代微调** — 把主观的「照着那个网站做」变成一份精确、可复现的规格定义，任何智能体都能据此稳定输出一致的设计。
+
+> [!TIP]
+> **视觉精修提示。** 若首轮产出相对参考仍显单薄或细节不足，可将**同一批参考链接或截图**再次提供给智能体，发起明确的**精修轮次**；可在保留初稿的前提下显著拉近与「高保真参照」的差距，无需从零重做。
+>
+> **Prompt：** **请其对照参考复审界面层级与点缀、字阶与留白、动效与材质及整体 UI，并将结论回填至当前实现。**
+
+## 兼容性
+
+符合 [Agent Skills 规范](https://agentskills.io)。可通过 [`skills` CLI](https://github.com/vercel-labs/skills) 安装到所有[支持的智能体](https://github.com/vercel-labs/skills#supported-agents)，包括 Cursor、Claude Code、Codex、GitHub Copilot 等 [40+ 款](https://github.com/vercel-labs/skills#supported-agents)。
+
+## 贡献
+
+欢迎提 Issue 与 Pull Request。若修改技能行为，请同步更新 `SKILL.md` 及 `references/` 下相关文件，保持文档与行为一致。
+
+## 许可证
+
+MIT
diff --git a/builtin-skills/frontend-design/design-dna/SKILL.md b/builtin-skills/frontend-design/design-dna/SKILL.md
new file mode 100644
index 00000000..3445a960
--- /dev/null
+++ b/builtin-skills/frontend-design/design-dna/SKILL.md
@@ -0,0 +1,104 @@
+---
+name: design-dna
+description: >-
+  Extract, define, and apply design DNA across three dimensions: design system
+  (tokens), design style (qualitative feel), and visual effects (Canvas, WebGL,
+  3D, particles, shaders, scroll effects, etc.). Use this skill when: (1) a user
+  wants to see the full 3-dimension design structure/schema, (2) a user provides
+  images, screenshots, or URLs of reference designs and wants them analyzed into
+  a structured JSON profile covering all three dimensions, (3) a user has a
+  Design DNA JSON and content and wants a design generated from it, or (4) any
+  combination of these phases. Triggers on "design DNA", "extract design style",
+  "analyze design", "design tokens from reference", "generate design from JSON",
+  "design system from screenshot", "design profile", "style guide JSON",
+  "visual effects analysis", "design with effects", "3d design analysis".
+---
+
+# Design DNA
+
+A 3-phase workflow for extracting, structuring, and applying design identity across three dimensions:
+
+1. **Design System** — measurable tokens (color, typography, spacing, layout, shape, elevation, motion, components)
+2. **Design Style** — qualitative perception (mood, visual language, composition, imagery, interaction feel, brand voice)
+3. **Visual Effects** — special rendering (Canvas, WebGL, 3D, particles, shaders, scroll effects, cursor effects, SVG animations, glassmorphism, etc.)
+
+## Phases
+
+### Phase 1: Structure — Output the Schema
+
+When the user asks for the structural dimensions or schema:
+
+1. Read [references/schema.md](references/schema.md)
+2. Present the full schema with field descriptions
+3. Explain the three dimensions and their roles:
+   - **design_system**: What you can measure — exact hex values, pixel sizes, rem scales
+   - **design_style**: What you can feel — mood, personality, composition strategy
+   - **visual_effects**: What you can see but can't express in CSS alone — WebGL scenes, particle systems, shader distortions, scroll-driven animations
+4. Ask if the user wants to customize or extend any dimensions
+
+### Phase 2: Analyze — Extract DNA from References
+
+When the user provides images, screenshots, or links representing a target design style:
+
+1. Read [references/schema.md](references/schema.md) for the full field list
+2. For each reference provided:
+   - If image/screenshot: analyze visual properties directly
+   - If URL: fetch and analyze the page's visual design
+3. For every field in the schema, extract or infer a value from the references
+4. When multiple references conflict, note the dominant pattern and mention variants
+5. Output a complete Design DNA JSON — every field populated, no empty strings
+6. After output, ask: "Want to adjust any values before using this for generation?"
+
+**Analysis approach per dimension:**
+
+#### Dimension 1: design_system
+- **color**: Extract dominant palette via visual sampling. Primary by area dominance, secondary by supporting role, accent by CTA usage. Map neutral scale from lightest background to darkest text.
+- **typography**: Identify font families by visual characteristics (geometric, humanist, serif class). Estimate scale ratios from heading/body size relationships.
+- **spacing**: Assess density by element proximity. Measure rhythm by section gap consistency.
+- **layout**: Identify grid by content alignment patterns. Note max-width, column count, asymmetry.
+- **shape**: Measure border-radius by comparing to element height. Note border and divider presence.
+- **elevation**: Classify shadow softness, spread, and layering approach.
+- **motion**: If observable (video/interactive), note easing curves and duration feel.
+
+#### Dimension 2: design_style
+- Synthesize holistic impressions — mood, personality, composition strategy
+- Compare against genre archetypes (SaaS, editorial, brutalist, etc.)
+- Note ornamentation level and whitespace philosophy
+
+#### Dimension 3: visual_effects
+- **From code**: Scan for `<canvas>`, WebGL contexts, Three.js/Pixi.js imports, GSAP/Lottie usage, custom shaders, IntersectionObserver scroll triggers, SVG `<animate>` elements
+- **From screenshots**: Describe visible effects that go beyond standard CSS — glowing particles, 3D object renders, noise textures, gradient animations, parallax depth, cursor trails, text distortions, glassmorphic surfaces. Note these in `composite_notes` when exact implementation can't be determined.
+- **From video/interaction demos**: Note scroll behaviors, hover distortions, transition choreography, loading sequences
+- Set `enabled: false` for any effect category not present in the reference
+- Rate `overview.effect_intensity` and `overview.performance_tier` based on what's observed
+
+### Phase 3: Generate — Apply DNA to Content
+
+When the user provides DNA JSON + content to design:
+
+1. Read [references/generation-guide.md](references/generation-guide.md)
+2. Parse the DNA JSON and extract all tokens across three dimensions
+3. Build CSS custom properties from `design_system` values
+4. Apply `design_style` qualitative fields to guide subjective design decisions
+5. When the design needs assets or source materials, fetch them from the original source whenever possible. If the user provided a URL, retrieve the real asset from that URL instead of recreating, approximating, or substituting it.
+6. Implement `visual_effects` using appropriate technologies:
+   - Lightweight effects → CSS animations, SVG, vanilla JS
+   - Medium effects → Canvas 2D, GSAP, Lottie
+   - Heavy effects → Three.js, custom GLSL shaders, Pixi.js
+7. Generate the design output (default: self-contained HTML with inline CSS/JS)
+8. Run quality checks from the generation guide
+
+**If the user provides only content without DNA JSON**, ask whether to:
+- Analyze a reference first (go to Phase 2)
+- Use a described style (extract DNA from description, then generate)
+
+## Phase Combinations
+
+Users may invoke any combination:
+- **Phase 1 only**: "Show me the design structure/schema"
+- **Phase 2 only**: "Analyze this design" (with images/links)
+- **Phase 2 → 3**: "Analyze this design and build me a landing page in the same style"
+- **Phase 1 → 2 → 3**: Full pipeline
+- **Phase 3 only**: User already has DNA JSON
+
+Detect which phase(s) are needed from context and execute accordingly.
diff --git a/builtin-skills/frontend-design/design-dna/references/generation-guide.md b/builtin-skills/frontend-design/design-dna/references/generation-guide.md
new file mode 100644
index 00000000..29fd737c
--- /dev/null
+++ b/builtin-skills/frontend-design/design-dna/references/generation-guide.md
@@ -0,0 +1,209 @@
+# Generation Guide
+
+How to use a completed Design DNA JSON to generate designs in Phase 3. Covers all three dimensions.
+
+## Priority Order
+
+When generating a design from DNA JSON + content:
+
+1. **Color & Typography** — define 80% of visual identity
+2. **Spacing & Layout** — structural rhythm
+3. **Shape & Elevation** — surface treatment
+4. **Design Style qualitative fields** — mood, personality, composition approach
+5. **Visual Effects** — special rendering layer (Canvas, WebGL, shaders, etc.)
+6. **Motion & Interaction** — enhance after static layout and effects are solid
+
+## Dimension 1: design_system → Code
+
+### Tailwind CSS / Utility-First
+```
+color.primary.hex        → --color-primary / bg-[hex]
+typography.font_families → font-family config
+spacing.scale            → spacing config values
+shape.border_radius      → rounded-{sm|md|lg|full}
+elevation.levels         → shadow-{sm|md|lg}
+```
+
+### Plain CSS / CSS Variables
+Generate a `:root` block with all design tokens:
+```css
+:root {
+  --color-primary: {color.primary.hex};
+  --color-secondary: {color.secondary.hex};
+  --color-accent: {color.accent.hex};
+  --font-heading: {typography.font_families.heading};
+  --font-body: {typography.font_families.body};
+  --radius-sm: {shape.border_radius.small};
+  --radius-md: {shape.border_radius.medium};
+  --radius-lg: {shape.border_radius.large};
+  --shadow-low: {elevation.levels.low};
+  --shadow-med: {elevation.levels.medium};
+  --shadow-high: {elevation.levels.high};
+  --ease: {motion.easing};
+  --duration-micro: {motion.duration_scale.micro};
+  --duration-normal: {motion.duration_scale.normal};
+  --duration-macro: {motion.duration_scale.macro};
+  /* ... map all tokens */
+}
+```
+
+### Component Decisions
+- `components.button_style` → button classes and variants
+- `components.card_style` → card container treatment
+- `components.navigation_pattern` → nav component choice
+- `interaction_feel.hover_behavior` → :hover / :focus states
+- `motion.easing` + `motion.duration_scale` → transition properties
+
+## Dimension 2: design_style → Subjective Decisions
+
+| DNA Field | Guides |
+|---|---|
+| aesthetic.mood | Overall emotional feeling — warm tones, cool precision, etc. |
+| visual_language.whitespace_usage | padding/margin generosity |
+| visual_language.contrast_level | How much elements pop vs. blend |
+| composition.hierarchy_method | What tool to use for emphasis |
+| composition.balance_type | Symmetric layout vs. dynamic asymmetry |
+| imagery.graphic_elements | Decorative SVGs, gradients, patterns |
+| brand_voice_in_ui.tone | Microcopy phrasing |
+| interaction_feel.microinteraction_density | How many hover/click effects |
+
+## Dimension 3: visual_effects → Special Rendering
+
+### Technology Selection by Performance Tier
+
+| Tier | Technologies | When to Use |
+|---|---|---|
+| **lightweight** | CSS animations, SVG SMIL, vanilla JS | `overview.performance_tier` = "lightweight" |
+| **medium** | Canvas 2D, GSAP, Lottie, anime.js | `overview.performance_tier` = "medium" |
+| **heavy** | Three.js, custom GLSL, Pixi.js, WebGL | `overview.performance_tier` = "heavy" |
+
+### Implementation Patterns
+
+#### Background Effects
+```
+"none"              → skip
+"gradient-animation" → CSS @keyframes on linear-gradient or conic-gradient
+"noise-field"       → Canvas 2D with Perlin/simplex noise
+"mesh-gradient"     → SVG <mesh> or canvas interpolation
+"video-bg"          → <video autoplay muted loop> with poster fallback
+"generative-art"    → Canvas 2D or WebGL generative algorithms
+```
+
+#### Particle Systems
+When `particle_systems.enabled: true`:
+- For `count` < 100 and no complex physics → vanilla JS + Canvas 2D
+- For `count` >= 100 or complex interaction → consider Pixi.js or Three.js Points
+- Map `interaction` ("mouse-repel", "mouse-attract") to pointer event handlers
+- Use `requestAnimationFrame` loop; include destroy/cleanup on unmount
+
+#### 3D Elements
+When `3d_elements.enabled: true`:
+- Default to Three.js unless DNA specifies otherwise
+- Apply `lighting`, `camera`, `materials` from params
+- Add `post_processing` effects via EffectComposer
+- Handle resize with `ResizeObserver`
+- Load via CDN: `https://cdn.jsdelivr.net/npm/three@latest/build/three.module.js`
+
+#### Shader Effects
+When `shader_effects.enabled: true`:
+- Create vertex/fragment shaders based on `type`
+- Pass `uniforms` from params (time, resolution, mouse position)
+- For "noise-distortion": use noise functions matching `noise_type`
+- Animate via `requestAnimationFrame` updating `u_time` uniform
+
+#### Scroll Effects
+- **Parallax**: Use `transform: translateY()` with scroll offset × layer speed
+- **Scroll-triggered**: Use `IntersectionObserver` with `threshold` array
+- **Scrub behavior**: If "scrubbed", animation progress = scroll progress. If "triggered", play once on enter.
+
+#### Text Effects
+```
+"split-letter-animate" → Split text into <span> per char/word, stagger CSS animation
+"typewriter"           → CSS steps() or JS interval revealing chars
+"glitch"               → Layered clip-path + color offset animation
+"gradient-fill"        → background-clip: text with animated gradient
+"3d-extrude"           → text-shadow stack or WebGL text geometry
+```
+
+#### Cursor Effects
+When `cursor_effects.enabled: true`:
+- Hide default cursor: `cursor: none`
+- Create custom cursor element following `pointermove`
+- "magnetic-buttons": Apply transform pull on hover proximity
+- "spotlight": Radial gradient mask following cursor
+- "trail": Spawn fading elements on move
+
+#### Glassmorphism / Neumorphism
+```
+"glass"             → backdrop-filter: blur({blur_radius}); background: rgba(..., {transparency})
+"neumorphic-light"  → Dual box-shadow (light + dark offset) on light bg
+"neumorphic-dark"   → Dual box-shadow (inverted) on dark bg
+"frosted-layers"    → Stacked blur layers with varying opacity
+```
+
+#### Canvas Drawings
+When `canvas_drawings.enabled: true`:
+- Initialize canvas with `width/height` matching container
+- Use `draw_method` to select rendering approach
+- Animate with `requestAnimationFrame`
+- Handle `responsiveness` via ResizeObserver
+
+#### SVG Animations
+When `svg_animations.enabled: true`:
+- "path-draw": Animate `stroke-dashoffset` from path length to 0
+- "morph-shapes": Interpolate `d` attribute between two paths
+- "stroke-animation": Animate stroke properties (dasharray, width, color)
+
+### Fallback Strategy
+
+Always implement the fallback defined in `overview.fallback_strategy`:
+
+```js
+// Example: reduce to CSS on low-end devices
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+const isLowEnd = navigator.hardwareConcurrency <= 2;
+if (prefersReduced || isLowEnd) {
+  // Apply fallback: static CSS version, disable canvas/WebGL
+}
+```
+
+## Output Format
+
+Generate output as a single self-contained HTML file with inline CSS and JS (unless user specifies a framework). Include:
+
+1. CSS custom properties block from `design_system` tokens
+2. Component styles from `design_system.components` + `design_style`
+3. Layout structure per `design_system.layout`
+4. Content populated from user-provided content
+5. Visual effects implemented per `visual_effects` specification
+6. Animations/transitions if `design_system.motion.philosophy` is not "none"
+7. Fallback handling for effects
+
+For heavy effects requiring external libraries, load via CDN `<script>` tags:
+```html
+<!-- Three.js -->
+<script type="importmap">{"imports":{"three":"https://cdn.jsdelivr.net/npm/three@latest/build/three.module.js"}}</script>
+
+<!-- GSAP -->
+<script src="https://cdn.jsdelivr.net/npm/gsap@latest/dist/gsap.min.js"></script>
+
+<!-- Lottie -->
+<script src="https://cdn.jsdelivr.net/npm/lottie-web@latest/build/player/lottie.min.js"></script>
+```
+
+## Quality Checks
+
+Before delivering, verify:
+- [ ] Every color in output traces back to DNA palette
+- [ ] Font families match DNA specification
+- [ ] Spacing rhythm matches DNA scale
+- [ ] Border radius matches DNA shape tokens
+- [ ] Overall mood matches `design_style.aesthetic.mood`
+- [ ] Component patterns match DNA `components` descriptions
+- [ ] Contrast ratios meet WCAG AA minimum (4.5:1 body text, 3:1 large text)
+- [ ] Visual effects match `visual_effects` specification (type, technology, params)
+- [ ] Fallback strategy is implemented for effects
+- [ ] `prefers-reduced-motion` is respected
+- [ ] No effects render when their `enabled` flag is `false`
+- [ ] Canvas/WebGL contexts are properly sized and handle resize
+- [ ] Animation loops use `requestAnimationFrame` (no `setInterval`)
diff --git a/builtin-skills/frontend-design/design-dna/references/schema.md b/builtin-skills/frontend-design/design-dna/references/schema.md
new file mode 100644
index 00000000..13815120
--- /dev/null
+++ b/builtin-skills/frontend-design/design-dna/references/schema.md
@@ -0,0 +1,366 @@
+# Design DNA Schema
+
+Three-dimensional design profile:
+- **design_system** — measurable tokens
+- **design_style** — qualitative perception
+- **visual_effects** — special rendering such as Canvas, WebGL, 3D, particles, shaders, scroll effects, cursor effects, SVG animation, and glassmorphism
+
+Every field below must appear in the final JSON output.
+
+## Top-Level Structure
+
+### `meta`
+- `name`
+- `description`
+- `source_references`
+- `created_at`
+
+### `design_system`
+The structural and measurable layer.
+
+#### `design_system.color`
+- `palette_type`
+- `primary.hex`
+- `primary.role`
+- `secondary.hex`
+- `secondary.role`
+- `accent.hex`
+- `accent.role`
+- `neutral.scale`
+- `neutral.usage`
+- `semantic.success`
+- `semantic.warning`
+- `semantic.error`
+- `semantic.info`
+- `surface.background`
+- `surface.card`
+- `surface.elevated`
+- `contrast_strategy`
+
+#### `design_system.typography`
+- `type_scale.display.size`
+- `type_scale.display.weight`
+- `type_scale.display.line_height`
+- `type_scale.display.tracking`
+- `type_scale.heading_1.size`
+- `type_scale.heading_1.weight`
+- `type_scale.heading_1.line_height`
+- `type_scale.heading_1.tracking`
+- `type_scale.heading_2.size`
+- `type_scale.heading_2.weight`
+- `type_scale.heading_2.line_height`
+- `type_scale.heading_2.tracking`
+- `type_scale.heading_3.size`
+- `type_scale.heading_3.weight`
+- `type_scale.heading_3.line_height`
+- `type_scale.heading_3.tracking`
+- `type_scale.body.size`
+- `type_scale.body.weight`
+- `type_scale.body.line_height`
+- `type_scale.body.tracking`
+- `type_scale.body_small.size`
+- `type_scale.body_small.weight`
+- `type_scale.body_small.line_height`
+- `type_scale.body_small.tracking`
+- `type_scale.caption.size`
+- `type_scale.caption.weight`
+- `type_scale.caption.line_height`
+- `type_scale.caption.tracking`
+- `type_scale.overline.size`
+- `type_scale.overline.weight`
+- `type_scale.overline.line_height`
+- `type_scale.overline.tracking`
+- `font_families.heading`
+- `font_families.body`
+- `font_families.mono`
+- `font_style_notes`
+
+#### `design_system.spacing`
+- `base_unit`
+- `scale`
+- `content_density`
+- `section_rhythm`
+
+#### `design_system.layout`
+- `grid_system`
+- `max_content_width`
+- `columns`
+- `gutter`
+- `breakpoints`
+- `alignment_tendency`
+
+#### `design_system.shape`
+- `border_radius.small`
+- `border_radius.medium`
+- `border_radius.large`
+- `border_radius.pill`
+- `border_usage`
+- `divider_style`
+
+#### `design_system.elevation`
+- `shadow_style`
+- `levels.low`
+- `levels.medium`
+- `levels.high`
+- `depth_cues`
+
+#### `design_system.iconography`
+- `style`
+- `stroke_weight`
+- `size_scale`
+- `preferred_set`
+
+#### `design_system.motion`
+- `easing`
+- `duration_scale.micro`
+- `duration_scale.normal`
+- `duration_scale.macro`
+- `entrance_pattern`
+- `exit_pattern`
+- `philosophy`
+
+#### `design_system.components`
+- `button_style`
+- `input_style`
+- `card_style`
+- `navigation_pattern`
+- `modal_style`
+- `list_style`
+- `component_notes`
+
+### `design_style`
+The qualitative and perceptual layer.
+
+#### `design_style.aesthetic`
+- `mood`
+- `visual_metaphor`
+- `era_influence`
+- `genre`
+- `personality_traits`
+- `adjectives`
+
+#### `design_style.visual_language`
+- `complexity`
+- `ornamentation`
+- `whitespace_usage`
+- `visual_weight_distribution`
+- `focal_strategy`
+- `contrast_level`
+- `texture_usage`
+
+#### `design_style.composition`
+- `hierarchy_method`
+- `balance_type`
+- `flow_direction`
+- `grouping_strategy`
+- `negative_space_role`
+
+#### `design_style.imagery`
+- `photo_treatment`
+- `illustration_style`
+- `graphic_elements`
+- `pattern_usage`
+- `image_shape`
+
+#### `design_style.interaction_feel`
+- `feedback_style`
+- `hover_behavior`
+- `transition_personality`
+- `loading_style`
+- `microinteraction_density`
+
+#### `design_style.brand_voice_in_ui`
+- `tone`
+- `formality`
+- `cta_style`
+- `empty_state_approach`
+- `error_tone`
+
+### `visual_effects`
+The special rendering and advanced visual behavior layer.
+
+#### `visual_effects.overview`
+- `effect_intensity`
+- `performance_tier`
+- `fallback_strategy`
+- `primary_technology`
+
+#### `visual_effects.background_effects`
+- `type`
+- `description`
+- `technology`
+- `params.color_palette`
+- `params.speed`
+- `params.density`
+- `params.opacity`
+- `params.blend_mode`
+
+#### `visual_effects.particle_systems`
+- `enabled`
+- `type`
+- `description`
+- `technology`
+- `params.count`
+- `params.shape`
+- `params.size_range`
+- `params.movement_pattern`
+- `params.color_behavior`
+- `params.interaction`
+- `params.spawn_area`
+
+#### `visual_effects.3d_elements`
+- `enabled`
+- `type`
+- `description`
+- `technology`
+- `params.renderer`
+- `params.lighting`
+- `params.camera`
+- `params.materials`
+- `params.geometry`
+- `params.post_processing`
+- `params.interaction_model`
+
+#### `visual_effects.shader_effects`
+- `enabled`
+- `type`
+- `description`
+- `technology`
+- `params.uniforms`
+- `params.vertex_manipulation`
+- `params.fragment_output`
+- `params.noise_type`
+- `params.distortion`
+
+#### `visual_effects.scroll_effects.parallax`
+- `enabled`
+- `layers`
+- `depth_range`
+- `speed_curve`
+
+#### `visual_effects.scroll_effects.scroll_triggered_animations`
+- `enabled`
+- `trigger_points`
+- `animation_type`
+- `scrub_behavior`
+
+#### `visual_effects.scroll_effects.scroll_morphing`
+- `enabled`
+- `description`
+
+#### `visual_effects.text_effects`
+- `type`
+- `description`
+- `technology`
+- `params.split_strategy`
+- `params.animation_per_unit`
+- `params.stagger`
+- `params.effect_style`
+
+#### `visual_effects.cursor_effects`
+- `enabled`
+- `type`
+- `description`
+- `params.shape`
+- `params.size`
+- `params.blend_mode`
+- `params.trail`
+- `params.interaction_zone`
+
+#### `visual_effects.image_effects`
+- `type`
+- `description`
+- `technology`
+- `params.filter_pipeline`
+- `params.hover_transform`
+- `params.reveal_animation`
+- `params.distortion_type`
+
+#### `visual_effects.glassmorphism_neumorphism`
+- `enabled`
+- `style`
+- `params.blur_radius`
+- `params.transparency`
+- `params.border_treatment`
+- `params.shadow_type`
+- `params.light_source_angle`
+
+#### `visual_effects.canvas_drawings`
+- `enabled`
+- `type`
+- `description`
+- `technology`
+- `params.draw_method`
+- `params.animation_loop`
+- `params.color_scheme`
+- `params.responsiveness`
+- `params.interaction`
+
+#### `visual_effects.svg_animations`
+- `enabled`
+- `type`
+- `description`
+- `params.animation_method`
+- `params.path_morphing`
+- `params.stroke_animation`
+- `params.filter_effects`
+
+#### `visual_effects.composite_notes`
+- Free-text notes for layered effects, implementation ambiguity, performance trade-offs, or screenshot-only observations
+
+## Field Guidance
+
+### `design_system` (Dimension 1: Structural / Measurable)
+Concrete, token-level values. Extract exact values where visible; estimate from visual inspection otherwise.
+
+- **`color.palette_type`**: "monochromatic", "complementary", "analogous", "triadic", "split-complementary"
+- **`color.contrast_strategy`**: How text/background contrast is managed — "high contrast", "subtle layers", "dark-on-light dominant"
+- **`typography.font_style_notes`**: e.g. "geometric sans with humanist touches"
+- **`spacing.content_density`**: "compact", "comfortable", "spacious"
+- **`spacing.section_rhythm`**: How vertical spacing varies between sections
+- **`layout.alignment_tendency`**: "strict grid", "centered", "asymmetric", "mixed"
+- **`shape.border_usage`**: "none", "subtle 1px", "bold borders", "only on inputs"
+- **`elevation.shadow_style`**: "none", "soft diffused", "hard drop", "layered"
+- **`elevation.depth_cues`**: "shadows", "overlapping layers", "blur/glass", "color intensity"
+- **`motion.philosophy`**: "minimal functional", "playful bouncy", "cinematic", "none"
+- **`components`**: Describe observed patterns — e.g. "ghost buttons with thick borders, rounded inputs with inner shadow"
+
+### `design_style` (Dimension 2: Qualitative / Perceptual)
+Subjective assessments. Use descriptive language.
+
+- **`aesthetic.mood`**: Array of 3–5 mood words, e.g. ["calm", "professional", "warm"]
+- **`aesthetic.genre`**: e.g. "corporate SaaS", "indie creative", "luxury editorial", "neo-brutalist"
+- **`aesthetic.personality_traits`**: As if the design were a person, e.g. ["confident", "approachable", "meticulous"]
+- **`visual_language.complexity`**: "minimal", "moderate", "rich", "maximal"
+- **`visual_language.ornamentation`**: "none", "subtle accents", "decorative", "heavily ornamented"
+- **`visual_language.focal_strategy`**: "single hero element", "distributed interest", "progressive reveal"
+- **`composition.hierarchy_method`**: "scale contrast", "color weight", "spatial isolation", "typographic hierarchy"
+- **`composition.balance_type`**: "symmetric", "asymmetric", "radial", "mosaic"
+- **`interaction_feel.transition_personality`**: "snappy", "smooth glide", "bouncy elastic", "fade-subtle"
+- **`brand_voice_in_ui.cta_style`**: "direct imperative", "friendly invitation", "urgent scarcity", "subtle suggestion"
+
+### `visual_effects` (Dimension 3: Special Rendering / Visual Wizardry)
+Effects beyond standard CSS. These often require Canvas, WebGL, SVG animation, shader programs, or JS animation libraries. When not directly observable from static code, describe them from screenshots or video.
+
+- **`overview.effect_intensity`**: "none", "subtle-accent", "moderate", "heavy-immersive"
+- **`overview.performance_tier`**: "lightweight" (CSS + simple JS), "medium" (Canvas 2D, SVG anim), "heavy" (WebGL, Three.js, shaders)
+- **`overview.fallback_strategy`**: What happens on low-end devices — "disable effects", "reduce to CSS", "static snapshot"
+- **`overview.primary_technology`**: "CSS only", "Canvas 2D", "WebGL/Three.js", "GSAP", "Lottie", "SVG SMIL", "Pixi.js"
+- **`background_effects.type`**: "gradient-animation", "noise-field", "mesh-gradient", "video-bg", "generative-art", "none"
+- **`particle_systems.type`**: "floating-dots", "confetti", "snow", "fireflies", "connected-nodes", "custom"
+- **`particle_systems.params.interaction`**: "mouse-repel", "mouse-attract", "click-burst", "none"
+- **`3d_elements.type`**: "hero-model", "product-viewer", "scene-bg", "text-extrusion", "abstract-geometry"
+- **`3d_elements.params.post_processing`**: e.g. ["bloom", "FXAA", "depth-of-field", "chromatic-aberration"]
+- **`shader_effects.type`**: "noise-distortion", "wave", "morph", "color-shift", "custom-GLSL"
+- **`shader_effects.params.noise_type`**: "perlin", "simplex", "worley", "fbm"
+- **`scroll_effects.parallax.layers`**: Number of depth layers, e.g. "3"
+- **`scroll_effects.scroll_triggered_animations.animation_type`**: "fade-up", "scale-in", "clip-reveal", "counter", "draw-SVG"
+- **`text_effects.type`**: "split-letter-animate", "typewriter", "glitch", "gradient-fill", "3d-extrude", "none"
+- **`text_effects.params.split_strategy`**: "by-char", "by-word", "by-line"
+- **`cursor_effects.type`**: "custom-cursor", "magnetic-buttons", "spotlight", "trail", "none"
+- **`image_effects.type`**: "hover-distortion", "reveal-clip", "parallax-tilt", "rgb-shift", "none"
+- **`image_effects.params.distortion_type`**: "barrel", "wave", "liquid", "glitch"
+- **`glassmorphism_neumorphism.style`**: "glass", "neumorphic-light", "neumorphic-dark", "frosted-layers", "none"
+- **`canvas_drawings.type`**: "generative-lines", "interactive-blobs", "data-visualization", "pattern-fill", "none"
+- **`svg_animations.type`**: "path-draw", "morph-shapes", "logo-reveal", "decorative-loop", "none"
+- **`composite_notes`**: Free-text description of how multiple effects layer together, performance trade-offs, or effects visible only in screenshots that cannot be fully captured in structured fields
diff --git a/builtin-skills/frontend-design/design-taste-frontend/SKILL.md b/builtin-skills/frontend-design/design-taste-frontend/SKILL.md
new file mode 100644
index 00000000..ccc3a2f8
--- /dev/null
+++ b/builtin-skills/frontend-design/design-taste-frontend/SKILL.md
@@ -0,0 +1,226 @@
+---
+name: design-taste-frontend
+description: Senior UI/UX Engineer. Architect digital interfaces overriding default LLM biases. Enforces metric-based rules, strict component architecture, CSS hardware acceleration, and balanced design engineering.
+---
+
+# High-Agency Frontend Skill
+
+## 1. ACTIVE BASELINE CONFIGURATION
+* DESIGN_VARIANCE: 8 (1=Perfect Symmetry, 10=Artsy Chaos)
+* MOTION_INTENSITY: 6 (1=Static/No movement, 10=Cinematic/Magic Physics)
+* VISUAL_DENSITY: 4 (1=Art Gallery/Airy, 10=Pilot Cockpit/Packed Data)
+
+**AI Instruction:** The standard baseline for all generations is strictly set to these values (8, 6, 4). Do not ask the user to edit this file. Otherwise, ALWAYS listen to the user: adapt these values dynamically based on what they explicitly request in their chat prompts. Use these baseline (or user-overridden) values as your global variables to drive the specific logic in Sections 3 through 7.
+
+## 2. DEFAULT ARCHITECTURE & CONVENTIONS
+Unless the user explicitly specifies a different stack, adhere to these structural constraints to maintain consistency:
+
+* **DEPENDENCY VERIFICATION [MANDATORY]:** Before importing ANY 3rd party library (e.g. `framer-motion`, `lucide-react`, `zustand`), you MUST check `package.json`. If the package is missing, you MUST output the installation command (e.g. `npm install package-name`) before providing the code. **Never** assume a library exists.
+* **Framework & Interactivity:** React or Next.js. Default to Server Components (`RSC`). 
+    * **RSC SAFETY:** Global state works ONLY in Client Components. In Next.js, wrap providers in a `"use client"` component.
+    * **INTERACTIVITY ISOLATION:** If Sections 4 or 7 (Motion/Liquid Glass) are active, the specific interactive UI component MUST be extracted as an isolated leaf component with `'use client'` at the very top. Server Components must exclusively render static layouts.
+* **State Management:** Use local `useState`/`useReducer` for isolated UI. Use global state strictly for deep prop-drilling avoidance.
+* **Styling Policy:** Use Tailwind CSS (v3/v4) for 90% of styling. 
+    * **TAILWIND VERSION LOCK:** Check `package.json` first. Do not use v4 syntax in v3 projects. 
+    * **T4 CONFIG GUARD:** For v4, do NOT use `tailwindcss` plugin in `postcss.config.js`. Use `@tailwindcss/postcss` or the Vite plugin.
+* **ANTI-EMOJI POLICY [CRITICAL]:** NEVER use emojis in code, markup, text content, or alt text. Replace symbols with high-quality icons (Radix, Phosphor) or clean SVG primitives. Emojis are BANNED.
+* **Responsiveness & Spacing:**
+  * Standardize breakpoints (`sm`, `md`, `lg`, `xl`).
+  * Contain page layouts using `max-w-[1400px] mx-auto` or `max-w-7xl`.
+  * **Viewport Stability [CRITICAL]:** NEVER use `h-screen` for full-height Hero sections. ALWAYS use `min-h-[100dvh]` to prevent catastrophic layout jumping on mobile browsers (iOS Safari).
+  * **Grid over Flex-Math:** NEVER use complex flexbox percentage math (`w-[calc(33%-1rem)]`). ALWAYS use CSS Grid (`grid grid-cols-1 md:grid-cols-3 gap-6`) for reliable structures.
+* **Icons:** You MUST use exactly `@phosphor-icons/react` or `@radix-ui/react-icons` as the import paths (check installed version). Standardize `strokeWidth` globally (e.g., exclusively use `1.5` or `2.0`).
+
+
+## 3. DESIGN ENGINEERING DIRECTIVES (Bias Correction)
+LLMs have statistical biases toward specific UI cliché patterns. Proactively construct premium interfaces using these engineered rules:
+
+**Rule 1: Deterministic Typography**
+* **Display/Headlines:** Default to `text-4xl md:text-6xl tracking-tighter leading-none`.
+    * **ANTI-SLOP:** Discourage `Inter` for "Premium" or "Creative" vibes. Force unique character using `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`.
+    * **TECHNICAL UI RULE:** Serif fonts are strictly BANNED for Dashboard/Software UIs. For these contexts, use exclusively high-end Sans-Serif pairings (`Geist` + `Geist Mono` or `Satoshi` + `JetBrains Mono`).
+* **Body/Paragraphs:** Default to `text-base text-gray-600 leading-relaxed max-w-[65ch]`.
+
+**Rule 2: Color Calibration**
+* **Constraint:** Max 1 Accent Color. Saturation < 80%.
+* **THE LILA BAN:** The "AI Purple/Blue" aesthetic is strictly BANNED. No purple button glows, no neon gradients. Use absolute neutral bases (Zinc/Slate) with high-contrast, singular accents (e.g. Emerald, Electric Blue, or Deep Rose).
+* **COLOR CONSISTENCY:** Stick to one palette for the entire output. Do not fluctuate between warm and cool grays within the same project.
+
+**Rule 3: Layout Diversification**
+* **ANTI-CENTER BIAS:** Centered Hero/H1 sections are strictly BANNED when `LAYOUT_VARIANCE > 4`. Force "Split Screen" (50/50), "Left Aligned content/Right Aligned asset", or "Asymmetric White-space" structures.
+
+**Rule 4: Materiality, Shadows, and "Anti-Card Overuse"**
+* **DASHBOARD HARDENING:** For `VISUAL_DENSITY > 7`, generic card containers are strictly BANNED. Use logic-grouping via `border-t`, `divide-y`, or purely negative space. Data metrics should breathe without being boxed in unless elevation (z-index) is functionally required.
+* **Execution:** Use cards ONLY when elevation communicates hierarchy. When a shadow is used, tint it to the background hue.
+
+**Rule 5: Interactive UI States**
+* **Mandatory Generation:** LLMs naturally generate "static" successful states. You MUST implement full interaction cycles:
+  * **Loading:** Skeletal loaders matching layout sizes (avoid generic circular spinners).
+  * **Empty States:** Beautifully composed empty states indicating how to populate data.
+  * **Error States:** Clear, inline error reporting (e.g., forms).
+  * **Tactile Feedback:** On `:active`, use `-translate-y-[1px]` or `scale-[0.98]` to simulate a physical push indicating success/action.
+
+**Rule 6: Data & Form Patterns**
+* **Forms:** Label MUST sit above input. Helper text is optional but should exist in markup. Error text below input. Use a standard `gap-2` for input blocks.
+
+## 4. CREATIVE PROACTIVITY (Anti-Slop Implementation)
+To actively combat generic AI designs, systematically implement these high-end coding concepts as your baseline:
+* **"Liquid Glass" Refraction:** When glassmorphism is needed, go beyond `backdrop-blur`. Add a 1px inner border (`border-white/10`) and a subtle inner shadow (`shadow-[inset_0_1px_0_rgba(255,255,255,0.1)]`) to simulate physical edge refraction.
+* **Magnetic Micro-physics (If MOTION_INTENSITY > 5):** Implement buttons that pull slightly toward the mouse cursor. **CRITICAL:** NEVER use React `useState` for magnetic hover or continuous animations. Use EXCLUSIVELY Framer Motion's `useMotionValue` and `useTransform` outside the React render cycle to prevent performance collapse on mobile.
+* **Perpetual Micro-Interactions:** When `MOTION_INTENSITY > 5`, embed continuous, infinite micro-animations (Pulse, Typewriter, Float, Shimmer, Carousel) in standard components (avatars, status dots, backgrounds). Apply premium Spring Physics (`type: "spring", stiffness: 100, damping: 20`) to all interactive elements—no linear easing.
+* **Layout Transitions:** Always utilize Framer Motion's `layout` and `layoutId` props for smooth re-ordering, resizing, and shared element transitions across state changes.
+* **Staggered Orchestration:** Do not mount lists or grids instantly. Use `staggerChildren` (Framer) or CSS cascade (`animation-delay: calc(var(--index) * 100ms)`) to create sequential waterfall reveals. **CRITICAL:** For `staggerChildren`, the Parent (`variants`) and Children MUST reside in the identical Client Component tree. If data is fetched asynchronously, pass the data as props into a centralized Parent Motion wrapper.
+
+## 5. PERFORMANCE GUARDRAILS
+* **DOM Cost:** Apply grain/noise filters exclusively to fixed, pointer-event-none pseudo-elements (e.g., `fixed inset-0 z-50 pointer-events-none`) and NEVER to scrolling containers to prevent continuous GPU repaints and mobile performance degradation.
+* **Hardware Acceleration:** Never animate `top`, `left`, `width`, or `height`. Animate exclusively via `transform` and `opacity`.
+* **Z-Index Restraint:** NEVER spam arbitrary `z-50` or `z-10` unprompted. Use z-indexes strictly for systemic layer contexts (Sticky Navbars, Modals, Overlays).
+
+## 6. TECHNICAL REFERENCE (Dial Definitions)
+
+### DESIGN_VARIANCE (Level 1-10)
+* **1-3 (Predictable):** Flexbox `justify-center`, strict 12-column symmetrical grids, equal paddings.
+* **4-7 (Offset):** Use `margin-top: -2rem` overlapping, varied image aspect ratios (e.g., 4:3 next to 16:9), left-aligned headers over center-aligned data.
+* **8-10 (Asymmetric):** Masonry layouts, CSS Grid with fractional units (e.g., `grid-template-columns: 2fr 1fr 1fr`), massive empty zones (`padding-left: 20vw`). 
+* **MOBILE OVERRIDE:** For levels 4-10, any asymmetric layout above `md:` MUST aggressively fall back to a strict, single-column layout (`w-full`, `px-4`, `py-8`) on viewports `< 768px` to prevent horizontal scrolling and layout breakage.
+
+### MOTION_INTENSITY (Level 1-10)
+* **1-3 (Static):** No automatic animations. CSS `:hover` and `:active` states only.
+* **4-7 (Fluid CSS):** Use `transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1)`. Use `animation-delay` cascades for load-ins. Focus strictly on `transform` and `opacity`. Use `will-change: transform` sparingly.
+* **8-10 (Advanced Choreography):** Complex scroll-triggered reveals or parallax. Use Framer Motion hooks. NEVER use `window.addEventListener('scroll')`.
+
+### VISUAL_DENSITY (Level 1-10)
+* **1-3 (Art Gallery Mode):** Lots of white space. Huge section gaps. Everything feels very expensive and clean.
+* **4-7 (Daily App Mode):** Normal spacing for standard web apps.
+* **8-10 (Cockpit Mode):** Tiny paddings. No card boxes; just 1px lines to separate data. Everything is packed. **Mandatory:** Use Monospace (`font-mono`) for all numbers.
+
+## 7. AI TELLS (Forbidden Patterns)
+To guarantee a premium, non-generic output, you MUST strictly avoid these common AI design signatures unless explicitly requested:
+
+### Visual & CSS
+* **NO Neon/Outer Glows:** Do not use default `box-shadow` glows or auto-glows. Use inner borders or subtle tinted shadows.
+* **NO Pure Black:** Never use `#000000`. Use Off-Black, Zinc-950, or Charcoal.
+* **NO Oversaturated Accents:** Desaturate accents to blend elegantly with neutrals.
+* **NO Excessive Gradient Text:** Do not use text-fill gradients for large headers.
+* **NO Custom Mouse Cursors:** They are outdated and ruin performance/accessibility.
+
+### Typography
+* **NO Inter Font:** Banned. Use `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`.
+* **NO Oversized H1s:** The first heading should not scream. Control hierarchy with weight and color, not just massive scale.
+* **Serif Constraints:** Use Serif fonts ONLY for creative/editorial designs. **NEVER** use Serif on clean Dashboards.
+
+### Layout & Spacing
+* **Align & Space Perfectly:** Ensure padding and margins are mathematically perfect. Avoid floating elements with awkward gaps.
+* **NO 3-Column Card Layouts:** The generic "3 equal cards horizontally" feature row is BANNED. Use a 2-column Zig-Zag, asymmetric grid, or horizontal scrolling approach instead.
+
+### Content & Data (The "Jane Doe" Effect)
+* **NO Generic Names:** "John Doe", "Sarah Chan", or "Jack Su" are banned. Use highly creative, realistic-sounding names.
+* **NO Generic Avatars:** DO NOT use standard SVG "egg" or Lucide user icons for avatars. Use creative, believable photo placeholders or specific styling.
+* **NO Fake Numbers:** Avoid predictable outputs like `99.99%`, `50%`, or basic phone numbers (`1234567`). Use organic, messy data (`47.2%`, `+1 (312) 847-1928`).
+* **NO Startup Slop Names:** "Acme", "Nexus", "SmartFlow". Invent premium, contextual brand names.
+* **NO Filler Words:** Avoid AI copywriting clichés like "Elevate", "Seamless", "Unleash", or "Next-Gen". Use concrete verbs.
+
+### External Resources & Components
+* **NO Broken Unsplash Links:** Do not use Unsplash. Use absolute, reliable placeholders like `https://picsum.photos/seed/{random_string}/800/600` or SVG UI Avatars.
+* **shadcn/ui Customization:** You may use `shadcn/ui`, but NEVER in its generic default state. You MUST customize the radii, colors, and shadows to match the high-end project aesthetic.
+* **Production-Ready Cleanliness:** Code must be extremely clean, visually striking, memorable, and meticulously refined in every detail.
+
+## 8. THE CREATIVE ARSENAL (High-End Inspiration)
+Do not default to generic UI. Pull from this library of advanced concepts to ensure the output is visually striking and memorable. When appropriate, leverage **GSAP (ScrollTrigger/Parallax)** for complex scrolltelling or **ThreeJS/WebGL** for 3D/Canvas animations, rather than basic CSS motion. **CRITICAL:** Never mix GSAP/ThreeJS with Framer Motion in the same component tree. Default to Framer Motion for UI/Bento interactions. Use GSAP/ThreeJS EXCLUSIVELY for isolated full-page scrolltelling or canvas backgrounds, wrapped in strict useEffect cleanup blocks.
+
+### The Standard Hero Paradigm
+* Stop doing centered text over a dark image. Try asymmetric Hero sections: Text cleanly aligned to the left or right. The background should feature a high-quality, relevant image with a subtle stylistic fade (darkening or lightening gracefully into the background color depending on if it is Light or Dark mode).
+
+### Navigation & Menüs
+* **Mac OS Dock Magnification:** Nav-bar at the edge; icons scale fluidly on hover.
+* **Magnetic Button:** Buttons that physically pull toward the cursor.
+* **Gooey Menu:** Sub-items detach from the main button like a viscous liquid.
+* **Dynamic Island:** A pill-shaped UI component that morphs to show status/alerts.
+* **Contextual Radial Menu:** A circular menu expanding exactly at the click coordinates.
+* **Floating Speed Dial:** A FAB that springs out into a curved line of secondary actions.
+* **Mega Menu Reveal:** Full-screen dropdowns that stagger-fade complex content.
+
+### Layout & Grids
+* **Bento Grid:** Asymmetric, tile-based grouping (e.g., Apple Control Center).
+* **Masonry Layout:** Staggered grid without fixed row heights (e.g., Pinterest).
+* **Chroma Grid:** Grid borders or tiles showing subtle, continuously animating color gradients.
+* **Split Screen Scroll:** Two screen halves sliding in opposite directions on scroll.
+* **Curtain Reveal:** A Hero section parting in the middle like a curtain on scroll.
+
+### Cards & Containers
+* **Parallax Tilt Card:** A 3D-tilting card tracking the mouse coordinates.
+* **Spotlight Border Card:** Card borders that illuminate dynamically under the cursor.
+* **Glassmorphism Panel:** True frosted glass with inner refraction borders.
+* **Holographic Foil Card:** Iridescent, rainbow light reflections shifting on hover.
+* **Tinder Swipe Stack:** A physical stack of cards the user can swipe away.
+* **Morphing Modal:** A button that seamlessly expands into its own full-screen dialog container.
+
+### Scroll-Animations
+* **Sticky Scroll Stack:** Cards that stick to the top and physically stack over each other.
+* **Horizontal Scroll Hijack:** Vertical scroll translates into a smooth horizontal gallery pan.
+* **Locomotive Scroll Sequence:** Video/3D sequences where framerate is tied directly to the scrollbar.
+* **Zoom Parallax:** A central background image zooming in/out seamlessly as you scroll.
+* **Scroll Progress Path:** SVG vector lines or routes that draw themselves as the user scrolls.
+* **Liquid Swipe Transition:** Page transitions that wipe the screen like a viscous liquid.
+
+### Galleries & Media
+* **Dome Gallery:** A 3D gallery feeling like a panoramic dome.
+* **Coverflow Carousel:** 3D carousel with the center focused and edges angled back.
+* **Drag-to-Pan Grid:** A boundless grid you can freely drag in any compass direction.
+* **Accordion Image Slider:** Narrow vertical/horizontal image strips that expand fully on hover.
+* **Hover Image Trail:** The mouse leaves a trail of popping/fading images behind it.
+* **Glitch Effect Image:** Brief RGB-channel shifting digital distortion on hover.
+
+### Typography & Text
+* **Kinetic Marquee:** Endless text bands that reverse direction or speed up on scroll.
+* **Text Mask Reveal:** Massive typography acting as a transparent window to a video background.
+* **Text Scramble Effect:** Matrix-style character decoding on load or hover.
+* **Circular Text Path:** Text curved along a spinning circular path.
+* **Gradient Stroke Animation:** Outlined text with a gradient continuously running along the stroke.
+* **Kinetic Typography Grid:** A grid of letters dodging or rotating away from the cursor.
+
+### Micro-Interactions & Effects
+* **Particle Explosion Button:** CTAs that shatter into particles upon success.
+* **Liquid Pull-to-Refresh:** Mobile reload indicators acting like detaching water droplets.
+* **Skeleton Shimmer:** Shifting light reflections moving across placeholder boxes.
+* **Directional Hover Aware Button:** Hover fill entering from the exact side the mouse entered.
+* **Ripple Click Effect:** Visual waves rippling precisely from the click coordinates.
+* **Animated SVG Line Drawing:** Vectors that draw their own contours in real-time.
+* **Mesh Gradient Background:** Organic, lava-lamp-like animated color blobs.
+* **Lens Blur Depth:** Dynamic focus blurring background UI layers to highlight a foreground action.
+
+## 9. THE "MOTION-ENGINE" BENTO PARADIGM
+When generating modern SaaS dashboards or feature sections, you MUST utilize the following "Bento 2.0" architecture and motion philosophy. This goes beyond static cards and enforces a "Vercel-core meets Dribbble-clean" aesthetic heavily reliant on perpetual physics.
+
+### A. Core Design Philosophy
+* **Aesthetic:** High-end, minimal, and functional.
+* **Palette:** Background in `#f9fafb`. Cards are pure white (`#ffffff`) with a 1px border of `border-slate-200/50`.
+* **Surfaces:** Use `rounded-[2.5rem]` for all major containers. Apply a "diffusion shadow" (a very light, wide-spreading shadow, e.g., `shadow-[0_20px_40px_-15px_rgba(0,0,0,0.05)]`) to create depth without clutter.
+* **Typography:** Strict `Geist`, `Satoshi`, or `Cabinet Grotesk` font stack. Use subtle tracking (`tracking-tight`) for headers.
+* **Labels:** Titles and descriptions must be placed **outside and below** the cards to maintain a clean, gallery-style presentation.
+* **Pixel-Perfection:** Use generous `p-8` or `p-10` padding inside cards.
+
+### B. The Animation Engine Specs (Perpetual Motion)
+All cards must contain **"Perpetual Micro-Interactions."** Use the following Framer Motion principles:
+* **Spring Physics:** No linear easing. Use `type: "spring", stiffness: 100, damping: 20` for a premium, weighty feel.
+* **Layout Transitions:** Heavily utilize the `layout` and `layoutId` props to ensure smooth re-ordering, resizing, and shared element state transitions.
+* **Infinite Loops:** Every card must have an "Active State" that loops infinitely (Pulse, Typewriter, Float, or Carousel) to ensure the dashboard feels "alive".
+* **Performance:** Wrap dynamic lists in `<AnimatePresence>` and optimize for 60fps. **PERFORMANCE CRITICAL:** Any perpetual motion or infinite loop MUST be memoized (React.memo) and completely isolated in its own microscopic Client Component. Never trigger re-renders in the parent layout.
+
+### C. The 5-Card Archetypes (Micro-Animation Specs)
+Implement these specific micro-animations when constructing Bento grids (e.g., Row 1: 3 cols | Row 2: 2 cols split 70/30):
+1. **The Intelligent List:** A vertical stack of items with an infinite auto-sorting loop. Items swap positions using `layoutId`, simulating an AI prioritizing tasks in real-time.
+2. **The Command Input:** A search/AI bar with a multi-step Typewriter Effect. It cycles through complex prompts, including a blinking cursor and a "processing" state with a shimmering loading gradient.
+3. **The Live Status:** A scheduling interface with "breathing" status indicators. Include a pop-up notification badge that emerges with an "Overshoot" spring effect, stays for 3 seconds, and vanishes.
+4. **The Wide Data Stream:** A horizontal "Infinite Carousel" of data cards or metrics. Ensure the loop is seamless (using `x: ["0%", "-100%"]`) with a speed that feels effortless.
+5. **The Contextual UI (Focus Mode):** A document view that animates a staggered highlight of a text block, followed by a "Float-in" of a floating action toolbar with micro-icons.
+
+## 10. FINAL PRE-FLIGHT CHECK
+Evaluate your code against this matrix before outputting. This is the **last** filter you apply to your logic.
+- [ ] Is global state used appropriately to avoid deep prop-drilling rather than arbitrarily?
+- [ ] Is mobile layout collapse (`w-full`, `px-4`, `max-w-7xl mx-auto`) guaranteed for high-variance designs?
+- [ ] Do full-height sections safely use `min-h-[100dvh]` instead of the bugged `h-screen`?
+- [ ] Do `useEffect` animations contain strict cleanup functions?
+- [ ] Are empty, loading, and error states provided?
+- [ ] Are cards omitted in favor of spacing where possible?
+- [ ] Did you strictly isolate CPU-heavy perpetual animations in their own Client Components?
diff --git a/builtin-skills/frontend-design/frontend-design/SKILL.md b/builtin-skills/frontend-design/frontend-design/SKILL.md
new file mode 100644
index 00000000..600b6db4
--- /dev/null
+++ b/builtin-skills/frontend-design/frontend-design/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
\ No newline at end of file
diff --git a/builtin-skills/frontend-design/high-end-visual-design/SKILL.md b/builtin-skills/frontend-design/high-end-visual-design/SKILL.md
new file mode 100644
index 00000000..4038f41e
--- /dev/null
+++ b/builtin-skills/frontend-design/high-end-visual-design/SKILL.md
@@ -0,0 +1,98 @@
+---
+name: high-end-visual-design
+description: Teaches the AI to design like a high-end agency. Defines the exact fonts, spacing, shadows, card structures, and animations that make a website feel expensive. Blocks all the common defaults that make AI designs look cheap or generic.
+---
+
+# Agent Skill: Principal UI/UX Architect & Motion Choreographer (Awwwards-Tier)
+
+## 1. Meta Information & Core Directive
+- **Persona:** `Vanguard_UI_Architect`
+- **Objective:** You engineer $150k+ agency-level digital experiences, not just websites. Your output must exude haptic depth, cinematic spatial rhythm, obsessive micro-interactions, and flawless fluid motion. 
+- **The Variance Mandate:** NEVER generate the exact same layout or aesthetic twice in a row. You must dynamically combine different premium layout archetypes and texture profiles while strictly adhering to the elite "Apple-esque / Linear-tier" design language.
+
+## 2. THE "ABSOLUTE ZERO" DIRECTIVE (STRICT ANTI-PATTERNS)
+If your generated code includes ANY of the following, the design instantly fails:
+- **Banned Fonts:** Inter, Roboto, Arial, Open Sans, Helvetica. (Assume premium fonts like `Geist`, `Clash Display`, `PP Editorial New`, or `Plus Jakarta Sans` are available).
+- **Banned Icons:** Standard thick-stroked Lucide, FontAwesome, or Material Icons. Use only ultra-light, precise lines (e.g., Phosphor Light, Remix Line).
+- **Banned Borders & Shadows:** Generic 1px solid gray borders. Harsh, dark drop shadows (`shadow-md`, `rgba(0,0,0,0.3)`). 
+- **Banned Layouts:** Edge-to-edge sticky navbars glued to the top. Symmetrical, boring 3-column Bootstrap-style grids without massive whitespace gaps.
+- **Banned Motion:** Standard `linear` or `ease-in-out` transitions. Instant state changes without interpolation.
+
+## 3. THE CREATIVE VARIANCE ENGINE
+Before writing code, silently "roll the dice" and select ONE combination from the following archetypes based on the prompt's context to ensure the output is uniquely tailored but always premium:
+
+### A. Vibe & Texture Archetypes (Pick 1)
+1. **Ethereal Glass (SaaS / AI / Tech):** Deepest OLED black (`#050505`), radial mesh gradients (e.g., subtle glowing purple/emerald orbs) in the background. Vantablack cards with heavy `backdrop-blur-2xl` and pure white/10 hairlines. Wide geometric Grotesk typography.
+2. **Editorial Luxury (Lifestyle / Real Estate / Agency):** Warm creams (`#FDFBF7`), muted sage, or deep espresso tones. High-contrast Variable Serif fonts for massive headings. Subtle CSS noise/film-grain overlay (`opacity-[0.03]`) for a physical paper feel.
+3. **Soft Structuralism (Consumer / Health / Portfolio):** Silver-grey or completely white backgrounds. Massive bold Grotesk typography. Airy, floating components with unbelievably soft, highly diffused ambient shadows.
+
+### B. Layout Archetypes (Pick 1)
+1. **The Asymmetrical Bento:** A masonry-like CSS Grid of varying card sizes (e.g., `col-span-8 row-span-2` next to stacked `col-span-4` cards) to break visual monotony.
+   - **Mobile Collapse:** Falls back to a single-column stack (`grid-cols-1`) with generous vertical gaps (`gap-6`). All `col-span` overrides reset to `col-span-1`.
+2. **The Z-Axis Cascade:** Elements are stacked like physical cards, slightly overlapping each other with varying depths of field, some with a subtle `-2deg` or `3deg` rotation to break the digital grid.
+   - **Mobile Collapse:** Remove all rotations and negative-margin overlaps below `768px`. Stack vertically with standard spacing. Overlapping elements cause touch-target conflicts on mobile.
+3. **The Editorial Split:** Massive typography on the left half (`w-1/2`), with interactive, scrollable horizontal image pills or staggered interactive cards on the right.
+   - **Mobile Collapse:** Converts to a full-width vertical stack (`w-full`). Typography block sits on top, interactive content flows below with horizontal scroll preserved if needed.
+
+**Mobile Override (Universal):** Any asymmetric layout above `md:` MUST aggressively fall back to `w-full`, `px-4`, `py-8` on viewports below `768px`. Never use `h-screen` for full-height sections — always use `min-h-[100dvh]` to prevent iOS Safari viewport jumping.
+
+## 4. HAPTIC MICRO-AESTHETICS (COMPONENT MASTERY)
+
+### A. The "Double-Bezel" (Doppelrand / Nested Architecture)
+Never place a premium card, image, or container flatly on the background. They must look like physical, machined hardware (like a glass plate sitting in an aluminum tray) using nested enclosures.
+- **Outer Shell:** A wrapper `div` with a subtle background (`bg-black/5` or `bg-white/5`), a hairline outer border (`ring-1 ring-black/5` or `border border-white/10`), a specific padding (e.g., `p-1.5` or `p-2`), and a large outer radius (`rounded-[2rem]`).
+- **Inner Core:** The actual content container inside the shell. It has its own distinct background color, its own inner highlight (`shadow-[inset_0_1px_1px_rgba(255,255,255,0.15)]`), and a mathematically calculated smaller radius (e.g., `rounded-[calc(2rem-0.375rem)]`) for concentric curves.
+
+### B. Nested CTA & "Island" Button Architecture
+- **Structure:** Primary interactive buttons must be fully rounded pills (`rounded-full`) with generous padding (`px-6 py-3`). 
+- **The "Button-in-Button" Trailing Icon:** If a button has an arrow (`↗`), it NEVER sits naked next to the text. It must be nested inside its own distinct circular wrapper (e.g., `w-8 h-8 rounded-full bg-black/5 dark:bg-white/10 flex items-center justify-center`) placed completely flush with the main button's right inner padding.
+
+### C. Spatial Rhythm & Tension
+- **Macro-Whitespace:** Double your standard padding. Use `py-24` to `py-40` for sections. Allow the design to breathe heavily.
+- **Eyebrow Tags:** Precede major H1/H2s with a microscopic, pill-shaped badge (`rounded-full px-3 py-1 text-[10px] uppercase tracking-[0.2em] font-medium`).
+
+## 5. MOTION CHOREOGRAPHY (FLUID DYNAMICS)
+Never use default transitions. All motion must simulate real-world mass and spring physics. Use custom cubic-beziers (e.g., `transition-all duration-700 ease-[cubic-bezier(0.32,0.72,0,1)]`).
+
+### A. The "Fluid Island" Nav & Hamburger Reveal
+- **Closed State:** The Navbar is a floating glass pill detached from the top (`mt-6`, `mx-auto`, `w-max`, `rounded-full`).
+- **The Hamburger Morph:** On click, the 2 or 3 lines of the hamburger icon must fluidly rotate and translate to form a perfect 'X' (`rotate-45` and `-rotate-45` with absolute positioning), not just disappear.
+- **The Modal Expansion:** The menu should open as a massive, screen-filling overlay with a heavy glass effect (`backdrop-blur-3xl bg-black/80` or `bg-white/80`). 
+- **Staggered Mask Reveal:** The navigation links inside the expanded state do not just appear. They fade in and slide up from an invisible box (`translate-y-12 opacity-0` to `translate-y-0 opacity-100`) with a staggered delay (`delay-100`, `delay-150`, `delay-200` for each item).
+
+### B. Magnetic Button Hover Physics
+- Use the `group` utility. On hover, do not just change the background color.
+- Scale the entire button down slightly (`active:scale-[0.98]`) to simulate physical pressing.
+- The nested inner icon circle should translate diagonally (`group-hover:translate-x-1 group-hover:-translate-y-[1px]`) and scale up slightly (`scale-105`), creating internal kinetic tension.
+
+### C. Scroll Interpolation (Entry Animations)
+- Elements never appear statically on load. As they enter the viewport, they must execute a gentle, heavy fade-up (`translate-y-16 blur-md opacity-0` resolving to `translate-y-0 blur-0 opacity-100` over 800ms+).
+- For JavaScript-driven scroll reveals, use `IntersectionObserver` or Framer Motion's `whileInView`. Never use `window.addEventListener('scroll')` — it causes continuous reflows and kills mobile performance.
+
+## 6. PERFORMANCE GUARDRAILS
+- **GPU-Safe Animation:** Never animate `top`, `left`, `width`, or `height`. Animate exclusively via `transform` and `opacity`. Use `will-change: transform` sparingly and only on elements that are actively animating.
+- **Blur Constraints:** Apply `backdrop-blur` only to fixed or sticky elements (navbars, overlays). Never apply blur filters to scrolling containers or large content areas — this causes continuous GPU repaints and severe mobile frame drops.
+- **Grain/Noise Overlays:** Apply noise textures exclusively to fixed, `pointer-events-none` pseudo-elements (`position: fixed; inset: 0; z-index: 50`). Never attach them to scrolling containers.
+- **Z-Index Discipline:** Do not use arbitrary `z-50` or `z-[9999]`. Reserve z-indexes strictly for systemic layers: sticky nav, modals, overlays, tooltips.
+
+## 7. EXECUTION PROTOCOL
+When generating UI code, follow this exact sequence:
+1. **[SILENT THOUGHT]** Roll the Variance Engine (Section 3). Choose your Vibe and Layout Archetypes based on the prompt's context to ensure a unique output.
+2. **[SCAFFOLD]** Establish the background texture, macro-whitespace scale, and massive typography sizes.
+3. **[ARCHITECT]** Build the DOM strictly using the "Double-Bezel" (Doppelrand) technique for all major cards, inputs, and feature grids. Use exaggerated squircle radii (`rounded-[2rem]`).
+4. **[CHOREOGRAPH]** Inject the custom `cubic-bezier` transitions, the staggered navigation reveals, and the button-in-button hover physics.
+5. **[OUTPUT]** Deliver flawless, pixel-perfect React/Tailwind/HTML code. Do not include basic, generic fallbacks.
+
+## 8. PRE-OUTPUT CHECKLIST
+Evaluate your code against this matrix before delivering. This is the last filter.
+- [ ] No banned fonts, icons, borders, shadows, layouts, or motion patterns from Section 2 are present
+- [ ] A Vibe Archetype and Layout Archetype from Section 3 were consciously selected and applied
+- [ ] All major cards and containers use the Double-Bezel nested architecture (outer shell + inner core)
+- [ ] CTA buttons use the Button-in-Button trailing icon pattern where applicable
+- [ ] Section padding is at minimum `py-24` — the layout breathes heavily
+- [ ] All transitions use custom cubic-bezier curves — no `linear` or `ease-in-out`
+- [ ] Scroll entry animations are present — no element appears statically
+- [ ] Layout collapses gracefully below `768px` to single-column with `w-full` and `px-4`
+- [ ] All animations use only `transform` and `opacity` — no layout-triggering properties
+- [ ] `backdrop-blur` is only applied to fixed/sticky elements, never to scrolling content
+- [ ] The overall impression reads as "$150k agency build", not "template with nice fonts"
diff --git a/builtin-skills/frontend-design/senior-frontend/SKILL.md b/builtin-skills/frontend-design/senior-frontend/SKILL.md
new file mode 100644
index 00000000..4a1214e6
--- /dev/null
+++ b/builtin-skills/frontend-design/senior-frontend/SKILL.md
@@ -0,0 +1,473 @@
+---
+name: "senior-frontend"
+description: Frontend development skill for React, Next.js, TypeScript, and Tailwind CSS applications. Use when building React components, optimizing Next.js performance, analyzing bundle sizes, scaffolding frontend projects, implementing accessibility, or reviewing frontend code quality.
+---
+
+# Senior Frontend
+
+Frontend development patterns, performance optimization, and automation tools for React/Next.js applications.
+
+## Table of Contents
+
+- [Project Scaffolding](#project-scaffolding)
+- [Component Generation](#component-generation)
+- [Bundle Analysis](#bundle-analysis)
+- [React Patterns](#react-patterns)
+- [Next.js Optimization](#nextjs-optimization)
+- [Accessibility and Testing](#accessibility-and-testing)
+
+---
+
+## Project Scaffolding
+
+Generate a new Next.js or React project with TypeScript, Tailwind CSS, and best practice configurations.
+
+### Workflow: Create New Frontend Project
+
+1. Run the scaffolder with your project name and template:
+   ```bash
+   python scripts/frontend_scaffolder.py my-app --template nextjs
+   ```
+
+2. Add optional features (auth, api, forms, testing, storybook):
+   ```bash
+   python scripts/frontend_scaffolder.py dashboard --template nextjs --features auth,api
+   ```
+
+3. Navigate to the project and install dependencies:
+   ```bash
+   cd my-app && npm install
+   ```
+
+4. Start the development server:
+   ```bash
+   npm run dev
+   ```
+
+### Scaffolder Options
+
+| Option | Description |
+|--------|-------------|
+| `--template nextjs` | Next.js 14+ with App Router and Server Components |
+| `--template react` | React + Vite with TypeScript |
+| `--features auth` | Add NextAuth.js authentication |
+| `--features api` | Add React Query + API client |
+| `--features forms` | Add React Hook Form + Zod validation |
+| `--features testing` | Add Vitest + Testing Library |
+| `--dry-run` | Preview files without creating them |
+
+### Generated Structure (Next.js)
+
+```
+my-app/
+├── app/
+│   ├── layout.tsx        # Root layout with fonts
+│   ├── page.tsx          # Home page
+│   ├── globals.css       # Tailwind + CSS variables
+│   └── api/health/route.ts
+├── components/
+│   ├── ui/               # Button, Input, Card
+│   └── layout/           # Header, Footer, Sidebar
+├── hooks/                # useDebounce, useLocalStorage
+├── lib/                  # utils (cn), constants
+├── types/                # TypeScript interfaces
+├── tailwind.config.ts
+├── next.config.js
+└── package.json
+```
+
+---
+
+## Component Generation
+
+Generate React components with TypeScript, tests, and Storybook stories.
+
+### Workflow: Create a New Component
+
+1. Generate a client component:
+   ```bash
+   python scripts/component_generator.py Button --dir src/components/ui
+   ```
+
+2. Generate a server component:
+   ```bash
+   python scripts/component_generator.py ProductCard --type server
+   ```
+
+3. Generate with test and story files:
+   ```bash
+   python scripts/component_generator.py UserProfile --with-test --with-story
+   ```
+
+4. Generate a custom hook:
+   ```bash
+   python scripts/component_generator.py FormValidation --type hook
+   ```
+
+### Generator Options
+
+| Option | Description |
+|--------|-------------|
+| `--type client` | Client component with 'use client' (default) |
+| `--type server` | Async server component |
+| `--type hook` | Custom React hook |
+| `--with-test` | Include test file |
+| `--with-story` | Include Storybook story |
+| `--flat` | Create in output dir without subdirectory |
+| `--dry-run` | Preview without creating files |
+
+### Generated Component Example
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+import { cn } from '@/lib/utils';
+
+interface ButtonProps {
+  className?: string;
+  children?: React.ReactNode;
+}
+
+export function Button({ className, children }: ButtonProps) {
+  return (
+    <div className={cn('', className)}>
+      {children}
+    </div>
+  );
+}
+```
+
+---
+
+## Bundle Analysis
+
+Analyze package.json and project structure for bundle optimization opportunities.
+
+### Workflow: Optimize Bundle Size
+
+1. Run the analyzer on your project:
+   ```bash
+   python scripts/bundle_analyzer.py /path/to/project
+   ```
+
+2. Review the health score and issues:
+   ```
+   Bundle Health Score: 75/100 (C)
+
+   HEAVY DEPENDENCIES:
+     moment (290KB)
+       Alternative: date-fns (12KB) or dayjs (2KB)
+
+     lodash (71KB)
+       Alternative: lodash-es with tree-shaking
+   ```
+
+3. Apply the recommended fixes by replacing heavy dependencies.
+
+4. Re-run with verbose mode to check import patterns:
+   ```bash
+   python scripts/bundle_analyzer.py . --verbose
+   ```
+
+### Bundle Score Interpretation
+
+| Score | Grade | Action |
+|-------|-------|--------|
+| 90-100 | A | Bundle is well-optimized |
+| 80-89 | B | Minor optimizations available |
+| 70-79 | C | Replace heavy dependencies |
+| 60-69 | D | Multiple issues need attention |
+| 0-59 | F | Critical bundle size problems |
+
+### Heavy Dependencies Detected
+
+The analyzer identifies these common heavy packages:
+
+| Package | Size | Alternative |
+|---------|------|-------------|
+| moment | 290KB | date-fns (12KB) or dayjs (2KB) |
+| lodash | 71KB | lodash-es with tree-shaking |
+| axios | 14KB | Native fetch or ky (3KB) |
+| jquery | 87KB | Native DOM APIs |
+| @mui/material | Large | shadcn/ui or Radix UI |
+
+---
+
+## React Patterns
+
+Reference: `references/react_patterns.md`
+
+### Compound Components
+
+Share state between related components:
+
+```tsx
+const Tabs = ({ children }) => {
+  const [active, setActive] = useState(0);
+  return (
+    <TabsContext.Provider value={{ active, setActive }}>
+      {children}
+    </TabsContext.Provider>
+  );
+};
+
+Tabs.List = TabList;
+Tabs.Panel = TabPanel;
+
+// Usage
+<Tabs>
+  <Tabs.List>
+    <Tabs.Tab>One</Tabs.Tab>
+    <Tabs.Tab>Two</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel>Content 1</Tabs.Panel>
+  <Tabs.Panel>Content 2</Tabs.Panel>
+</Tabs>
+```
+
+### Custom Hooks
+
+Extract reusable logic:
+
+```tsx
+function useDebounce<T>(value: T, delay = 500): T {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debouncedValue;
+}
+
+// Usage
+const debouncedSearch = useDebounce(searchTerm, 300);
+```
+
+### Render Props
+
+Share rendering logic:
+
+```tsx
+function DataFetcher({ url, render }) {
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch(url).then(r => r.json()).then(setData).finally(() => setLoading(false));
+  }, [url]);
+
+  return render({ data, loading });
+}
+
+// Usage
+<DataFetcher
+  url="/api/users"
+  render={({ data, loading }) =>
+    loading ? <Spinner /> : <UserList users={data} />
+  }
+/>
+```
+
+---
+
+## Next.js Optimization
+
+Reference: `references/nextjs_optimization_guide.md`
+
+### Server vs Client Components
+
+Use Server Components by default. Add 'use client' only when you need:
+- Event handlers (onClick, onChange)
+- State (useState, useReducer)
+- Effects (useEffect)
+- Browser APIs
+
+```tsx
+// Server Component (default) - no 'use client'
+async function ProductPage({ params }) {
+  const product = await getProduct(params.id);  // Server-side fetch
+
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <AddToCartButton productId={product.id} />  {/* Client component */}
+    </div>
+  );
+}
+
+// Client Component
+'use client';
+function AddToCartButton({ productId }) {
+  const [adding, setAdding] = useState(false);
+  return <button onClick={() => addToCart(productId)}>Add</button>;
+}
+```
+
+### Image Optimization
+
+```tsx
+import Image from 'next/image';
+
+// Above the fold - load immediately
+<Image
+  src="/hero.jpg"
+  alt="Hero"
+  width={1200}
+  height={600}
+  priority
+/>
+
+// Responsive image with fill
+<div className="relative aspect-video">
+  <Image
+    src="/product.jpg"
+    alt="Product"
+    fill
+    sizes="(max-width: 768px) 100vw, 50vw"
+    className="object-cover"
+  />
+</div>
+```
+
+### Data Fetching Patterns
+
+```tsx
+// Parallel fetching
+async function Dashboard() {
+  const [user, stats] = await Promise.all([
+    getUser(),
+    getStats()
+  ]);
+  return <div>...</div>;
+}
+
+// Streaming with Suspense
+async function ProductPage({ params }) {
+  return (
+    <div>
+      <ProductDetails id={params.id} />
+      <Suspense fallback={<ReviewsSkeleton />}>
+        <Reviews productId={params.id} />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+---
+
+## Accessibility and Testing
+
+Reference: `references/frontend_best_practices.md`
+
+### Accessibility Checklist
+
+1. **Semantic HTML**: Use proper elements (`<button>`, `<nav>`, `<main>`)
+2. **Keyboard Navigation**: All interactive elements focusable
+3. **ARIA Labels**: Provide labels for icons and complex widgets
+4. **Color Contrast**: Minimum 4.5:1 for normal text
+5. **Focus Indicators**: Visible focus states
+
+```tsx
+// Accessible button
+<button
+  type="button"
+  aria-label="Close dialog"
+  onClick={onClose}
+  className="focus-visible:ring-2 focus-visible:ring-blue-500"
+>
+  <XIcon aria-hidden="true" />
+</button>
+
+// Skip link for keyboard users
+<a href="#main-content" className="sr-only focus:not-sr-only">
+  Skip to main content
+</a>
+```
+
+### Testing Strategy
+
+```tsx
+// Component test with React Testing Library
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('button triggers action on click', async () => {
+  const onClick = vi.fn();
+  render(<Button onClick={onClick}>Click me</Button>);
+
+  await userEvent.click(screen.getByRole('button'));
+  expect(onClick).toHaveBeenCalledTimes(1);
+});
+
+// Test accessibility
+test('dialog is accessible', async () => {
+  render(<Dialog open={true} title="Confirm" />);
+
+  expect(screen.getByRole('dialog')).toBeInTheDocument();
+  expect(screen.getByRole('dialog')).toHaveAttribute('aria-labelledby');
+});
+```
+
+---
+
+## Quick Reference
+
+### Common Next.js Config
+
+```js
+// next.config.js
+const nextConfig = {
+  images: {
+    remotePatterns: [{ hostname: "cdnexamplecom" }],
+    formats: ['image/avif', 'image/webp'],
+  },
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@heroicons/react'],
+  },
+};
+```
+
+### Tailwind CSS Utilities
+
+```tsx
+// Conditional classes with cn()
+import { cn } from '@/lib/utils';
+
+<button className={cn(
+  'px-4 py-2 rounded',
+  variant === 'primary' && 'bg-blue-500 text-white',
+  disabled && 'opacity-50 cursor-not-allowed'
+)} />
+```
+
+### TypeScript Patterns
+
+```tsx
+// Props with children
+interface CardProps {
+  className?: string;
+  children: React.ReactNode;
+}
+
+// Generic component
+interface ListProps<T> {
+  items: T[];
+  renderItem: (item: T) => React.ReactNode;
+}
+
+function List<T>({ items, renderItem }: ListProps<T>) {
+  return <ul>{items.map(renderItem)}</ul>;
+}
+```
+
+---
+
+## Resources
+
+- React Patterns: `references/react_patterns.md`
+- Next.js Optimization: `references/nextjs_optimization_guide.md`
+- Best Practices: `references/frontend_best_practices.md`
diff --git a/builtin-skills/frontend-design/senior-frontend/references/frontend_best_practices.md b/builtin-skills/frontend-design/senior-frontend/references/frontend_best_practices.md
new file mode 100644
index 00000000..dfa106a4
--- /dev/null
+++ b/builtin-skills/frontend-design/senior-frontend/references/frontend_best_practices.md
@@ -0,0 +1,806 @@
+# Frontend Best Practices
+
+Modern frontend development standards for accessibility, testing, TypeScript, and Tailwind CSS.
+
+---
+
+## Table of Contents
+
+- [Accessibility (a11y)](#accessibility-a11y)
+- [Testing Strategies](#testing-strategies)
+- [TypeScript Patterns](#typescript-patterns)
+- [Tailwind CSS](#tailwind-css)
+- [Project Structure](#project-structure)
+- [Security](#security)
+
+---
+
+## Accessibility (a11y)
+
+### Semantic HTML
+
+```tsx
+// BAD - Divs for everything
+<div onClick={handleClick}>Click me</div>
+<div class="header">...</div>
+<div class="nav">...</div>
+
+// GOOD - Semantic elements
+<button onClick={handleClick}>Click me</button>
+<header>...</header>
+<nav>...</nav>
+<main>...</main>
+<article>...</article>
+<aside>...</aside>
+<footer>...</footer>
+```
+
+### Keyboard Navigation
+
+```tsx
+// Ensure all interactive elements are keyboard accessible
+function Modal({ isOpen, onClose, children }: ModalProps) {
+  const modalRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (isOpen) {
+      // Focus first focusable element
+      const focusable = modalRef.current?.querySelectorAll(
+        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+      );
+      (focusable?.[0] as HTMLElement)?.focus();
+
+      // Trap focus within modal
+      const handleTab = (e: KeyboardEvent) => {
+        if (e.key === 'Tab' && focusable) {
+          const first = focusable[0] as HTMLElement;
+          const last = focusable[focusable.length - 1] as HTMLElement;
+
+          if (e.shiftKey && document.activeElement === first) {
+            e.preventDefault();
+            last.focus();
+          } else if (!e.shiftKey && document.activeElement === last) {
+            e.preventDefault();
+            first.focus();
+          }
+        }
+
+        if (e.key === 'Escape') {
+          onClose();
+        }
+      };
+
+      document.addEventListener('keydown', handleTab);
+      return () => document.removeEventListener('keydown', handleTab);
+    }
+  }, [isOpen, onClose]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div
+      ref={modalRef}
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="modal-title"
+    >
+      {children}
+    </div>
+  );
+}
+```
+
+### ARIA Attributes
+
+```tsx
+// Live regions for dynamic content
+<div aria-live="polite" aria-atomic="true">
+  {status && <p>{status}</p>}
+</div>
+
+// Loading states
+<button disabled={isLoading} aria-busy={isLoading}>
+  {isLoading ? 'Loading...' : 'Submit'}
+</button>
+
+// Form labels
+<label htmlFor="email">Email address</label>
+<input
+  id="email"
+  type="email"
+  aria-required="true"
+  aria-invalid={!!errors.email}
+  aria-describedby={errors.email ? 'email-error' : undefined}
+/>
+{errors.email && (
+  <p id="email-error" role="alert">
+    {errors.email}
+  </p>
+)}
+
+// Navigation
+<nav aria-label="Main navigation">
+  <ul>
+    <li><a href="/" aria-current={isHome ? 'page' : undefined}>Home</a></li>
+    <li><a href="/about" aria-current={isAbout ? 'page' : undefined}>About</a></li>
+  </ul>
+</nav>
+
+// Toggle buttons
+<button
+  aria-pressed={isEnabled}
+  onClick={() => setIsEnabled(!isEnabled)}
+>
+  {isEnabled ? 'Enabled' : 'Disabled'}
+</button>
+
+// Expandable sections
+<button
+  aria-expanded={isOpen}
+  aria-controls="content-panel"
+  onClick={() => setIsOpen(!isOpen)}
+>
+  Show details
+</button>
+<div id="content-panel" hidden={!isOpen}>
+  Content here
+</div>
+```
+
+### Color Contrast
+
+```tsx
+// Ensure 4.5:1 contrast ratio for text (WCAG AA)
+// Use tools like @axe-core/react for testing
+
+// tailwind.config.js - Define accessible colors
+module.exports = {
+  theme: {
+    colors: {
+      // Primary with proper contrast
+      primary: {
+        DEFAULT: '#2563eb', // Blue 600
+        foreground: '#ffffff',
+      },
+      // Error state
+      error: {
+        DEFAULT: '#dc2626', // Red 600
+        foreground: '#ffffff',
+      },
+      // Text colors with proper contrast
+      foreground: '#0f172a', // Slate 900
+      muted: '#64748b', // Slate 500 - minimum 4.5:1 on white
+    },
+  },
+};
+
+// Never rely on color alone
+<span className="text-red-600">
+  <ErrorIcon aria-hidden="true" />
+  <span>Error: Invalid input</span>
+</span>
+```
+
+### Screen Reader Only Content
+
+```tsx
+// Visually hidden but accessible to screen readers
+const srOnly = 'absolute w-px h-px p-0 -m-px overflow-hidden whitespace-nowrap border-0';
+
+// Skip link for keyboard users
+<a href="#main-content" className={srOnly + ' focus:not-sr-only focus:absolute focus:top-0'}>
+  Skip to main content
+</a>
+
+// Icon buttons need labels
+<button aria-label="Close menu">
+  <XIcon aria-hidden="true" />
+</button>
+
+// Or use visually hidden text
+<button>
+  <XIcon aria-hidden="true" />
+  <span className={srOnly}>Close menu</span>
+</button>
+```
+
+---
+
+## Testing Strategies
+
+### Component Testing with Testing Library
+
+```tsx
+// Button.test.tsx
+import { render, screen, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Button } from './Button';
+
+describe('Button', () => {
+  it('renders with correct text', () => {
+    render(<Button>Click me</Button>);
+    expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument();
+  });
+
+  it('calls onClick when clicked', async () => {
+    const user = userEvent.setup();
+    const handleClick = jest.fn();
+
+    render(<Button onClick={handleClick}>Click me</Button>);
+    await user.click(screen.getByRole('button'));
+
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('is disabled when loading', () => {
+    render(<Button isLoading>Submit</Button>);
+    expect(screen.getByRole('button')).toBeDisabled();
+    expect(screen.getByRole('button')).toHaveAttribute('aria-busy', 'true');
+  });
+
+  it('shows loading text when loading', () => {
+    render(<Button isLoading loadingText="Submitting...">Submit</Button>);
+    expect(screen.getByText('Submitting...')).toBeInTheDocument();
+  });
+});
+```
+
+### Hook Testing
+
+```tsx
+// useCounter.test.ts
+import { renderHook, act } from '@testing-library/react';
+import { useCounter } from './useCounter';
+
+describe('useCounter', () => {
+  it('initializes with default value', () => {
+    const { result } = renderHook(() => useCounter());
+    expect(result.current.count).toBe(0);
+  });
+
+  it('initializes with custom value', () => {
+    const { result } = renderHook(() => useCounter(10));
+    expect(result.current.count).toBe(10);
+  });
+
+  it('increments count', () => {
+    const { result } = renderHook(() => useCounter());
+
+    act(() => {
+      result.current.increment();
+    });
+
+    expect(result.current.count).toBe(1);
+  });
+
+  it('resets to initial value', () => {
+    const { result } = renderHook(() => useCounter(5));
+
+    act(() => {
+      result.current.increment();
+      result.current.increment();
+      result.current.reset();
+    });
+
+    expect(result.current.count).toBe(5);
+  });
+});
+```
+
+### Integration Testing
+
+```tsx
+// LoginForm.test.tsx
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { LoginForm } from './LoginForm';
+import { AuthProvider } from '@/contexts/AuthContext';
+
+const mockLogin = jest.fn();
+
+jest.mock('@/lib/auth', () => ({
+  login: (...args: unknown[]) => mockLogin(...args),
+}));
+
+describe('LoginForm', () => {
+  beforeEach(() => {
+    mockLogin.mockReset();
+  });
+
+  it('submits form with valid credentials', async () => {
+    const user = userEvent.setup();
+    mockLogin.mockResolvedValueOnce({ user: { id: '1', name: 'Test' } });
+
+    render(
+      <AuthProvider>
+        <LoginForm />
+      </AuthProvider>
+    );
+
+    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
+    await user.type(screen.getByLabelText(/password/i), 'password123');
+    await user.click(screen.getByRole('button', { name: /sign in/i }));
+
+    await waitFor(() => {
+      expect(mockLogin).toHaveBeenCalledWith('test@example.com', 'password123');
+    });
+  });
+
+  it('shows validation errors for empty fields', async () => {
+    const user = userEvent.setup();
+
+    render(
+      <AuthProvider>
+        <LoginForm />
+      </AuthProvider>
+    );
+
+    await user.click(screen.getByRole('button', { name: /sign in/i }));
+
+    expect(await screen.findByText(/email is required/i)).toBeInTheDocument();
+    expect(await screen.findByText(/password is required/i)).toBeInTheDocument();
+    expect(mockLogin).not.toHaveBeenCalled();
+  });
+});
+```
+
+### E2E Testing with Playwright
+
+```typescript
+// e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Checkout flow', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/');
+    await page.click('[data-testid="product-1"] button');
+    await page.click('[data-testid="cart-button"]');
+  });
+
+  test('completes checkout with valid payment', async ({ page }) => {
+    await page.click('text=Proceed to Checkout');
+
+    // Fill shipping info
+    await page.fill('[name="email"]', 'test@example.com');
+    await page.fill('[name="address"]', '123 Test St');
+    await page.fill('[name="city"]', 'Test City');
+    await page.selectOption('[name="state"]', 'CA');
+    await page.fill('[name="zip"]', '90210');
+
+    await page.click('text=Continue to Payment');
+    await page.click('text=Place Order');
+
+    // Verify success
+    await expect(page).toHaveURL(/\/order\/confirmation/);
+    await expect(page.locator('h1')).toHaveText('Order Confirmed!');
+  });
+});
+```
+
+---
+
+## TypeScript Patterns
+
+### Component Props
+
+```tsx
+// Use interface for component props
+interface ButtonProps {
+  variant?: 'primary' | 'secondary' | 'ghost';
+  size?: 'sm' | 'md' | 'lg';
+  isLoading?: boolean;
+  children: React.ReactNode;
+  onClick?: () => void;
+}
+
+// Extend HTML attributes
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary';
+  isLoading?: boolean;
+}
+
+function Button({ variant = 'primary', isLoading, children, ...props }: ButtonProps) {
+  return (
+    <button
+      {...props}
+      disabled={props.disabled || isLoading}
+      className={cn(variants[variant], props.className)}
+    >
+      {isLoading ? <Spinner /> : children}
+    </button>
+  );
+}
+
+// Polymorphic components
+type PolymorphicProps<E extends React.ElementType> = {
+  as?: E;
+} & React.ComponentPropsWithoutRef<E>;
+
+function Box<E extends React.ElementType = 'div'>({
+  as,
+  children,
+  ...props
+}: PolymorphicProps<E>) {
+  const Component = as || 'div';
+  return <Component {...props}>{children}</Component>;
+}
+
+// Usage
+<Box as="section" id="hero">Content</Box>
+<Box as="article">Article content</Box>
+```
+
+### Discriminated Unions
+
+```tsx
+// State machines with exhaustive type checking
+type AsyncState<T> =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: T }
+  | { status: 'error'; error: Error };
+
+function DataDisplay<T>({ state, render }: {
+  state: AsyncState<T>;
+  render: (data: T) => React.ReactNode;
+}) {
+  switch (state.status) {
+    case 'idle':
+      return null;
+    case 'loading':
+      return <Spinner />;
+    case 'success':
+      return <>{render(state.data)}</>;
+    case 'error':
+      return <ErrorMessage error={state.error} />;
+    // TypeScript ensures all cases are handled
+  }
+}
+```
+
+### Generic Components
+
+```tsx
+// Generic list component
+interface ListProps<T> {
+  items: T[];
+  renderItem: (item: T, index: number) => React.ReactNode;
+  keyExtractor: (item: T) => string;
+  emptyMessage?: string;
+}
+
+function List<T>({ items, renderItem, keyExtractor, emptyMessage }: ListProps<T>) {
+  if (items.length === 0) {
+    return <p className="text-muted">{emptyMessage || 'No items'}</p>;
+  }
+
+  return (
+    <ul>
+      {items.map((item, index) => (
+        <li key={keyExtractor(item)}>{renderItem(item, index)}</li>
+      ))}
+    </ul>
+  );
+}
+
+// Usage
+<List
+  items={users}
+  keyExtractor={(user) => user.id}
+  renderItem={(user) => <UserCard user={user} />}
+/>
+```
+
+### Type Guards
+
+```tsx
+// User-defined type guards
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+interface Admin extends User {
+  role: 'admin';
+  permissions: string[];
+}
+
+function isAdmin(user: User): user is Admin {
+  return 'role' in user && user.role === 'admin';
+}
+
+function UserBadge({ user }: { user: User }) {
+  if (isAdmin(user)) {
+    // TypeScript knows user is Admin here
+    return <Badge variant="admin">Admin ({user.permissions.length} perms)</Badge>;
+  }
+
+  return <Badge>User</Badge>;
+}
+
+// API response type guards
+interface ApiSuccess<T> {
+  success: true;
+  data: T;
+}
+
+interface ApiError {
+  success: false;
+  error: string;
+}
+
+type ApiResponse<T> = ApiSuccess<T> | ApiError;
+
+function isApiSuccess<T>(response: ApiResponse<T>): response is ApiSuccess<T> {
+  return response.success === true;
+}
+```
+
+---
+
+## Tailwind CSS
+
+### Component Variants with CVA
+
+```tsx
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '@/lib/utils';
+
+const buttonVariants = cva(
+  // Base styles
+  'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        primary: 'bg-blue-600 text-white hover:bg-blue-700 focus-visible:ring-blue-500',
+        secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200 focus-visible:ring-gray-500',
+        ghost: 'hover:bg-gray-100 hover:text-gray-900',
+        destructive: 'bg-red-600 text-white hover:bg-red-700 focus-visible:ring-red-500',
+      },
+      size: {
+        sm: 'h-8 px-3 text-sm',
+        md: 'h-10 px-4 text-sm',
+        lg: 'h-12 px-6 text-base',
+        icon: 'h-10 w-10',
+      },
+    },
+    defaultVariants: {
+      variant: 'primary',
+      size: 'md',
+    },
+  }
+);
+
+interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {}
+
+function Button({ className, variant, size, ...props }: ButtonProps) {
+  return (
+    <button
+      className={cn(buttonVariants({ variant, size }), className)}
+      {...props}
+    />
+  );
+}
+
+// Usage
+<Button variant="primary" size="lg">Large Primary</Button>
+<Button variant="ghost" size="icon"><MenuIcon /></Button>
+```
+
+### Responsive Design
+
+```tsx
+// Mobile-first responsive design
+<div className="
+  grid
+  grid-cols-1          {/* Mobile: 1 column */}
+  sm:grid-cols-2       {/* 640px+: 2 columns */}
+  lg:grid-cols-3       {/* 1024px+: 3 columns */}
+  xl:grid-cols-4       {/* 1280px+: 4 columns */}
+  gap-4
+  sm:gap-6
+  lg:gap-8
+">
+  {products.map(product => <ProductCard key={product.id} product={product} />)}
+</div>
+
+// Container with responsive padding
+<div className="container mx-auto px-4 sm:px-6 lg:px-8">
+  Content
+</div>
+
+// Hide/show based on breakpoint
+<nav className="hidden md:flex">Desktop nav</nav>
+<button className="md:hidden">Mobile menu</button>
+```
+
+### Animation Utilities
+
+```tsx
+// Skeleton loading
+<div className="animate-pulse space-y-4">
+  <div className="h-4 bg-gray-200 rounded w-3/4" />
+  <div className="h-4 bg-gray-200 rounded w-1/2" />
+</div>
+
+// Transitions
+<button className="
+  transition-all
+  duration-200
+  ease-in-out
+  hover:scale-105
+  active:scale-95
+">
+  Hover me
+</button>
+
+// Custom animations in tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      animation: {
+        'fade-in': 'fadeIn 0.3s ease-out',
+        'slide-up': 'slideUp 0.3s ease-out',
+        'spin-slow': 'spin 3s linear infinite',
+      },
+      keyframes: {
+        fadeIn: {
+          '0%': { opacity: '0' },
+          '100%': { opacity: '1' },
+        },
+        slideUp: {
+          '0%': { transform: 'translateY(10px)', opacity: '0' },
+          '100%': { transform: 'translateY(0)', opacity: '1' },
+        },
+      },
+    },
+  },
+};
+
+// Usage
+<div className="animate-fade-in">Fading in</div>
+```
+
+---
+
+## Project Structure
+
+### Feature-Based Structure
+
+```
+src/
+├── app/                    # Next.js App Router
+│   ├── (auth)/             # Auth route group
+│   │   ├── login/
+│   │   └── register/
+│   ├── dashboard/
+│   │   ├── page.tsx
+│   │   └── layout.tsx
+│   └── layout.tsx
+├── components/
+│   ├── ui/                 # Shared UI components
+│   │   ├── Button.tsx
+│   │   ├── Input.tsx
+│   │   └── index.ts
+│   └── features/           # Feature-specific components
+│       ├── auth/
+│       │   ├── LoginForm.tsx
+│       │   └── RegisterForm.tsx
+│       └── dashboard/
+│           ├── StatsCard.tsx
+│           └── RecentActivity.tsx
+├── hooks/                  # Custom React hooks
+│   ├── useAuth.ts
+│   ├── useDebounce.ts
+│   └── useLocalStorage.ts
+├── lib/                    # Utilities and configs
+│   ├── utils.ts
+│   ├── api.ts
+│   └── constants.ts
+├── types/                  # TypeScript types
+│   ├── user.ts
+│   └── api.ts
+└── styles/
+    └── globals.css
+```
+
+### Barrel Exports
+
+```tsx
+// components/ui/index.ts
+export { Button } from './Button';
+export { Input } from './Input';
+export { Card, CardHeader, CardContent, CardFooter } from './Card';
+export { Dialog, DialogTrigger, DialogContent } from './Dialog';
+
+// Usage
+import { Button, Input, Card } from '@/components/ui';
+```
+
+---
+
+## Security
+
+### XSS Prevention
+
+React escapes content by default, which prevents most XSS attacks. When you need to render HTML content:
+
+1. **Avoid rendering raw HTML** when possible
+2. **Sanitize with DOMPurify** for trusted content sources
+3. **Use allow-lists** for permitted tags and attributes
+
+```tsx
+// React escapes by default - this is safe
+<div>{userInput}</div>
+
+// When you must render HTML, sanitize first
+import DOMPurify from 'dompurify';
+
+function SafeHTML({ html }: { html: string }) {
+  const sanitized = DOMPurify.sanitize(html, {
+    ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a', 'p'],
+    ALLOWED_ATTR: ['href'],
+  });
+
+  return <div dangerouslySetInnerHTML={{ __html: sanitized }} />;
+}
+```
+
+### Input Validation
+
+```tsx
+import { z } from 'zod';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+
+const schema = z.object({
+  email: z.string().email('Invalid email address'),
+  password: z.string()
+    .min(8, 'Password must be at least 8 characters')
+    .regex(/[A-Z]/, 'Password must contain uppercase letter')
+    .regex(/[0-9]/, 'Password must contain number'),
+  confirmPassword: z.string(),
+}).refine((data) => data.password === data.confirmPassword, {
+  message: 'Passwords do not match',
+  path: ['confirmPassword'],
+});
+
+type FormData = z.infer<typeof schema>;
+
+function RegisterForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
+    resolver: zodResolver(schema),
+  });
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <Input {...register('email')} error={errors.email?.message} />
+      <Input type="password" {...register('password')} error={errors.password?.message} />
+      <Input type="password" {...register('confirmPassword')} error={errors.confirmPassword?.message} />
+      <Button type="submit">Register</Button>
+    </form>
+  );
+}
+```
+
+### Secure API Calls
+
+```tsx
+// Use environment variables for API endpoints
+const API_URL = process.env.NEXT_PUBLIC_API_URL;
+
+// Never include secrets in client code - use server-side API routes
+// app/api/data/route.ts
+export async function GET() {
+  const response = await fetch('https://api.example.com/data', {
+    headers: {
+      'Authorization': `Bearer ${process.env.API_SECRET}`, // Server-side only
+    },
+  });
+
+  return Response.json(await response.json());
+}
+```
diff --git a/builtin-skills/frontend-design/senior-frontend/references/nextjs_optimization_guide.md b/builtin-skills/frontend-design/senior-frontend/references/nextjs_optimization_guide.md
new file mode 100644
index 00000000..d1157a36
--- /dev/null
+++ b/builtin-skills/frontend-design/senior-frontend/references/nextjs_optimization_guide.md
@@ -0,0 +1,724 @@
+# Next.js Optimization Guide
+
+Performance optimization techniques for Next.js 14+ applications.
+
+---
+
+## Table of Contents
+
+- [Rendering Strategies](#rendering-strategies)
+- [Image Optimization](#image-optimization)
+- [Code Splitting](#code-splitting)
+- [Data Fetching](#data-fetching)
+- [Caching Strategies](#caching-strategies)
+- [Bundle Optimization](#bundle-optimization)
+- [Core Web Vitals](#core-web-vitals)
+
+---
+
+## Rendering Strategies
+
+### Server Components (Default)
+
+Server Components render on the server and send HTML to the client. Use for data-heavy, non-interactive content.
+
+```tsx
+// app/products/page.tsx - Server Component (default)
+async function ProductsPage() {
+  // This runs on the server - no client bundle impact
+  const products = await db.products.findMany();
+
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      {products.map(product => (
+        <ProductCard key={product.id} product={product} />
+      ))}
+    </div>
+  );
+}
+```
+
+### Client Components
+
+Use `'use client'` only when you need:
+- Event handlers (onClick, onChange)
+- State (useState, useReducer)
+- Effects (useEffect)
+- Browser APIs (window, document)
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+
+function AddToCartButton({ productId }: { productId: string }) {
+  const [isAdding, setIsAdding] = useState(false);
+
+  async function handleClick() {
+    setIsAdding(true);
+    await addToCart(productId);
+    setIsAdding(false);
+  }
+
+  return (
+    <button onClick={handleClick} disabled={isAdding}>
+      {isAdding ? 'Adding...' : 'Add to Cart'}
+    </button>
+  );
+}
+```
+
+### Mixing Server and Client Components
+
+```tsx
+// app/products/[id]/page.tsx - Server Component
+async function ProductPage({ params }: { params: { id: string } }) {
+  const product = await getProduct(params.id);
+
+  return (
+    <div>
+      {/* Server-rendered content */}
+      <h1>{product.name}</h1>
+      <p>{product.description}</p>
+
+      {/* Client component for interactivity */}
+      <AddToCartButton productId={product.id} />
+
+      {/* Server component for reviews */}
+      <ProductReviews productId={product.id} />
+    </div>
+  );
+}
+```
+
+### Static vs Dynamic Rendering
+
+```tsx
+// Force static generation at build time
+export const dynamic = 'force-static';
+
+// Force dynamic rendering at request time
+export const dynamic = 'force-dynamic';
+
+// Revalidate every 60 seconds (ISR)
+export const revalidate = 60;
+
+// Revalidate on-demand
+import { revalidatePath, revalidateTag } from 'next/cache';
+
+async function updateProduct(id: string, data: ProductData) {
+  await db.products.update({ where: { id }, data });
+
+  // Revalidate specific path
+  revalidatePath(`/products/${id}`);
+
+  // Or revalidate by tag
+  revalidateTag('products');
+}
+```
+
+---
+
+## Image Optimization
+
+### Next.js Image Component
+
+```tsx
+import Image from 'next/image';
+
+// Basic optimized image
+<Image
+  src="/hero.jpg"
+  alt="Hero image"
+  width={1200}
+  height={600}
+  priority // Load immediately for LCP
+/>
+
+// Responsive image
+<Image
+  src="/product.jpg"
+  alt="Product"
+  fill
+  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
+  className="object-cover"
+/>
+
+// With placeholder blur
+import productImage from '@/public/product.jpg';
+
+<Image
+  src={productImage}
+  alt="Product"
+  placeholder="blur" // Uses imported image data
+/>
+```
+
+### Remote Images Configuration
+
+```js
+// next.config.js
+module.exports = {
+  images: {
+    remotePatterns: [
+      {
+        protocol: 'https',
+        hostname: 'cdn.example.com',
+        pathname: '/images/**',
+      },
+      {
+        protocol: 'https',
+        hostname: '*.cloudinary.com',
+      },
+    ],
+    // Image formats (webp is default)
+    formats: ['image/avif', 'image/webp'],
+    // Device sizes for srcset
+    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
+    // Image sizes for srcset
+    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
+  },
+};
+```
+
+### Lazy Loading Patterns
+
+```tsx
+// Images below the fold - lazy load (default)
+<Image
+  src="/gallery/photo1.jpg"
+  alt="Gallery photo"
+  width={400}
+  height={300}
+  loading="lazy" // Default behavior
+/>
+
+// Above the fold - load immediately
+<Image
+  src="/hero.jpg"
+  alt="Hero"
+  width={1200}
+  height={600}
+  priority
+  loading="eager"
+/>
+```
+
+---
+
+## Code Splitting
+
+### Dynamic Imports
+
+```tsx
+import dynamic from 'next/dynamic';
+
+// Basic dynamic import
+const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
+  loading: () => <ChartSkeleton />,
+});
+
+// Disable SSR for client-only components
+const MapComponent = dynamic(() => import('@/components/Map'), {
+  ssr: false,
+  loading: () => <div className="h-[400px] bg-gray-100" />,
+});
+
+// Named exports
+const Modal = dynamic(() =>
+  import('@/components/ui').then(mod => mod.Modal)
+);
+
+// With suspense
+const DashboardCharts = dynamic(() => import('@/components/DashboardCharts'), {
+  loading: () => <Suspense fallback={<ChartsSkeleton />} />,
+});
+```
+
+### Route-Based Splitting
+
+```tsx
+// app/dashboard/analytics/page.tsx
+// This page only loads when /dashboard/analytics is visited
+import { Suspense } from 'react';
+import AnalyticsCharts from './AnalyticsCharts';
+
+export default function AnalyticsPage() {
+  return (
+    <Suspense fallback={<AnalyticsSkeleton />}>
+      <AnalyticsCharts />
+    </Suspense>
+  );
+}
+```
+
+### Parallel Routes for Code Splitting
+
+```
+app/
+├── dashboard/
+│   ├── @analytics/
+│   │   └── page.tsx    # Loaded in parallel
+│   ├── @metrics/
+│   │   └── page.tsx    # Loaded in parallel
+│   ├── layout.tsx
+│   └── page.tsx
+```
+
+```tsx
+// app/dashboard/layout.tsx
+export default function DashboardLayout({
+  children,
+  analytics,
+  metrics,
+}: {
+  children: React.ReactNode;
+  analytics: React.ReactNode;
+  metrics: React.ReactNode;
+}) {
+  return (
+    <div className="grid grid-cols-2 gap-4">
+      {children}
+      <Suspense fallback={<AnalyticsSkeleton />}>{analytics}</Suspense>
+      <Suspense fallback={<MetricsSkeleton />}>{metrics}</Suspense>
+    </div>
+  );
+}
+```
+
+---
+
+## Data Fetching
+
+### Server-Side Data Fetching
+
+```tsx
+// Parallel data fetching
+async function Dashboard() {
+  // Start both requests simultaneously
+  const [user, stats, notifications] = await Promise.all([
+    getUser(),
+    getStats(),
+    getNotifications(),
+  ]);
+
+  return (
+    <div>
+      <UserHeader user={user} />
+      <StatsPanel stats={stats} />
+      <NotificationList notifications={notifications} />
+    </div>
+  );
+}
+```
+
+### Streaming with Suspense
+
+```tsx
+import { Suspense } from 'react';
+
+async function ProductPage({ params }: { params: { id: string } }) {
+  const product = await getProduct(params.id);
+
+  return (
+    <div>
+      {/* Immediate content */}
+      <h1>{product.name}</h1>
+      <p>{product.description}</p>
+
+      {/* Stream reviews - don't block page */}
+      <Suspense fallback={<ReviewsSkeleton />}>
+        <Reviews productId={params.id} />
+      </Suspense>
+
+      {/* Stream recommendations */}
+      <Suspense fallback={<RecommendationsSkeleton />}>
+        <Recommendations productId={params.id} />
+      </Suspense>
+    </div>
+  );
+}
+
+// Slow data component
+async function Reviews({ productId }: { productId: string }) {
+  const reviews = await getReviews(productId); // Slow query
+  return <ReviewList reviews={reviews} />;
+}
+```
+
+### Request Memoization
+
+```tsx
+// Next.js automatically dedupes identical requests
+async function Layout({ children }) {
+  const user = await getUser(); // Request 1
+  return <div>{children}</div>;
+}
+
+async function Header() {
+  const user = await getUser(); // Same request - cached!
+  return <div>Hello, {user.name}</div>;
+}
+
+// Both components call getUser() but only one request is made
+```
+
+---
+
+## Caching Strategies
+
+### Fetch Cache Options
+
+```tsx
+// Cache indefinitely (default for static)
+fetch('https://api.example.com/data');
+
+// No cache - always fresh
+fetch('https://api.example.com/data', { cache: 'no-store' });
+
+// Revalidate after time
+fetch('https://api.example.com/data', {
+  next: { revalidate: 3600 } // 1 hour
+});
+
+// Tag-based revalidation
+fetch('https://api.example.com/products', {
+  next: { tags: ['products'] }
+});
+
+// Later, revalidate by tag
+import { revalidateTag } from 'next/cache';
+revalidateTag('products');
+```
+
+### Route Segment Config
+
+```tsx
+// app/products/page.tsx
+
+// Revalidate every hour
+export const revalidate = 3600;
+
+// Or force dynamic
+export const dynamic = 'force-dynamic';
+
+// Generate static params at build
+export async function generateStaticParams() {
+  const products = await getProducts();
+  return products.map(p => ({ id: p.id }));
+}
+```
+
+### unstable_cache for Custom Caching
+
+```tsx
+import { unstable_cache } from 'next/cache';
+
+const getCachedUser = unstable_cache(
+  async (userId: string) => {
+    const user = await db.users.findUnique({ where: { id: userId } });
+    return user;
+  },
+  ['user-cache'],
+  {
+    revalidate: 3600, // 1 hour
+    tags: ['users'],
+  }
+);
+
+// Usage
+const user = await getCachedUser(userId);
+```
+
+---
+
+## Bundle Optimization
+
+### Analyze Bundle Size
+
+```bash
+# Install analyzer
+npm install @next/bundle-analyzer
+
+# Update next.config.js
+const withBundleAnalyzer = require('@next/bundle-analyzer')({
+  enabled: process.env.ANALYZE === 'true',
+});
+
+module.exports = withBundleAnalyzer({
+  // config
+});
+
+# Run analysis
+ANALYZE=true npm run build
+```
+
+### Tree Shaking Imports
+
+```tsx
+// BAD - Imports entire library
+import _ from 'lodash';
+const result = _.debounce(fn, 300);
+
+// GOOD - Import only what you need
+import debounce from 'lodash/debounce';
+const result = debounce(fn, 300);
+
+// GOOD - Named imports (tree-shakeable)
+import { debounce } from 'lodash-es';
+```
+
+### Optimize Dependencies
+
+```js
+// next.config.js
+module.exports = {
+  // Transpile specific packages
+  transpilePackages: ['ui-library', 'shared-utils'],
+
+  // Optimize package imports
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@heroicons/react'],
+  },
+
+  // External packages for server
+  serverExternalPackages: ['sharp', 'bcrypt'],
+};
+```
+
+### Font Optimization
+
+```tsx
+// app/layout.tsx
+import { Inter, Roboto_Mono } from 'next/font/google';
+
+const inter = Inter({
+  subsets: ['latin'],
+  display: 'swap',
+  variable: '--font-inter',
+});
+
+const robotoMono = Roboto_Mono({
+  subsets: ['latin'],
+  display: 'swap',
+  variable: '--font-roboto-mono',
+});
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
+      <body className="font-sans">{children}</body>
+    </html>
+  );
+}
+```
+
+---
+
+## Core Web Vitals
+
+### Largest Contentful Paint (LCP)
+
+```tsx
+// Optimize LCP hero image
+import Image from 'next/image';
+
+export default function Hero() {
+  return (
+    <section className="relative h-[600px]">
+      <Image
+        src="/hero.jpg"
+        alt="Hero"
+        fill
+        priority // Preload for LCP
+        sizes="100vw"
+        className="object-cover"
+      />
+      <div className="relative z-10">
+        <h1>Welcome</h1>
+      </div>
+    </section>
+  );
+}
+
+// Preload critical resources in layout
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <head>
+        <link rel="preload" href="/hero.jpg" as="image" />
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+### Cumulative Layout Shift (CLS)
+
+```tsx
+// Prevent CLS with explicit dimensions
+<Image
+  src="/product.jpg"
+  alt="Product"
+  width={400}
+  height={300}
+/>
+
+// Or use aspect ratio
+<div className="aspect-video relative">
+  <Image src="/video-thumb.jpg" alt="Video" fill />
+</div>
+
+// Skeleton placeholders
+function ProductCard({ product }: { product?: Product }) {
+  if (!product) {
+    return (
+      <div className="animate-pulse">
+        <div className="h-48 bg-gray-200 rounded" />
+        <div className="h-4 bg-gray-200 rounded mt-2 w-3/4" />
+        <div className="h-4 bg-gray-200 rounded mt-1 w-1/2" />
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      <Image src={product.image} alt={product.name} width={300} height={200} />
+      <h3>{product.name}</h3>
+      <p>{product.price}</p>
+    </div>
+  );
+}
+```
+
+### First Input Delay (FID) / Interaction to Next Paint (INP)
+
+```tsx
+// Defer non-critical JavaScript
+import Script from 'next/script';
+
+export default function Layout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+
+        {/* Load analytics after page is interactive */}
+        <Script
+          src="https://analytics.example.com/script.js"
+          strategy="afterInteractive"
+        />
+
+        {/* Load chat widget when idle */}
+        <Script
+          src="https://chat.example.com/widget.js"
+          strategy="lazyOnload"
+        />
+      </body>
+    </html>
+  );
+}
+
+// Use web workers for heavy computation
+// app/components/DataProcessor.tsx
+'use client';
+
+import { useEffect, useState } from 'react';
+
+function DataProcessor({ data }: { data: number[] }) {
+  const [result, setResult] = useState<number | null>(null);
+
+  useEffect(() => {
+    const worker = new Worker(new URL('../workers/processor.js', import.meta.url));
+
+    worker.postMessage(data);
+    worker.onmessage = (e) => setResult(e.data);
+
+    return () => worker.terminate();
+  }, [data]);
+
+  return <div>Result: {result}</div>;
+}
+```
+
+### Measuring Performance
+
+```tsx
+// app/components/PerformanceMonitor.tsx
+'use client';
+
+import { useReportWebVitals } from 'next/web-vitals';
+
+export function PerformanceMonitor() {
+  useReportWebVitals((metric) => {
+    switch (metric.name) {
+      case 'LCP':
+        console.log('LCP:', metric.value);
+        break;
+      case 'FID':
+        console.log('FID:', metric.value);
+        break;
+      case 'CLS':
+        console.log('CLS:', metric.value);
+        break;
+      case 'TTFB':
+        console.log('TTFB:', metric.value);
+        break;
+    }
+
+    // Send to analytics
+    analytics.track('web-vital', {
+      name: metric.name,
+      value: metric.value,
+      id: metric.id,
+    });
+  });
+
+  return null;
+}
+```
+
+---
+
+## Quick Reference
+
+### Performance Checklist
+
+| Area | Optimization | Impact |
+|------|-------------|--------|
+| Images | Use next/image with priority for LCP | High |
+| Fonts | Use next/font with display: swap | Medium |
+| Code | Dynamic imports for heavy components | High |
+| Data | Parallel fetching with Promise.all | High |
+| Render | Server Components by default | High |
+| Cache | Configure revalidate appropriately | Medium |
+| Bundle | Tree-shake imports, analyze size | Medium |
+
+### Config Template
+
+```js
+// next.config.js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  images: {
+    remotePatterns: [{ hostname: 'cdn.example.com' }],
+    formats: ['image/avif', 'image/webp'],
+  },
+  experimental: {
+    optimizePackageImports: ['lucide-react'],
+  },
+  headers: async () => [
+    {
+      source: '/(.*)',
+      headers: [
+        { key: 'X-Content-Type-Options', value: 'nosniff' },
+        { key: 'X-Frame-Options', value: 'DENY' },
+      ],
+    },
+  ],
+};
+
+module.exports = nextConfig;
+```
diff --git a/builtin-skills/frontend-design/senior-frontend/references/react_patterns.md b/builtin-skills/frontend-design/senior-frontend/references/react_patterns.md
new file mode 100644
index 00000000..e0a23ce2
--- /dev/null
+++ b/builtin-skills/frontend-design/senior-frontend/references/react_patterns.md
@@ -0,0 +1,746 @@
+# React Patterns
+
+Production-ready patterns for building scalable React applications with TypeScript.
+
+---
+
+## Table of Contents
+
+- [Component Composition](#component-composition)
+- [Custom Hooks](#custom-hooks)
+- [State Management](#state-management)
+- [Performance Patterns](#performance-patterns)
+- [Error Boundaries](#error-boundaries)
+- [Anti-Patterns](#anti-patterns)
+
+---
+
+## Component Composition
+
+### Compound Components
+
+Use compound components when building reusable UI components with multiple related parts.
+
+```tsx
+// Compound component pattern for a Select
+interface SelectContextType {
+  value: string;
+  onChange: (value: string) => void;
+}
+
+const SelectContext = createContext<SelectContextType | null>(null);
+
+function Select({ children, value, onChange }: {
+  children: React.ReactNode;
+  value: string;
+  onChange: (value: string) => void;
+}) {
+  return (
+    <SelectContext.Provider value={{ value, onChange }}>
+      <div className="relative">{children}</div>
+    </SelectContext.Provider>
+  );
+}
+
+function SelectTrigger({ children }: { children: React.ReactNode }) {
+  const context = useContext(SelectContext);
+  if (!context) throw new Error('SelectTrigger must be used within Select');
+
+  return (
+    <button className="flex items-center gap-2 px-4 py-2 border rounded">
+      {children}
+    </button>
+  );
+}
+
+function SelectOption({ value, children }: { value: string; children: React.ReactNode }) {
+  const context = useContext(SelectContext);
+  if (!context) throw new Error('SelectOption must be used within Select');
+
+  return (
+    <div
+      onClick={() => context.onChange(value)}
+      className={`px-4 py-2 cursor-pointer hover:bg-gray-100 ${
+        context.value === value ? 'bg-blue-50' : ''
+      }`}
+    >
+      {children}
+    </div>
+  );
+}
+
+// Attach sub-components
+Select.Trigger = SelectTrigger;
+Select.Option = SelectOption;
+
+// Usage
+<Select value={selected} onChange={setSelected}>
+  <Select.Trigger>Choose option</Select.Trigger>
+  <Select.Option value="a">Option A</Select.Option>
+  <Select.Option value="b">Option B</Select.Option>
+</Select>
+```
+
+### Render Props
+
+Use render props when you need to share behavior with flexible rendering.
+
+```tsx
+interface MousePosition {
+  x: number;
+  y: number;
+}
+
+function MouseTracker({ render }: { render: (pos: MousePosition) => React.ReactNode }) {
+  const [position, setPosition] = useState<MousePosition>({ x: 0, y: 0 });
+
+  useEffect(() => {
+    const handleMouseMove = (e: MouseEvent) => {
+      setPosition({ x: e.clientX, y: e.clientY });
+    };
+    window.addEventListener('mousemove', handleMouseMove);
+    return () => window.removeEventListener('mousemove', handleMouseMove);
+  }, []);
+
+  return <>{render(position)}</>;
+}
+
+// Usage
+<MouseTracker
+  render={({ x, y }) => (
+    <div>Mouse position: {x}, {y}</div>
+  )}
+/>
+```
+
+### Higher-Order Components (HOC)
+
+Use HOCs for cross-cutting concerns like authentication or logging.
+
+```tsx
+function withAuth<P extends object>(WrappedComponent: React.ComponentType<P>) {
+  return function AuthenticatedComponent(props: P) {
+    const { user, isLoading } = useAuth();
+
+    if (isLoading) return <LoadingSpinner />;
+    if (!user) return <Navigate to="/login" />;
+
+    return <WrappedComponent {...props} />;
+  };
+}
+
+// Usage
+const ProtectedDashboard = withAuth(Dashboard);
+```
+
+---
+
+## Custom Hooks
+
+### useAsync - Handle async operations
+
+```tsx
+interface AsyncState<T> {
+  data: T | null;
+  error: Error | null;
+  status: 'idle' | 'loading' | 'success' | 'error';
+}
+
+function useAsync<T>(asyncFn: () => Promise<T>, deps: any[] = []) {
+  const [state, setState] = useState<AsyncState<T>>({
+    data: null,
+    error: null,
+    status: 'idle',
+  });
+
+  const execute = useCallback(async () => {
+    setState({ data: null, error: null, status: 'loading' });
+    try {
+      const data = await asyncFn();
+      setState({ data, error: null, status: 'success' });
+    } catch (error) {
+      setState({ data: null, error: error as Error, status: 'error' });
+    }
+  }, deps);
+
+  useEffect(() => {
+    execute();
+  }, [execute]);
+
+  return { ...state, refetch: execute };
+}
+
+// Usage
+function UserProfile({ userId }: { userId: string }) {
+  const { data: user, status, error, refetch } = useAsync(
+    () => fetchUser(userId),
+    [userId]
+  );
+
+  if (status === 'loading') return <Spinner />;
+  if (status === 'error') return <Error message={error?.message} />;
+  if (!user) return null;
+
+  return <Profile user={user} />;
+}
+```
+
+### useDebounce - Debounce values
+
+```tsx
+function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debouncedValue;
+}
+
+// Usage
+function SearchInput() {
+  const [query, setQuery] = useState('');
+  const debouncedQuery = useDebounce(query, 300);
+
+  useEffect(() => {
+    if (debouncedQuery) {
+      searchAPI(debouncedQuery);
+    }
+  }, [debouncedQuery]);
+
+  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
+}
+```
+
+### useLocalStorage - Persist state
+
+```tsx
+function useLocalStorage<T>(key: string, initialValue: T) {
+  const [storedValue, setStoredValue] = useState<T>(() => {
+    if (typeof window === 'undefined') return initialValue;
+    try {
+      const item = window.localStorage.getItem(key);
+      return item ? JSON.parse(item) : initialValue;
+    } catch {
+      return initialValue;
+    }
+  });
+
+  const setValue = useCallback((value: T | ((val: T) => T)) => {
+    try {
+      const valueToStore = value instanceof Function ? value(storedValue) : value;
+      setStoredValue(valueToStore);
+      if (typeof window !== 'undefined') {
+        window.localStorage.setItem(key, JSON.stringify(valueToStore));
+      }
+    } catch (error) {
+      console.error('Error saving to localStorage:', error);
+    }
+  }, [key, storedValue]);
+
+  return [storedValue, setValue] as const;
+}
+
+// Usage
+const [theme, setTheme] = useLocalStorage('theme', 'light');
+```
+
+### useMediaQuery - Responsive design
+
+```tsx
+function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(false);
+
+  useEffect(() => {
+    const media = window.matchMedia(query);
+    setMatches(media.matches);
+
+    const listener = (e: MediaQueryListEvent) => setMatches(e.matches);
+    media.addEventListener('change', listener);
+    return () => media.removeEventListener('change', listener);
+  }, [query]);
+
+  return matches;
+}
+
+// Usage
+function ResponsiveNav() {
+  const isMobile = useMediaQuery('(max-width: 768px)');
+  return isMobile ? <MobileNav /> : <DesktopNav />;
+}
+```
+
+### usePrevious - Track previous values
+
+```tsx
+function usePrevious<T>(value: T): T | undefined {
+  const ref = useRef<T>();
+
+  useEffect(() => {
+    ref.current = value;
+  }, [value]);
+
+  return ref.current;
+}
+
+// Usage
+function Counter() {
+  const [count, setCount] = useState(0);
+  const prevCount = usePrevious(count);
+
+  return (
+    <div>
+      Current: {count}, Previous: {prevCount}
+    </div>
+  );
+}
+```
+
+---
+
+## State Management
+
+### Context with Reducer
+
+For complex state that multiple components need to access.
+
+```tsx
+// types.ts
+interface CartItem {
+  id: string;
+  name: string;
+  price: number;
+  quantity: number;
+}
+
+interface CartState {
+  items: CartItem[];
+  total: number;
+}
+
+type CartAction =
+  | { type: 'ADD_ITEM'; payload: CartItem }
+  | { type: 'REMOVE_ITEM'; payload: string }
+  | { type: 'UPDATE_QUANTITY'; payload: { id: string; quantity: number } }
+  | { type: 'CLEAR_CART' };
+
+// reducer.ts
+function cartReducer(state: CartState, action: CartAction): CartState {
+  switch (action.type) {
+    case 'ADD_ITEM': {
+      const existingItem = state.items.find(i => i.id === action.payload.id);
+      if (existingItem) {
+        return {
+          ...state,
+          items: state.items.map(item =>
+            item.id === action.payload.id
+              ? { ...item, quantity: item.quantity + 1 }
+              : item
+          ),
+        };
+      }
+      return {
+        ...state,
+        items: [...state.items, { ...action.payload, quantity: 1 }],
+      };
+    }
+    case 'REMOVE_ITEM':
+      return {
+        ...state,
+        items: state.items.filter(i => i.id !== action.payload),
+      };
+    case 'UPDATE_QUANTITY':
+      return {
+        ...state,
+        items: state.items.map(item =>
+          item.id === action.payload.id
+            ? { ...item, quantity: action.payload.quantity }
+            : item
+        ),
+      };
+    case 'CLEAR_CART':
+      return { items: [], total: 0 };
+    default:
+      return state;
+  }
+}
+
+// context.tsx
+const CartContext = createContext<{
+  state: CartState;
+  dispatch: React.Dispatch<CartAction>;
+} | null>(null);
+
+function CartProvider({ children }: { children: React.ReactNode }) {
+  const [state, dispatch] = useReducer(cartReducer, { items: [], total: 0 });
+
+  // Compute total whenever items change
+  const stateWithTotal = useMemo(() => ({
+    ...state,
+    total: state.items.reduce((sum, item) => sum + item.price * item.quantity, 0),
+  }), [state.items]);
+
+  return (
+    <CartContext.Provider value={{ state: stateWithTotal, dispatch }}>
+      {children}
+    </CartContext.Provider>
+  );
+}
+
+function useCart() {
+  const context = useContext(CartContext);
+  if (!context) throw new Error('useCart must be used within CartProvider');
+  return context;
+}
+```
+
+### Zustand (Lightweight Alternative)
+
+```tsx
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+interface AuthStore {
+  user: User | null;
+  token: string | null;
+  login: (email: string, password: string) => Promise<void>;
+  logout: () => void;
+}
+
+const useAuthStore = create<AuthStore>()(
+  persist(
+    (set) => ({
+      user: null,
+      token: null,
+      login: async (email, password) => {
+        const { user, token } = await authAPI.login(email, password);
+        set({ user, token });
+      },
+      logout: () => set({ user: null, token: null }),
+    }),
+    { name: 'auth-storage' }
+  )
+);
+
+// Usage
+function Profile() {
+  const { user, logout } = useAuthStore();
+  return user ? <div>{user.name} <button onClick={logout}>Logout</button></div> : null;
+}
+```
+
+---
+
+## Performance Patterns
+
+### React.memo with Custom Comparison
+
+```tsx
+interface ListItemProps {
+  item: { id: string; name: string; count: number };
+  onSelect: (id: string) => void;
+}
+
+const ListItem = React.memo(
+  function ListItem({ item, onSelect }: ListItemProps) {
+    return (
+      <div onClick={() => onSelect(item.id)}>
+        {item.name} ({item.count})
+      </div>
+    );
+  },
+  (prevProps, nextProps) => {
+    // Only re-render if item data changed
+    return (
+      prevProps.item.id === nextProps.item.id &&
+      prevProps.item.name === nextProps.item.name &&
+      prevProps.item.count === nextProps.item.count
+    );
+  }
+);
+```
+
+### useMemo for Expensive Calculations
+
+```tsx
+function DataTable({ data, sortColumn, filterText }: {
+  data: Item[];
+  sortColumn: string;
+  filterText: string;
+}) {
+  const processedData = useMemo(() => {
+    // Filter
+    let result = data.filter(item =>
+      item.name.toLowerCase().includes(filterText.toLowerCase())
+    );
+
+    // Sort
+    result = [...result].sort((a, b) => {
+      const aVal = a[sortColumn as keyof Item];
+      const bVal = b[sortColumn as keyof Item];
+      return aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
+    });
+
+    return result;
+  }, [data, sortColumn, filterText]);
+
+  return (
+    <table>
+      {processedData.map(item => (
+        <tr key={item.id}>{/* ... */}</tr>
+      ))}
+    </table>
+  );
+}
+```
+
+### useCallback for Stable References
+
+```tsx
+function ParentComponent() {
+  const [items, setItems] = useState<Item[]>([]);
+
+  // Stable reference - won't cause child re-renders
+  const handleItemClick = useCallback((id: string) => {
+    setItems(prev => prev.map(item =>
+      item.id === id ? { ...item, selected: !item.selected } : item
+    ));
+  }, []);
+
+  const handleAddItem = useCallback((newItem: Item) => {
+    setItems(prev => [...prev, newItem]);
+  }, []);
+
+  return (
+    <>
+      <ItemList items={items} onItemClick={handleItemClick} />
+      <AddItemForm onAdd={handleAddItem} />
+    </>
+  );
+}
+```
+
+### Virtualization for Long Lists
+
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual';
+
+function VirtualList({ items }: { items: Item[] }) {
+  const parentRef = useRef<HTMLDivElement>(null);
+
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 50, // estimated row height
+    overscan: 5,
+  });
+
+  return (
+    <div ref={parentRef} className="h-[400px] overflow-auto">
+      <div
+        style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}
+      >
+        {virtualizer.getVirtualItems().map(virtualRow => (
+          <div
+            key={virtualRow.key}
+            style={{
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              width: '100%',
+              height: `${virtualRow.size}px`,
+              transform: `translateY(${virtualRow.start}px)`,
+            }}
+          >
+            {items[virtualRow.index].name}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Error Boundaries
+
+### Class-Based Error Boundary
+
+```tsx
+interface ErrorBoundaryProps {
+  children: React.ReactNode;
+  fallback?: React.ReactNode;
+  onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+}
+
+class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+    this.props.onError?.(error, errorInfo);
+    // Log to error reporting service
+    console.error('Error caught:', error, errorInfo);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback || (
+        <div className="p-4 bg-red-50 border border-red-200 rounded">
+          <h2 className="text-red-800 font-bold">Something went wrong</h2>
+          <p className="text-red-600">{this.state.error?.message}</p>
+          <button
+            onClick={() => this.setState({ hasError: false, error: null })}
+            className="mt-2 px-4 py-2 bg-red-600 text-white rounded"
+          >
+            Try Again
+          </button>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+
+// Usage
+<ErrorBoundary
+  fallback={<ErrorFallback />}
+  onError={(error) => trackError(error)}
+>
+  <MyComponent />
+</ErrorBoundary>
+```
+
+### Suspense with Error Boundary
+
+```tsx
+function DataComponent() {
+  return (
+    <ErrorBoundary fallback={<ErrorMessage />}>
+      <Suspense fallback={<LoadingSpinner />}>
+        <AsyncDataLoader />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+```
+
+---
+
+## Anti-Patterns
+
+### Avoid: Inline Object/Array Creation in JSX
+
+```tsx
+// BAD - Creates new object every render, causes re-renders
+<Component style={{ color: 'red' }} items={[1, 2, 3]} />
+
+// GOOD - Define outside or use useMemo
+const style = { color: 'red' };
+const items = [1, 2, 3];
+<Component style={style} items={items} />
+
+// Or with useMemo for dynamic values
+const style = useMemo(() => ({ color: theme.primary }), [theme.primary]);
+```
+
+### Avoid: Index as Key for Dynamic Lists
+
+```tsx
+// BAD - Index keys break with reordering/filtering
+{items.map((item, index) => (
+  <Item key={index} data={item} />
+))}
+
+// GOOD - Use stable unique ID
+{items.map(item => (
+  <Item key={item.id} data={item} />
+))}
+```
+
+### Avoid: Prop Drilling
+
+```tsx
+// BAD - Passing props through many levels
+<App user={user}>
+  <Layout user={user}>
+    <Sidebar user={user}>
+      <UserInfo user={user} />
+    </Sidebar>
+  </Layout>
+</App>
+
+// GOOD - Use Context
+const UserContext = createContext<User | null>(null);
+
+function App() {
+  return (
+    <UserContext.Provider value={user}>
+      <Layout>
+        <Sidebar>
+          <UserInfo />
+        </Sidebar>
+      </Layout>
+    </UserContext.Provider>
+  );
+}
+
+function UserInfo() {
+  const user = useContext(UserContext);
+  return <div>{user?.name}</div>;
+}
+```
+
+### Avoid: Mutating State Directly
+
+```tsx
+// BAD - Mutates state directly
+const addItem = (item: Item) => {
+  items.push(item); // WRONG
+  setItems(items);  // Won't trigger re-render
+};
+
+// GOOD - Create new array
+const addItem = (item: Item) => {
+  setItems(prev => [...prev, item]);
+};
+
+// GOOD - For objects
+const updateUser = (field: string, value: string) => {
+  setUser(prev => ({ ...prev, [field]: value }));
+};
+```
+
+### Avoid: useEffect for Derived State
+
+```tsx
+// BAD - Unnecessary effect and extra render
+const [items, setItems] = useState<Item[]>([]);
+const [total, setTotal] = useState(0);
+
+useEffect(() => {
+  setTotal(items.reduce((sum, item) => sum + item.price, 0));
+}, [items]);
+
+// GOOD - Compute during render
+const [items, setItems] = useState<Item[]>([]);
+const total = items.reduce((sum, item) => sum + item.price, 0);
+
+// Or useMemo for expensive calculations
+const total = useMemo(
+  () => items.reduce((sum, item) => sum + item.price, 0),
+  [items]
+);
+```
diff --git a/builtin-skills/frontend-design/stitch-design-taste/DESIGN.md b/builtin-skills/frontend-design/stitch-design-taste/DESIGN.md
new file mode 100644
index 00000000..ef78a972
--- /dev/null
+++ b/builtin-skills/frontend-design/stitch-design-taste/DESIGN.md
@@ -0,0 +1,121 @@
+# Design System: Taste Standard
+**Skill:** stitch-design-taste
+
+---
+
+## Configuration — Set Your Style
+Adjust these dials before using this design system. They control how creative, dense, and animated the output should be. Pick the level that fits your project.
+
+| Dial | Level | Description |
+|------|-------|-------------|
+| **Creativity** | `8` | `1` = Ultra-minimal, Swiss, silent, monochrome. `5` = Balanced, clean but with personality. `10` = Expressive, editorial, bold typography experiments, inline images in headlines, strong asymmetry. Default: `8` |
+| **Density** | `4` | `1` = Gallery-airy, massive whitespace. `5` = Balanced sections. `10` = Cockpit-dense, data-heavy. Default: `4` |
+| **Variance** | `8` | `1` = Predictable, symmetric grids. `5` = Subtle offsets. `10` = Artsy chaotic, no two sections alike. Default: `8` |
+| **Motion Intent** | `6` | `1` = Static, no animation noted. `5` = Subtle hover/entrance cues. `10` = Cinematic orchestration noted in every component. Default: `6` |
+
+> **How to use:** Change the numbers above to match your project's vibe. At **Creativity 1–3**, the system produces clean, quiet, Notion-like interfaces. At **Creativity 7–10**, expect inline image typography, dramatic scale contrast, and strong editorial layouts. The rest of the rules below adapt to your chosen levels.
+
+---
+
+## 1. Visual Theme & Atmosphere
+A restrained, gallery-airy interface with confident asymmetric layouts and fluid spring-physics motion. The atmosphere is clinical yet warm — like a well-lit architecture studio where every element earns its place through function. Density is balanced (Level 4), variance runs high (Level 8) to prevent symmetrical boredom, and motion is fluid but never theatrical (Level 6). The overall impression: expensive, intentional, alive.
+
+## 2. Color Palette & Roles
+- **Canvas White** (#F9FAFB) — Primary background surface. Warm-neutral, never clinical blue-white
+- **Pure Surface** (#FFFFFF) — Card and container fill. Used with whisper shadow for elevation
+- **Charcoal Ink** (#18181B) — Primary text. Zinc-950 depth — never pure black
+- **Steel Secondary** (#71717A) — Body text, descriptions, metadata. Zinc-500 warmth
+- **Muted Slate** (#94A3B8) — Tertiary text, timestamps, disabled states
+- **Whisper Border** (rgba(226,232,240,0.5)) — Card borders, structural 1px lines. Semi-transparent for depth
+- **Diffused Shadow** (rgba(0,0,0,0.05)) — Card elevation. Wide-spreading, 40px blur, -15px offset. Never harsh
+
+### Accent Selection (Pick ONE per project)
+- **Emerald Signal** (#10B981) — For growth, success, positive data dashboards
+- **Electric Blue** (#3B82F6) — For productivity, SaaS, developer tools
+- **Deep Rose** (#E11D48) — For creative, editorial, fashion-adjacent projects
+- **Amber Warmth** (#F59E0B) — For community, social, warm-toned products
+
+### Banned Colors
+- Purple/Violet neon gradients — the "AI Purple" aesthetic
+- Pure Black (#000000) — always Off-Black or Zinc-950
+- Oversaturated accents above 80% saturation
+- Mixed warm/cool gray systems within one project
+
+## 3. Typography Rules
+- **Display:** `Geist`, `Satoshi`, `Cabinet Grotesk`, or `Outfit` — Track-tight (`-0.025em`), controlled fluid scale, weight-driven hierarchy (700–900). Not screaming. Leading compressed (`1.1`). Alternatives forced — `Inter` is BANNED for premium contexts
+- **Body:** Same family at weight 400 — Relaxed leading (`1.65`), 65ch max-width, Steel Secondary color (#71717A)
+- **Mono:** `Geist Mono` or `JetBrains Mono` — For code blocks, metadata, timestamps. When density exceeds Level 7, all numbers switch to monospace
+- **Scale:** Display at `clamp(2.25rem, 5vw, 3.75rem)`. Body at `1rem/1.125rem`. Mono metadata at `0.8125rem`
+
+### Banned Fonts
+- `Inter` — banned everywhere in premium/creative contexts
+- Generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`, `Palatino`) — BANNED. If serif is needed for editorial/creative, use only distinctive modern serifs like `Fraunces`, `Gambarino`, `Editorial New`, or `Instrument Serif`. Never use default browser serif stacks. Serif is always BANNED in dashboards or software UIs regardless
+
+## 4. Component Stylings
+* **Buttons:** Flat surface, no outer glow. Primary: accent fill with white text. Secondary: ghost/outline. Active state: `-1px translateY` or `scale(0.98)` for tactile push. Hover: subtle background shift, never glow
+* **Cards/Containers:** Generously rounded corners (`2.5rem`). Pure white fill. Whisper border (`1px`, semi-transparent). Diffused shadow (`0 20px 40px -15px rgba(0,0,0,0.05)`). Internal padding `2rem–2.5rem`. Used ONLY when elevation communicates hierarchy — high-density layouts replace cards with `border-top` dividers or negative space
+* **Inputs/Forms:** Label positioned above input. Helper text optional. Error text below in Deep Rose. Focus ring in accent color, `2px` offset. No floating labels. Standard `0.5rem` gap between label-input-error stack
+* **Navigation:** Sleek, sticky. Icons scale on hover (Dock Magnification optional). No hamburger on desktop. Clean horizontal with generous spacing
+* **Loaders:** Skeletal shimmer matching exact layout dimensions and rounded corners. Shifting light reflection across placeholder shapes. Never circular spinners
+* **Empty States:** Composed illustration or icon composition with guidance text. Never just "No data found"
+* **Error States:** Inline, contextual. Red accent underline or border. Clear recovery action
+
+## 5. Hero Section
+The Hero is the first impression — it must be striking, creative, and never generic.
+- **Inline Image Typography:** Embed small, contextual photos or visuals directly between words or letters in the headline. Example: "We build [photo of hands typing] digital [photo of screen] products" — images sit inline at type-height, rounded, acting as visual punctuation between words. This is the signature creative technique
+- **No Overlapping Elements:** Text must never overlap images or other text. Every element has its own clear spatial zone. No z-index stacking of content layers, no absolute-positioned headlines over images. Clean separation always
+- **No Filler Text:** "Scroll to explore", "Swipe down", scroll arrow icons, bouncing chevrons, and any instructional UI chrome are BANNED. The user knows how to scroll. Let the content pull them in naturally
+- **Asymmetric Structure:** Centered Hero layouts are BANNED at this variance level. Use Split Screen (50/50), Left-Aligned text / Right visual, or Asymmetric Whitespace with large empty zones
+- **CTA Restraint:** Maximum one primary CTA button. No secondary "Learn more" links. No redundant micro-copy below the headline
+
+## 6. Layout Principles
+- **Grid-First:** CSS Grid for all structural layouts. Never flexbox percentage math (`calc(33% - 1rem)` is BANNED)
+- **No Overlapping:** Elements must never overlap each other. No absolute-positioned layers stacking content on content. Every element occupies its own grid cell or flow position. Clean, separated spatial zones
+- **Feature Sections:** The "3 equal cards in a row" pattern is BANNED. Use 2-column Zig-Zag, asymmetric Bento grids (2fr 1fr 1fr), or horizontal scroll galleries
+- **Containment:** All content within `max-width: 1400px`, centered. Generous horizontal padding (`1rem` mobile, `2rem` tablet, `4rem` desktop)
+- **Full-Height:** Use `min-height: 100dvh` — never `height: 100vh` (iOS Safari address bar jump)
+- **Bento Architecture:** For feature grids, use Row 1: 3 columns | Row 2: 2 columns (70/30 split). Each tile contains a perpetual micro-animation
+
+## 7. Responsive Rules
+Every screen must work flawlessly across all viewports. **Responsive is not optional — it is a hard requirement. Every single element must be tested at 375px, 768px, and 1440px.**
+- **Mobile-First Collapse (< 768px):** All multi-column layouts collapse to a strict single column. `width: 100%`, `padding: 1rem`, `gap: 1.5rem`. No exceptions
+- **No Horizontal Scroll:** Horizontal overflow on mobile is a critical failure. All elements must fit within viewport width. If any element causes horizontal scroll, the design is broken
+- **Typography Scaling:** Headlines scale down gracefully via `clamp()`. Body text stays `1rem` minimum. Never shrink body below `14px`. Headlines must remain readable on 375px screens
+- **Touch Targets:** All interactive elements minimum `44px` tap target. Generous spacing between clickable items. Buttons must be full-width on mobile
+- **Image Behavior:** Hero and inline images scale proportionally. Inline typography images (photos between words) stack below the headline on mobile instead of inline
+- **Navigation:** Desktop horizontal nav collapses to a clean mobile menu (slide-in or full-screen overlay). No tiny hamburger icons without labels
+- **Cards & Grids:** Bento grids and asymmetric layouts revert to stacked single-column cards with full-width. Maintain internal padding (`1rem`)
+- **Spacing Consistency:** Vertical section gaps reduce proportionally on mobile (`clamp(3rem, 8vw, 6rem)`). Never cramped, never excessively airy
+- **Testing Viewports:** Designs must be verified at: `375px` (iPhone SE), `390px` (iPhone 14), `768px` (iPad), `1024px` (small laptop), `1440px` (desktop)
+
+## 8. Motion & Interaction (Code-Phase Intent)
+> **Note:** Stitch generates static screens — it does not animate. This section documents the **intended motion behavior** so that the coding agent (Antigravity, Cursor, etc.) knows exactly how to implement animations when building the exported design into a live product.
+
+- **Physics Engine:** Spring-based exclusively. `stiffness: 100, damping: 20`. No linear easing anywhere. Premium, weighty feel on all interactive elements
+- **Perpetual Micro-Loops:** Every active dashboard component has an infinite-loop state — Pulse on status dots, Typewriter on search bars, Float on feature icons, Shimmer on loading states
+- **Staggered Orchestration:** Lists and grids mount with cascaded delays (`animation-delay: calc(var(--index) * 100ms)`). Waterfall reveals, never instant mount
+- **Layout Transitions:** Smooth re-ordering via shared element IDs. Items swap positions with physics, simulating real-time intelligence
+- **Hardware Rules:** Animate ONLY `transform` and `opacity`. Never `top`, `left`, `width`, `height`. Grain/noise filters on fixed, pointer-events-none pseudo-elements only
+- **Performance:** CPU-heavy perpetual animations isolated in microscopic leaf components. Never trigger parent re-renders. Target 60fps minimum
+
+## 9. Anti-Patterns (Banned)
+- No emojis — anywhere in UI, code, or alt text
+- No `Inter` font — use `Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`
+- No generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`) — if serif is needed, use distinctive modern serifs only (`Fraunces`, `Instrument Serif`)
+- No pure black (`#000000`) — Off-Black or Zinc-950 only
+- No neon outer glows or default box-shadow glows
+- No oversaturated accent colors above 80%
+- No excessive gradient text on large headers
+- No custom mouse cursors
+- No overlapping elements — text never overlaps images or other content. Clean spatial separation always
+- No 3-column equal card layouts for features
+- No centered Hero sections (at this variance level)
+- No filler UI text: "Scroll to explore", "Swipe down", "Discover more below", scroll arrows, bouncing chevrons — all BANNED
+- No generic names: "John Doe", "Sarah Chan", "Acme", "Nexus", "SmartFlow"
+- No fake round numbers: `99.99%`, `50%`, `1234567` — use organic data: `47.2%`, `+1 (312) 847-1928`
+- No AI copywriting clichés: "Elevate", "Seamless", "Unleash", "Next-Gen", "Revolutionize"
+- No broken Unsplash links — use `picsum.photos/seed/{id}/800/600` or SVG UI Avatars
+- No generic `shadcn/ui` defaults — customize radii, colors, shadows to match this system
+- No `z-index` spam — use only for Navbar, Modal, Overlay layer contexts
+- No `h-screen` — always `min-h-[100dvh]`
+- No circular loading spinners — skeletal shimmer only
diff --git a/builtin-skills/frontend-design/stitch-design-taste/SKILL.md b/builtin-skills/frontend-design/stitch-design-taste/SKILL.md
new file mode 100644
index 00000000..56e1266f
--- /dev/null
+++ b/builtin-skills/frontend-design/stitch-design-taste/SKILL.md
@@ -0,0 +1,184 @@
+---
+name: stitch-design-taste
+description: Semantic Design System Skill for Google Stitch. Generates agent-friendly DESIGN.md files that enforce premium, anti-generic UI standards — strict typography, calibrated color, asymmetric layouts, perpetual micro-motion, and hardware-accelerated performance.
+---
+
+# Stitch Design Taste — Semantic Design System Skill
+
+## Overview
+This skill generates `DESIGN.md` files optimized for Google Stitch screen generation. It translates the battle-tested anti-slop frontend engineering directives into Stitch's native semantic design language — descriptive, natural-language rules paired with precise values that Stitch's AI agent can interpret to produce premium, non-generic interfaces.
+
+The generated `DESIGN.md` serves as the **single source of truth** for prompting Stitch to generate new screens that align with a curated, high-agency design language. Stitch interprets design through **"Visual Descriptions"** supported by specific color values, typography specs, and component behaviors.
+
+## Prerequisites
+- Access to Google Stitch via [labs.google.com/stitch](https://labs.google.com/stitch)
+- Optionally: Stitch MCP Server for programmatic integration with Cursor, Antigravity, or Gemini CLI
+
+## The Goal
+Generate a `DESIGN.md` file that encodes:
+1. **Visual atmosphere** — the mood, density, and design philosophy
+2. **Color calibration** — neutrals, accents, and banned patterns with hex codes
+3. **Typographic architecture** — font stacks, scale hierarchy, and anti-patterns
+4. **Component behaviors** — buttons, cards, inputs with interaction states
+5. **Layout principles** — grid systems, spacing philosophy, responsive strategy
+6. **Motion philosophy** — animation engine specs, spring physics, perpetual micro-interactions
+7. **Anti-patterns** — explicit list of banned AI design clichés
+
+## Analysis & Synthesis Instructions
+
+### 1. Define the Atmosphere
+Evaluate the target project's intent. Use evocative adjectives from the taste spectrum:
+- **Density:** "Art Gallery Airy" (1–3) → "Daily App Balanced" (4–7) → "Cockpit Dense" (8–10)
+- **Variance:** "Predictable Symmetric" (1–3) → "Offset Asymmetric" (4–7) → "Artsy Chaotic" (8–10)
+- **Motion:** "Static Restrained" (1–3) → "Fluid CSS" (4–7) → "Cinematic Choreography" (8–10)
+
+Default baseline: Variance 8, Motion 6, Density 4. Adapt dynamically based on user's vibe description.
+
+### 2. Map the Color Palette
+For each color provide: **Descriptive Name** + **Hex Code** + **Functional Role**.
+
+**Mandatory constraints:**
+- Maximum 1 accent color. Saturation below 80%
+- The "AI Purple/Blue Neon" aesthetic is strictly BANNED — no purple button glows, no neon gradients
+- Use absolute neutral bases (Zinc/Slate) with high-contrast singular accents
+- Stick to one palette for the entire output — no warm/cool gray fluctuation
+- Never use pure black (`#000000`) — use Off-Black, Zinc-950, or Charcoal
+
+### 3. Establish Typography Rules
+- **Display/Headlines:** Track-tight, controlled scale. Not screaming. Hierarchy through weight and color, not just massive size
+- **Body:** Relaxed leading, max 65 characters per line
+- **Font Selection:** `Inter` is BANNED for premium/creative contexts. Force unique character: `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`
+- **Serif Ban:** Generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`, `Palatino`) are BANNED. If serif is needed for editorial/creative contexts, use only distinctive modern serifs: `Fraunces`, `Gambarino`, `Editorial New`, or `Instrument Serif`. Serif is always BANNED in dashboards or software UIs
+- **Dashboard Constraint:** Use Sans-Serif pairings exclusively (`Geist` + `Geist Mono` or `Satoshi` + `JetBrains Mono`)
+- **High-Density Override:** When density exceeds 7, all numbers must use Monospace
+
+### 4. Define the Hero Section
+The Hero is the first impression and must be creative, striking, and never generic:
+- **Inline Image Typography:** Embed small, contextual photos or visuals directly between words or letters in the headline. Images sit inline at type-height, rounded, acting as visual punctuation. This is the signature creative technique
+- **No Overlapping:** Text must never overlap images or other text. Every element occupies its own clean spatial zone
+- **No Filler Text:** "Scroll to explore", "Swipe down", scroll arrow icons, bouncing chevrons are BANNED. The content should pull users in naturally
+- **Asymmetric Structure:** Centered Hero layouts BANNED when variance exceeds 4
+- **CTA Restraint:** Maximum one primary CTA. No secondary "Learn more" links
+
+### 5. Describe Component Stylings
+For each component type, describe shape, color, shadow depth, and interaction behavior:
+- **Buttons:** Tactile push feedback on active state. No neon outer glows. No custom mouse cursors
+- **Cards:** Use ONLY when elevation communicates hierarchy. Tint shadows to background hue. For high-density layouts, replace cards with border-top dividers or negative space
+- **Inputs/Forms:** Label above input, helper text optional, error text below. Standard gap spacing
+- **Loading States:** Skeletal loaders matching layout dimensions — no generic circular spinners
+- **Empty States:** Composed compositions indicating how to populate data
+- **Error States:** Clear, inline error reporting
+
+### 6. Define Layout Principles
+- No overlapping elements — every element occupies its own clear spatial zone. No absolute-positioned content stacking
+- Centered Hero sections are BANNED when variance exceeds 4 — force Split Screen, Left-Aligned, or Asymmetric Whitespace
+- The generic "3 equal cards horizontally" feature row is BANNED — use 2-column Zig-Zag, asymmetric grid, or horizontal scroll
+- CSS Grid over Flexbox math — never use `calc()` percentage hacks
+- Contain layouts using max-width constraints (e.g., 1400px centered)
+- Full-height sections must use `min-h-[100dvh]` — never `h-screen` (iOS Safari catastrophic jump)
+
+### 7. Define Responsive Rules
+Every design must work across all viewports:
+- **Mobile-First Collapse (< 768px):** All multi-column layouts collapse to single column. No exceptions
+- **No Horizontal Scroll:** Horizontal overflow on mobile is a critical failure
+- **Typography Scaling:** Headlines scale via `clamp()`. Body text minimum `1rem`/`14px`
+- **Touch Targets:** All interactive elements minimum `44px` tap target
+- **Image Behavior:** Inline typography images (photos between words) stack below headline on mobile
+- **Navigation:** Desktop horizontal nav collapses to clean mobile menu
+- **Spacing:** Vertical section gaps reduce proportionally (`clamp(3rem, 8vw, 6rem)`)
+
+### 8. Encode Motion Philosophy
+- **Spring Physics default:** `stiffness: 100, damping: 20` — premium, weighty feel. No linear easing
+- **Perpetual Micro-Interactions:** Every active component should have an infinite loop state (Pulse, Typewriter, Float, Shimmer)
+- **Staggered Orchestration:** Never mount lists instantly — use cascade delays for waterfall reveals
+- **Performance:** Animate exclusively via `transform` and `opacity`. Never animate `top`, `left`, `width`, `height`. Grain/noise filters on fixed pseudo-elements only
+
+### 9. List Anti-Patterns (AI Tells)
+Encode these as explicit "NEVER DO" rules in the DESIGN.md:
+- No emojis anywhere
+- No `Inter` font
+- No generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`) — distinctive modern serifs only if needed
+- No pure black (`#000000`)
+- No neon/outer glow shadows
+- No oversaturated accents
+- No excessive gradient text on large headers
+- No custom mouse cursors
+- No overlapping elements — clean spatial separation always
+- No 3-column equal card layouts
+- No generic names ("John Doe", "Acme", "Nexus")
+- No fake round numbers (`99.99%`, `50%`)
+- No AI copywriting clichés ("Elevate", "Seamless", "Unleash", "Next-Gen")
+- No filler UI text: "Scroll to explore", "Swipe down", scroll arrows, bouncing chevrons
+- No broken Unsplash links — use `picsum.photos` or SVG avatars
+- No centered Hero sections (for high-variance projects)
+
+## Output Format (DESIGN.md Structure)
+
+```markdown
+# Design System: [Project Title]
+
+## 1. Visual Theme & Atmosphere
+(Evocative description of the mood, density, variance, and motion intensity.
+Example: "A restrained, gallery-airy interface with confident asymmetric layouts
+and fluid spring-physics motion. The atmosphere is clinical yet warm — like a
+well-lit architecture studio.")
+
+## 2. Color Palette & Roles
+- **Canvas White** (#F9FAFB) — Primary background surface
+- **Pure Surface** (#FFFFFF) — Card and container fill
+- **Charcoal Ink** (#18181B) — Primary text, Zinc-950 depth
+- **Muted Steel** (#71717A) — Secondary text, descriptions, metadata
+- **Whisper Border** (rgba(226,232,240,0.5)) — Card borders, 1px structural lines
+- **[Accent Name]** (#XXXXXX) — Single accent for CTAs, active states, focus rings
+(Max 1 accent. Saturation < 80%. No purple/neon.)
+
+## 3. Typography Rules
+- **Display:** [Font Name] — Track-tight, controlled scale, weight-driven hierarchy
+- **Body:** [Font Name] — Relaxed leading, 65ch max-width, neutral secondary color
+- **Mono:** [Font Name] — For code, metadata, timestamps, high-density numbers
+- **Banned:** Inter, generic system fonts for premium contexts. Serif fonts banned in dashboards.
+
+## 4. Component Stylings
+* **Buttons:** Flat, no outer glow. Tactile -1px translate on active. Accent fill for primary, ghost/outline for secondary.
+* **Cards:** Generously rounded corners (2.5rem). Diffused whisper shadow. Used only when elevation serves hierarchy. High-density: replace with border-top dividers.
+* **Inputs:** Label above, error below. Focus ring in accent color. No floating labels.
+* **Loaders:** Skeletal shimmer matching exact layout dimensions. No circular spinners.
+* **Empty States:** Composed, illustrated compositions — not just "No data" text.
+
+## 5. Layout Principles
+(Grid-first responsive architecture. Asymmetric splits for Hero sections.
+Strict single-column collapse below 768px. Max-width containment.
+No flexbox percentage math. Generous internal padding.)
+
+## 6. Motion & Interaction
+(Spring physics for all interactive elements. Staggered cascade reveals.
+Perpetual micro-loops on active dashboard components. Hardware-accelerated
+transforms only. Isolated Client Components for CPU-heavy animations.)
+
+## 7. Anti-Patterns (Banned)
+(Explicit list of forbidden patterns: no emojis, no Inter, no pure black,
+no neon glows, no 3-column equal grids, no AI copywriting clichés,
+no generic placeholder names, no broken image links.)
+```
+
+## Best Practices
+- **Be Descriptive:** "Deep Charcoal Ink (#18181B)" — not just "dark text"
+- **Be Functional:** Explain what each element is used for
+- **Be Consistent:** Same terminology throughout the document
+- **Be Precise:** Include exact hex codes, rem values, pixel values in parentheses
+- **Be Opinionated:** This is not a neutral template — it enforces a specific, premium aesthetic
+
+## Tips for Success
+1. Start with the atmosphere — understand the vibe before detailing tokens
+2. Look for patterns — identify consistent spacing, sizing, and styling
+3. Think semantically — name colors by purpose, not just appearance
+4. Consider hierarchy — document how visual weight communicates importance
+5. Encode the bans — anti-patterns are as important as the rules themselves
+
+## Common Pitfalls to Avoid
+- Using technical jargon without translation ("rounded-xl" instead of "generously rounded corners")
+- Omitting hex codes or using only descriptive names
+- Forgetting functional roles of design elements
+- Being too vague in atmosphere descriptions
+- Ignoring the anti-pattern list — these are what make the output premium
+- Defaulting to generic "safe" designs instead of enforcing the curated aesthetic
diff --git a/builtin-skills/iOS-Dev/app-icon-generator/SKILL.md b/builtin-skills/iOS-Dev/app-icon-generator/SKILL.md
new file mode 100644
index 00000000..1fcd27f1
--- /dev/null
+++ b/builtin-skills/iOS-Dev/app-icon-generator/SKILL.md
@@ -0,0 +1,526 @@
+---
+name: app-icon-generator
+description: Generates app icons in all required sizes for iOS, Android, and PWA from a single source image. Use when user asks to "generate app icons", "create ios icons", "android app icons", "favicon", or "pwa icons".
+allowed-tools: [Read, Write, Bash, Glob]
+---
+
+# App Icon Generator
+
+Generates app icons in all required sizes for iOS, Android, PWA, and web from a single source image.
+
+## When to Use
+
+- "Generate app icons for iOS"
+- "Create Android app icons"
+- "Generate all icon sizes"
+- "Create favicon"
+- "PWA icons"
+- "App icon set"
+
+## Instructions
+
+### 1. Verify Source Image
+
+Check for source icon file:
+
+```bash
+# Look for icon source
+find . -name "*icon*.png" -o -name "*logo*.png"
+```
+
+**Source image requirements:**
+- Minimum 1024x1024 pixels (recommended)
+- Square (1:1 aspect ratio)
+- PNG format with transparency (if needed)
+- High quality, not compressed
+- No text too close to edges (safe area: center 70%)
+
+Present findings and ask for source if not found.
+
+### 2. Check for Image Processing Tools
+
+Verify available tools:
+
+```bash
+# Check for ImageMagick
+which convert || echo "ImageMagick not found"
+
+# Check for sharp-cli
+which sharp || echo "sharp-cli not found"
+
+# Check for sips (macOS)
+which sips || echo "sips not found (macOS only)"
+```
+
+**Installation guide if needed:**
+
+```bash
+# macOS
+brew install imagemagick
+
+# Ubuntu/Debian
+sudo apt-get install imagemagick
+
+# Node.js (cross-platform, recommended)
+npm install -g sharp-cli
+```
+
+### 3. Generate iOS Icons
+
+**iOS requires multiple sizes:**
+
+```bash
+# iOS App Icons (all required sizes)
+declare -a ios_sizes=(
+  "20"    # iPhone Notification (2x, 3x)
+  "29"    # iPhone Settings (2x, 3x)
+  "40"    # iPhone Spotlight (2x, 3x)
+  "60"    # iPhone App (2x, 3x)
+  "76"    # iPad App (1x, 2x)
+  "83.5"  # iPad Pro App (2x)
+  "1024"  # App Store
+)
+
+# Generate using ImageMagick
+for size in "${ios_sizes[@]}"; do
+  convert icon-source.png -resize ${size}x${size} "ios/icon-${size}.png"
+
+  # Generate 2x
+  size2x=$((size * 2))
+  convert icon-source.png -resize ${size2x}x${size2x} "ios/icon-${size}@2x.png"
+
+  # Generate 3x (for relevant sizes)
+  if [[ $size -eq 20 || $size -eq 29 || $size -eq 40 || $size -eq 60 ]]; then
+    size3x=$((size * 3))
+    convert icon-source.png -resize ${size3x}x${size3x} "ios/icon-${size}@3x.png"
+  fi
+done
+```
+
+**Or using sharp-cli:**
+
+```bash
+# Generate all iOS sizes
+sharp -i icon-source.png -o ios/icon-{size}.png \
+  resize 20 40 60 58 80 87 120 180 76 152 167 1024
+```
+
+**Contents.json for Xcode:**
+
+```json
+{
+  "images": [
+    {
+      "size": "20x20",
+      "idiom": "iphone",
+      "filename": "icon-40.png",
+      "scale": "2x"
+    },
+    {
+      "size": "20x20",
+      "idiom": "iphone",
+      "filename": "icon-60.png",
+      "scale": "3x"
+    },
+    {
+      "size": "29x29",
+      "idiom": "iphone",
+      "filename": "icon-58.png",
+      "scale": "2x"
+    },
+    {
+      "size": "29x29",
+      "idiom": "iphone",
+      "filename": "icon-87.png",
+      "scale": "3x"
+    },
+    {
+      "size": "40x40",
+      "idiom": "iphone",
+      "filename": "icon-80.png",
+      "scale": "2x"
+    },
+    {
+      "size": "40x40",
+      "idiom": "iphone",
+      "filename": "icon-120.png",
+      "scale": "3x"
+    },
+    {
+      "size": "60x60",
+      "idiom": "iphone",
+      "filename": "icon-120.png",
+      "scale": "2x"
+    },
+    {
+      "size": "60x60",
+      "idiom": "iphone",
+      "filename": "icon-180.png",
+      "scale": "3x"
+    },
+    {
+      "size": "1024x1024",
+      "idiom": "ios-marketing",
+      "filename": "icon-1024.png",
+      "scale": "1x"
+    }
+  ],
+  "info": {
+    "version": 1,
+    "author": "xcode"
+  }
+}
+```
+
+### 4. Generate Android Icons
+
+**Android adaptive icons:**
+
+Android uses adaptive icons with separate foreground and background layers.
+
+```bash
+# Android icon sizes (in dp)
+# mdpi = 1x, hdpi = 1.5x, xhdpi = 2x, xxhdpi = 3x, xxxhdpi = 4x
+
+# mipmap-mdpi (48x48)
+convert icon-source.png -resize 48x48 android/mipmap-mdpi/ic_launcher.png
+
+# mipmap-hdpi (72x72)
+convert icon-source.png -resize 72x72 android/mipmap-hdpi/ic_launcher.png
+
+# mipmap-xhdpi (96x96)
+convert icon-source.png -resize 96x96 android/mipmap-xhdpi/ic_launcher.png
+
+# mipmap-xxhdpi (144x144)
+convert icon-source.png -resize 144x144 android/mipmap-xxhdpi/ic_launcher.png
+
+# mipmap-xxxhdpi (192x192)
+convert icon-source.png -resize 192x192 android/mipmap-xxxhdpi/ic_launcher.png
+
+# Play Store (512x512)
+convert icon-source.png -resize 512x512 android/playstore-icon.png
+```
+
+**Adaptive icon XML:**
+
+```xml
+<!-- res/mipmap-anydpi-v26/ic_launcher.xml -->
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/ic_launcher_background"/>
+    <foreground android:drawable="@mipmap/ic_launcher_foreground"/>
+</adaptive-icon>
+```
+
+**Round icon variant:**
+
+```bash
+# Generate round icons (same sizes)
+for size in 48 72 96 144 192; do
+  density=$(get_density $size)  # mdpi, hdpi, etc.
+  convert icon-source.png -resize ${size}x${size} \
+    \( +clone -threshold -1 -negate -fill white -draw "circle $((size/2)),$((size/2)) $((size/2)),0" \) \
+    -alpha off -compose copy_opacity -composite \
+    "android/mipmap-${density}/ic_launcher_round.png"
+done
+```
+
+### 5. Generate PWA Icons
+
+**Progressive Web App icons:**
+
+```bash
+# PWA icon sizes
+sharp -i icon-source.png -o pwa/icon-{size}.png \
+  resize 72 96 128 144 152 192 384 512
+
+# Also generate maskable icons (with safe area)
+# Maskable icons need 40% safe area
+sharp -i icon-source.png -o pwa/icon-{size}-maskable.png \
+  resize 72 96 128 144 152 192 384 512 \
+  --extend top=10 bottom=10 left=10 right=10
+```
+
+**manifest.json:**
+
+```json
+{
+  "name": "My App",
+  "short_name": "App",
+  "icons": [
+    {
+      "src": "/icons/icon-72.png",
+      "sizes": "72x72",
+      "type": "image/png"
+    },
+    {
+      "src": "/icons/icon-96.png",
+      "sizes": "96x96",
+      "type": "image/png"
+    },
+    {
+      "src": "/icons/icon-128.png",
+      "sizes": "128x128",
+      "type": "image/png"
+    },
+    {
+      "src": "/icons/icon-144.png",
+      "sizes": "144x144",
+      "type": "image/png"
+    },
+    {
+      "src": "/icons/icon-152.png",
+      "sizes": "152x152",
+      "type": "image/png"
+    },
+    {
+      "src": "/icons/icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/icons/icon-384.png",
+      "sizes": "384x384",
+      "type": "image/png"
+    },
+    {
+      "src": "/icons/icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    },
+    {
+      "src": "/icons/icon-192-maskable.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "maskable"
+    },
+    {
+      "src": "/icons/icon-512-maskable.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    }
+  ]
+}
+```
+
+### 6. Generate Favicons
+
+**Web favicons (multiple sizes):**
+
+```bash
+# Standard sizes
+convert icon-source.png -resize 16x16 favicon-16.png
+convert icon-source.png -resize 32x32 favicon-32.png
+convert icon-source.png -resize 48x48 favicon-48.png
+
+# Create multi-size .ico file
+convert favicon-16.png favicon-32.png favicon-48.png favicon.ico
+
+# Apple touch icon
+convert icon-source.png -resize 180x180 apple-touch-icon.png
+
+# Microsoft tile
+convert icon-source.png -resize 144x144 mstile-144.png
+```
+
+**HTML head tags:**
+
+```html
+<!-- Favicons -->
+<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16.png">
+<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32.png">
+<link rel="icon" type="image/png" sizes="48x48" href="/favicon-48.png">
+<link rel="shortcut icon" href="/favicon.ico">
+
+<!-- Apple touch icon -->
+<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
+
+<!-- Android -->
+<link rel="icon" type="image/png" sizes="192x192" href="/android-chrome-192.png">
+<link rel="icon" type="image/png" sizes="512x512" href="/android-chrome-512.png">
+
+<!-- Microsoft -->
+<meta name="msapplication-TileColor" content="#ffffff">
+<meta name="msapplication-TileImage" content="/mstile-144.png">
+```
+
+### 7. Generate React Native Icons
+
+**For React Native apps:**
+
+```bash
+# iOS (place in ios/AppName/Images.xcassets/AppIcon.appiconset/)
+# Same as iOS native above
+
+# Android (place in android/app/src/main/res/)
+# Same as Android native above
+```
+
+**Or use react-native-make:**
+
+```bash
+npx react-native set-icon --path icon-source.png
+```
+
+### 8. Generate Flutter Icons
+
+**Using flutter_launcher_icons:**
+
+```yaml
+# pubspec.yaml
+dev_dependencies:
+  flutter_launcher_icons: ^0.13.1
+
+flutter_launcher_icons:
+  android: "launcher_icon"
+  ios: true
+  image_path: "assets/icon.png"
+  adaptive_icon_background: "#ffffff"
+  adaptive_icon_foreground: "assets/icon-foreground.png"
+```
+
+```bash
+# Generate icons
+flutter pub get
+flutter pub run flutter_launcher_icons
+```
+
+### 9. Create Automated Script
+
+**Complete icon generation script:**
+
+```bash
+#!/bin/bash
+# generate-icons.sh
+
+SOURCE_ICON="icon-source.png"
+OUTPUT_DIR="generated-icons"
+
+# Check if source exists
+if [ ! -f "$SOURCE_ICON" ]; then
+  echo "Error: Source icon not found: $SOURCE_ICON"
+  exit 1
+fi
+
+# Create directories
+mkdir -p "$OUTPUT_DIR"/{ios,android,pwa,web}
+
+echo "🎨 Generating app icons..."
+
+# iOS icons
+echo "📱 iOS icons..."
+for size in 40 60 58 87 80 120 180 76 152 167 1024; do
+  convert "$SOURCE_ICON" -resize ${size}x${size} \
+    "$OUTPUT_DIR/ios/icon-${size}.png"
+  echo "  ✓ ${size}x${size}"
+done
+
+# Android icons
+echo "🤖 Android icons..."
+convert "$SOURCE_ICON" -resize 48x48 "$OUTPUT_DIR/android/mdpi.png"
+convert "$SOURCE_ICON" -resize 72x72 "$OUTPUT_DIR/android/hdpi.png"
+convert "$SOURCE_ICON" -resize 96x96 "$OUTPUT_DIR/android/xhdpi.png"
+convert "$SOURCE_ICON" -resize 144x144 "$OUTPUT_DIR/android/xxhdpi.png"
+convert "$SOURCE_ICON" -resize 192x192 "$OUTPUT_DIR/android/xxxhdpi.png"
+convert "$SOURCE_ICON" -resize 512x512 "$OUTPUT_DIR/android/playstore.png"
+echo "  ✓ All densities generated"
+
+# PWA icons
+echo "🌐 PWA icons..."
+for size in 72 96 128 144 152 192 384 512; do
+  convert "$SOURCE_ICON" -resize ${size}x${size} \
+    "$OUTPUT_DIR/pwa/icon-${size}.png"
+  echo "  ✓ ${size}x${size}"
+done
+
+# Favicons
+echo "🔖 Favicons..."
+convert "$SOURCE_ICON" -resize 16x16 "$OUTPUT_DIR/web/favicon-16.png"
+convert "$SOURCE_ICON" -resize 32x32 "$OUTPUT_DIR/web/favicon-32.png"
+convert "$SOURCE_ICON" -resize 48x48 "$OUTPUT_DIR/web/favicon-48.png"
+convert "$OUTPUT_DIR/web/favicon-"{16,32,48}.png "$OUTPUT_DIR/web/favicon.ico"
+convert "$SOURCE_ICON" -resize 180x180 "$OUTPUT_DIR/web/apple-touch-icon.png"
+echo "  ✓ All favicons generated"
+
+echo "✅ Icon generation complete!"
+echo "📁 Icons saved to: $OUTPUT_DIR"
+```
+
+### 10. Provide Integration Instructions
+
+**iOS (Xcode):**
+1. Open Xcode project
+2. Navigate to Assets.xcassets
+3. Right-click → New App Icon
+4. Drag generated icons to appropriate slots
+
+**Android (Android Studio):**
+1. Right-click res folder
+2. New → Image Asset
+3. Select generated icons
+4. Configure adaptive icon layers
+
+**Web:**
+1. Copy icons to public/icons/ folder
+2. Update manifest.json with icon paths
+3. Add favicon links to index.html
+
+**React Native:**
+1. Copy iOS icons to `ios/AppName/Images.xcassets/AppIcon.appiconset/`
+2. Copy Android icons to `android/app/src/main/res/mipmap-*/`
+3. Update Contents.json for iOS
+
+### Best Practices
+
+**Design Guidelines:**
+- Keep important content in center 80%
+- Avoid thin lines (minimum 2px)
+- Test on dark and light backgrounds
+- Use simple, recognizable shapes
+- Avoid text (too small on icons)
+- Use bold colors for visibility
+
+**Technical Guidelines:**
+- Source: 1024x1024 minimum
+- Format: PNG with transparency
+- Color space: sRGB
+- No compression on source
+- Square aspect ratio
+- Safe area for maskable: 40% padding
+
+**Testing:**
+- Test on actual devices
+- Check all sizes render correctly
+- Verify transparency works
+- Test dark mode appearance
+- Check adaptive icon animations (Android)
+
+### Size Reference
+
+**iOS:**
+- 20pt (40x40, 60x60)
+- 29pt (58x58, 87x87)
+- 40pt (80x80, 120x120)
+- 60pt (120x120, 180x180)
+- 76pt (76x76, 152x152)
+- 83.5pt (167x167)
+- 1024x1024 (App Store)
+
+**Android:**
+- mdpi: 48x48
+- hdpi: 72x72
+- xhdpi: 96x96
+- xxhdpi: 144x144
+- xxxhdpi: 192x192
+- Play Store: 512x512
+
+**PWA:**
+- 72x72, 96x96, 128x128
+- 144x144, 152x152, 192x192
+- 384x384, 512x512
+
+**Web:**
+- 16x16, 32x32 (favicon)
+- 180x180 (Apple touch)
+- 192x192, 512x512 (Android)
diff --git a/builtin-skills/iOS-Dev/app-store-screenshots/SKILL.md b/builtin-skills/iOS-Dev/app-store-screenshots/SKILL.md
new file mode 100644
index 00000000..1e09a2e9
--- /dev/null
+++ b/builtin-skills/iOS-Dev/app-store-screenshots/SKILL.md
@@ -0,0 +1,647 @@
+---
+name: app-store-screenshots
+description: Use when building App Store screenshot pages, generating exportable marketing screenshots for iOS apps, or creating programmatic screenshot generators with Next.js. Triggers on app store, screenshots, marketing assets, html-to-image, phone mockup.
+---
+
+# App Store Screenshots Generator
+
+## Overview
+
+Build a Next.js page that renders iOS App Store screenshots as **advertisements** (not UI showcases) and exports them via `html-to-image` at Apple's required resolutions. Screenshots are the single most important conversion asset on the App Store.
+
+## Core Principle
+
+**Screenshots are advertisements, not documentation.** Every screenshot sells one idea. If you're showing UI, you're doing it wrong — you're selling a *feeling*, an *outcome*, or killing a *pain point*.
+
+## Step 1: Ask the User These Questions
+
+Before writing ANY code, ask the user all of these. Do not proceed until you have answers:
+
+### Required
+
+1. **App screenshots** — "Where are your app screenshots? (PNG files of actual device captures)"
+2. **App icon** — "Where is your app icon PNG?"
+3. **Brand colors** — "What are your brand colors? (accent color, text color, background preference)"
+4. **Font** — "What font does your app use? (or what font do you want for the screenshots?)"
+5. **Feature list** — "List your app's features in priority order. What's the #1 thing your app does?"
+6. **Number of slides** — "How many screenshots do you want? (Apple allows up to 10)"
+7. **Style direction** — "What style do you want? Examples: warm/organic, dark/moody, clean/minimal, bold/colorful, gradient-heavy, flat. Share App Store screenshot references if you have any."
+
+### Optional
+
+8. **iPad screenshots** — "Do you also have iPad screenshots? If so, we'll generate iPad App Store screenshots too (recommended for universal apps)."
+9. **Component assets** — "Do you have any UI element PNGs (cards, widgets, etc.) you want as floating decorations? If not, that's fine — we'll skip them."
+10. **Localized screenshots** — "Do you want screenshots in multiple languages? This helps your listing rank in regional App Stores even if your app is English-only. If yes: which languages? (e.g. en, de, es, pt, ja, ar, he)"
+11. **Theme preset system** — "Do you want one art direction, or reusable visual themes (for example: clean-light, dark-bold, warm-editorial) so you can swap screenshot looks quickly?"
+12. **Additional instructions** — "Any specific requirements, constraints, or preferences?"
+
+### Derived from answers (do NOT ask — decide yourself)
+
+Based on the user's style direction, brand colors, and app aesthetic, decide:
+- **Background style**: gradient direction, colors, whether light or dark base
+- **Decorative elements**: blobs, glows, geometric shapes, or none — match the style
+- **Dark vs light slides**: how many of each, which features suit dark treatment
+- **Typography treatment**: weight, tracking, line height — match the brand personality
+- **Color palette**: derive text colors, secondary colors, shadow tints from the brand colors
+- **Theme preset names**: turn vague style requests into reusable theme ids the user can switch between
+- **RTL behavior**: if any locale is RTL (`ar`, `he`, `fa`, `ur`), mirror layout intentionally instead of just translating the text
+
+**IMPORTANT:** If the user gives additional instructions at any point during the process, follow them. User instructions always override skill defaults.
+
+## Step 2: Set Up the Project
+
+### Detect Package Manager
+
+Check what's available, use this priority: **bun > pnpm > yarn > npm**
+
+```bash
+# Check in order
+which bun && echo "use bun" || which pnpm && echo "use pnpm" || which yarn && echo "use yarn" || echo "use npm"
+```
+
+### Scaffold (if no existing Next.js project)
+
+```bash
+# With bun:
+bunx create-next-app@latest . --typescript --tailwind --app --src-dir --no-eslint --import-alias "@/*"
+bun add html-to-image
+
+# With pnpm:
+pnpx create-next-app@latest . --typescript --tailwind --app --src-dir --no-eslint --import-alias "@/*"
+pnpm add html-to-image
+
+# With yarn:
+yarn create next-app . --typescript --tailwind --app --src-dir --no-eslint --import-alias "@/*"
+yarn add html-to-image
+
+# With npm:
+npx create-next-app@latest . --typescript --tailwind --app --src-dir --no-eslint --import-alias "@/*"
+npm install html-to-image
+```
+
+### Copy the Phone Mockup
+
+The skill includes a pre-measured iPhone mockup at `mockup.png` (co-located with this SKILL.md). Copy it to the project's `public/` directory. The mockup file is in the same directory as this skill file. No iPad mockup is needed — the iPad frame is CSS-only.
+
+### File Structure
+
+```
+project/
+├── public/
+│   ├── mockup.png              # iPhone frame (included with skill)
+│   ├── app-icon.png            # User's app icon
+│   ├── screenshots/            # iPhone app screenshots
+│   │   ├── home.png
+│   │   ├── feature-1.png
+│   │   └── ...
+│   └── screenshots-ipad/       # iPad app screenshots (optional)
+│       ├── home.png
+│       ├── feature-1.png
+│       └── ...
+├── src/app/
+│   ├── layout.tsx              # Font setup
+│   └── page.tsx                # The screenshot generator (single file)
+└── package.json
+```
+
+**Note:** No iPad mockup PNG is needed — the iPad frame is rendered with CSS (see iPad Mockup Component below).
+
+**Multi-language:** nest screenshots under a locale folder per language. The generator switches the `base` path; all slide image srcs stay identical.
+
+```
+└── screenshots/
+    ├── en/
+    │   ├── home.png
+    │   ├── feature-1.png
+    │   └── ...
+    ├── de/
+    │   └── ...
+    └── {locale}/
+```
+
+If iPad screenshots are localized too, mirror the same locale structure:
+
+```
+└── screenshots-ipad/
+    ├── en/
+    ├── de/
+    └── {locale}/
+```
+
+**The entire generator is a single `page.tsx` file.** No routing, no extra layouts, no API routes.
+
+### Multi-language: Locale Tabs
+
+Add a `LOCALES` array and locale tabs to the toolbar. Every slide src uses `base` — no hardcoded paths:
+
+```tsx
+const LOCALES = ["en", "de", "es"] as const; // use whatever langs were defined
+type Locale = typeof LOCALES[number];
+
+// In ScreenshotsPage:
+const [locale, setLocale] = useState<Locale>("en");
+const base = `/screenshots/${locale}`;
+
+// Toolbar tabs:
+{LOCALES.map(l => (
+  <button key={l} onClick={() => setLocale(l)}
+    style={{ fontWeight: locale === l ? 700 : 400 }}>
+    {l.toUpperCase()}
+  </button>
+))}
+
+// In every slide — unchanged between single and multi-language:
+<Phone src={`${base}/home.png`} alt="Home" />
+```
+
+### Theme Presets + Locale Metadata
+
+Add a small config layer so the user can switch theme and locale without rewriting slide components:
+
+```tsx
+const LOCALES = ["en", "de", "ar"] as const;
+type Locale = typeof LOCALES[number];
+
+const RTL_LOCALES = new Set<Locale>(["ar"]);
+
+const THEMES = {
+  "clean-light": {
+    bg: "#F6F1EA",
+    fg: "#171717",
+    accent: "#5B7CFA",
+    muted: "#6B7280",
+  },
+  "dark-bold": {
+    bg: "#0B1020",
+    fg: "#F8FAFC",
+    accent: "#8B5CF6",
+    muted: "#94A3B8",
+  },
+  "warm-editorial": {
+    bg: "#F7E8DA",
+    fg: "#2B1D17",
+    accent: "#D97706",
+    muted: "#7C5A47",
+  },
+} as const;
+
+type ThemeId = keyof typeof THEMES;
+
+const COPY_BY_LOCALE = {
+  en: { hero: "Build better habits" },
+  de: { hero: "Baue bessere Gewohnheiten auf" },
+  ar: { hero: "ابنِ عادات أفضل" },
+} satisfies Record<Locale, { hero: string }>;
+
+const [themeId, setThemeId] = useState<ThemeId>("clean-light");
+const [locale, setLocale] = useState<Locale>("en");
+
+const theme = THEMES[themeId];
+const copy = COPY_BY_LOCALE[locale];
+const isRtl = RTL_LOCALES.has(locale);
+```
+
+Use theme tokens everywhere instead of hardcoding colors. For RTL locales, set `dir={isRtl ? "rtl" : "ltr"}` on the screenshot canvas and mirror asymmetric layouts intentionally.
+
+Support query params for automation:
+
+```tsx
+// ?locale=de&theme=dark-bold&device=ipad
+```
+
+### Font Setup
+
+```tsx
+// src/app/layout.tsx
+import { YourFont } from "next/font/google"; // Use whatever font the user specified
+const font = YourFont({ subsets: ["latin"] });
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return <html><body className={font.className}>{children}</body></html>;
+}
+```
+
+## Step 3: Plan the Slides
+
+### Screenshot Framework (Narrative Arc)
+
+Adapt this framework to the user's requested slide count. Not all slots are required — pick what fits:
+
+| Slot | Purpose | Notes |
+|------|---------|-------|
+| #1 | **Hero / Main Benefit** | App icon + tagline + home screen. This is the ONLY one most people see. |
+| #2 | **Differentiator** | What makes this app unique vs competitors |
+| #3 | **Ecosystem** | Widgets, extensions, watch — beyond the main app. Skip if N/A. |
+| #4+ | **Core Features** | One feature per slide, most important first |
+| 2nd to last | **Trust Signal** | Identity/craft — "made for people who [X]" |
+| Last | **More Features** | Pills listing extras + coming soon. Skip if few features. |
+
+**Rules:**
+- Each slide sells ONE idea. Never two features on one slide.
+- Vary layouts across slides — never repeat the same template structure.
+- Include 1-2 contrast slides (inverted bg) for visual rhythm.
+
+## Step 4: Write Copy FIRST
+
+Get all headlines approved before building layouts. Bad copy ruins good design.
+
+### The Iron Rules
+
+1. **One idea per headline.** Never join two things with "and."
+2. **Short, common words.** 1-2 syllables. No jargon unless it's domain-specific.
+3. **3-5 words per line.** Must be readable at thumbnail size in the App Store.
+4. **Line breaks are intentional.** Control where lines break with `<br />`.
+
+### Three Approaches (pick one per slide)
+
+| Type | What it does | Example |
+|------|-------------|---------|
+| **Paint a moment** | You picture yourself doing it | "Check your coffee without opening the app." |
+| **State an outcome** | What your life looks like after | "A home for every coffee you buy." |
+| **Kill a pain** | Name a problem and destroy it | "Never waste a great bag of coffee." |
+
+### What NEVER Works
+
+- **Feature lists as headlines**: "Log every item with tags, categories, and notes"
+- **Two ideas joined by "and"**: "Track X and never miss Y"
+- **Compound clauses**: "Save and customize X for every Y you own"
+- **Vague aspirational**: "Every item, tracked"
+- **Marketing buzzwords**: "AI-powered tips" (unless it's actually AI)
+
+### Bad-to-Better Headline Examples
+
+Use these patterns to rewrite weak copy before building any layout:
+
+| Weak | Better | Why it wins |
+|------|--------|-------------|
+| Track habits and stay motivated | Keep your streak alive | one idea, faster to parse |
+| Organize tasks with AI summaries and smart sorting | Turn notes into next steps | outcome-first, less jargon |
+| Save recipes with tags, filters, and favorites | Find dinner fast | sells the user benefit, not the UI |
+| Manage budgets and never miss payments | See where money goes | cleaner promise, no dual claim |
+| AI-powered wellness support | Feel calmer tonight | concrete emotional outcome |
+
+### Copy Process
+
+1. Write 3 options per slide using the three approaches
+2. Read each at arm's length — if you can't parse it in 1 second, it's too complex
+3. Check: does each line have 3-5 words? If not, adjust line breaks
+4. Present options to the user with reasoning for each
+
+### Example Prompt Shapes
+
+If the user gives a weak or underspecified request, reshape it internally into something like:
+
+```text
+Build App Store screenshots for my habit tracker.
+The app helps people stay consistent with simple daily routines.
+I want 6 slides, clean/minimal style, warm neutrals, and a calm premium feel.
+```
+
+```text
+Generate App Store screenshots for my personal finance app.
+The app's main strengths are fast expense capture, clear monthly trends, and shared budgets.
+I want a sharp, modern style with high contrast and 7 slides.
+```
+
+```text
+Create exportable App Store screenshots for my AI note-taking app.
+The core value is turning messy voice notes into clean summaries and action items.
+I want bold copy, dark backgrounds, and a polished tech-forward look.
+```
+
+The pattern is:
+
+1. app category + core outcome
+2. top features in priority order
+3. desired slide count
+4. style direction
+
+### Localization Rules
+
+- Do not literally translate headlines if the result becomes long or awkward.
+- Re-write copy for the target market while keeping the same selling idea.
+- Re-check line breaks per locale; German, French, and Portuguese often need shorter claims.
+- For RTL languages, also reverse badge alignment, supporting decorations, and phone offsets when the composition depends on left/right weight.
+
+### Reference Apps for Copy Style
+
+- **Raycast** — specific, descriptive, one concrete value per slide
+- **Turf** — ultra-simple action verbs, conversational
+- **Mela / Notion** — warm, minimal, elegant
+
+## Step 5: Build the Page
+
+### Architecture
+
+```
+page.tsx
+├── Constants (IPHONE_W/H, IPAD_W/H, SIZES, design tokens)
+├── LOCALES / RTL_LOCALES / THEMES / COPY_BY_LOCALE
+├── Phone component (mockup PNG with screen overlay)
+├── IPad component (CSS-only frame with screen overlay)
+├── Caption component (label + headline, accepts canvasW for scaling)
+├── Decorative components (blobs, glows, shapes — based on style direction)
+├── iPhoneSlide1..N components (one per slide)
+├── iPadSlide1..N components (same designs, adjusted for iPad proportions)
+├── IPHONE_SCREENSHOTS / IPAD_SCREENSHOTS arrays (registries)
+├── ScreenshotPreview (ResizeObserver scaling + hover export)
+└── ScreenshotsPage (grid + locale tabs + theme tabs + device toggle + export logic)
+```
+
+### Export Sizes (Apple Required, portrait)
+
+#### iPhone
+
+```typescript
+const IPHONE_SIZES = [
+  { label: '6.9"', w: 1320, h: 2868 },
+  { label: '6.5"', w: 1284, h: 2778 },
+  { label: '6.3"', w: 1206, h: 2622 },
+  { label: '6.1"', w: 1125, h: 2436 },
+] as const;
+```
+
+Design at the LARGEST size (1320x2868) and scale down for export.
+
+#### iPad (Optional)
+
+If the user provides iPad screenshots, also generate iPad App Store screenshots:
+
+```typescript
+const IPAD_SIZES = [
+  { label: '13" iPad', w: 2064, h: 2752 },
+  { label: '12.9" iPad Pro', w: 2048, h: 2732 },
+] as const;
+```
+
+Design iPad slides at 2064x2752 and scale down. iPad screenshots are optional but recommended — they're required for iPad-only apps and improve listing quality for universal apps.
+
+#### Device Toggle
+
+When supporting both devices, add a toggle (iPhone / iPad) in the toolbar next to the size dropdown. The size dropdown should switch between iPhone and iPad sizes based on the selected device. Support a `?device=ipad` URL parameter for headless/automated capture workflows.
+
+#### Theme + Locale Toggles
+
+Place locale and theme selectors in the same toolbar as device + size. This turns the generator into a small control panel instead of a one-off page.
+
+- `locale` switches screenshot folders and copy dictionaries
+- `theme` switches design tokens only
+- `device` switches iPhone/iPad slide registries
+- `size` switches export resolution only
+
+### Rendering Strategy
+
+Each screenshot is designed at full resolution (1320x2868px). Two copies exist:
+
+1. **Preview**: CSS `transform: scale()` via ResizeObserver to fit a grid card
+2. **Export**: Offscreen at `position: absolute; left: -9999px` at true resolution
+
+### Phone Mockup Component
+
+The included `mockup.png` has these pre-measured values:
+
+```typescript
+const MK_W = 1022;  // mockup image width
+const MK_H = 2082;  // mockup image height
+const SC_L = (52 / MK_W) * 100;   // screen left offset %
+const SC_T = (46 / MK_H) * 100;   // screen top offset %
+const SC_W = (918 / MK_W) * 100;  // screen width %
+const SC_H = (1990 / MK_H) * 100; // screen height %
+const SC_RX = (126 / 918) * 100;  // border-radius x %
+const SC_RY = (126 / 1990) * 100; // border-radius y %
+```
+
+```tsx
+function Phone({ src, alt, style, className = "" }: {
+  src: string; alt: string; style?: React.CSSProperties; className?: string;
+}) {
+  return (
+    <div className={`relative ${className}`}
+      style={{ aspectRatio: `${MK_W}/${MK_H}`, ...style }}>
+      <img src="/mockup.png" alt=""
+        className="block w-full h-full" draggable={false} />
+      <div className="absolute z-10 overflow-hidden"
+        style={{
+          left: `${SC_L}%`, top: `${SC_T}%`,
+          width: `${SC_W}%`, height: `${SC_H}%`,
+          borderRadius: `${SC_RX}% / ${SC_RY}%`,
+        }}>
+        <img src={src} alt={alt}
+          className="block w-full h-full object-cover object-top"
+          draggable={false} />
+      </div>
+    </div>
+  );
+}
+```
+
+### iPad Mockup Component (CSS-Only)
+
+Unlike the iPhone mockup which uses a pre-measured PNG frame, the iPad uses a **CSS-only frame**. This avoids needing a separate mockup asset and looks clean at any resolution.
+
+**Critical dimension:** The frame aspect ratio must be `770/1000` so the inner screen area (92% width × 94.4% height) matches the 3:4 aspect ratio of iPad screenshots. Using incorrect proportions causes black bars or stretched screenshots.
+
+```tsx
+function IPad({ src, alt, style, className = "" }: {
+  src: string; alt: string; style?: React.CSSProperties; className?: string;
+}) {
+  return (
+    <div className={`relative ${className}`}
+      style={{ aspectRatio: "770/1000", ...style }}>
+      <div style={{
+        width: "100%", height: "100%", borderRadius: "5% / 3.6%",
+        background: "linear-gradient(180deg, #2C2C2E 0%, #1C1C1E 100%)",
+        position: "relative", overflow: "hidden",
+        boxShadow: "inset 0 0 0 1px rgba(255,255,255,0.1), 0 8px 40px rgba(0,0,0,0.6)",
+      }}>
+        {/* Front camera dot */}
+        <div style={{
+          position: "absolute", top: "1.2%", left: "50%",
+          transform: "translateX(-50%)", width: "0.9%", height: "0.65%",
+          borderRadius: "50%", background: "#111113",
+          border: "1px solid rgba(255,255,255,0.08)", zIndex: 20,
+        }} />
+        {/* Bezel edge highlight */}
+        <div style={{
+          position: "absolute", inset: 0, borderRadius: "5% / 3.6%",
+          border: "1px solid rgba(255,255,255,0.06)",
+          pointerEvents: "none", zIndex: 15,
+        }} />
+        {/* Screen area */}
+        <div style={{
+          position: "absolute", left: "4%", top: "2.8%",
+          width: "92%", height: "94.4%",
+          borderRadius: "2.2% / 1.6%", overflow: "hidden", background: "#000",
+        }}>
+          <img src={src} alt={alt}
+            style={{ display: "block", width: "100%", height: "100%",
+              objectFit: "cover", objectPosition: "top" }}
+            draggable={false} />
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+**iPad layout adjustments vs iPhone:**
+- Use `width: "65-70%"` for iPad mockups (vs 82-86% for iPhone) — iPad is wider relative to its height
+- Two-iPad layouts work the same as two-phone layouts but with adjusted widths
+- Caption font sizes should scale from `canvasW` (which is 2064 for iPad vs 1320 for iPhone)
+- Same slide designs/copy can be reused — just swap the Phone component for IPad and adjust positioning
+
+### Typography (Resolution-Independent)
+
+All sizing relative to canvas width W:
+
+| Element | Size | Weight | Line Height |
+|---------|------|--------|-------------|
+| Category label | `W * 0.028` | 600 (semibold) | default |
+| Headline | `W * 0.09` to `W * 0.1` | 700 (bold) | 1.0 |
+| Hero headline | `W * 0.1` | 700 (bold) | 0.92 |
+
+### Phone Placement Patterns
+
+Vary across slides — NEVER use the same layout twice in a row:
+
+**Centered phone** (hero, single-feature):
+```
+bottom: 0, width: "82-86%", translateX(-50%) translateY(12-14%)
+```
+
+**Two phones layered** (comparison):
+```
+Back: left: "-8%", width: "65%", rotate(-4deg), opacity: 0.55
+Front: right: "-4%", width: "82%", translateY(10%)
+```
+
+**Phone + floating elements** (only if user provided component PNGs):
+```
+Cards should NOT block the phone's main content.
+Position at edges, slight rotation (2-5deg), drop shadows.
+If distracting, push partially off-screen or make smaller.
+```
+
+### "More Features" Slide (Optional)
+
+Dark/contrast background with app icon, headline ("And so much more."), and feature pills. Can include a "Coming Soon" section with dimmer pills.
+
+## Step 6: Export
+
+### Why html-to-image, NOT html2canvas
+
+`html2canvas` breaks on CSS filters, gradients, drop-shadow, backdrop-filter, and complex clipping. `html-to-image` uses native browser SVG serialization — handles all CSS faithfully.
+
+### Export Implementation
+
+```typescript
+import { toPng } from "html-to-image";
+
+// Before capture: move element on-screen
+el.style.left = "0px";
+el.style.opacity = "1";
+el.style.zIndex = "-1";
+
+const opts = { width: W, height: H, pixelRatio: 1, cacheBust: true };
+
+// CRITICAL: Double-call trick — first warms up fonts/images, second produces clean output
+await toPng(el, opts);
+const dataUrl = await toPng(el, opts);
+
+// After capture: move back off-screen
+el.style.left = "-9999px";
+el.style.opacity = "";
+el.style.zIndex = "";
+```
+
+### Export Matrix
+
+If the project supports multiple locales and themes, add bulk export helpers so the user can export everything in one pass:
+
+```typescript
+const jobs = LOCALES.flatMap(locale =>
+  ACTIVE_THEME_IDS.flatMap(themeId =>
+    ACTIVE_DEVICES.flatMap(device =>
+      getSlidesFor(device).map((slide, index) => ({
+        locale,
+        themeId,
+        device,
+        index,
+        slide,
+      })),
+    ),
+  ),
+);
+```
+
+Name files so they sort cleanly and preserve metadata:
+
+```text
+01-hero-en-clean-light-iphone-1320x2868.png
+01-hero-ar-dark-bold-ipad-2064x2752.png
+```
+
+At minimum, support:
+
+1. export current slide
+2. export all slides for current locale/device/theme
+3. export all locales for current theme
+4. export full matrix when the user explicitly asks for it
+
+### Key Rules
+
+- **Double-call trick**: First `toPng()` loads fonts/images lazily. Second produces clean output. Without this, exports are blank.
+- **On-screen for capture**: Temporarily move to `left: 0` before calling `toPng`.
+- **Offscreen container**: Use `position: absolute; left: -9999px` (not `fixed`).
+- **Resizing**: Load data URL into Image, draw onto canvas at target size.
+- 300ms delay between sequential exports.
+- Set `fontFamily` on the offscreen container.
+- **Numbered filenames**: Prefix exports with zero-padded index so they sort correctly: `01-hero-1320x2868.png`, `02-freshness-1320x2868.png`, etc. Use `String(index + 1).padStart(2, "0")`.
+
+## Step 7: Final QA Gate
+
+Before handing the page back to the user, review every slide against this checklist:
+
+### Message Quality
+
+- **One idea per slide**: if a headline sells two ideas, split it or simplify it
+- **First slide is strongest**: the hero slide should communicate the main benefit immediately
+- **Readable in one second**: if you cannot parse it instantly at arm's length, rewrite it
+
+### Visual Quality
+
+- **No repeated layouts in sequence**: adjacent slides should not feel templated
+- **Decorative elements support the story**: they should add energy without covering the app UI
+- **Visual rhythm exists**: include at least one contrast slide when the set is long enough
+
+### Export Quality
+
+- **No clipped text or assets** after scaling to the selected export size
+- **Screenshots are correctly aligned** inside the phone or iPad frame
+- **Filenames sort correctly** with zero-padded numeric prefixes
+- **Theme tokens are applied consistently** across all slides in the same preset
+- **Localized copy still fits** after translation, especially on long-word languages
+- **RTL slides feel designed, not just flipped**
+
+### Hand-off Behavior
+
+When you present the finished work:
+
+1. briefly explain the narrative arc across the slides
+2. mention any slides that intentionally use contrast or different layout treatment
+3. call out any assumptions you made about brand tone, copy, or missing assets
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| All slides look the same | Vary phone position (center, left, right, two-phone, no-phone) |
+| Decorative elements invisible | Increase size and opacity — better too visible than invisible |
+| Copy is too complex | "One second at arm's length" test |
+| Floating elements block the phone | Move off-screen edges or above the phone |
+| Plain white/black background | Use gradients — even subtle ones add depth |
+| Too cluttered | Remove floating elements, simplify to phone + caption |
+| Too simple/empty | Add larger decorative elements, floating items at edges |
+| Headlines use "and" | Split into two slides or pick one idea |
+| No visual contrast across slides | Mix light and dark backgrounds |
+| Export is blank | Use double-call trick; move element on-screen before capture |
diff --git a/builtin-skills/iOS-Dev/icon-generator/SKILL.md b/builtin-skills/iOS-Dev/icon-generator/SKILL.md
new file mode 100644
index 00000000..04949746
--- /dev/null
+++ b/builtin-skills/iOS-Dev/icon-generator/SKILL.md
@@ -0,0 +1,48 @@
+---
+name: icon-generator
+description: Generate web UI/UX icon assets (favicon.ico, apple-touch-icon, PWA icons incl. maskable) and optionally Unreal Engine packaging icons (Windows .ico, macOS .iconset/.icns, Linux .png) from a single source SVG/PNG; use when you need correct multi-size icon files, safe-area guidance, manifests/head tags, or automation.
+---
+
+# Icon Generator
+
+You generate icon asset bundles for **web UI/UX first** (favicons + PWA icons), and you can also generate **Unreal Engine packaging** icon assets when needed.
+
+## Fast workflow
+
+1. Pick target(s): Web UI/UX (favicon + PWA icons) and/or Unreal Engine packaging (optional).
+
+2. Pick the source icon: prefer a **1024x1024 PNG** (square) or a clean **SVG**. If it's not square, choose whether to crop or pad (default: pad).
+
+3. Generate the assets using [`scripts/generate_icons.py`](scripts/generate_icons.py).
+
+Web/PWA sizes and safe-area rules: [`references/web-ui-ux.md`](references/web-ui-ux.md)
+
+Unreal Engine formats and expectations: [`references/unreal-engine.md`](references/unreal-engine.md)
+
+Full size tables: [`references/icon-sizes.md`](references/icon-sizes.md)
+
+4. Verify output quality: ensure the `.ico` contains multiple sizes, and the 16/24/32 px variants are crisp.
+
+## Quality rules (what "good" looks like)
+
+- **Design for small sizes**: avoid thin strokes, tiny text, and busy details.
+- **Prefer transparent backgrounds** for desktop icons unless you intentionally "plate" the icon.
+- **Preview at 16px and 24px**. If it becomes muddy, create a simpler variant.
+
+## Automation (recommended)
+
+Run and customize the script:
+
+- Script: [`scripts/generate_icons.py`](scripts/generate_icons.py)
+- It supports:
+  - Web/PWA set: `favicon.ico`, `apple-touch-icon.png`, `icon-192.png`, `icon-512.png`, `icon-maskable-512.png`
+  - UE sets (optional): Windows `.ico`, macOS `.iconset`, Linux `.png`
+
+If you need HTML `<head>` snippets, `manifest.webmanifest` examples, and maskable safe-area guidance, read:
+
+- [`references/web-ui-ux.md`](references/web-ui-ux.md)
+
+## Notes
+
+- If your input is SVG and Python SVG rasterization is unavailable on your machine, export a 1024x1024 PNG first (e.g., Inkscape), then rerun the script using the PNG.
+- Keep this SKILL.md lean; detailed size tables live in the reference files.
diff --git a/builtin-skills/iOS-Dev/icon-generator/references/icon-sizes.md b/builtin-skills/iOS-Dev/icon-generator/references/icon-sizes.md
new file mode 100644
index 00000000..20e8dadb
--- /dev/null
+++ b/builtin-skills/iOS-Dev/icon-generator/references/icon-sizes.md
@@ -0,0 +1,39 @@
+# Icon size tables
+
+## Web UI/UX (favicons + PWA)
+
+Minimal, modern set:
+
+- `favicon.ico`: 16×16, 32×32 (optionally 48×48)
+- `apple-touch-icon.png`: 180×180
+- `icon-192.png`: 192×192
+- `icon-512.png`: 512×512
+- `icon-maskable-512.png`: 512×512 (opaque background + padding)
+
+## Unreal Engine packaging (optional)
+
+### Windows `.ico`
+
+Recommended embedded sizes:
+
+- 16, 24, 32, 48, 64, 128, 256
+
+### macOS `.iconset` (source for `.icns`)
+
+Common iconset sizes and filenames:
+
+- `icon_16x16.png` (16)
+- `icon_16x16@2x.png` (32)
+- `icon_32x32.png` (32)
+- `icon_32x32@2x.png` (64)
+- `icon_128x128.png` (128)
+- `icon_128x128@2x.png` (256)
+- `icon_256x256.png` (256)
+- `icon_256x256@2x.png` (512)
+- `icon_512x512.png` (512)
+- `icon_512x512@2x.png` (1024)
+
+### Linux
+
+- 256×256 PNG (common baseline)
+- 512×512 PNG (nice to have)
diff --git a/builtin-skills/iOS-Dev/icon-generator/references/unreal-engine.md b/builtin-skills/iOS-Dev/icon-generator/references/unreal-engine.md
new file mode 100644
index 00000000..49fb2c88
--- /dev/null
+++ b/builtin-skills/iOS-Dev/icon-generator/references/unreal-engine.md
@@ -0,0 +1,29 @@
+# Unreal Engine packaging icons (optional target)
+
+## What UE typically expects
+
+- **Windows**: a multi-resolution `.ico` (commonly max 256×256)
+- **macOS**: an `.icns` (UE may require `.icns` even if Apple has moved toward asset catalogs)
+- **Linux**: usually a `.png` (commonly 256×256)
+
+## What this skill generates
+
+Using `--targets ue`, the script outputs:
+
+- `ue/windows/icon.ico` (multi-size)
+- `ue/mac/AppIcon.iconset/` (iconset PNGs)
+- `ue/linux/icon-256.png`, `ue/linux/icon-512.png`
+
+### Creating `.icns` (macOS)
+
+Creating `.icns` is easiest on macOS with `iconutil`.
+
+- Input: the `AppIcon.iconset/` folder
+- Output: `AppIcon.icns`
+
+If you’re not on macOS, keep the `.iconset` in source control and generate `.icns` on a Mac build machine.
+
+## Quality reminder
+
+Even if a single “master” PNG exists, small sizes often need a simplified design.
+If your 16×16 looks mushy, create a simplified icon variant and regenerate.
diff --git a/builtin-skills/iOS-Dev/icon-generator/references/web-ui-ux.md b/builtin-skills/iOS-Dev/icon-generator/references/web-ui-ux.md
new file mode 100644
index 00000000..9c9a6e5f
--- /dev/null
+++ b/builtin-skills/iOS-Dev/icon-generator/references/web-ui-ux.md
@@ -0,0 +1,56 @@
+# Web UI/UX icon set (favicon + PWA)
+
+## Recommended minimal output set
+
+This set covers modern browsers + iOS home screen + Android/PWA:
+
+- `favicon.ico` (multi-size container): include 16×16 and 32×32 (optionally 48×48)
+- `apple-touch-icon.png` (180×180)
+- `icon-192.png` (192×192)
+- `icon-512.png` (512×512)
+- `icon-maskable-512.png` (512×512, **maskable**, opaque background, padded content)
+
+This is intentionally “minimal but effective”. You can add more sizes if you have a specific requirement.
+
+## HTML `<head>` snippet
+
+Use this as a starting point:
+
+- `<link rel="icon" href="/favicon.ico">`
+- `<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">`
+- `<link rel="icon" type="image/png" sizes="192x192" href="/icon-192.png">`
+- `<link rel="icon" type="image/png" sizes="512x512" href="/icon-512.png">`
+- `<link rel="manifest" href="/manifest.webmanifest">` (if PWA)
+
+## `manifest.webmanifest` example
+
+Include both normal (“any”) and maskable icons:
+
+```json
+{
+  "name": "My App",
+  "short_name": "MyApp",
+  "display": "standalone",
+  "start_url": "/",
+  "icons": [
+    { "src": "/icon-192.png", "type": "image/png", "sizes": "192x192", "purpose": "any" },
+    { "src": "/icon-512.png", "type": "image/png", "sizes": "512x512", "purpose": "any" },
+    { "src": "/icon-maskable-512.png", "type": "image/png", "sizes": "512x512", "purpose": "maskable" }
+  ]
+}
+```
+
+## Maskable safe area (practical rule)
+
+Maskable icons can be cropped into different shapes by the OS/launcher.
+
+- Keep important content inside the **center ~80%** of the image.
+- Use an **opaque background** for the full 512×512.
+
+In the generator script, this corresponds to `--maskable-scale 0.80` (default).
+
+## Common failure modes
+
+- You only provide a big 512×512 and let the browser scale down → looks blurry at 16×16.
+- You use transparent background for iOS “Add to Home Screen” icons → iOS may render it with an ugly fill.
+- Your maskable icon has no padding → the launcher crops off your logo.
diff --git a/builtin-skills/iOS-Dev/ios-swift-development/SKILL.md b/builtin-skills/iOS-Dev/ios-swift-development/SKILL.md
new file mode 100644
index 00000000..ca33b846
--- /dev/null
+++ b/builtin-skills/iOS-Dev/ios-swift-development/SKILL.md
@@ -0,0 +1,101 @@
+---
+name: ios-swift-development
+description: >
+  Develop native iOS apps with Swift. Covers MVVM architecture, SwiftUI,
+  URLSession for networking, Combine for reactive programming, and Core Data
+  persistence.
+---
+
+# iOS Swift Development
+
+## Table of Contents
+
+- [Overview](#overview)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Reference Guides](#reference-guides)
+- [Best Practices](#best-practices)
+
+## Overview
+
+Build high-performance native iOS applications using Swift with modern frameworks including SwiftUI, Combine, and async/await patterns.
+
+## When to Use
+
+- Creating native iOS applications with optimal performance
+- Leveraging iOS-specific features and APIs
+- Building apps that require tight hardware integration
+- Using SwiftUI for declarative UI development
+- Implementing complex animations and transitions
+
+## Quick Start
+
+Minimal working example:
+
+```swift
+import Foundation
+import Combine
+
+struct User: Codable, Identifiable {
+  let id: UUID
+  var name: String
+  var email: String
+}
+
+class UserViewModel: ObservableObject {
+  @Published var user: User?
+  @Published var isLoading = false
+  @Published var errorMessage: String?
+
+  private let networkService: NetworkService
+
+  init(networkService: NetworkService = .shared) {
+    self.networkService = networkService
+  }
+
+  @MainActor
+  func fetchUser(id: UUID) async {
+    isLoading = true
+    errorMessage = nil
+
+// ... (see reference guides for full implementation)
+```
+
+## Reference Guides
+
+Detailed implementations in the `references/` directory:
+
+| Guide | Contents |
+|---|---|
+| [MVVM Architecture Setup](references/mvvm-architecture-setup.md) | MVVM Architecture Setup |
+| [Network Service with URLSession](references/network-service-with-urlsession.md) | Network Service with URLSession |
+| [SwiftUI Views](references/swiftui-views.md) | SwiftUI Views |
+
+## Best Practices
+
+### ✅ DO
+
+- Use SwiftUI for modern UI development
+- Implement MVVM architecture
+- Use async/await patterns
+- Store sensitive data in Keychain
+- Handle errors gracefully
+- Use @StateObject for ViewModels
+- Validate API responses properly
+- Implement Core Data for persistence
+- Test on multiple iOS versions
+- Use dependency injection
+- Follow Swift style guidelines
+
+### ❌ DON'T
+
+- Store tokens in UserDefaults
+- Make network calls on main thread
+- Use deprecated UIKit patterns
+- Ignore memory leaks
+- Skip error handling
+- Use force unwrapping (!)
+- Store passwords in code
+- Ignore accessibility
+- Deploy untested code
+- Use hardcoded API URLs
diff --git a/builtin-skills/iOS-Dev/ios-swift-development/references/mvvm-architecture-setup.md b/builtin-skills/iOS-Dev/ios-swift-development/references/mvvm-architecture-setup.md
new file mode 100644
index 00000000..829527cd
--- /dev/null
+++ b/builtin-skills/iOS-Dev/ios-swift-development/references/mvvm-architecture-setup.md
@@ -0,0 +1,60 @@
+# MVVM Architecture Setup
+
+## MVVM Architecture Setup
+
+```swift
+import Foundation
+import Combine
+
+struct User: Codable, Identifiable {
+  let id: UUID
+  var name: String
+  var email: String
+}
+
+class UserViewModel: ObservableObject {
+  @Published var user: User?
+  @Published var isLoading = false
+  @Published var errorMessage: String?
+
+  private let networkService: NetworkService
+
+  init(networkService: NetworkService = .shared) {
+    self.networkService = networkService
+  }
+
+  @MainActor
+  func fetchUser(id: UUID) async {
+    isLoading = true
+    errorMessage = nil
+
+    do {
+      user = try await networkService.fetch(User.self, from: "/users/\(id)")
+    } catch {
+      errorMessage = error.localizedDescription
+    }
+
+    isLoading = false
+  }
+
+  @MainActor
+  func updateUser(_ userData: User) async {
+    guard let user = user else { return }
+
+    do {
+      self.user = try await networkService.put(
+        User.self,
+        to: "/users/\(user.id)",
+        body: userData
+      )
+    } catch {
+      errorMessage = "Failed to update user"
+    }
+  }
+
+  func logout() {
+    user = nil
+    errorMessage = nil
+  }
+}
+```
diff --git a/builtin-skills/iOS-Dev/ios-swift-development/references/network-service-with-urlsession.md b/builtin-skills/iOS-Dev/ios-swift-development/references/network-service-with-urlsession.md
new file mode 100644
index 00000000..a64e9c7f
--- /dev/null
+++ b/builtin-skills/iOS-Dev/ios-swift-development/references/network-service-with-urlsession.md
@@ -0,0 +1,99 @@
+# Network Service with URLSession
+
+## Network Service with URLSession
+
+```swift
+class NetworkService {
+  static let shared = NetworkService()
+
+  private let session: URLSession
+  private let baseURL: URL
+
+  init(
+    session: URLSession = .shared,
+    baseURL: URL = URL(string: "https://api.example.com")!
+  ) {
+    self.session = session
+    self.baseURL = baseURL
+  }
+
+  func fetch<T: Decodable>(
+    _: T.Type,
+    from endpoint: String
+  ) async throws -> T {
+    let url = baseURL.appendingPathComponent(endpoint)
+    var request = URLRequest(url: url)
+    request.addAuthHeader()
+
+    let (data, response) = try await session.data(for: request)
+    try validateResponse(response)
+
+    let decoder = JSONDecoder()
+    decoder.dateDecodingStrategy = .iso8601
+    return try decoder.decode(T.self, from: data)
+  }
+
+  func put<T: Decodable, Body: Encodable>(
+    _: T.Type,
+    to endpoint: String,
+    body: Body
+  ) async throws -> T {
+    let url = baseURL.appendingPathComponent(endpoint)
+    var request = URLRequest(url: url)
+    request.httpMethod = "PUT"
+    request.addAuthHeader()
+    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+
+    let encoder = JSONEncoder()
+    encoder.dateEncodingStrategy = .iso8601
+    request.httpBody = try encoder.encode(body)
+
+    let (data, response) = try await session.data(for: request)
+    try validateResponse(response)
+
+    let decoder = JSONDecoder()
+    return try decoder.decode(T.self, from: data)
+  }
+
+  private func validateResponse(_ response: URLResponse) throws {
+    guard let httpResponse = response as? HTTPURLResponse else {
+      throw NetworkError.invalidResponse
+    }
+
+    switch httpResponse.statusCode {
+    case 200...299:
+      return
+    case 401:
+      throw NetworkError.unauthorized
+    case 500...599:
+      throw NetworkError.serverError
+    default:
+      throw NetworkError.unknown
+    }
+  }
+}
+
+enum NetworkError: LocalizedError {
+  case invalidResponse
+  case unauthorized
+  case serverError
+  case unknown
+
+  var errorDescription: String? {
+    switch self {
+    case .invalidResponse: return "Invalid response"
+    case .unauthorized: return "Unauthorized"
+    case .serverError: return "Server error"
+    case .unknown: return "Unknown error"
+    }
+  }
+}
+
+extension URLRequest {
+  mutating func addAuthHeader() {
+    if let token = KeychainManager.shared.getToken() {
+      setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+    }
+  }
+}
+```
diff --git a/builtin-skills/iOS-Dev/ios-swift-development/references/swiftui-views.md b/builtin-skills/iOS-Dev/ios-swift-development/references/swiftui-views.md
new file mode 100644
index 00000000..7f5b45db
--- /dev/null
+++ b/builtin-skills/iOS-Dev/ios-swift-development/references/swiftui-views.md
@@ -0,0 +1,112 @@
+# SwiftUI Views
+
+## SwiftUI Views
+
+```swift
+struct ContentView: View {
+  @StateObject var userViewModel = UserViewModel()
+
+  var body: some View {
+    TabView {
+      HomeView()
+        .tabItem { Label("Home", systemImage: "house") }
+
+      ProfileView(viewModel: userViewModel)
+        .tabItem { Label("Profile", systemImage: "person") }
+    }
+  }
+}
+
+struct HomeView: View {
+  @State var items: [Item] = []
+  @State var loading = true
+
+  var body: some View {
+    NavigationView {
+      ZStack {
+        if loading {
+          ProgressView()
+        } else {
+          List(items) { item in
+            NavigationLink(destination: ItemDetailView(item: item)) {
+              VStack(alignment: .leading) {
+                Text(item.title).font(.headline)
+                Text(item.description).font(.subheadline).foregroundColor(.gray)
+              }
+            }
+          }
+        }
+      }
+      .navigationTitle("Items")
+      .task {
+        await loadItems()
+      }
+    }
+  }
+
+  private func loadItems() async {
+    do {
+      items = try await NetworkService.shared.fetch([Item].self, from: "/items")
+    } catch {
+      print("Error: \(error)")
+    }
+    loading = false
+  }
+}
+
+struct ItemDetailView: View {
+  let item: Item
+  @Environment(\.dismiss) var dismiss
+
+  var body: some View {
+    ScrollView {
+      VStack(alignment: .leading, spacing: 16) {
+        Text(item.title).font(.title2).fontWeight(.bold)
+        Text(item.description).font(.body)
+        Text("Price: $\(String(format: "%.2f", item.price))")
+          .font(.headline).foregroundColor(.blue)
+        Spacer()
+      }
+      .padding()
+    }
+    .navigationBarTitleDisplayMode(.inline)
+  }
+}
+
+struct ProfileView: View {
+  @ObservedObject var viewModel: UserViewModel
+  @State var isLoading = true
+
+  var body: some View {
+    NavigationView {
+      ZStack {
+        if viewModel.isLoading {
+          ProgressView()
+        } else if let user = viewModel.user {
+          VStack(spacing: 20) {
+            Text(user.name).font(.title).fontWeight(.bold)
+            Text(user.email).font(.subheadline)
+            Button("Logout") { viewModel.logout() }
+              .foregroundColor(.red)
+            Spacer()
+          }
+          .padding()
+        } else {
+          Text("No profile data")
+        }
+      }
+      .navigationTitle("Profile")
+      .task {
+        await viewModel.fetchUser(id: UUID())
+      }
+    }
+  }
+}
+
+struct Item: Codable, Identifiable {
+  let id: String
+  let title: String
+  let description: String
+  let price: Double
+}
+```
diff --git a/builtin-skills/iOS-Dev/mobile-development/SKILL.md b/builtin-skills/iOS-Dev/mobile-development/SKILL.md
new file mode 100644
index 00000000..dad1e839
--- /dev/null
+++ b/builtin-skills/iOS-Dev/mobile-development/SKILL.md
@@ -0,0 +1,261 @@
+---
+# ═══════════════════════════════════════════════════════════════════════════
+# SKILL: Mobile Development
+# Version: 2.0.0 | Updated: 2025-01
+# ═══════════════════════════════════════════════════════════════════════════
+name: mobile-development
+description: iOS (Swift, SwiftUI), Android (Kotlin, Compose), cross-platform (Flutter, React Native), and game development (Unity, Unreal).
+
+# ACTIVATION TRIGGERS
+triggers:
+  - ios
+  - android
+  - flutter
+  - react native
+  - mobile
+  - swift
+  - kotlin
+  - unity
+  - game development
+
+# SKILL PARAMETERS
+parameters:
+  platform:
+    type: string
+    enum: [ios, android, cross-platform, games]
+    required: true
+  project_type:
+    type: string
+    required: false
+    description: Type of app (social, productivity, game, etc.)
+
+# OUTPUT SPECIFICATION
+outputs:
+  recommended_stack:
+    type: object
+  learning_path:
+    type: array
+  portfolio_projects:
+    type: array
+
+# RELIABILITY
+retry:
+  max_attempts: 3
+  backoff: exponential
+
+# OBSERVABILITY
+observability:
+  log_level: info
+
+level: advanced
+prerequisites:
+  - core-development
+
+sasmp_version: "1.3.0"
+bonded_agent: 01-core-paths
+bond_type: PRIMARY_BOND
+---
+
+# Mobile Development Skill
+
+## Quick Reference
+
+| Platform | Language | Framework | Timeline | Job Market |
+|----------|----------|-----------|----------|------------|
+| **iOS** | Swift | SwiftUI | 6-9 mo | High |
+| **Android** | Kotlin | Compose | 6-9 mo | High |
+| **Cross-Platform** | Dart | Flutter | 4-6 mo | Growing |
+| **Games** | C# | Unity | 12-24 mo | Moderate |
+
+---
+
+## Learning Paths
+
+### iOS Development
+```
+[1] Swift Fundamentals (4-6 wk)
+ │  └─ Types, optionals, closures, protocols
+ │
+ ▼
+[2] SwiftUI (4-6 wk)
+ │  └─ Views, modifiers, state, binding
+ │
+ ▼
+[3] Navigation + Data (3-4 wk)
+ │  └─ NavigationStack, SwiftData/Core Data
+ │
+ ▼
+[4] Networking + Async (2-3 wk)
+ │  └─ URLSession, async/await, Combine
+ │
+ ▼
+[5] Testing + App Store (2 wk)
+    └─ XCTest, TestFlight, submission
+```
+
+**2025 Stack:** Swift 5.10 + SwiftUI + SwiftData + Xcode 16
+
+---
+
+### Android Development
+```
+[1] Kotlin Fundamentals (4-6 wk)
+ │  └─ Null safety, coroutines, data classes
+ │
+ ▼
+[2] Jetpack Compose (4-6 wk)
+ │  └─ Composables, state, effects
+ │
+ ▼
+[3] Architecture (3-4 wk)
+ │  └─ MVVM, Room, Navigation
+ │
+ ▼
+[4] Networking + DI (2-3 wk)
+ │  └─ Retrofit, Hilt, Flow
+ │
+ ▼
+[5] Testing + Play Store (2 wk)
+    └─ JUnit, Espresso, release
+```
+
+**2025 Stack:** Kotlin 2.0 + Jetpack Compose + Room + Hilt
+
+---
+
+### Flutter (Cross-Platform)
+```
+[1] Dart Fundamentals (2-3 wk)
+ │
+ ▼
+[2] Flutter Widgets (3-4 wk)
+ │
+ ▼
+[3] State Management (2-3 wk)
+ │  └─ Riverpod or Bloc
+ │
+ ▼
+[4] Backend Integration (2 wk)
+ │  └─ Firebase, REST APIs
+ │
+ ▼
+[5] Deploy to Both Stores (1 wk)
+```
+
+**2025 Stack:** Flutter 3.x + Dart 3.x + Riverpod + Firebase
+
+---
+
+### Game Development
+```
+[1] Game Basics (4-6 wk)
+ │  └─ Game loop, input handling
+ │
+ ▼
+[2] Unity/C# Fundamentals (6-8 wk)
+ │  └─ GameObjects, Components, Scripts
+ │
+ ▼
+[3] Physics + Graphics (4-6 wk)
+ │  └─ Rigidbody, colliders, shaders
+ │
+ ▼
+[4] Audio + Polish (2-4 wk)
+ │
+ ▼
+[5] Publish (ongoing)
+    └─ Steam, App Store, Play Store
+```
+
+**2025 Stack:** Unity 6 LTS + C# OR Unreal 5.4 + C++
+
+---
+
+## Platform Decision Tree
+
+```
+Which platform?
+│
+├─► Apple ecosystem only?
+│   └─► iOS (Swift + SwiftUI)
+│
+├─► Android ecosystem only?
+│   └─► Android (Kotlin + Compose)
+│
+├─► Both platforms?
+│   ├─► Performance-critical? → Native for both
+│   ├─► Budget/time limited? → Flutter
+│   └─► Web developer background? → React Native
+│
+└─► Making games?
+    ├─► 2D/3D indie → Unity
+    ├─► AAA quality → Unreal
+    └─► Simple 2D → Godot
+```
+
+---
+
+## Game Engine Comparison
+
+| Engine | Market | Language | Learning | Best For |
+|--------|--------|----------|----------|----------|
+| **Unity** | 51% | C# | Medium | Indie, mobile, VR |
+| **Unreal** | 31% | C++/BP | Hard | AAA, high-fidelity |
+| **Godot** | 10% | GDScript | Easy | Indie, 2D |
+
+---
+
+## Troubleshooting
+
+```
+Native vs Cross-platform?
+├─► Need platform-specific APIs (HealthKit, ARCore)? → Native
+├─► Performance-critical (AR/VR, complex animations)? → Native
+├─► Budget or time limited? → Flutter
+├─► Team knows JavaScript? → React Native
+└─► Starting from scratch? → Flutter (best DX)
+
+Simulator works, device doesn't?
+├─► Missing entitlements/capabilities?
+├─► Different iOS/Android version?
+├─► Network connectivity issues?
+└─► Always test on real devices from day 1
+
+App rejected by store?
+├─► Read rejection reason carefully
+├─► Check App Store Review Guidelines
+├─► Most common: metadata issues, crashes, spam
+└─► Appeal if unjustified
+```
+
+---
+
+## Common Failure Modes
+
+| Symptom | Root Cause | Recovery |
+|---------|------------|----------|
+| Slow UI | Too many recompositions | Profile, optimize state |
+| Memory leaks | Not cleaning up resources | Use lifecycle-aware components |
+| App rejected | Guidelines violation | Read guidelines BEFORE building |
+| Game stutters | Draw call overhead | Object pooling, LOD, batching |
+
+---
+
+## Portfolio Projects
+
+### Mobile (Progressive)
+1. **Todo App** - CRUD basics
+2. **Weather App** - API integration
+3. **Chat App** - Real-time, auth
+4. **Payment App** - Stripe, security
+
+### Games
+1. **2D Platformer** - Physics basics
+2. **3D Runner** - 3D graphics, particles
+3. **Multiplayer Game** - Networking
+
+---
+
+## Next Actions
+
+Specify your target platform for a detailed learning plan.
diff --git a/builtin-skills/iOS-Dev/mobile-development/references/MOBILE_GUIDE.md b/builtin-skills/iOS-Dev/mobile-development/references/MOBILE_GUIDE.md
new file mode 100644
index 00000000..c1b17dca
--- /dev/null
+++ b/builtin-skills/iOS-Dev/mobile-development/references/MOBILE_GUIDE.md
@@ -0,0 +1,73 @@
+# Mobile Development Guide for Cloudflare
+
+## PWA on Cloudflare Pages
+
+```json
+// manifest.json
+{
+  "name": "My PWA",
+  "short_name": "PWA",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#f38020",
+  "icons": [
+    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
+  ]
+}
+```
+
+## Service Worker with Cloudflare
+
+```typescript
+// sw.ts - Offline-first strategy
+const CACHE_NAME = 'v1';
+const OFFLINE_URL = '/offline.html';
+
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => {
+      return cache.addAll([OFFLINE_URL, '/', '/styles.css']);
+    })
+  );
+});
+
+self.addEventListener('fetch', (event) => {
+  event.respondWith(
+    fetch(event.request).catch(() => caches.match(OFFLINE_URL))
+  );
+});
+```
+
+## Mobile API with Workers
+
+```typescript
+// Optimized for mobile clients
+export default {
+  async fetch(request: Request, env: Env) {
+    const userAgent = request.headers.get('User-Agent') || '';
+    const isMobile = /Mobile|Android|iPhone/i.test(userAgent);
+
+    return Response.json({
+      data: await getData(env),
+      optimized: isMobile ? 'mobile' : 'desktop'
+    }, {
+      headers: {
+        'Cache-Control': isMobile ? 'max-age=300' : 'max-age=3600'
+      }
+    });
+  }
+};
+```
+
+## Deployment
+
+```bash
+# Deploy to Cloudflare Pages
+npx wrangler pages deploy dist --project-name=my-pwa
+```
+
+---
+
+*Cloudflare Plugin - Mobile Development Skill*
diff --git a/builtin-skills/marketing/clean-general/SKILL.md b/builtin-skills/marketing/clean-general/SKILL.md
new file mode 100644
index 00000000..099a3e68
--- /dev/null
+++ b/builtin-skills/marketing/clean-general/SKILL.md
@@ -0,0 +1,97 @@
+---
+name: clean-general
+description: Use when writing, fixing, editing, or reviewing Python code quality. Enforces Clean Code's core principles—DRY, single responsibility, clear intent, no magic numbers, proper abstractions.
+---
+
+# General Clean Code Principles
+
+## Critical Rules
+
+**G5: DRY (Don't Repeat Yourself)**
+
+Every piece of knowledge has one authoritative representation.
+
+```python
+# Bad - duplication
+tax_rate = 0.0825
+ca_total = subtotal * 1.0825
+ny_total = subtotal * 1.07
+
+# Good - single source of truth
+TAX_RATES = {"CA": 0.0825, "NY": 0.07}
+def calculate_total(subtotal: float, state: str) -> float:
+    return subtotal * (1 + TAX_RATES[state])
+```
+
+**G16: No Obscured Intent**
+
+Don't be clever. Be clear.
+
+```python
+# Bad - what does this do?
+return (x & 0x0F) << 4 | (y & 0x0F)
+
+# Good - obvious intent
+return pack_coordinates(x, y)
+```
+
+**G23: Prefer Polymorphism to If/Else**
+
+```python
+# Bad - will grow forever
+def calculate_pay(employee):
+    if employee.type == "SALARIED":
+        return employee.salary
+    elif employee.type == "HOURLY":
+        return employee.hours * employee.rate
+    elif employee.type == "COMMISSIONED":
+        return employee.base + employee.commission
+
+# Good - open/closed principle
+class SalariedEmployee:
+    def calculate_pay(self): return self.salary
+
+class HourlyEmployee:
+    def calculate_pay(self): return self.hours * self.rate
+
+class CommissionedEmployee:
+    def calculate_pay(self): return self.base + self.commission
+```
+
+**G25: Replace Magic Numbers with Named Constants**
+
+```python
+# Bad
+if elapsed_time > 86400:
+    ...
+
+# Good
+SECONDS_PER_DAY = 86400
+if elapsed_time > SECONDS_PER_DAY:
+    ...
+```
+
+**G30: Functions Should Do One Thing**
+
+If you can extract another function, your function does more than one thing.
+
+**G36: Law of Demeter (Avoid Train Wrecks)**
+
+```python
+# Bad - reaching through multiple objects
+output_dir = context.options.scratch_dir.absolute_path
+
+# Good - one dot
+output_dir = context.get_scratch_dir()
+```
+
+## Enforcement Checklist
+
+When reviewing AI-generated code, verify:
+- [ ] No duplication (G5)
+- [ ] Clear intent, no magic numbers (G16, G25)
+- [ ] Polymorphism over conditionals (G23)
+- [ ] Functions do one thing (G30)
+- [ ] No Law of Demeter violations (G36)
+- [ ] Boundary conditions handled (G3)
+- [ ] Dead code removed (G9)
diff --git a/builtin-skills/marketing/my-writing-style b/builtin-skills/marketing/my-writing-style
deleted file mode 160000
index d94826e1..00000000
--- a/builtin-skills/marketing/my-writing-style
+++ /dev/null
@@ -1 +0,0 @@
-Subproject commit d94826e1cd48f5403b82a5a909efdfab96221259
diff --git a/builtin-skills/marketing/my-writing-style/README.md b/builtin-skills/marketing/my-writing-style/README.md
new file mode 100644
index 00000000..1ef85ef4
--- /dev/null
+++ b/builtin-skills/marketing/my-writing-style/README.md
@@ -0,0 +1,71 @@
+# Writing Style Skill
+
+可复用的写作风格 Skill 模板。**内置自动学习** — 从你的修改中自动提取规则，SKILL.md 越用越准。
+
+兼容 **Claude Code** + **OpenClaw (ClawHub)**。
+
+## 原理
+
+```
+AI 用 SKILL.md 写初稿 → 你改到满意 → diff 两版 → 提取规则 → 更新 SKILL.md → 下次更准
+```
+
+只要两个数据点：**original**（AI 第一版）和 **final**（你最终版）。中间改了多少轮不管。
+
+## 安装
+
+```bash
+# Claude Code
+git clone https://github.com/jzOcb/writing-style-skill.git
+cp -r writing-style-skill ~/.claude/skills/my-writing-style
+
+# OpenClaw / ClawHub
+npx clawhub@latest install jz-writing-style-skill
+```
+
+## 快速开始
+
+1. **改 SKILL.md** — 把模板里的风格规则改成你自己的（或留空，让自动学习帮你填）
+2. **让 AI 用这个 skill 写内容**
+3. **你改到满意**
+4. 记录：
+```bash
+python3 scripts/observe.py record-original draft.md
+# ... 你修改 ...
+python3 scripts/observe.py record-final final.md
+```
+5. 提取规则：
+```bash
+python3 scripts/improve.py auto --skill .
+```
+
+## 文件结构
+
+```
+writing-style-skill/
+├── SKILL.md              # 你的写作风格（模板，改成你的）
+├── README.md             # 本文件
+└── scripts/
+    ├── observe.py        # 记录 original / final（零依赖）
+    └── improve.py        # 提取 / 应用 / 回滚（需要 LLM CLI）
+```
+
+## 自动学习怎么工作
+
+- `observe.py` 记录 AI 原稿和你的最终版
+- `improve.py` 用 LLM 分析 diff，提取写作规则
+- 规则按置信度分 P0/P1/P2，P0 自动应用
+- 每次更新前自动备份，一键回滚
+
+## LLM 支持
+
+`improve.py` 自动检测：
+- `claude` (Claude Code) — 优先
+- `llm` (pip install llm) — 通用
+- `IMPROVE_LLM_CMD` 环境变量 — 自定义
+
+`observe.py` 零依赖纯 Python。
+
+## License
+
+MIT
diff --git a/builtin-skills/marketing/my-writing-style/SKILL.md b/builtin-skills/marketing/my-writing-style/SKILL.md
new file mode 100644
index 00000000..08cc2901
--- /dev/null
+++ b/builtin-skills/marketing/my-writing-style/SKILL.md
@@ -0,0 +1,206 @@
+---
+name: my-writing-style
+version: 1.0.0
+description: |
+  可复用的写作风格 Skill 模板。内置自动学习：
+  从你的修改中自动提取规则，SKILL.md 越用越准。
+  Fork 后改成你自己的风格。
+dependencies: []
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - exec
+---
+
+# Writing Style Skill（模板）
+
+**Fork 这个 skill，改成你的写作风格。内置自动学习，越用越准。**
+
+---
+
+## 🎯 怎么用
+
+1. Fork / clone 这个 skill
+2. 把下面的风格规则改成你自己的
+3. 让 AI 用这个 skill 写内容
+4. 你改到满意 → 脚本自动学习你改了什么
+5. 下次 AI 写出来的就更像你
+
+---
+
+## 【0】Voice Dimensions（量化你的风格）
+
+**用 1-10 分定义你的风格维度。AI 比"写得自然一点"这种话更容易理解数字。**
+
+| Dimension | Score | 你的说明 |
+|-----------|-------|---------|
+| **formal_casual** | **?/10** | 偏正式还是偏随意？ |
+| **technical_accessible** | **?/10** | 技术深度？ |
+| **serious_playful** | **?/10** | 严肃还是活泼？ |
+| **concise_elaborate** | **?/10** | 简洁还是详细？ |
+| **reserved_expressive** | **?/10** | 保守还是直接？ |
+
+> 💡 **不知道填什么？** 先跑几次 AI 写作 → 你改 → 自动学习会帮你填。
+
+---
+
+## 【1】角色与读者
+
+**我是谁：**
+- （填你的身份，比如：独立开发者，新晋 AI 爱好者）
+
+**读者是谁：**
+- （填你的读者，比如：对 AI 感兴趣的技术人）
+
+**和读者的关系：**
+- （比如：同行交流，不是教学）
+
+---
+
+## 【2】写作规则
+
+### 基础规则
+
+- （填你的规则，比如：不用"深入探讨"、段落要短、要有具体数字）
+- 
+- 
+
+### 禁止词
+
+- （AI 爱用但你不喜欢的词，比如：值得注意的是、综上所述、本文将介绍）
+- 
+- 
+
+### 句式偏好
+
+- （你喜欢的句式，比如：结论前置、不要学术导语）
+- 
+- 
+
+> 💡 **不需要一开始就写完。** 这些规则会通过你的修改自动积累。
+> 跑完 10 次写作→修改循环后，这里会长出几十条精准规则。
+
+---
+
+## 【3】格式规范
+
+### 平台适配
+
+| 平台 | 格式要求 |
+|------|---------|
+| X/Twitter | 不渲染 markdown，用纯文本 |
+| 小红书 | emoji 多、分段短 |
+| 博客 | 标准 markdown |
+| （你的平台） | （你的要求）|
+
+---
+
+## 🔄 自动学习（内置）
+
+**这个 skill 会从你的修改中自动学习。不需要手动写规则。**
+
+### 工作原理
+
+```
+AI 用这个 skill 写初稿
+    ↓
+你改到满意
+    ↓
+脚本 diff 两版 → 提取你改了什么
+    ↓
+新规则自动写入这个 SKILL.md
+    ↓
+下次 AI 写出来就更像你
+```
+
+### 只需要两个数据点
+
+- **original**: AI 生成的第一版
+- **final**: 你最终确认的版本
+
+中间改了几轮不管。在 Google Doc 里来回改了 10 次？无所谓，只比较首尾。
+
+### Agent 操作指南
+
+**写完内容后：**
+```bash
+python3 scripts/observe.py record-original <file> --account <账号> --content-type <类型>
+```
+
+**人类确认最终版后：**
+```bash
+python3 scripts/observe.py record-final <file> --match <hash>
+```
+
+**提取规则（手动或 cron 自动）：**
+```bash
+python3 scripts/improve.py auto --skill .
+```
+
+### 规则分级
+
+| 级别 | 含义 | 处理方式 |
+|------|------|---------|
+| P0 | 高置信度（多次出现） | 自动应用 |
+| P1 | 中置信度 | 人工确认 |
+| P2 | 低置信度（仅 1 次） | 存档观察 |
+
+### 安全
+
+- 每次更新前自动备份 SKILL.md
+- `improve.py rollback` 一键回滚
+- auto 模式只应用 P0
+
+---
+
+## 📊 CLI 参考
+
+### observe.py（零依赖纯 Python）
+
+| 命令 | 功能 |
+|------|------|
+| `record-original <file>` | 记录 AI 原稿 |
+| `record-final <file> --match <hash>` | 记录最终版 |
+| `pending` | 查看待配对 |
+| `stats` | 统计 |
+
+### improve.py（需要 LLM CLI）
+
+| 命令 | 功能 |
+|------|------|
+| `extract [--days 7]` | 提取改进建议 |
+| `auto` | 提取 + 自动应用 P0 |
+| `show` | 查看提案 |
+| `apply <id>` | 应用提案 |
+| `rollback` | 回滚 |
+
+支持的 LLM CLI: `claude`（Claude Code）/ `llm`（pip install llm）/ `IMPROVE_LLM_CMD` 环境变量
+
+---
+
+## 📂 数据存储
+
+```
+~/clawd/memory/                    # OpenClaw
+~/.claude/memory/                  # Claude Code
+├── skill-runs/<skill-name>/
+│   └── YYYY-MM-DD.jsonl          # 每日观察日志
+├── skill-proposals/<skill-name>/
+│   └── YYYYMMDD-HHMMSS.md       # 改进提案
+└── skill-backups/<skill-name>/
+    └── SKILL-YYYYMMDD-HHMMSS.md  # 自动备份
+```
+
+自动检测环境，不需要手动配置路径。
+
+---
+
+## 🚀 30 天预期
+
+| 时间 | 预期效果 |
+|------|---------|
+| 第 1 周 | 积累 3-5 次修改，生成第一批规则 |
+| 第 2 周 | 10+ 条规则，AI 输出明显更像你 |
+| 第 1 月 | 30+ 条规则，风格维度自动校准 |
+| 持续 | 规则库稳定增长，新 pattern 自动捕捉 |
diff --git a/builtin-skills/marketing/my-writing-style/scripts/improve.py b/builtin-skills/marketing/my-writing-style/scripts/improve.py
new file mode 100644
index 00000000..5f8e36b0
--- /dev/null
+++ b/builtin-skills/marketing/my-writing-style/scripts/improve.py
@@ -0,0 +1,426 @@
+#!/usr/bin/env python3
+"""
+Self-Improving Skill — Improver
+
+从人类修改中提取规则，更新目标 SKILL.md。
+
+用法:
+    python3 improve.py extract [--days 7] [--date 2026-03-17]
+    python3 improve.py auto                  # 提取 + 自动应用 P0（cron 用）
+    python3 improve.py show                  # 查看所有提案
+    python3 improve.py apply <proposal_id>   # 应用指定提案
+    python3 improve.py rollback              # 回滚上次应用
+
+环境变量:
+    SKILL_LOG_DIR      — 日志目录
+    SKILL_TARGET_PATH  — 目标 SKILL.md 路径
+    SKILL_PROPOSAL_DIR — 提案目录
+    SKILL_BACKUP_DIR   — 备份目录
+"""
+
+import sys
+import json
+import os
+import argparse
+import subprocess
+import shutil
+from pathlib import Path
+from datetime import datetime, timedelta
+
+# 默认路径 — 自动检测 OpenClaw (~/.openclaw) 或 Claude Code (~/.claude)
+def _detect_base():
+    """检测数据存储基目录"""
+    # 优先级: 环境变量 > ~/clawd > ~/.openclaw > ~/.claude > ~/.self-improving
+    if os.environ.get("SKILL_BASE_DIR"):
+        return Path(os.environ["SKILL_BASE_DIR"])
+    candidates = [
+        Path.home() / "clawd" / "memory",
+        Path.home() / ".openclaw" / "memory",
+        Path.home() / ".claude" / "memory",
+    ]
+    for c in candidates:
+        if c.parent.exists():
+            return c
+    return Path.home() / ".self-improving" / "memory"
+
+_BASE = _detect_base()
+DEFAULT_LOG_DIR = _BASE / "skill-runs" / "default"
+DEFAULT_PROPOSAL_DIR = _BASE / "skill-proposals" / "default"
+DEFAULT_BACKUP_DIR = _BASE / "skill-backups" / "default"
+
+
+def get_paths(args=None):
+    """解析所有路径配置"""
+    skill_name = "default"
+    if args and hasattr(args, 'skill') and args.skill:
+        skill_name = Path(args.skill).name
+
+    base = Path.home() / "clawd" / "memory"
+
+    log_dir = Path(os.environ.get("SKILL_LOG_DIR",
+                   getattr(args, 'log_dir', None) or
+                   str(base / "skill-runs" / skill_name)))
+
+    proposal_dir = Path(os.environ.get("SKILL_PROPOSAL_DIR",
+                        getattr(args, 'proposal_dir', None) or
+                        str(base / "skill-proposals" / skill_name)))
+
+    backup_dir = Path(os.environ.get("SKILL_BACKUP_DIR",
+                      getattr(args, 'backup_dir', None) or
+                      str(base / "skill-backups" / skill_name)))
+
+    # 目标 SKILL.md
+    if os.environ.get("SKILL_TARGET_PATH"):
+        target = Path(os.environ["SKILL_TARGET_PATH"])
+    elif args and hasattr(args, 'target') and args.target:
+        target = Path(args.target)
+    elif args and hasattr(args, 'skill') and args.skill:
+        target = Path(args.skill) / "SKILL.md"
+    else:
+        target = None
+
+    for d in (log_dir, proposal_dir, backup_dir):
+        d.mkdir(parents=True, exist_ok=True)
+
+    return log_dir, proposal_dir, backup_dir, target
+
+
+def read_log_entries(log_file):
+    if not log_file.exists():
+        return []
+    entries = []
+    with log_file.open("r") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    return entries
+
+
+def collect_edits(log_dir, days=1, date_str=None):
+    """收集有实际修改的 final/edited 记录"""
+    edits = []
+    if date_str:
+        log_file = log_dir / f"{date_str}.jsonl"
+        entries = read_log_entries(log_file)
+        edits.extend([e for e in entries
+                      if e["type"] in ("final", "edited") and not e.get("no_change")])
+    else:
+        for i in range(days):
+            date = (datetime.now() - timedelta(days=i)).strftime("%Y-%m-%d")
+            log_file = log_dir / f"{date}.jsonl"
+            entries = read_log_entries(log_file)
+            edits.extend([e for e in entries
+                          if e["type"] in ("final", "edited") and not e.get("no_change")])
+    return edits
+
+
+def call_llm(prompt, timeout=180):
+    """调用 LLM — 自动检测可用的 CLI (claude / openclaw / llm)"""
+    # 优先级: claude CLI → openclaw exec → generic llm CLI
+    candidates = [
+        ["claude", "--print", "--model", "sonnet"],  # Claude Code
+        ["claude", "--print"],                         # Claude Code (default model)
+        ["llm", "-m", "claude-sonnet"],               # simon willison's llm CLI
+        ["llm"],                                       # llm CLI default
+    ]
+    for cmd in candidates:
+        try:
+            result = subprocess.run(cmd, input=prompt, capture_output=True,
+                                    text=True, timeout=timeout)
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            continue
+
+    # fallback: 如果 IMPROVE_LLM_CMD 环境变量设置了，用它
+    custom_cmd = os.environ.get("IMPROVE_LLM_CMD")
+    if custom_cmd:
+        try:
+            result = subprocess.run(custom_cmd.split(), input=prompt,
+                                    capture_output=True, text=True, timeout=timeout)
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            pass
+
+    print("❌ LLM 调用失败。支持的方式：")
+    print("   - 安装 Claude Code CLI (claude --print)")
+    print("   - 安装 llm CLI (pip install llm)")
+    print("   - 设置 IMPROVE_LLM_CMD 环境变量")
+    return None
+
+
+def extract_improvements(args):
+    log_dir, proposal_dir, _, target = get_paths(args)
+    days = getattr(args, 'days', 1) or 1
+    date_str = getattr(args, 'date', None)
+
+    edits = collect_edits(log_dir, days=days, date_str=date_str)
+    if not edits:
+        print("⚠️  没有修改记录")
+        return None
+
+    print(f"📊 找到 {len(edits)} 次修改，正在分析...")
+
+    # 读当前 SKILL.md
+    current_skill = ""
+    if target and target.exists():
+        current_skill = target.read_text()
+
+    # 构建对比数据
+    edit_summaries = []
+    for i, edit in enumerate(edits):
+        orig = edit.get("original_content", "")[:3000]
+        final = edit.get("final_content", edit.get("edited_content", ""))[:3000]
+        ctx = edit.get("context", {})
+        edit_summaries.append({
+            "index": i + 1,
+            "account": ctx.get("account", "unknown"),
+            "content_type": ctx.get("content_type", "unknown"),
+            "original": orig,
+            "final": final,
+        })
+
+    proposal_id = datetime.now().strftime("%Y%m%d-%H%M%S")
+
+    prompt = f"""你是 writing style skill 的改进助手。
+
+分析人类对 AI 生成文章的修改，提取可以加入 SKILL.md 的新规则。
+
+## 当前 SKILL.md（最后 3000 字，避免重复）
+{current_skill[-3000:]}
+
+## 修改记录（original vs final）
+{json.dumps(edit_summaries, ensure_ascii=False, indent=2)}
+
+## 要求
+1. 对比 original 和 final，找出系统性修改
+2. 只提取有 pattern 的修改（至少 2 次，或单次但改动幅度大且明确）
+3. 不要提取已在 SKILL.md 中的规则
+4. 每条规则必须可执行
+
+## 输出格式
+
+---
+id: {proposal_id}
+date: {datetime.now().isoformat()}
+source: {len(edits)} edits
+status: pending
+---
+
+# Improvement Proposal
+
+## 提取的改进建议
+
+### 1. 新禁止词
+- **`词`** → 替代: "YYY" | 理由: ... | 优先级: **P0/P1/P2**
+
+### 2. 新风格规则
+- 规则描述 | 理由: ... | 优先级: **P0/P1/P2**
+
+### 3. 反模式
+- 描述 | 理由: ... | 优先级: **P0/P1/P2**
+
+P0=高置信度(多次), P1=中置信度, P2=低置信度(仅1次)
+"""
+
+    suggestions = call_llm(prompt)
+    if not suggestions:
+        return None
+
+    proposal_file = proposal_dir / f"{proposal_id}.md"
+    proposal_file.write_text(suggestions)
+
+    print(f"✅ 改进建议已保存: {proposal_file}")
+    print(f"\n{suggestions[:2000]}")
+    if len(suggestions) > 2000:
+        print(f"\n... (完整内容见文件)")
+    return proposal_id
+
+
+def show_proposals(args):
+    _, proposal_dir, _, _ = get_paths(args)
+    proposals = list(proposal_dir.glob("*.md"))
+
+    if not proposals:
+        print("⚠️  没有提案")
+        return
+
+    print(f"\n📋 共 {len(proposals)} 个提案:\n")
+    for p in sorted(proposals, reverse=True):
+        content = p.read_text()
+        status = "unknown"
+        for line in content.split("\n")[:10]:
+            if line.startswith("status:"):
+                status = line.split(":", 1)[1].strip()
+        icon = {"pending": "⏳", "applied": "✅", "rejected": "❌"}.get(
+            status.split("(")[0].strip(), "❓")
+        print(f"  {icon} {p.stem} — {status}")
+
+
+def backup_skill(target, backup_dir):
+    if not target or not target.exists():
+        return None
+    name = f"SKILL-{datetime.now().strftime('%Y%m%d-%H%M%S')}.md"
+    backup_path = backup_dir / name
+    shutil.copy2(target, backup_path)
+    print(f"📦 备份: {backup_path}")
+    return backup_path
+
+
+def apply_proposal(args):
+    _, proposal_dir, backup_dir, target = get_paths(args)
+    proposal_id = args.proposal_id
+    proposal_file = proposal_dir / f"{proposal_id}.md"
+
+    if not proposal_file.exists():
+        print(f"❌ 提案不存在: {proposal_id}")
+        return
+
+    if not target or not target.exists():
+        print(f"❌ 目标 SKILL.md 不存在（用 --skill 或 --target 指定）")
+        return
+
+    proposal_content = proposal_file.read_text()
+    current_skill = target.read_text()
+
+    auto_mode = getattr(args, 'auto', False)
+    filter_level = "P0" if auto_mode else "P0 和 P1"
+
+    backup_skill(target, backup_dir)
+
+    prompt = f"""把改进提案中的 **{filter_level}** 规则合并到 SKILL.md。
+
+规则：
+1. 新禁止词 → 加到禁止词 section
+2. 新风格规则 → 加到对应 section
+3. 不删除已有规则，不改文件结构
+4. version +0.1
+
+## 提案
+{proposal_content}
+
+## 当前 SKILL.md
+{current_skill}
+
+输出完整更新后的 SKILL.md。不加代码块包裹。"""
+
+    updated = call_llm(prompt, timeout=300)
+    if not updated:
+        print("❌ 合并失败")
+        return
+
+    target.write_text(updated)
+
+    new_content = proposal_content.replace(
+        "status: pending",
+        f"status: applied ({datetime.now().strftime('%Y-%m-%d')})")
+    proposal_file.write_text(new_content)
+
+    print(f"✅ 已应用提案 {proposal_id}")
+    print(f"💡 回滚: python3 improve.py rollback")
+
+
+def auto_improve(args):
+    log_dir, _, _, _ = get_paths(args)
+    edits = collect_edits(log_dir, days=7)
+
+    if not edits:
+        print("⚠️  最近 7 天没有修改记录，跳过")
+        return
+
+    print(f"🤖 自动模式: {len(edits)} 次修改")
+
+    args.days = 7
+    args.date = None
+    proposal_id = extract_improvements(args)
+
+    if not proposal_id:
+        return
+
+    _, proposal_dir, _, _ = get_paths(args)
+    content = (proposal_dir / f"{proposal_id}.md").read_text()
+
+    if "P0" not in content:
+        print("ℹ️  没有 P0 规则，跳过自动应用")
+        return
+
+    print("\n🔄 自动应用 P0 规则...")
+    apply_args = argparse.Namespace(**vars(args))
+    apply_args.proposal_id = proposal_id
+    apply_args.auto = True
+    apply_proposal(apply_args)
+
+
+def rollback(args):
+    _, _, backup_dir, target = get_paths(args)
+
+    if not target:
+        print("❌ 未指定目标 SKILL.md")
+        return
+
+    backups = sorted(backup_dir.glob("SKILL-*.md"), reverse=True)
+    if not backups:
+        print("❌ 没有备份")
+        return
+
+    latest = backups[0]
+    # 保存当前版本
+    if target.exists():
+        emergency = backup_dir / f"SKILL-pre-rollback-{datetime.now().strftime('%Y%m%d-%H%M%S')}.md"
+        shutil.copy2(target, emergency)
+
+    shutil.copy2(latest, target)
+    print(f"✅ 已回滚到: {latest.name}")
+
+
+def add_common_args(parser):
+    parser.add_argument("--skill", help="目标 skill 目录")
+    parser.add_argument("--target", help="目标 SKILL.md 路径")
+    parser.add_argument("--log-dir", help="日志目录")
+    parser.add_argument("--proposal-dir", help="提案目录")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Self-Improving Skill — Improver")
+    subparsers = parser.add_subparsers(dest="action")
+
+    p_ext = subparsers.add_parser("extract", help="提取改进建议")
+    p_ext.add_argument("--date", help="指定日期")
+    p_ext.add_argument("--days", type=int, default=1)
+    add_common_args(p_ext)
+
+    p_show = subparsers.add_parser("show", help="查看提案")
+    add_common_args(p_show)
+
+    p_apply = subparsers.add_parser("apply", help="应用提案")
+    p_apply.add_argument("proposal_id")
+    add_common_args(p_apply)
+
+    p_auto = subparsers.add_parser("auto", help="自动提取+应用P0")
+    add_common_args(p_auto)
+
+    p_rb = subparsers.add_parser("rollback", help="回滚")
+    add_common_args(p_rb)
+
+    args = parser.parse_args()
+    if not args.action:
+        parser.print_help()
+        sys.exit(1)
+
+    actions = {
+        "extract": extract_improvements,
+        "show": show_proposals,
+        "apply": apply_proposal,
+        "auto": auto_improve,
+        "rollback": rollback,
+    }
+    actions[args.action](args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/builtin-skills/marketing/my-writing-style/scripts/observe.py b/builtin-skills/marketing/my-writing-style/scripts/observe.py
new file mode 100644
index 00000000..61cfe179
--- /dev/null
+++ b/builtin-skills/marketing/my-writing-style/scripts/observe.py
@@ -0,0 +1,309 @@
+#!/usr/bin/env python3
+"""
+Self-Improving Skill — Observation Layer
+
+通用的 original → final 记录器。适用于任何 "AI 生成 → 人类修改" 的循环。
+
+用法:
+    python3 observe.py record-original article.md [--text "..."] [--account X] [--content-type article]
+    python3 observe.py record-final article.md [--match <hash>] [--text "..."]
+    python3 observe.py pending
+    python3 observe.py stats
+
+环境变量:
+    SKILL_LOG_DIR  — 日志目录（默认 ~/clawd/memory/skill-runs/default/）
+"""
+
+import sys
+import json
+import os
+import argparse
+from pathlib import Path
+from datetime import datetime, timedelta
+import hashlib
+
+# 日志目录 — 自动检测 OpenClaw / Claude Code / standalone
+def _detect_base():
+    if os.environ.get("SKILL_BASE_DIR"):
+        return Path(os.environ["SKILL_BASE_DIR"])
+    candidates = [
+        Path.home() / "clawd" / "memory",
+        Path.home() / ".openclaw" / "memory",
+        Path.home() / ".claude" / "memory",
+    ]
+    for c in candidates:
+        if c.parent.exists():
+            return c
+    return Path.home() / ".self-improving" / "memory"
+
+DEFAULT_LOG_DIR = _detect_base() / "skill-runs" / "default"
+
+
+def get_log_dir(args=None):
+    """按优先级决定日志目录：--log-dir > SKILL_LOG_DIR > default"""
+    if args and hasattr(args, 'log_dir') and args.log_dir:
+        d = Path(args.log_dir)
+    elif os.environ.get("SKILL_LOG_DIR"):
+        d = Path(os.environ["SKILL_LOG_DIR"])
+    elif args and hasattr(args, 'skill') and args.skill:
+        skill_name = Path(args.skill).name
+        d = Path.home() / "clawd" / "memory" / "skill-runs" / skill_name
+    else:
+        d = DEFAULT_LOG_DIR
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def get_log_file(log_dir, date_str=None):
+    if date_str is None:
+        date_str = datetime.now().strftime("%Y-%m-%d")
+    return log_dir / f"{date_str}.jsonl"
+
+
+def compute_hash(content):
+    return hashlib.md5(content.encode()).hexdigest()[:8]
+
+
+def get_content(args):
+    if hasattr(args, 'text') and args.text:
+        return args.text
+    if hasattr(args, 'stdin') and args.stdin:
+        return sys.stdin.read()
+    if hasattr(args, 'file') and args.file:
+        p = Path(args.file)
+        if not p.exists():
+            print(f"❌ 文件不存在: {args.file}")
+            sys.exit(1)
+        return p.read_text()
+    return None
+
+
+def read_log_entries(log_file):
+    if not log_file.exists():
+        return []
+    entries = []
+    with log_file.open("r") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    return entries
+
+
+def find_unmatched(log_dir, days=14):
+    """找到有 original 但没有 final 的记录（兼容旧 edited/no-change type）"""
+    all_originals = {}
+    all_matched = set()
+
+    for i in range(days):
+        date = (datetime.now() - timedelta(days=i)).strftime("%Y-%m-%d")
+        entries = read_log_entries(get_log_file(log_dir, date))
+        for e in entries:
+            if e["type"] == "original":
+                e["_date"] = date
+                all_originals[e["content_hash"]] = e
+            elif e["type"] in ("final", "edited", "no-change"):
+                all_matched.add(e["content_hash"])
+
+    return {h: o for h, o in all_originals.items() if h not in all_matched}
+
+
+def record_original(args):
+    content = get_content(args)
+    if not content:
+        print("❌ 需要提供内容（文件路径、--text 或 --stdin）")
+        sys.exit(1)
+
+    log_dir = get_log_dir(args)
+    content_hash = compute_hash(content)
+
+    context = {}
+    if hasattr(args, 'account') and args.account:
+        context["account"] = args.account
+    if hasattr(args, 'content_type') and args.content_type:
+        context["content_type"] = args.content_type
+
+    log_entry = {
+        "timestamp": datetime.now().isoformat(),
+        "type": "original",
+        "content_hash": content_hash,
+        "file": str(args.file) if hasattr(args, 'file') and args.file else None,
+        "content": content,
+        "context": context,
+        "char_count": len(content),
+    }
+
+    log_file = get_log_file(log_dir)
+    with log_file.open("a") as f:
+        f.write(json.dumps(log_entry, ensure_ascii=False) + "\n")
+
+    print(f"✅ 记录原稿: {content_hash}")
+    print(f"📝 字数: {len(content)}")
+    print(f"📁 日志: {log_file}")
+    return content_hash
+
+
+def record_final(args):
+    content = get_content(args)
+    if not content:
+        print("❌ 需要提供最终版内容")
+        sys.exit(1)
+
+    log_dir = get_log_dir(args)
+    target_hash = getattr(args, 'match', None)
+
+    if target_hash:
+        # 指定 hash，跨天查找
+        original = None
+        for i in range(14):
+            date = (datetime.now() - timedelta(days=i)).strftime("%Y-%m-%d")
+            entries = read_log_entries(get_log_file(log_dir, date))
+            for e in entries:
+                if e["type"] == "original" and e["content_hash"] == target_hash:
+                    original = e
+                    break
+            if original:
+                break
+        if not original:
+            print(f"❌ 找不到 hash {target_hash} 的原稿")
+            sys.exit(1)
+    else:
+        # 自动匹配最近的未配对 original
+        unmatched = find_unmatched(log_dir, 14)
+        if not unmatched:
+            print("❌ 没有待配对的原稿")
+            sys.exit(1)
+        target_hash = list(unmatched.keys())[-1]
+        original = unmatched[target_hash]
+
+    is_same = content.strip() == original["content"].strip()
+
+    log_entry = {
+        "timestamp": datetime.now().isoformat(),
+        "type": "final",
+        "content_hash": target_hash,
+        "original_content": original["content"],
+        "final_content": content,
+        "original_char_count": len(original["content"]),
+        "final_char_count": len(content),
+        "context": original.get("context", {}),
+        "no_change": is_same,
+    }
+
+    log_file = get_log_file(log_dir)
+    with log_file.open("a") as f:
+        f.write(json.dumps(log_entry, ensure_ascii=False) + "\n")
+
+    if is_same:
+        print(f"✅ 记录最终版: {target_hash} (无修改 — 正反馈)")
+    else:
+        diff_pct = ((len(content) - len(original["content"])) / max(len(original["content"]), 1)) * 100
+        print(f"✅ 记录最终版: {target_hash}")
+        print(f"📝 原稿: {len(original['content'])} 字 → 最终: {len(content)} 字 ({diff_pct:+.1f}%)")
+    print(f"📁 日志: {log_file}")
+
+
+def show_pending(args):
+    log_dir = get_log_dir(args)
+    unmatched = find_unmatched(log_dir, 14)
+
+    if not unmatched:
+        print("✅ 全部已配对")
+        return
+
+    print(f"\n⏳ {len(unmatched)} 条待配对:\n")
+    for h, entry in unmatched.items():
+        preview = entry["content"][:80].replace("\n", " ")
+        ctx = entry.get("context", {})
+        account = ctx.get("account", "?")
+        date = entry.get("_date", "?")
+        print(f"  📄 {h} | {date} | {account}")
+        print(f"     {preview}...")
+        print()
+
+
+def show_stats(args):
+    log_dir = get_log_dir(args)
+    all_files = sorted(log_dir.glob("*.jsonl"))
+
+    total_originals = 0
+    total_finals = 0
+    total_no_change = 0
+    total_changed = 0
+
+    for log_file in all_files:
+        entries = read_log_entries(log_file)
+        total_originals += sum(1 for e in entries if e["type"] == "original")
+        finals = [e for e in entries if e["type"] in ("final", "edited")]
+        total_finals += len(finals)
+        total_no_change += sum(1 for e in finals if e.get("no_change"))
+        total_changed += sum(1 for e in finals if not e.get("no_change"))
+
+    pending = find_unmatched(log_dir, 14)
+
+    print(f"\n📊 Self-Improving Skill 观察统计")
+    print(f"{'='*40}")
+    print(f"📁 日志天数: {len(all_files)}")
+    print(f"📝 原稿: {total_originals}")
+    print(f"✅ 已配对: {total_finals}")
+    print(f"   ├ 有修改: {total_changed}")
+    print(f"   └ 无修改: {total_no_change}")
+    print(f"⏳ 待配对: {len(pending)}")
+    if total_finals > 0:
+        print(f"📈 修改率: {total_changed}/{total_finals} = {total_changed/total_finals*100:.0f}%")
+
+
+def add_common_args(parser):
+    """添加通用参数"""
+    parser.add_argument("--skill", help="目标 skill 目录名（用于定位日志目录）")
+    parser.add_argument("--log-dir", help="自定义日志目录")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Self-Improving Skill — Observation Layer")
+    subparsers = parser.add_subparsers(dest="action")
+
+    # record-original
+    p_orig = subparsers.add_parser("record-original", help="记录 AI 原稿")
+    p_orig.add_argument("file", nargs="?", help="文件路径")
+    p_orig.add_argument("--text", help="直接传入文本")
+    p_orig.add_argument("--stdin", action="store_true", help="从 stdin 读取")
+    p_orig.add_argument("--account", help="发布账号")
+    p_orig.add_argument("--content-type", help="内容类型")
+    add_common_args(p_orig)
+
+    # record-final
+    p_final = subparsers.add_parser("record-final", help="记录最终版")
+    p_final.add_argument("file", nargs="?", help="文件路径")
+    p_final.add_argument("--text", help="直接传入文本")
+    p_final.add_argument("--stdin", action="store_true", help="从 stdin 读取")
+    p_final.add_argument("--match", help="匹配的原稿 hash")
+    add_common_args(p_final)
+
+    # pending
+    p_pending = subparsers.add_parser("pending", help="查看待配对原稿")
+    add_common_args(p_pending)
+
+    # stats
+    p_stats = subparsers.add_parser("stats", help="总体统计")
+    add_common_args(p_stats)
+
+    args = parser.parse_args()
+    if not args.action:
+        parser.print_help()
+        sys.exit(1)
+
+    actions = {
+        "record-original": record_original,
+        "record-final": record_final,
+        "pending": show_pending,
+        "stats": show_stats,
+    }
+    actions[args.action](args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/builtin-skills/marketing/wechat-article-writer/SKILL.md b/builtin-skills/marketing/wechat-article-writer/SKILL.md
new file mode 100644
index 00000000..c4d60284
--- /dev/null
+++ b/builtin-skills/marketing/wechat-article-writer/SKILL.md
@@ -0,0 +1,62 @@
+---
+name: wechat-article-writer
+description: 公众号文章自动化写作流程。支持资料搜索、文章撰写、爆款标题生成、排版优化。当用户提到写公众号、微信文章、自媒体写作、爆款文章、内容创作时使用此 skill。
+---
+
+# 公众号文章写作流程
+
+4 步完成高质量公众号文章：搜索资料 → 撰写文章 → 生成标题 → 排版优化
+
+## Step 1: 搜索资料
+
+使用 WebSearch 工具搜索主题相关资料：
+
+```
+搜索要求：
+1. 并行搜索多个来源（官方文档、X/Twitter、Reddit、技术论坛）
+2. 优先获取最新资料（当月/当季）
+3. 可启动多个并行 Task 加速搜索
+4. 深度总结搜索结果
+```
+
+## Step 2: 撰写文章
+
+**必须先读取用户的 CLAUDE.md 获取写作风格**
+
+撰写要求：
+- 5000-10000 字
+- 故事化开头，带情感色彩（兴奋/焦虑/好奇）
+- 准备 2-3 个备选标题
+- 结构：效果展示 → 问题描述 → 步骤教学 → 升华总结
+- 遵循 CLAUDE.md 中定义的写作风格和结尾语
+
+## Step 3: 生成标题
+
+生成 5 个爆款标题，特点：
+- **痛点明确**：直击读者痛处（"还在手动..."）
+- **数字吸引**：具体数字更有说服力（"3分钟"、"5个技巧"）
+- **结果导向**：承诺具体收益（"效率暴涨10倍"）
+- **情绪调动**：惊、神技、秘籍等词汇
+- **悬念设置**：引发好奇心
+
+## Step 4: 排版优化
+
+优化建议：
+1. **段落结构**：每段 3-5 行，重要数据单独成段加粗
+2. **配图位置**：标题下方封面图、步骤后效果图、结尾总结图
+3. **代码块**：前后留白，语法高亮
+4. **金句**：单独成段，增强记忆点
+
+## 示例
+
+用户请求：
+```
+帮我写一篇关于 Claude Code 使用技巧的公众号文章
+```
+
+执行流程：
+1. 搜索 Claude Code 最新功能和使用技巧
+2. 读取 CLAUDE.md 获取写作风格
+3. 撰写 1200 字左右的教程文章
+4. 生成 5 个爆款标题供选择
+5. 提供排版和配图建议
diff --git a/builtin-skills/marketing/writing-clearly-and-concisely/README.md b/builtin-skills/marketing/writing-clearly-and-concisely/README.md
new file mode 100644
index 00000000..af644445
--- /dev/null
+++ b/builtin-skills/marketing/writing-clearly-and-concisely/README.md
@@ -0,0 +1,157 @@
+# Writing Clearly and Concisely
+
+A skill that applies William Strunk Jr.'s timeless writing principles to produce clearer, stronger, more professional prose while avoiding common AI writing patterns.
+
+## Purpose
+
+This skill helps you write better prose for human readers. It draws from two sources:
+
+1. **The Elements of Style** (Strunk, 1918) - Time-tested rules for clear, forceful writing
+2. **AI Pattern Avoidance** - Research-backed guidance on avoiding generic, puffy language that LLMs tend to produce
+
+Whether you're writing documentation, commit messages, error messages, or any text humans will read, this skill helps you cut fluff and say what you mean.
+
+## When to Use
+
+Use this skill whenever you write prose for humans:
+
+- **Documentation** - README files, API docs, technical explanations
+- **Git workflow** - Commit messages, pull request descriptions
+- **User-facing text** - Error messages, UI copy, help text, tooltips
+- **Code comments** - Inline documentation, docstrings
+- **Reports and summaries** - Status updates, analysis, explanations
+- **Editing** - Improving clarity of existing text
+
+**Trigger phrases:**
+- "Write documentation for..."
+- "Draft a README"
+- "Edit this for clarity"
+- "Make this more concise"
+- "Review this commit message"
+
+## How It Works
+
+1. **Load the skill** when writing prose for human readers
+2. **Apply Strunk's core principles** - active voice, positive form, concrete language, cut needless words
+3. **Avoid AI patterns** - no puffery, no empty phrases, no promotional adjectives
+4. **Reference detailed guides** when needed for specific rules
+
+### Context-Efficient Approach
+
+The skill uses progressive disclosure to save context:
+
+- **SKILL.md** (~1,000 tokens) loads first with the core rules
+- **Reference files** (1,000-4,500 tokens each) load only when needed
+- **Most tasks need only one file**: `03-elementary-principles-of-composition.md`
+
+For tight context situations, dispatch a subagent with your draft and the relevant section file.
+
+## Key Features
+
+### Strunk's Core Rules
+
+The skill emphasizes these principles from *The Elements of Style*:
+
+| Rule | Principle |
+|------|-----------|
+| 10 | Use active voice |
+| 11 | Put statements in positive form |
+| 12 | Use definite, specific, concrete language |
+| 13 | Omit needless words |
+| 16 | Keep related words together |
+| 18 | Place emphatic words at end of sentence |
+
+### AI Pattern Detection
+
+The skill identifies and eliminates common LLM writing patterns:
+
+- **Puffery**: pivotal, crucial, vital, testament, enduring legacy
+- **Empty "-ing" phrases**: ensuring reliability, showcasing features
+- **Promotional adjectives**: groundbreaking, seamless, robust, cutting-edge
+- **Overused AI vocabulary**: delve, leverage, multifaceted, foster, realm, tapestry
+- **Formatting overuse**: excessive bullets, emoji decorations, bold on every other word
+
+## Reference Files
+
+| Section | File | Tokens | Content |
+|---------|------|--------|---------|
+| Grammar & punctuation | `02-elementary-rules-of-usage.md` | ~2,500 | Comma rules, possessives, sentence structure |
+| Composition principles | `03-elementary-principles-of-composition.md` | ~4,500 | Active voice, concision, paragraph structure |
+| Formatting | `04-a-few-matters-of-form.md` | ~1,000 | Headings, quotations, formatting conventions |
+| Word choice | `05-words-and-expressions-commonly-misused.md` | ~4,000 | Common errors, word selection |
+| AI patterns | `signs-of-ai-writing.md` | ~25,000 | Wikipedia editors' field guide to AI detection |
+
+## Usage Examples
+
+### Example 1: Tightening a Commit Message
+
+**Before:**
+> This commit implements the functionality for ensuring that user authentication is properly handled, showcasing robust error handling capabilities.
+
+**After:**
+> Add user authentication with error handling
+
+### Example 2: Rewriting Documentation
+
+**Before:**
+> This groundbreaking feature leverages cutting-edge technology to deliver a seamless experience, fostering better engagement and driving impactful results.
+
+**After:**
+> This feature uses WebSocket connections to update the dashboard in real time.
+
+### Example 3: Fixing Passive Voice
+
+**Before:**
+> The configuration file is read by the application at startup.
+
+**After:**
+> The application reads the configuration file at startup.
+
+### Example 4: Removing Hedging
+
+**Before:**
+> It is important to note that the API might potentially return an error in certain situations.
+
+**After:**
+> The API returns an error when the token expires.
+
+## Best Practices
+
+1. **Be specific, not grandiose** - Say what it actually does, not how important it is
+2. **Cut first, add later** - Remove words until meaning suffers, then add back what's needed
+3. **Prefer active voice** - "The function returns X" beats "X is returned by the function"
+4. **State positively** - "He forgot" beats "He did not remember"
+5. **Use concrete language** - "The server crashed" beats "An issue occurred"
+6. **Load reference files sparingly** - Most tasks need only `03-elementary-principles-of-composition.md`
+
+## Directory Structure
+
+```
+writing-clearly-and-concisely/
+  SKILL.md                 # Main skill definition
+  README.md                # This file
+  signs-of-ai-writing.md   # AI pattern detection guide
+  elements-of-style/
+    01-introductory.md
+    02-elementary-rules-of-usage.md
+    03-elementary-principles-of-composition.md
+    04-a-few-matters-of-form.md
+    05-words-and-expressions-commonly-misused.md
+```
+
+## Installation
+
+**Claude Code:**
+```bash
+cp -r skills/writing-clearly-and-concisely ~/.claude/skills/
+```
+
+**Claude.ai:**
+Add the skill to project knowledge or paste SKILL.md contents into your conversation.
+
+## Attribution
+
+- Original skill by @joshuadavidthomas from [joshuadavidthomas/agent-skills](https://github.com/joshuadavidthomas/agent-skills) (MIT)
+- Adapted from [obra/the-elements-of-style](https://github.com/obra/the-elements-of-style)
+- Writing principles from *The Elements of Style* by William Strunk Jr. (1918)
+- AI pattern research from Wikipedia's field guide to AI-generated content detection
diff --git a/builtin-skills/marketing/writing-clearly-and-concisely/SKILL.md b/builtin-skills/marketing/writing-clearly-and-concisely/SKILL.md
new file mode 100644
index 00000000..81a94732
--- /dev/null
+++ b/builtin-skills/marketing/writing-clearly-and-concisely/SKILL.md
@@ -0,0 +1,93 @@
+---
+name: writing-clearly-and-concisely
+description: Use when writing prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Applies Strunk's timeless rules for clearer, stronger, more professional writing.
+---
+
+# Writing Clearly and Concisely
+
+## Overview
+
+Write with clarity and force. This skill covers what to do (Strunk) and what not to do (AI patterns).
+
+## When to Use This Skill
+
+Use this skill whenever you write prose for humans:
+
+- Documentation, README files, technical explanations
+- Commit messages, pull request descriptions
+- Error messages, UI copy, help text, comments
+- Reports, summaries, or any explanation
+- Editing to improve clarity
+
+**If you're writing sentences for a human to read, use this skill.**
+
+## Limited Context Strategy
+
+When context is tight:
+
+1. Write your draft using judgment
+2. Dispatch a subagent with your draft and the relevant section file
+3. Have the subagent copyedit and return the revision
+
+Loading a single section (~1,000-4,500 tokens) instead of everything saves significant context.
+
+## Elements of Style
+
+William Strunk Jr.'s *The Elements of Style* (1918) teaches you to write clearly and cut ruthlessly.
+
+### Rules
+
+**Elementary Rules of Usage (Grammar/Punctuation)**:
+
+1. Form possessive singular by adding 's
+2. Use comma after each term in series except last
+3. Enclose parenthetic expressions between commas
+4. Comma before conjunction introducing co-ordinate clause
+5. Don't join independent clauses by comma
+6. Don't break sentences in two
+7. Participial phrase at beginning refers to grammatical subject
+
+**Elementary Principles of Composition**:
+
+8. One paragraph per topic
+9. Begin paragraph with topic sentence
+10. **Use active voice**
+11. **Put statements in positive form**
+12. **Use definite, specific, concrete language**
+13. **Omit needless words**
+14. Avoid succession of loose sentences
+15. Express co-ordinate ideas in similar form
+16. **Keep related words together**
+17. Keep to one tense in summaries
+18. **Place emphatic words at end of sentence**
+
+### Reference Files
+
+The rules above are summarized from Strunk's original text. For complete explanations with examples:
+
+| Section | File | ~Tokens |
+|---------|------|---------|
+| Grammar, punctuation, comma rules | `02-elementary-rules-of-usage.md` | 2,500 |
+| Paragraph structure, active voice, concision | `03-elementary-principles-of-composition.md` | 4,500 |
+| Headings, quotations, formatting | `04-a-few-matters-of-form.md` | 1,000 |
+| Word choice, common errors | `05-words-and-expressions-commonly-misused.md` | 4,000 |
+
+**Most tasks need only `03-elementary-principles-of-composition.md`** — it covers active voice, positive form, concrete language, and omitting needless words.
+
+## AI Writing Patterns to Avoid
+
+LLMs regress to statistical means, producing generic, puffy prose. Avoid:
+
+- **Puffery:** pivotal, crucial, vital, testament, enduring legacy
+- **Empty "-ing" phrases:** ensuring reliability, showcasing features, highlighting capabilities
+- **Promotional adjectives:** groundbreaking, seamless, robust, cutting-edge
+- **Overused AI vocabulary:** delve, leverage, multifaceted, foster, realm, tapestry
+- **Formatting overuse:** excessive bullets, emoji decorations, bold on every other word
+
+Be specific, not grandiose. Say what it actually does.
+
+For comprehensive research on why these patterns occur, see `signs-of-ai-writing.md`. Wikipedia editors developed this guide to detect AI-generated submissions — their patterns are well-documented and field-tested.
+
+## Bottom Line
+
+Writing for humans? Load the relevant section from `elements-of-style/` and apply the rules. For most tasks, `03-elementary-principles-of-composition.md` covers what matters most.
diff --git a/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/01-introductory.md b/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/01-introductory.md
new file mode 100644
index 00000000..667b823b
--- /dev/null
+++ b/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/01-introductory.md
@@ -0,0 +1,3 @@
+## I. Introductory
+
+This handbook summarizes the essentials of plain English style. It focuses on the rules of usage and principles of composition most often broken, offering a compact alternative to exhaustive manuals. Master the guidance here, then look to the best authors for finer points of style.
diff --git a/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/02-elementary-rules-of-usage.md b/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/02-elementary-rules-of-usage.md
new file mode 100644
index 00000000..b42e5ef9
--- /dev/null
+++ b/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/02-elementary-rules-of-usage.md
@@ -0,0 +1,214 @@
+## II. Elementary Rules Of Usage
+
+### Rule 1. Form the possessive singular of nouns by adding 's.
+
+Follow this rule whatever the final consonant. Thus write,
+
+Charles's friend
+
+Burns's poems
+
+the witch's malice
+
+This is the usage of the United States Government Printing Office and of the Oxford University Press.
+
+Exceptions are the possessive of ancient proper names ending in *-es* and *-is*, the possessive *Jesus'*, and such forms as *for conscience' sake*, *for righteousness' sake*. But such forms as *Achilles' heel*, *Moses' laws*, *Isis' temple* are commonly replaced by
+
+the heel of Achilles
+
+the laws of Moses
+
+the temple of Isis
+
+The pronominal possessives *hers*, *its*, *theirs*, *yours*, and *oneself* have no apostrophe.
+
+### Rule 2. In a series of three or more terms with a single conjunction, use a comma after each term except the last.
+
+Thus write,
+
+red, white, and blue
+
+gold, silver, or copper
+
+He opened the letter, read it, and made a note of its contents.
+
+This is also the usage of the Government Printing Office and of the Oxford University Press.
+
+In the names of business firms the last comma is omitted, as,
+
+Brown, Shipley & Co.
+
+### Rule 3. Enclose parenthetic expressions between commas.
+
+The best way to see a country, unless you are pressed for time, is to travel on foot.
+
+This rule is difficult to apply; it is frequently hard to decide whether a single word, such as *however*, or a brief phrase, is or is not parenthetic. If the interruption to the flow of the sentence is but slight, the writer may safely omit the commas. But whether the interruption be slight or considerable, he must never insert one comma and omit the other. Such punctuation as
+
+Marjorie's husband, Colonel Nelson paid us a visit yesterday,
+
+or
+
+My brother you will be pleased to hear, is now in perfect health,
+
+is indefensible.
+
+If a parenthetic expression is preceded by a conjunction, place the first comma before the conjunction, not after it.
+
+He saw us coming, and unaware that we had learned of his treachery, greeted us with a smile.
+
+Always to be regarded as parenthetic and to be enclosed between commas (or, at the end of the sentence, between comma and period) are the following:
+
+\(1\) the year, when forming part of a date, and the day of the month, when following the day of the week:
+
+February to July, 1916.
+
+April 6, 1917.
+
+Monday, November 11, 1918.
+
+\(2\) the abbreviations *etc.* and *jr.*
+
+\(3\) non-restrictive relative clauses, that is, those which do not serve to identify or define the antecedent noun, and similar clauses introduced by conjunctions indicating time or place.
+
+The audience, which had at first been indifferent, became more and more interested.
+
+In this sentence the clause introduced by *which* does not serve to tell which of several possible audiences is meant; what audience is in question is supposed to be already known. The clause adds, parenthetically, a statement supplementing that in the main clause. The sentence is virtually a combination of two statements which might have been made independently:
+
+The audience had at first been indifferent. It became more and more interested.
+
+Compare the restrictive relative clause, not set off by commas, in the sentence,
+
+The candidate who best meets these requirements will obtain the place.
+
+Here the clause introduced by *who* does serve to tell which of several possible candidates is meant; the sentence cannot be split up into two independent statements.
+
+The difference in punctuation in the two sentences following is based on the same principle:
+
+Nether Stowey, where Coleridge wrote The Rime of the Ancient Mariner, is a few miles from Bridgewater.
+
+The day will come when you will admit your mistake.
+
+Nether Stowey is completely identified by its name; the statement about Coleridge is therefore supplementary and parenthetic. The *day* spoken of is identified only by the dependent clause, which is therefore restrictive.
+
+Similar in principle to the enclosing of parenthetic expressions between commas is the setting off by commas of phrases or dependent clauses preceding or following the main clause of a sentence.
+
+Partly by hard fighting, partly by diplomatic skill, they enlarged their dominions to the east, and rose to royal rank with the possession of Sicily, exchanged afterwards for Sardinia.
+
+Other illustrations may be found in sentences quoted under Rules 4, 5, 6, 7, 16, and 18.
+
+The writer should be careful not to set off independent clauses by commas: see under Rule 5.
+
+### Rule 4. Place a comma before a conjunction introducing a co-ordinate clause.
+
+The early records of the city have disappeared, and the story of its first years can no longer be reconstructed.
+
+The situation is perilous, but there is still one chance of escape.
+
+Sentences of this type, isolated from their context, may seem to be in need of rewriting. As they make complete sense when the comma is reached, the second clause has the appearance of an afterthought. Further, *and* is the least specific of connectives. Used between independent clauses, it indicates only that a relation exists between them without defining that relation. In the example above, the relation is that of cause and result. The two sentences might be rewritten:
+
+As the early records of the city have disappeared, the story of its first years can no longer be reconstructed.
+
+Although the situation is perilous, there is still one chance of escape.
+
+Or the subordinate clauses might be replaced by phrases:
+
+Owing to the disappearance of the early records of the city, the story of its first years can no longer be reconstructed.
+
+In this perilous situation, there is still one chance of escape.
+
+But a writer may err by making his sentences too uniformly compact and periodic, and an occasional loose sentence prevents the style from becoming too formal and gives the reader a certain relief. Consequently, loose sentences of the type first quoted are common in easy, unstudied writing. But a writer should be careful not to construct too many of his sentences after this pattern (see Rule 14).
+
+Two-part sentences of which the second member is introduced by *as* (in the sense of *because*), *for*, *or*, *nor*, and *while* (in the sense of *and at the same time*) likewise require a comma before the conjunction.
+
+If the second member is introduced by an adverb, a semicolon, not a comma, is required (see Rule 5). The connectives *so* and *yet* may be used either as adverbs or as conjunctions, accordingly as the second clause is felt to be co-ordinate or subordinate; consequently either mark of punctuation may be justified. But these uses of *so* (equivalent to *accordingly* or to *so that*) are somewhat colloquial and should, as a rule, be avoided in writing. A simple correction, usually serviceable, is to omit the word *so* and begin the first clause with *as* or *since*:
+
+| Original | Revision |
+| --- | --- |
+| I had never been in the place before; so I had difficulty in finding my way about. | As I had never been in the place before, I had difficulty in finding my way about. |
+
+If a dependent clause, or an introductory phrase requiring to be set off by a comma, precedes the second independent clause, no comma is needed after the conjunction.
+
+The situation is perilous, but if we are prepared to act promptly, there is still one chance of escape.
+
+When the subject is the same for both clauses and is expressed only once, a comma is required if the connective is *but*. If the connective is *and*, the comma should be omitted if the relation between the two statements is close or immediate.
+
+I have heard his arguments, but am still unconvinced.
+
+He has had several years' experience and is thoroughly competent.
+
+### Rule 5. Do not join independent clauses by a comma.
+
+If two or more clauses, grammatically complete and not joined by a conjunction, are to form a single compound sentence, the proper mark of punctuation is a semicolon.
+
+Stevenson's romances are entertaining; they are full of exciting adventures.
+
+It is nearly half past five; we cannot reach town before dark.
+
+It is of course equally correct to write the above as two sentences each, replacing the semicolons by periods.
+
+Stevenson's romances are entertaining. They are full of exciting adventures.
+
+It is nearly half past five. We cannot reach town before dark.
+
+If a conjunction is inserted the proper mark is a comma (Rule 4).
+
+Stevenson's romances are entertaining, for they are full of exciting adventures.
+
+It is nearly half past five, and we cannot reach town before dark.
+
+A comparison of the three forms given above will show clearly the advantage of the first. It is, at least in the examples given, better than the second form, because it suggests the close relationship between the two statements in a way that the second does not attempt, and better than the third, because briefer and therefore more forcible. Indeed it may be said that this simple method of indicating relationship between statements is one of the most useful devices of composition. The relationship, as above, is commonly one of cause or of consequence.
+
+Note that if the second clause is preceded by an adverb, such as *accordingly*, *besides*, *then*, *therefore*, or *thus*, and not by a conjunction, the semicolon is still required.
+
+Two exceptions to the rule may be admitted. If the clauses are very short, and are alike in form, a comma is usually permissible:
+
+Man proposes, God disposes.
+
+The gate swung apart, the bridge fell, the portcullis was drawn up.
+
+Note that in these examples the relation is not one of cause or consequence. Also in the colloquial form of expression,
+
+I hardly knew him, he was so changed,
+
+a comma, not a semicolon, is required. But this form of expression is inappropriate in writing, except in the dialogue of a story or play, or perhaps in a familiar letter.
+
+### Rule 6. Do not break sentences in two.
+
+In other words, do not use periods for commas.
+
+I met them on a Cunard liner several years ago. Coming home from Liverpool to New York.
+
+He was an interesting talker. A man who had traveled all over the world and lived in half a dozen countries.
+
+In both these examples, the first period should be replaced by a comma, and the following word begun with a small letter.
+
+It is permissible to make an emphatic word or expression serve the purpose of a sentence and to punctuate it accordingly:
+
+Again and again he called out. No reply.
+
+The writer must, however, be certain that the emphasis is warranted, and that he will not be suspected of a mere blunder in syntax or in punctuation.
+
+Rules 3, 4, 5, and 6 cover the most important principles in the punctuation of ordinary sentences; they should be so thoroughly mastered that their application becomes second nature.
+
+### Rule 7. A participial phrase at the beginning of a sentence must refer to the grammatical subject.
+
+Walking slowly down the road, he saw a woman accompanied by two children.
+
+The word *walking* refers to the subject of the sentence, not to the woman. If the writer wishes to make it refer to the woman, he must recast the sentence:
+
+He saw a woman accompanied by two children, walking slowly down the road.
+
+Participial phrases preceded by a conjunction or by a preposition, nouns in apposition, adjectives, and adjective phrases come under the same rule if they begin the sentence.
+
+| Original | Revision |
+| --- | --- |
+| On arriving in Chicago, his friends met him at the station. | When he arrived (or, On his arrival) in Chicago, his friends met him at the station. |
+| A soldier of proved valor, they entrusted him with the defence of the city. | A soldier of proved valor, he was entrusted with the defence of the city. |
+| Young and inexperienced, the task seemed easy to me. | Young and inexperienced, I thought the task easy. |
+| Without a friend to counsel him, the temptation proved irresistible. | Without a friend to counsel him, he found the temptation irresistible. |
+
+Sentences violating this rule are often ludicrous.
+
+Being in a dilapidated condition, I was able to buy the house very cheap.
+
+Wondering irresolutely what to do next, the clock struck twelve.
diff --git a/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/03-elementary-principles-of-composition.md b/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/03-elementary-principles-of-composition.md
new file mode 100644
index 00000000..e92e08bd
--- /dev/null
+++ b/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/03-elementary-principles-of-composition.md
@@ -0,0 +1,398 @@
+## III. Elementary Principles Of Composition
+
+### Rule 8. Make the paragraph the unit of composition: one paragraph to each topic.
+
+If the subject on which you are writing is of slight extent, or if you intend to treat it very briefly, there may be no need of subdividing it into topics. Thus a brief description, a brief summary of a literary work, a brief account of a single incident, a narrative merely outlining an action, the setting forth of a single idea, any one of these is best written in a single paragraph. After the paragraph has been written, examine it to see whether subdivision will not improve it.
+
+Ordinarily, however, a subject requires subdivision into topics, each of which should be made the subject of a paragraph. The object of treating each topic in a paragraph by itself is, of course, to aid the reader. The beginning of each paragraph is a signal to him that a new step in the development of the subject has been reached.
+
+The extent of subdivision will vary with the length of the composition. For example, a short notice of a book or poem might consist of a single paragraph. One slightly longer might consist of two paragraphs:
+
+- A. Account of the work.
+- B. Critical discussion.
+
+A report on a poem, written for a class in literature, might consist of seven paragraphs:
+
+- A. Facts of composition and publication.
+- B. Kind of poem; metrical form.
+- C. Subject.
+- D. Treatment of subject.
+- E. For what chiefly remarkable.
+- F. Wherein characteristic of the writer.
+- G. Relationship to other works.
+
+The contents of paragraphs C and D would vary with the poem. Usually, paragraph C would indicate the actual or imagined circumstances of the poem (the situation), if these call for explanation, and would then state the subject and outline its development. If the poem is a narrative in the third person throughout, paragraph C need contain no more than a concise summary of the action. Paragraph D would indicate the leading ideas and show how they are made prominent, or would indicate what points in the narrative are chiefly emphasized.
+
+A novel might be discussed under the heads:
+
+- A. Setting.
+- B. Plot.
+- C. Characters.
+- D. Purpose.
+
+An historical event might be discussed under the heads:
+
+- A. What led up to the event.
+- B. Account of the event.
+- C. What the event led up to.
+
+In treating either of these last two subjects, the writer would probably find it necessary to subdivide one or more of the topics here given.
+
+As a rule, single sentences should not be written or printed as paragraphs. An exception may be made of sentences of transition, indicating the relation between the parts of an exposition or argument. Frequent exceptions are also necessary in textbooks, guidebooks, and other works in which many topics are treated briefly.
+
+In dialogue, each speech, even if only a single word, is a paragraph by itself; that is, a new paragraph begins with each change of speaker. The application of this rule, when dialogue and narrative are combined, is best learned from examples in well-printed works of fiction.
+
+### Rule 9. As a rule, begin each paragraph with a topic sentence, end it in conformity with the beginning.
+
+Again, the object is to aid the reader. The practice here recommended enables him to discover the purpose of each paragraph as he begins to read it, and to retain this purpose in mind as he ends it. For this reason, the most generally useful kind of paragraph, particularly in exposition and argument, is that in which
+
+\(a\) the topic sentence comes at or near the beginning;
+
+\(b\) the succeeding sentences explain or establish or develop the statement made in the topic sentence; and
+
+\(c\) the final sentence either emphasizes the thought of the topic sentence or states some important consequence.
+
+Ending with a digression, or with an unimportant detail, is particularly to be avoided.
+
+If the paragraph forms part of a larger composition, its relation to what precedes, or its function as a part of the whole, may need to be expressed. This can sometimes be done by a mere word or phrase (*again*; *therefore*; *for the same reason*) in the topic sentence. Sometimes, however, it is expedient to precede the topic sentence by one or more sentences of introduction or transition. If more than one such sentence is required, it is generally better to set apart the transitional sentences as a separate paragraph.
+
+According to the writer's purpose, he may, as indicated above, relate the body of the paragraph to the topic sentence in one or more of several different ways. He may make the meaning of the topic sentence clearer by restating it in other forms, by defining its terms, by denying the contrary, by giving illustrations or specific instances; he may establish it by proofs; or he may develop it by showing its implications and consequences. In a long paragraph, he may carry out several of these processes.
+
+1 Now, to be properly enjoyed, a walking tour should be gone upon alone. 2 If you go in a company, or even in pairs, it is no longer a walking tour in anything but name; it is something else and more in the nature of a picnic. 3 A walking tour should be gone upon alone, because freedom is of the essence; because you should be able to stop and go on, and follow this way or that, as the freak takes you; and because you must have your own pace, and neither trot alongside a champion walker, nor mince in time with a girl. 4 And you must be open to all impressions and let your thoughts take colour from what you see. 5 You should be as a pipe for any wind to play upon. 6 “I cannot see the wit,” says Hazlitt, “of walking and talking at the same time. 7 When I am in the country, I wish to vegetate like the country,” which is the gist of all that can be said upon the matter. 8 There should be no cackle of voices at your elbow, to jar on the meditative silence of the morning. 9 And so long as a man is reasoning he cannot surrender himself to that fine intoxication that comes of much motion in the open air, that begins in a sort of dazzle and sluggishness of the brain, and ends in a peace that passes comprehension.—Stevenson, Walking Tours.
+
+1 Topic sentence. 2 The meaning made clearer by denial of the contrary. 3 The topic sentence repeated, in abridged form, and supported by three reasons; the meaning of the third (“you must have your own pace”) made clearer by denying the contrary. 4 A fourth reason, stated in two forms. 5 The same reason, stated in still another form. 6–7 The same reason as stated by Hazlitt. 8 Repetition, in paraphrase, of the quotation from Hazlitt. 9 Final statement of the fourth reason, in language amplified and heightened to form a strong conclusion.
+
+1 It was chiefly in the eighteenth century that a very different conception of history grew up. 2 Historians then came to believe that their task was not so much to paint a picture as to solve a problem; to explain or illustrate the successive phases of national growth, prosperity, and adversity. 3 The history of morals, of industry, of intellect, and of art; the changes that take place in manners or beliefs; the dominant ideas that prevailed in successive periods; the rise, fall, and modification of political constitutions; in a word, all the conditions of national well-being became the subject of their works. 4 They sought rather to write a history of peoples than a history of kings. 5 They looked especially in history for the chain of causes and effects. 6 They undertook to study in the past the physiology of nations, and hoped by applying the experimental method on a large scale to deduce some lessons of real value about the conditions on which the welfare of society mainly depend.—Lecky, The Political Value of History.
+
+1 Topic sentence. 2 The meaning of the topic sentence made clearer; the new conception of history defined. 3 The definition expanded. 4 The definition explained by contrast. 5 The definition supplemented: another element in the new conception of history. 6 Conclusion: an important consequence of the new conception of history.
+
+In narration and description the paragraph sometimes begins with a concise, comprehensive statement serving to hold together the details that follow.
+
+The breeze served us admirably.
+
+The campaign opened with a series of reverses.
+
+The next ten or twelve pages were filled with a curious set of entries.
+
+But this device, if too often used, would become a mannerism. More commonly the opening sentence simply indicates by its subject with what the paragraph is to be principally concerned.
+
+At length I thought I might return towards the stockade.
+
+He picked up the heavy lamp from the table and began to explore.
+
+Another flight of steps, and they emerged on the roof.
+
+The brief paragraphs of animated narrative, however, are often without even this semblance of a topic sentence. The break between them serves the purpose of a rhetorical pause, throwing into prominence some detail of the action.
+
+### Rule 10. Use the active voice.
+
+The active voice is usually more direct and vigorous than the passive:
+
+I shall always remember my first visit to Boston.
+
+This is much better than
+
+My first visit to Boston will always be remembered by me.
+
+The latter sentence is less direct, less bold, and less concise. If the writer tries to make it more concise by omitting “by me,”
+
+My first visit to Boston will always be remembered,
+
+it becomes indefinite: is it the writer, or some person undisclosed, or the world at large, that will always remember this visit?
+
+This rule does not, of course, mean that the writer should entirely discard the passive voice, which is frequently convenient and sometimes necessary.
+
+The dramatists of the Restoration are little esteemed to-day.
+
+Modern readers have little esteem for the dramatists of the Restoration.
+
+The first would be the right form in a paragraph on the dramatists of the Restoration; the second, in a paragraph on the tastes of modern readers. The need of making a particular word the subject of the sentence will often, as in these examples, determine which voice is to be used.
+
+As a rule, avoid making one passive depend directly upon another.
+
+| Original | Revision |
+| --- | --- |
+| Gold was not allowed to be exported. | It was forbidden to export gold (The export of gold was prohibited). |
+| He has been proved to have been seen entering the building. | It has been proved that he was seen to enter the building. |
+
+In both the examples above, before correction, the word properly related to the second passive is made the subject of the first.
+
+A common fault is to use as the subject of a passive construction a noun which expresses the entire action, leaving to the verb no function beyond that of completing the sentence.
+
+| Original | Revision |
+| --- | --- |
+| A survey of this region was made in 1900. | This region was surveyed in 1900. |
+| Mobilization of the army was rapidly effected. | The army was rapidly mobilized. |
+| Confirmation of these reports cannot be obtained. | These reports cannot be confirmed. |
+
+Compare the _sentence,_ “The export of gold was prohibited,” in which the predicate “was prohibited” expresses something not implied in “export.”
+
+The habitual use of the active voice makes for forcible writing. This is true not only in narrative principally concerned with action, but in writing of any kind. Many a tame sentence of description or exposition can be made lively and emphatic by substituting a verb in the active voice for some such perfunctory expression as *there is*, or *could be heard*.
+
+| Original | Revision |
+| --- | --- |
+| There were a great number of dead leaves lying on the ground. | Dead leaves covered the ground. |
+| The sound of a guitar somewhere in the house could be heard. | Somewhere in the house a guitar hummed sleepily. |
+| The reason that he left college was that his health became impaired. | Failing health compelled him to leave college. |
+| It was not long before he was very sorry that he had said what he had. | He soon repented his words. |
+
+### Rule 11. Put statements in positive form.
+
+Make definite assertions. Avoid tame, colorless, hesitating, non-committal language. Use the word *not* as a means of denial or in antithesis, never as a means of evasion.
+
+| Original | Revision |
+| --- | --- |
+| He was not very often on time. | He usually came late. |
+| He did not think that studying Latin was much use. | He thought the study of Latin useless. |
+| The Taming of the Shrew is rather weak in spots. Shakespeare does not portray Katharine as a very admirable character, nor does Bianca remain long in memory as an important character in Shakespeare's works. | The women in The Taming of the Shrew are unattractive. Katharine is disagreeable, Bianca insignificant. |
+
+The last example, before correction, is indefinite as well as negative. The corrected version, consequently, is simply a guess at the writer's intention.
+
+All three examples show the weakness inherent in the word *not*. Consciously or unconsciously, the reader is dissatisfied with being told only what is not; he wishes to be told what is. Hence, as a rule, it is better to express even a negative in positive form.
+
+| Original | Revision |
+| --- | --- |
+| not honest | dishonest |
+| not important | trifling |
+| did not remember | forgot |
+| did not pay any attention to | ignored |
+| did not have much confidence in | distrusted |
+
+The antithesis of negative and positive is strong:
+
+Not charity, but simple justice.
+
+Not that I loved Caesar less, but Rome the more.
+
+Negative words other than *not* are usually strong:
+
+The sun never sets upon the British flag.
+
+### Rule 12. Use definite, specific, concrete language.
+
+Prefer the specific to the general, the definite to the vague, the concrete to the abstract.
+
+| Original | Revision |
+| --- | --- |
+| A period of unfavorable weather set in. | It rained every day for a week. |
+| He showed satisfaction as he took possession of his well-earned reward. | He grinned as he pocketed the coin. |
+| There is a general agreement among those who have enjoyed the experience that surf-riding is productive of great exhilaration. | All who have tried surf-riding agree that it is most exhilarating. |
+
+If those who have studied the art of writing are in accord on any one point, it is on this, that the surest method of arousing and holding the attention of the reader is by being specific, definite, and concrete. Critics have pointed out how much of the effectiveness of the greatest writers, Homer, Dante, Shakespeare, results from their constant definiteness and concreteness. Browning, to cite a more modern author, affords many striking examples. Take, for instance, the lines from My Last Duchess,
+
+Sir, 'twas all one! My favour at her breast,
+
+The dropping of the daylight in the west,
+
+The bough of cherries some officious fool
+
+Broke in the orchard for her, the white mule
+
+She rode with round the terrace—all and each
+
+Would draw from her alike the approving speech,
+
+Or blush, at least,
+
+and those which end the poem,
+
+Notice Neptune, though,
+
+Taming a sea-horse, thought a rarity,
+
+Which Claus of Innsbruck cast in bronze for me.
+
+These words call up pictures. Recall how in The Bishop Orders his Tomb in St. Praxed's Church “the Renaissance spirit—its worldliness, inconsistency, pride, hypocrisy, ignorance of itself, love of art, of luxury, of good Latin,” to quote Ruskin's comment on the poem, is made manifest in specific details and in concrete terms.
+
+Prose, in particular narrative and descriptive prose, is made vivid by the same means. If the experiences of Jim Hawkins and of David Balfour, of Kim, of Nostromo, have seemed for the moment real to countless readers, if in reading Carlyle we have almost the sense of being physically present at the taking of the Bastille, it is because of the definiteness of the details and the concreteness of the terms used. It is not that every detail is given; that would be impossible, as well as to no purpose; but that all the significant details are given, and not vaguely, but with such definiteness that the reader, in imagination, can project himself into the scene.
+
+In exposition and in argument, the writer must likewise never lose his hold upon the concrete, and even when he is dealing with general principles, he must give particular instances of their application.
+
+“This superiority of specific expressions is clearly due to the effort required to translate words into thoughts. As we do not think in generals, but in particulars—as whenever any class of things is referred to, we represent it to ourselves by calling to mind individual members of it, it follows that when an abstract word is used, the hearer or reader has to choose, from his stock of images, one or more by which he may figure to himself the genus mentioned. In doing this, some delay must arise, some force be expended; and if by employing a specific term an appropriate image can be at once suggested, an economy is achieved, and a more vivid impression produced.”
+
+Herbert Spencer, from whose Philosophy of Style the preceding paragraph is quoted, illustrates the principle by the sentences:
+
+| Original | Revision |
+| --- | --- |
+| In proportion as the manners, customs, and amusements of a nation are cruel and barbarous, the regulations of their penal code will be severe. | In proportion as men delight in battles, bull-fights, and combats of gladiators, will they punish by hanging, burning, and the rack. |
+
+### Rule 13. Omit needless words.
+
+Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he avoid all detail and treat his subjects only in outline, but that he make every word tell.
+
+Many expressions in common use violate this principle:
+
+| Original | Revision |
+| --- | --- |
+| the question as to whether | whether (the question whether) |
+| there is no doubt but that | no doubt (doubtless) |
+| used for fuel purposes | used for fuel |
+| he is a man who | he |
+| in a hasty manner | hastily |
+| this is a subject which | this subject |
+| His story is a strange one. | His story is strange. |
+
+In especial the expression *the fact that* should be revised out of every sentence in which it occurs.
+
+| Original | Revision |
+| --- | --- |
+| owing to the fact that | since (because) |
+| in spite of the fact that | though (although) |
+| call your attention to the fact that | remind you (notify you) |
+| I was unaware of the fact that | I was unaware that (did not know) |
+| the fact that he had not succeeded | his failure |
+| the fact that I had arrived | my arrival |
+
+See also under *case*, *character*, *nature*, *system* in Chapter V.
+
+*Who is*, *which was*, and the like are often superfluous.
+
+| Original | Revision |
+| --- | --- |
+| His brother, who is a member of the same firm | His brother, a member of the same firm |
+| Trafalgar, which was Nelson's last battle | Trafalgar, Nelson's last battle |
+
+As positive statement is more concise than negative, and the active voice more concise than the passive, many of the examples given under Rules 11 and 12 illustrate this rule as well.
+
+A common violation of conciseness is the presentation of a single complex idea, step by step, in a series of sentences or independent clauses which might to advantage be combined into one.
+
+| Original | Revision |
+| --- | --- |
+| Macbeth was very ambitious. This led him to wish to become king of Scotland. The witches told him that this wish of his would come true. The king of Scotland at this time was Duncan. Encouraged by his wife, Macbeth murdered Duncan. He was thus enabled to succeed Duncan as king. (51 words.) | Encouraged by his wife, Macbeth achieved his ambition and realized the prediction of the witches by murdering Duncan and becoming king of Scotland in his place. (26 words.) |
+| There were several less important courses, but these were the most important, and although they did not come every day, they came often enough to keep you in such a state of mind that you never knew what your next move would be. (43 words.) | These, the most important courses of all, came, if not daily, at least often enough to keep one under constant strain. (21 words.) |
+
+### Rule 14. Avoid a succession of loose sentences
+
+This rule refers especially to loose sentences of a particular type, those consisting of two co-ordinate clauses, the second introduced by a conjunction or relative. Although single sentences of this type may be unexceptionable (see under Rule 4), a series soon becomes monotonous and tedious.
+
+An unskilful writer will sometimes construct a whole paragraph of sentences of this kind, using as connectives *and*, *but*, *so*, and less frequently, *who*, *which*, *when*, *where*, and *while*, these last in non-restrictive senses (see under Rule 3).
+
+The third concert of the subscription series was given last evening, and a large audience was in attendance. Mr. Edward Appleton was the soloist, and the Boston Symphony Orchestra furnished the instrumental music. The former showed himself to be an artist of the first rank, while the latter proved itself fully deserving of its high reputation. The interest aroused by the series has been very gratifying to the Committee, and it is planned to give a similar series annually hereafter. The fourth concert will be given on Tuesday, May 10, when an equally attractive programme will be presented.
+
+Apart from its triteness and emptiness, the paragraph above is weak because of the structure of its sentences, with their mechanical symmetry and sing-song. Contrast with them the sentences in the paragraphs quoted under Rule 9, or in any piece of good English prose, as the preface (Before the Curtain) to Vanity Fair.
+
+If the writer finds that he has written a series of sentences of the type described, he should recast enough of them to remove the monotony, replacing them by simple sentences, by sentences of two clauses joined by a semicolon, by periodic sentences of two clauses, by sentences, loose or periodic, of three clauses—whichever best represent the real relations of the thought.
+
+### Rule 15. Express co-ordinate ideas in similar form.
+
+This principle, that of parallel construction, requires that expressions of similar content and function should be outwardly similar. The likeness of form enables the reader to recognize more readily the likeness of content and function. Familiar instances from the Bible are the Ten Commandments, the Beatitudes, and the petitions of the Lord's Prayer.
+
+The unskillful writer often violates this principle, from a mistaken belief that he should constantly vary the form of his expressions. It is true that in repeating a statement in order to emphasize it he may have need to vary its form. For illustration, see the paragraph from Stevenson quoted under Rule _9_. But apart from this, he should follow the principle of parallel construction.
+
+| Original | Revision |
+| --- | --- |
+| Formerly, science was taught by the textbook method, while now the laboratory method is employed. | Formerly, science was taught by the textbook method; now it is taught by the laboratory method. |
+
+The left-hand version gives the impression that the writer is undecided or timid; he seems unable or afraid to choose one form of expression and hold to it. The right-hand version shows that the writer has at least made his choice and abided by it.
+
+By this principle, an article or a preposition applying to all the members of a series must either be used only before the first term or else be repeated before each term.
+
+| Original | Revision |
+| --- | --- |
+| The French, the Italians, Spanish, and Portuguese | The French, the Italians, the Spanish, and the Portuguese |
+| In spring, summer, or in winter | In spring, summer, or winter (In spring, in summer, or in winter) |
+
+Correlative expressions (*both, and*; *not, but*; *not only, but also*; *either, or*; *first, second, third*; and the like) should be followed by the same grammatical construction, that is, virtually, by the same part of speech. (Such combinations as “both Henry and I,” “not silk, but a cheap substitute,” are obviously within the rule.) Many violations of this rule (as the first three below) arise from faulty arrangement; others (as the last) from the use of unlike constructions.
+
+| Original | Revision |
+| --- | --- |
+| It was both a long ceremony and very tedious. | The ceremony was both long and tedious. |
+| A time not for words, but action. | A time not for words, but for action. |
+| Either you must grant his request or incur his ill will. | You must either grant his request or incur his ill will. |
+| My objections are, first, the injustice of the measure; second, that it is unconstitutional. | My objections are, first, that the measure is unjust; second, that it is unconstitutional. |
+
+See also the third example under Rule 12 and the last under Rule 13.
+
+It may be asked, what if a writer needs to express a very large number of similar ideas, say twenty? Must he write twenty consecutive sentences of the same pattern? On closer examination he will probably find that the difficulty is imaginary, that his twenty ideas can be classified in groups, and that he need apply the principle only within each group. Otherwise he had best avoid difficulty by putting his statements in the form of a table.
+
+### Rule 16. Keep related words together.
+
+The position of the words in a sentence is the principal means of showing their relationship. The writer must therefore, so far as possible, bring together the words, and groups of words, that are related in thought, and keep apart those which are not so related.
+
+The subject of a sentence and the principal verb should not, as a rule, be separated by a phrase or clause that can be transferred to the beginning.
+
+| Original | Revision |
+| --- | --- |
+| Wordsworth, in the fifth book of The Excursion, gives a minute description of this church. | In the fifth book of The Excursion, Wordsworth gives a minute description of this church. |
+| Cast iron, when treated in a Bessemer converter, is changed into steel. | By treatment in a Bessemer converter, cast iron is changed into steel. |
+
+The objection is that the interposed phrase or clause needlessly interrupts the natural order of the main clause. Usually, however, this objection does not hold when the order is interrupted only by a relative clause or by an expression in apposition. Nor does it hold in periodic sentences in which the interruption is a deliberately used means of creating suspense (see examples under Rule 18).
+
+The relative pronoun should come, as a rule, immediately after its antecedent.
+
+| Original | Revision |
+| --- | --- |
+| There was a look in his eye that boded mischief. | In his eye was a look that boded mischief. |
+| He wrote three articles about his adventures in Spain, which were published in Harper's Magazine. | He published in Harper's Magazine three articles about his adventures in Spain. |
+| This is a portrait of Benjamin Harrison, grandson of William Henry Harrison, who became President in 1889. | This is a portrait of Benjamin Harrison, grandson of William Henry Harrison. He became President in 1889. |
+
+If the antecedent consists of a group of words, the relative comes at the end of the group, unless this would cause ambiguity.
+
+The Superintendent of the Chicago Division, who
+
+| Original | Revision |
+| --- | --- |
+| A proposal to amend the Sherman Act, which has been variously judged. | A proposal, which has been variously judged, to amend the Sherman Act. |
+| — | A proposal to amend the much-debated Sherman Act. |
+| The grandson of William Henry Harrison, who | William Henry Harrison's grandson, who |
+
+A noun in apposition may come between antecedent and relative, because in such a combination no real ambiguity can arise.
+
+The Duke of York, his brother, who was regarded with hostility by the Whigs
+
+Modifiers should come, if possible, next to the word they modify. If several expressions modify the same word, they should be so arranged that no wrong relation is suggested.
+
+| Original | Revision |
+| --- | --- |
+| All the members were not present. | Not all the members were present. |
+| He only found two mistakes. | He found only two mistakes. |
+| Major R. E. Joyce will give a lecture on Tuesday evening in Bailey Hall, to which the public is invited, on “My Experiences in Mesopotamia” at eight P. M. | On Tuesday evening at eight P. M., Major R. E. Joyce will give in Bailey Hall a lecture on “My Experiences in Mesopotamia.” The public is invited. |
+
+### Rule 17. In summaries, keep to one tense.
+
+In summarizing the action of a drama, the writer should always use the present tense. In summarizing a poem, story, or novel, he should preferably use the present, though he may use the past if he prefers. If the summary is in the present tense, antecedent action should be expressed by the perfect; if in the past, by the past perfect.
+
+An unforeseen chance prevents Friar John from delivering Friar Lawrence's letter to Romeo. Meanwhile, owing to her father's arbitrary change of the day set for her wedding, Juliet has been compelled to drink the potion on Tuesday night, with the result that Balthasar informs Romeo of her supposed death before Friar Lawrence learns of the non-delivery of the letter.
+
+But whichever tense be used in the summary, a past tense in indirect discourse or in indirect question remains unchanged.
+
+The Friar confesses that it was he who married them.
+
+Apart from the exceptions noted, whichever tense the writer chooses, he should use throughout. Shifting from one tense to the other gives the appearance of uncertainty and irresolution (compare Rule 15).
+
+In presenting the statements or the thought of some one else, as in summarizing an essay or reporting a speech, the writer should avoid intercalating such expressions as “he said,” “he stated,” “the speaker added,” “the speaker then went on to say,” “the author also thinks,” or the like. He should indicate clearly at the outset, once for all, that what follows is summary, and then waste no words in repeating the notification.
+
+In notebooks, in newspapers, in handbooks of literature, summaries of one kind or another may be indispensable, and for children in primary schools it is a useful exercise to retell a story in their own words. But in the criticism or interpretation of literature the writer should be careful to avoid dropping into summary. He may find it necessary to devote one or two sentences to indicating the subject, or the opening situation, of the work he is discussing; he may cite numerous details to illustrate its qualities. But he should aim to write an orderly discussion supported by evidence, not a summary with occasional comment. Similarly, if the scope of his discussion includes a number of works, he will as a rule do better not to take them up singly in chronological order, but to aim from the beginning at establishing general conclusions.
+
+### Rule 18. Place the emphatic words of a sentence at the end.
+
+The proper place in the sentence for the word, or group of words, which the writer desires to make most prominent is usually the end.
+
+| Original | Revision |
+| --- | --- |
+| Humanity has hardly advanced in fortitude since that time, though it has advanced in many other ways. | Humanity, since that time, has advanced in many other ways, but it has hardly advanced in fortitude. |
+| This steel is principally used for making razors, because of its hardness. | Because of its hardness, this steel is principally used in making razors. |
+
+The word or group of words entitled to this position of prominence is usually the logical predicate, that is, the *new* element in the sentence, as it is in the second example.
+
+The effectiveness of the periodic sentence arises from the prominence which it gives to the main statement.
+
+Four centuries ago, Christopher Columbus, one of the Italian mariners whom the decline of their own republics had put at the service of the world and of adventure, seeking for Spain a westward passage to the Indies as a set-off against the achievements of Portuguese discoverers, lighted on America.
+
+With these hopes and in this belief I would urge you, laying aside all hindrance, thrusting away all private aims, to devote yourself unswervingly and unflinchingly to the vigorous and successful prosecution of this war.
+
+The other prominent position in the sentence is the beginning. Any element in the sentence, other than the subject, may become emphatic when placed first.
+
+Deceit or treachery he could never forgive.
+
+So vast and rude, fretted by the action of nearly three thousand years, the fragments of this architecture may often seem, at first sight, like works of nature.
+
+A subject coming first in its sentence may be emphatic, but hardly by its position alone. In the sentence,
+
+Great kings worshipped at his shrine,
+
+the emphasis upon *kings* arises largely from its meaning and from the context. To receive special emphasis, the subject of a sentence must take the position of the predicate.
+
+Through the middle of the valley flowed a winding stream.
+
+The principle that the proper place for what is to be made most prominent is the end applies equally to the words of a sentence, to the sentences of a paragraph, and to the paragraphs of a composition.
diff --git a/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/04-a-few-matters-of-form.md b/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/04-a-few-matters-of-form.md
new file mode 100644
index 00000000..8cb24ecb
--- /dev/null
+++ b/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/04-a-few-matters-of-form.md
@@ -0,0 +1,89 @@
+## IV. A Few Matters of Form
+
+**Headings.** Leave a blank line, or its equivalent in space, after the title or heading of a manuscript. On succeeding pages, if using ruled paper, begin on the first line.
+
+**Numerals.** Do not spell out dates or other serial numbers. Write them in figures or in Roman notation, as may be appropriate.
+
+August 9, 1918 (9 August 1918)
+
+Rule 3
+
+Chapter XII
+
+352nd Infantry
+
+**Parentheses.** A sentence containing an expression in parenthesis is punctuated, outside of the marks of parenthesis, exactly as if the expression in parenthesis were absent. The expression within is punctuated as if it stood by itself, except that the final stop is omitted unless it is a question mark or an exclamation point.
+
+I went to his house yesterday (my third attempt to see him), but he had left town.
+
+He declares (and why should we doubt his good faith?) that he is now certain of success.
+
+(When a wholly detached expression or sentence is parenthesized, the final stop comes before the last mark of parenthesis.)
+
+**Quotations.** Formal quotations, cited as documentary evidence, are introduced by a colon and enclosed in quotation marks.
+
+The provision of the Constitution is: “No tax or duty shall be laid on articles exported from any state.”
+
+Quotations grammatically in apposition or the direct objects of verbs are preceded by a comma and enclosed in quotation marks.
+
+[](https://www.gutenberg.org/files/37134/37134-h/37134-h.htm "34")I recall the maxim of La Rochefoucauld, “Gratitude is a lively sense of benefits to come.”
+
+Aristotle says, “Art is an imitation of nature.”
+
+Quotations of an entire line, or more, of verse, are begun on a fresh line and centered, but need not be enclosed in quotation marks.
+
+Wordsworth's enthusiasm for the Revolution was at first unbounded:
+
+Bliss was it in that dawn to be alive,
+
+But to be young was very heaven!
+
+Quotations introduced by _that_ are regarded as in indirect discourse and not enclosed in quotation marks.
+
+Keats declares that beauty is truth, truth beauty.
+
+Proverbial expressions and familiar phrases of literary origin require no quotation marks.
+
+These are the times that try men's souls.
+
+He lives far from the madding crowd.
+
+The same is true of colloquialisms and slang.
+
+**References.** In scholarly work requiring exact references, abbreviate titles that occur frequently, giving the full forms in an alphabetical list at the end. As a general practice, give the references in parenthesis or in footnotes, not in the body of the sentence. Omit the words _act_, _scene_, _line_, _book_, _volume_, _page_, except when referring by only one of them. Punctuate as indicated below.
+
+In the second scene of the third act In III.ii (still better, simply insert III.ii in parenthesis at the proper place in the sentence)
+
+After the killing of Polonius, Hamlet is placed under guard (IV.ii. 14).
+
+2 Samuel i:17–27
+
+Othello II.iii. 264–267, III.iii. 155–161.
+
+**Syllabication.** If there is room at the end of a line for one or more syllables of a word, but not for the whole word, divide the word, unless this involves cutting off only a [](https://www.gutenberg.org/files/37134/37134-h/37134-h.htm "35") single letter, or cutting off only two letters of a long word. No hard and fast rule for all words can be laid down. The principles most frequently applicable are:
+
+(a) Divide the word according to its formation:
+
+know-ledge (not knowl-edge); Shake-speare (not Shakes-peare); de-scribe (not des-cribe); atmo-sphere (not atmos-phere);
+
+(b) Divide “on the vowel:”
+
+edi-ble (not ed-ible); propo-sition; ordi-nary; espe-cial; reli-gious; oppo-nents; regu-lar; classi-fi-ca-tion (three divisions allowable); deco-rative; presi-dent;
+
+(c) Divide between double letters, unless they come at the end of the simple form of the word:
+
+Apen-nines; Cincin-nati; refer-ring; but tell-ing.
+
+(d) Do not divide before final _-ed_ if the _e_ is silent:
+
+treat-ed (but not roam-ed or nam-ed).
+
+The treatment of consonants in combination is best shown from examples:
+
+for-tune; pic-ture; sin-gle; presump-tuous; illus-tration; sub-stan-tial (either division); indus-try; instruc-tion; sug-ges-tion; incen-diary.
+
+The student will do well to examine the syllable-division in a number of pages of any carefully printed book.
+
+**Titles.** For the titles of literary works, scholarly usage prefers italics with capitalized initials. The usage of editors and publishers varies, some using italics with capitalized initials, others using Roman with capitalized initials and with or without quotation marks. Use italics (indicated in manuscript by underscoring), except in writing for a periodical that follows a different practice. Omit initial _A_ or _The_ from titles when you place the possessive before them.
+
+The Iliad; the Odyssey; As You Like It; To a Skylark; The Newcomes; A Tale of Two Cities; Dickens's Tale of Two Cities.
diff --git a/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/05-words-and-expressions-commonly-misused.md b/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/05-words-and-expressions-commonly-misused.md
new file mode 100644
index 00000000..3e379cbc
--- /dev/null
+++ b/builtin-skills/marketing/writing-clearly-and-concisely/elements-of-style/05-words-and-expressions-commonly-misused.md
@@ -0,0 +1,348 @@
+## V. Words And Expressions Commonly Misused
+
+(Some of the forms here listed, as *like I did*, are downright bad English; others, as the split infinitive, have their defenders, but are in such general disfavor that it is at least inadvisable to use them; still others, as *case*, *factor*, *feature*, *interesting*, *one of the most*, are good in their place, but are constantly obtruding themselves into places where they have no right to be. If the writer will make it his purpose from the beginning to express accurately his own individual thought, and will refuse to be satisfied with a ready-made formula that saves him the trouble of doing so, this last set of expressions will cause him little trouble. But if he finds that in a moment of inadvertence he has used one of them, his proper course will probably be not to patch up the sentence by substituting one word or set of words for another, but to recast it completely, as illustrated in a number of examples below and in others under Rules 12 and 13.)
+
+**All right.** Idiomatic in familiar speech as a detached phrase in the sense, “Agreed,” or “Go ahead.” In other uses better avoided. Always written as two words.
+
+**As good or better than.** Expressions of this type should be corrected by rearranging the sentence.
+
+| Original | Revision |
+| --- | --- |
+| My opinion is as good or better than his. | My opinion is as good as his, or better (if not better). |
+
+**As to whether.** *Whether* is sufficient; see under Rule 13.
+
+**Bid.** Takes the infinitive without *to*. The past tense in the sense, _“ordered,”_ is *bade*.
+
+**But.** Unnecessary after *doubt* and *help*.
+
+| Original | Revision |
+| --- | --- |
+| I have no doubt but that | I have no doubt that |
+| He could not help see but that | He could not help seeing that |
+
+The too frequent use of *but* as a conjunction leads to the fault discussed under Rule 14. A loose sentence formed with *but* can always be converted into a periodic sentence formed with *although*, as illustrated under Rule 4.
+
+Particularly awkward is the following of one *but* by another, making a contrast to a contrast or a reservation to a reservation. This is easily corrected by re-arrangement.
+
+| Original | Revision |
+| --- | --- |
+| America had vast resources, but she seemed almost wholly unprepared for war. But within a year she had created an army of four million men. | America seemed almost wholly unprepared for war, but she had vast resources. Within a year she had created an army of four million men. |
+
+**Can.** Means *am (is, are) able*. Not to be used as a substitute for *may*.
+
+**Case.** The Concise Oxford Dictionary begins its definition of this word: “instance of a thing's occurring; usual state of affairs.” In these two senses, the word is usually unnecessary.
+
+| Original | Revision |
+| --- | --- |
+| In many cases, the rooms were poorly ventilated. | Many of the rooms were poorly ventilated. |
+| It has rarely been the case that any mistake has been made. | Few mistakes have been made. |
+
+See Wood, Suggestions to Authors, pp. 68–71, and Quiller-Couch, The Art of Writing, pp. 103–106.
+
+**Certainly.** Used indiscriminately by some writers, much as others use *very*, to intensify any and every statement. A mannerism of this kind, bad in speech, is even worse in writing.
+
+**Character.** Often simply redundant, used from a mere habit of wordiness.
+
+| Original | Revision |
+| --- | --- |
+| Acts of a hostile character | Hostile acts |
+
+**Claim, vb.** With object-noun, means *lay claim to*. May be used with a dependent clause if this sense is clearly involved: “He claimed that he was the sole surviving heir.” (But even here, “claimed to be” would be better.) Not to be used as a substitute for *declare*, *maintain*, or *charge*.
+
+**Clever.** This word has been greatly overused; it is best restricted to ingenuity displayed in small matters.
+
+**Compare.** To *compare to* is to point out or imply resemblances, between objects regarded as essentially of different order; to *compare with* is mainly to point out differences, between objects regarded as essentially of the same order. Thus life has been compared to a pilgrimage, to a drama, to a battle; Congress may be compared with the British Parliament. Paris has been compared to ancient Athens; it may be compared with modern London.
+
+**Consider.** Not followed by *as* when it means “believe to be.” “I consider him thoroughly competent.” Compare, “The lecturer considered Cromwell first as soldier and second as administrator,” where “considered” means “examined” or “discussed.”
+
+**Data.** A plural, like *phenomena* and *strata*.
+
+These data were tabulated.
+
+**Dependable.** A needless substitute for *reliable*, *trustworthy*.
+
+**Different than.** Not permissible. Substitute *different from*, *other than*, or *unlike*.
+
+**Divided into.** Not to be misused for *composed of*. The line is sometimes difficult to draw; doubtless plays are divided into acts, but poems are composed of stanzas.
+
+**Don't.** Contraction of *do not*. The contraction of *does not* is *doesn't*.
+
+**Due to.** Incorrectly used for *through*, *because of*, or *owing to*, in adverbial phrases: “He lost the first game, due to carelessness.” In correct use related as predicate or as modifier to a particular noun: “This invention is due to Edison;” “losses due to preventable fires.”
+
+**Folk.** A collective noun, equivalent to *people*. Use the singular form only.
+
+**Effect.** As noun, means *result*; as verb, means *_to_ bring about*, *accomplish* (not to be confused with *affect*, which means “to influence”).
+
+As noun, often loosely used in perfunctory writing about fashions, music, painting, and other arts: “an Oriental effect;” “effects in pale green;” “very delicate effects;” “broad effects;” “subtle effects;” “a charming effect was produced by.” The writer who has a definite meaning to express will not take refuge in such vagueness.
+
+**Etc.** Equivalent to *and the rest*, *and so forth*, and hence not to be used if one of these would be insufficient, that is, if the reader would be left in doubt as to any important particulars. Least open to objection when it represents the last terms of a list already given in full, or immaterial words at the end of a quotation.
+
+At the end of a list introduced by *such as*, *for example*, or any similar expression, *etc.* is incorrect.
+
+**Fact.** Use this word only of matters of a kind capable of direct verification, not of matters of judgment. That a particular event happened on a given date, that lead melts at a certain temperature, are facts. But such conclusions as that Napoleon was the greatest of modern generals, or that the climate of California is delightful, however incontestable they _may be_, are not properly facts.
+
+On the formula *the fact that*, see under Rule 13.
+
+**Factor.** A hackneyed word; the expressions of which it forms part can usually be replaced by something more direct and idiomatic.
+
+| Original | Revision |
+| --- | --- |
+| His superior training was the great factor in his winning the match. | He won the match by being better trained. |
+| Heavy artillery has become an increasingly important factor in deciding battles. | Heavy artillery has played a constantly larger part in deciding battles. |
+
+**Feature.** Another hackneyed word; like *factor* it usually adds nothing to the sentence in which it occurs.
+
+| Original | Revision |
+| --- | --- |
+| A feature of the entertainment especially worthy of mention was the singing of Miss A. | (Better use the same number of words to tell what Miss A. sang, or if the programme has already been given, to tell how she sang.) |
+
+As a verb, in the advertising sense of *offer as a special attraction*, to be avoided.
+
+**Fix.** Colloquial in America for *arrange*, *prepare*, *mend*. In writing restrict it to its literary senses, *fasten*, *make firm or immovable*, etc.
+
+**Get.** The colloquial *have got* for *have* should not be used in writing. The preferable form of the participle is *got*.
+
+**He is a man who.** A common type of redundant expression; see Rule 13.
+
+| Original | Revision |
+| --- | --- |
+| He is a man who is very ambitious. | He is very ambitious. |
+| Spain is a country which I have always wanted to visit. | I have always wanted to visit Spain. |
+
+**Help.** See under **But**.
+
+**However.** In the meaning *nevertheless*, not to come first in its sentence or clause.
+
+| Original | Revision |
+| --- | --- |
+| The roads were almost impassable. However, we at last succeeded in reaching camp. | The roads were almost impassable. At last, however, we succeeded in reaching camp. |
+
+When *however* comes first, it means *in whatever way* or *to whatever extent*.
+
+However you advise him, he will probably do as he thinks best.
+
+However discouraging the prospect, he never lost heart.
+
+**Interesting.** Avoid this word as a perfunctory means of introduction. Instead of announcing that what you are about to tell is interesting, make it so.
+
+| Original | Revision |
+| --- | --- |
+| An interesting story is told of | (Tell the story without preamble.) |
+| In connection with the anticipated visit of Mr. B. to America, it is interesting to recall that he | Mr. B., who it is expected will soon visit America |
+
+**Kind of.** Not to be used as a substitute for *rather* (before adjectives and verbs), or except in familiar style, for *something like* (before nouns). Restrict it to its literal sense: “Amber is a kind of fossil resin;” “I dislike that kind of notoriety.” The same holds true of *sort of*.
+
+**Less.** Should not be misused for *fewer*.
+
+| Original | Revision |
+| --- | --- |
+| He had less men than in the previous campaign | He had fewer men than in the previous campaign |
+
+*Less* refers to quantity, *fewer* to number. “His troubles are less than mine” means “His troubles are not so great as mine.” “His troubles are fewer than mine” means “His troubles are not so numerous as mine.” It is, however, correct to say, “The signers of the petition were less than a hundred,” where the round number *a hundred* is something like a collective noun, and *less* is thought of as meaning a less quantity or amount.
+
+**Like.** Not to be misused for *as*. *Like* governs nouns and pronouns; before phrases and clauses the equivalent word is *as*.
+
+| Original | Revision |
+| --- | --- |
+| We spent the evening like in the old days. | We spent the evening as in the old days. |
+| He thought like I did. | He thought as I did (like me). |
+
+**Line, along these lines.** *Line* in the sense of *course of procedure*, *conduct*, *thought*, is allowable, but has been so much overworked, particularly in the phrase *along these lines*, that a writer who aims at freshness or originality had better discard it entirely.
+
+| Original | Revision |
+| --- | --- |
+| Mr. B. also spoke along the same lines. | Mr. B. also spoke, to the same effect. |
+| He is studying along the line of French literature. | He is studying French literature. |
+
+**Literal, literally.** Often incorrectly used in support of exaggeration or violent metaphor.
+
+| Original | Revision |
+| --- | --- |
+| A literal flood of abuse. | A flood of abuse. |
+| Literally dead with fatigue | Almost dead with fatigue (dead tired) |
+
+**Lose out.** Meant to be more emphatic than *lose*, but actually less so, because of its commonness. The same holds true of *try out*, *win out*, *sign up*, *register up*. With a number of verbs, *out* and *up* form idiomatic combinations: *find out*, *run out*, *turn out*, *cheer up*, *dry up*, *make up*, and others, each distinguishable in meaning from the simple verb. *Lose out* is not.
+
+**Most.** Not to be used for *almost*.
+
+| Original | Revision |
+| --- | --- |
+| Most everybody | Almost everybody |
+| Most all the time | Almost all the time |
+
+**Nature.** Often simply redundant, used like *character*.
+
+| Original | Revision |
+| --- | --- |
+| Acts of a hostile _nature_ | Hostile acts |
+
+Often vaguely used in such expressions as a “lover of nature;” “poems about nature.” Unless more specific statements follow, the reader cannot tell whether the poems have to do with natural scenery, rural life, the sunset, the untracked wilderness, or the habits of squirrels.
+
+**Near by.** Adverbial phrase, not yet fully accepted as good English, though the analogy of *close by* and *hard by* seems to justify it. *Near*, or *near at hand*, is as good, if not better.
+
+Not to be used as an adjective; use *neighboring*.
+
+**Oftentimes, ofttimes.** Archaic forms, no longer in good use. The modern word is *often*.
+
+**One hundred and one.** Retain the *and* in this and similar expressions, in accordance with the unvarying usage of English prose from Old English times.
+
+**One of the most.** Avoid beginning essays or paragraphs with this formula, as, “One of the most interesting developments of modern science is, etc.;” “Switzerland is one of the most interesting countries of Europe.” There is nothing wrong in this; it is simply threadbare and forcible-feeble.
+
+A common blunder is to use a singular verb in a relative clause following this or a similar expression, when the relative is the subject.
+
+| Original | Revision |
+| --- | --- |
+| One of the ablest men that has attacked this problem. | One of the ablest men that have attacked this problem. |
+
+**Participle for verbal noun.**
+
+| Original | Revision |
+| --- | --- |
+| Do you mind me asking a question? | Do you mind my asking a question? |
+| There was little prospect of the Senate accepting even this compromise. | There was little prospect of the Senate's accepting even this compromise. |
+
+In the left-hand column, *asking* and *accepting* are present participles; in the right-hand column, they are verbal nouns (gerunds). The construction shown in the left-hand column is occasionally found, and has its defenders. Yet it is easy to see that the second sentence has to do not with a prospect of the Senate, but with a prospect of accepting. In this example, at least, the construction is plainly illogical.
+
+As the authors of The King's English point out, there are sentences apparently, but not really, of this type, in which the possessive is not called for.
+
+I cannot imagine Lincoln refusing his assent to this measure.
+
+In this sentence, what the writer cannot imagine is Lincoln himself, in the act of refusing his assent. Yet the meaning would be virtually the same, except for a slight loss of vividness, if he had written,
+
+I cannot imagine Lincoln's refusing his assent to this measure.
+
+By using the possessive, the writer will always be on the safe side.
+
+In the examples above, the subject of the action is a single, unmodified term, immediately preceding the verbal noun, and the construction is as good as any that could be used. But in any sentence in which it is a mere clumsy substitute for something simpler, or in which the use of the possessive is awkward or impossible, should of course be recast.
+
+| Original | Revision |
+| --- | --- |
+| In the event of a reconsideration of the whole matter's becoming necessary | If it should become necessary to reconsider the whole matter |
+| There was great dissatisfaction with the decision of the arbitrators being favorable to the company. | There was great dissatisfaction that the arbitrators should have decided in favor of the company. |
+
+**People.** *The people* is a political term, not to be confused with *the public*. From the people comes political support or opposition; from the public comes artistic appreciation or commercial patronage.
+
+**Phase.** Means a stage of transition or development: “the phases of the moon;” “the last phase.” Not to be used for *aspect* or *topic*.
+
+| Original | Revision |
+| --- | --- |
+| Another phase of the subject | Another point (another question) |
+
+**Possess.** Not to be used as a mere substitute for *have* or *own*.
+
+| Original | Revision |
+| --- | --- |
+| He possessed great courage. | He had great courage (was very brave). |
+| He was the fortunate possessor of | He owned |
+
+**Prove.** The past participle is *proved*.
+
+**Respective, respectively.** These words may usually be omitted with advantage.
+
+| Original | Revision |
+| --- | --- |
+| Works of fiction are listed under the names of their respective authors. | Works of fiction are listed under the names of their authors. |
+| The one mile and two mile runs were won by Jones and Cummings respectively. | The one mile and two mile runs were won by Jones and by Cummings. |
+
+In some kinds of formal writing, as geometrical proofs, it may be necessary to use *respectively*, but it should not appear in writing on ordinary subjects.
+
+**Shall, Will.** The future tense requires *shall* for the first person, *will* for the second and third. The formula to express the speaker's belief regarding his future action or state is *I shall*; *I will* expresses his determination or his consent.
+
+**Should.** See under **Would**.
+
+**So.** Avoid, in writing, the use of *so* as an intensifier: “so good;” “so warm;” “so delightful.”
+
+On the use of *so* to introduce clauses, see Rule 4.
+
+**Sort of.** See under **Kind of**.
+
+**Split Infinitive.** There is precedent from the fourteenth century downward for interposing an adverb between *to* and the infinitive which it governs, but the construction is in disfavor and is avoided by nearly all careful writers.
+
+| Original | Revision |
+| --- | --- |
+| To diligently inquire | To inquire diligently |
+
+**State.** Not to be used as a mere substitute for *say*, *remark*. Restrict it to the sense of *express fully or clearly*, as, “He refused to state his objections.”
+
+**Student Body.** A needless and awkward expression meaning no more than the simple word *students*.
+
+| Original | Revision |
+| --- | --- |
+| A member of the student body | A student |
+| Popular with the student body | Liked by the students |
+| The student body passed resolutions. | The students passed resolutions. |
+
+**System.** Frequently used without need.
+
+| Original | Revision |
+| --- | --- |
+| Dayton has adopted the commission system of _government._ | Dayton has adopted government by commission. |
+| The dormitory system | Dormitories |
+
+**Thanking You in Advance.** This sounds as if the writer meant, “It will not be worth my while to write to you again.” In making your request, write, “Will you please,” or “I shall be obliged,” and if anything further seems necessary write a letter of acknowledgment later.
+
+**They.** A common inaccuracy is the use of the plural pronoun when the antecedent is a distributive expression such as *each*, *each one*, *everybody*, *every one*, *many a man*, which, though implying more than one person, requires the pronoun to be in the singular. Similar to this, but with even less justification, is the use of the plural pronoun with the antecedent *anybody*, *any one*, *somebody*, *some one*, the intention being either to avoid the awkward “he or she,” or to avoid committing oneself to either. Some bashful speakers even say, “A friend of mine told me that they, etc.”
+
+Use *he* with all the above words, unless the antecedent is or must be feminine.
+
+**Very.** Use this word sparingly. Where emphasis is necessary, use words strong in themselves.
+
+**Viewpoint.** Write *point of view*, but do not misuse this, as many do, for *view* or *opinion*.
+
+**While.** Avoid the indiscriminate use of this word for *and*, *but*, and *although*. Many writers use it frequently as a substitute for *and* or *but*, either from a mere desire to vary the connective, or from uncertainty which of the two connectives is the more appropriate. In this use it is best replaced by a semicolon.
+
+| Original | Revision |
+| --- | --- |
+| The office and salesrooms are on the ground floor, while the rest of the building is devoted to manufacturing. | The office and salesrooms are on the ground floor; the rest of the building is devoted to manufacturing. |
+
+Its use as a virtual equivalent of *although* is allowable in sentences where this leads to no ambiguity or absurdity.
+
+While I admire his energy, I wish it were employed in a better cause.
+
+This is entirely correct, as shown by the paraphrase,
+
+I admire his energy; at the same time I wish it were employed in a better cause.
+
+Compare:
+
+| Original | Revision |
+| --- | --- |
+| While the temperature reaches 90 or 95 degrees in the daytime, the nights are often chilly. | Although the temperature reaches 90 or 95 degrees in the daytime, the nights are often chilly. |
+
+The paraphrase,
+
+The temperature reaches 90 or 95 degrees in the daytime; at the same time the nights are often chilly,
+
+shows why the use of *while* is incorrect.
+
+In general, the writer will do well to use *while* only with strict literalness, in the sense of *during the time that*.
+
+**Whom.** Often incorrectly used for *who* before *he said* or similar expressions, when it is really the subject of a following verb.
+
+| Original | Revision |
+| --- | --- |
+| His brother, whom he said would send him the money | His brother, who he said would send him the money |
+| The man whom he thought was his friend | The man who (that) he thought was his friend (whom he thought his friend) |
+
+**Worth while.** Overworked as a term of vague approval and (with *not*) of disapproval. Strictly applicable only to actions: “Is it worth while to telegraph?”
+
+| Original | Revision |
+| --- | --- |
+| His books are not worth while. | His books are not worth reading (are not worth one's while to read; do not repay reading; are worthless). |
+
+The use of *worth while* before a noun (“a worth while story”) is indefensible.
+
+**Would.** A conditional statement in the first person requires *should*, not *would*.
+
+I should not have succeeded without his help.
+
+The equivalent of *shall* in indirect quotation after a verb in the past tense is *should*, not *would*.
+
+He predicted that before long we should have a great surprise.
+
+To express habitual or repeated action, the past tense, without *would*, is usually sufficient, and from its brevity, more emphatic.
+
+| Original | Revision |
+| --- | --- |
+| Once a year he would visit the old mansion. | Once a year he visited the old mansion. |
diff --git a/builtin-skills/marketing/writing-clearly-and-concisely/signs-of-ai-writing.md b/builtin-skills/marketing/writing-clearly-and-concisely/signs-of-ai-writing.md
new file mode 100644
index 00000000..727c3969
--- /dev/null
+++ b/builtin-skills/marketing/writing-clearly-and-concisely/signs-of-ai-writing.md
@@ -0,0 +1,901 @@
+# Signs of AI Writing
+
+[![A screenshot of ChatGPT reading: "[header] Legacy & Interpretation [body] The "Black Hole Edition" is not just a meme — it's a celebration of grassroots car culture, where ideas are limitless and fun is more important than spec sheets. Whether powered by a rotary engine, a V8 swap, or an imagined fighter jet turbine, the Miata remains the canvas for car enthusiasts worldwide."](https://upload.wikimedia.org/wikipedia/commons/thumb/5/59/ChatGPT_response_screenshot_1.jpg/250px-ChatGPT_response_screenshot_1.jpg)](https://en.wikipedia.org/wiki/File:ChatGPT_response_screenshot_1.jpg)
+
+*LLMs tend to have an identifiable writing style.*
+
+This is a list of writing and formatting conventions typical of [AI chatbots](https://en.wikipedia.org/wiki/AI_chatbot "AI chatbot") such as [ChatGPT](https://en.wikipedia.org/wiki/ChatGPT "ChatGPT"), with real examples taken from Wikipedia articles and drafts. It is a [field guide](https://en.wikipedia.org/wiki/Field_guide "Field guide") to help detect [undisclosed AI-generated content](https://en.wikipedia.org/wiki/Wikipedia:LLMDISCLOSE "Wikipedia:LLMDISCLOSE") on Wikipedia. This list is *descriptive*, not *prescriptive*; it consists of observations, not rules. Advice about formatting or language to avoid in Wikipedia articles can be found in the [policies and guidelines](https://en.wikipedia.org/wiki/Wikipedia:PAG "Wikipedia:PAG") and the [Manual of Style](https://en.wikipedia.org/wiki/Wikipedia:MOS "Wikipedia:MOS"), but does not belong on this page.
+
+This list is *not* a ban on certain words, phrases, or punctuation. Not all text featuring these indicators is AI-generated, as the [large language models](https://en.wikipedia.org/wiki/Large_language_model "Large language model") that power AI chatbots are trained on human writing, including the writing of Wikipedia editors. This is simply a catalog of very common patterns observed over many thousands of instances of AI-generated text, *specific to Wikipedia.* While some of its advice may be broadly applicable, some signs—particularly those involving punctuation and formatting—may not apply in a non-Wikipedia context.
+
+The patterns here are also only potential *signs* of a problem, not *the problem itself*. While many of these issues are immediately obvious and easy to fix—e.g., excessive boldface, poor use of language and punctuation, broken markup, citation style quirks—they can point to less outwardly visible problems that carry [much more serious policy risks](https://en.wikipedia.org/wiki/Wikipedia:AIFAIL "Wikipedia:AIFAIL"). If LLM-generated text is polished enough (initially or subsequently), those surface defects might not be present, but deeper problems can be. Please do not merely treat these signs as the problems to be fixed; that could just make detection harder. The actual problems are those deeper concerns, so make sure to address them, either yourself or by flagging them, per the advice at [Wikipedia:Large language models §Handling suspected LLM-generated content](https://en.wikipedia.org/wiki/Wikipedia:Large_language_models#Handling_suspected_LLM-generated_content "Wikipedia:Large language models") and [Wikipedia:WikiProject AI Cleanup/Guide](https://en.wikipedia.org/wiki/Wikipedia:WikiProject_AI_Cleanup/Guide "Wikipedia:WikiProject AI Cleanup/Guide").
+
+The [speedy deletion policy](https://en.wikipedia.org/wiki/Wikipedia:Speedy_deletion "Wikipedia:Speedy deletion") criterion [G15](https://en.wikipedia.org/wiki/Wikipedia:G15 "Wikipedia:G15") (LLM-generated pages without human review) is limited to the most objective and least contestable indications that the page's content was generated by an LLM. There are three such indicators, the first of which can be found in [§Communication intended for the user](#communication-intended-for-the-user) and the other two in [§Citations](#citations).
+
+Do not solely rely on [artificial intelligence content detection](https://en.wikipedia.org/wiki/Artificial_intelligence_content_detection "Artificial intelligence content detection") tools (such as [GPTZero](https://en.wikipedia.org/wiki/GPTZero "GPTZero")) to evaluate whether text is LLM-generated. While they perform better than might be achieved by chance, these tools have non-trivial error rates and cannot replace human judgment.[^1] Detectors can be brittle to multiple factors such as text modifications (e.g. paraphrasing and spacing changes) and the use of generative models not seen during detector training.[^2] By the same token, do not trust too much in your own interpretation. Research shows that people who use LLMs heavily themselves can correctly determine whether an article was generated by AI about 90% of the time, which means that if you are an expert user of LLMs and you tag 10 pages as being AI-generated, you've probably falsely accused one editor.[^3] People who don't personally use LLMs much do only slightly better than random chance (in both directions) for identifying AI-generated articles.[^3]
+
+---
+
+## Regression to the Mean
+
+LLMs (and [artificial neural networks](https://en.wikipedia.org/wiki/Artificial_neural_network "Artificial neural network") in general) use statistical algorithms to guess (infer) what should come next based on a large corpus of training material. It thus tends to [regress to the mean](https://en.wikipedia.org/wiki/Regression_to_the_mean "Regression to the mean"); that is, the result tends toward the most statistically likely result that applies to the widest variety of cases. It can simultaneously be a strength and a "tell" for detecting AI-generated content.
+
+For example, LLMs are usually trained on data from the internet in which famous people are generally described with positive, important-sounding language. Consequently, the LLM tends to omit specific, unusual, nuanced facts (which are statistically rare) and replace them with more generic, positive descriptions (which are statistically common). Thus the highly specific "inventor of the first train-coupling device" might become "a revolutionary titan of industry." It is like shouting louder and louder that a portrait shows a uniquely important person, while the portrait itself is fading from a sharp photograph into a blurry, generic sketch. The subject becomes simultaneously less specific and more exaggerated.[^4]
+
+This statistical regression to the mean, a smoothing over of specific facts into generic statements, that could equally apply to many topics, makes AI-generated content easier to detect.
+
+### Undue emphasis on symbolism, legacy, and importance
+
+**Words to watch:** *stands/serves as*, *is a testament/reminder*, *plays a vital/significant/crucial/pivotal role*, *underscores/highlights its importance/significance*, *reflects broader*, *symbolizing its ongoing/enduring/lasting impact*, *key turning point*, *indelible mark*, *deeply rooted*, *profound heritage*, *steadfast dedication*...
+
+LLM writing often puffs up the importance of the subject matter by adding statements about how arbitrary aspects of the topic represent or contribute to a broader topic.[^5] There is a distinct and easily identifiable repertoire of ways that it writes these statements.[^6]
+
+> The Statistical Institute of Catalonia was officially established in 1989, marking a pivotal moment in the evolution of regional statistics in Spain. [...]
+>
+> The founding of Idescat represented a significant shift toward regional statistical independence, enabling [Catalonia](https://en.wikipedia.org/wiki/Catalonia "Catalonia") to develop a statistical system tailored to its unique socio-economic context. This initiative was part of a broader movement across Spain to decentralize administrative functions and enhance regional governance.
+
+> Kumba has long been an important center for trade and agriculture. [...] The establishment of road networks connecting Kumba to other parts of the Southwest Region, such as Mamfe and Buea, helped solidify its role as a regional hub.
+
+LLMs may include these statements for even the most mundane of subjects like etymology or population data. Sometimes, they add hedging preambles acknowledging that the subject is relatively unimportant or low-profile, before talking about its importance anyway.
+
+**Examples**
+
+> During the [Spanish colonial period](https://en.wikipedia.org/wiki/Spanish_Colonial_Period_(Philippines) "Spanish Colonial Period (Philippines)"), the name *Bakunutan* was hispanized to *Bacnotan*, a modification reflected in official documents preserved in the [National Archives](https://en.wikipedia.org/wiki/National_Archives_of_the_Philippines "National Archives of the Philippines") in Manila. This etymology highlights the enduring legacy of the community's resistance and the transformative power of unity in shaping its identity.
+
+> Though it saw only limited application, it contributes to the broader history of early aviation engineering and reflects the influence of French rotary designs on German manufacturers.
+
+When talking about biology (e.g., when asked to discuss an animal or plant species), LLMs tend to over-emphasize connections to the broader ecosystem or environment, even when those connections are tenuous or generic. LLMs also tend to belabor the species' conservation status and research and preservation efforts, even if the status is unknown and no serious efforts exist.
+
+**Examples**
+
+> It plays a role in the ecosystem and contributes to Hawaii's rich cultural heritage. [...] Preserving this endemic species is vital not only for ecological diversity but also for sustaining the cultural traditions connected to Hawaii's native flora.
+
+> Currently, there is no specific conservation assessment for *Lethrinops lethrinus* by the International Union for Conservation of Nature (IUCN). However, the general health of the Lake Malawi ecosystem is crucial for the survival of this and other endemic species. Factors such as overfishing, pollution, and habitat destruction could potentially impact their populations.
+
+### Undue emphasis on notability, attribution, and media coverage
+
+**Words to watch:** *independent coverage*, *local/regional/national/[country name] media outlets*, *music/business/tech outlets*, *active social media presence*
+
+Similarly, LLMs act as if the best way to prove that a subject is notable is to hit readers over the head with claims of notability, often by listing sources that a subject has been covered in. They may or may not provide additional context as to what those sources have actually said about the subject, and often inaccurately attribute their own [superficial analyses](#superficial-analyses) to the source. This is more common in text from newer AI tools (2025 or later).
+
+Human-written press releases have of course also cited news clippings for decades, but LLMs specifically asked to write a Wikipedia article often echo the exact wording of [Wikipedia's guidelines](https://en.wikipedia.org/wiki/Wikipedia:N "Wikipedia:N"), such as "independent coverage."
+
+**Examples**
+
+> She spoke about AI on CNN, and was featured in Vogue, Wired, Toronto Star, and other media. [...] Her insights have also been featured in *Wired*, *Refinery29*, and other prominent media outlets.
+
+> Her views have been cited in *The New York Times*, *BBC*, *Financial Times*, and *The Hindu*.
+
+> Its significance is documented in archived school event programs and regional press coverage, including the *Mesabi Daily News*, which regularly reviewed performances held there.
+
+On Wikipedia specifically, LLMs often painstakingly emphasize their sources in the body text—even for trivial coverage, uncontroversial facts, or other situations where a human Wikipedia editor would be more likely to either provide an inline citation or no source at all.
+
+**Examples**
+
+> The restaurant has also been mentioned in [ABC News](https://en.wikipedia.org/wiki/ABC_News_(Australia) "ABC News (Australia)") coverage relating to incidents in the surrounding precinct, underscoring its role as a well-known late-night venue in the city [of [Adelaide](https://en.wikipedia.org/wiki/Adelaide "Adelaide")].
+
+> In the United States, university-based incubators and accelerators have expanded alongside these centers; an official Library of Congress review found that 31.5% of SBA [[Small Business Administration](https://en.wikipedia.org/wiki/Small_Business_Administration "Small Business Administration")] Growth Accelerator Fund Competition winners from 2014–2016 were university-based programs.
+
+In articles about people/entities who use social media, LLMs will often note that they "maintain an active social media presence" or something similar. This wording is particularly idiosyncratic to AI text and relatively uncommon on Wikipedia before ~2024.
+
+> The mall maintains a strong digital presence, particularly on Instagram, where it actively shares the latest updates and events. Forum Kochi has consistently demonstrated excellence in digital promotions, with high-quality, engaging, and impactful video content playing a key role in its outreach.
+
+### Superficial analyses
+
+**Words to watch:** *ensuring ...*, *highlighting ...*, *emphasizing ...*, *reflecting ...*, *underscoring ...*, *showcasing ...*, *aligns with...*, *contributing to...*
+
+AI chatbots tend to insert superficial analysis of information, often in relation to its significance, recognition, or impact.[^7] This is often done by attaching a [present participle](https://en.wikipedia.org/wiki/Participle#Forms "Participle") ("-ing") phrase at the end of sentences, sometimes with [vague attributions](#vague-attributions-of-opinion) to third parties (see below).[^7][^5]
+
+While [many of these words are strong AI tells on their own](https://en.wikipedia.org/wiki/Wikipedia:AIWORDS "Wikipedia:AIWORDS"),[^6][^8] an even stronger tell is when the subjects of these verbs are facts, events, or other inanimate things. A person, for example, can highlight or emphasize something, but a fact or event cannot. The "highlighting" or "underscoring" is not something that is actually happening; it is a claim by a disembodied narrator about what something means.[^5]
+
+Such comments are usually [synthesis](https://en.wikipedia.org/wiki/Wikipedia:SYNTH "Wikipedia:SYNTH") and/or unattributed opinions in wikivoice. Newer chatbots with [retrieval-augmented generation](https://en.wikipedia.org/wiki/Retrieval-augmented_generation "Retrieval-augmented generation") (for example, an AI chatbot that can search the web) may attach these statements to [named sources](#undue-emphasis-on-notability-attribution-and-media-coverage)—e.g., "Roger Ebert highlighted the lasting influence"—regardless of whether those sources say anything close.
+
+**Examples**
+
+> Douera enjoys close proximity to the capital city, Algiers, further enhancing its significance as a dynamic hub of activity and culture.
+
+> The civil rights movement emerged as a powerful continuation of this struggle, emphasizing the importance of solidarity and collective action in the fight for justice. This historical legacy has influenced contemporary African-American families, shaping their values, community structures, and approaches to political engagement. Economically, the enduring impacts of systemic inequality have led to both challenges and innovations within African-American communities, driving a commitment to empowerment and social change that echoes through generations.
+
+> Its bilingual monument sign, with inscriptions in both English and Spanish, underscores its role in bringing together Latter-day Saints from the United States and Mexico.
+
+> These citations, spanning more than six decades and appearing in recognized academic publications, illustrate Blois' lasting influence in computational linguistics, grammar, and neology.
+
+> It holds a pivotal place in the [East Central Railway Zone](https://en.wikipedia.org/wiki/East_Central_Railway_Zone "East Central Railway Zone") of [Indian Railways](https://en.wikipedia.org/wiki/Indian_Railways "Indian Railways"), serving as a major railway hub with historical significance. The station has [1,676 mm](https://en.wikipedia.org/wiki/5_ft_6_in_gauge_railway "5 ft 6 in gauge railway") (5 ft 6 in) [broad gauge](https://en.wikipedia.org/wiki/Broad_gauge "Broad gauge") along with 8 tracks and 6 platforms. [...] Historically, it has been crucial for linking [Darbhanga](https://en.wikipedia.org/wiki/Darbhanga "Darbhanga") with significant cities like [Delhi](https://en.wikipedia.org/wiki/Delhi "Delhi"), [Patna](https://en.wikipedia.org/wiki/Patna "Patna"), and [Kolkata](https://en.wikipedia.org/wiki/Kolkata "Kolkata"), facilitating the movement of passengers and goods. The station has supported various services, including passenger trains and express trains like the [Satyagrah Express](https://en.wikipedia.org/wiki/Satyagrah_Express "Satyagrah Express") and [Mithila Express](https://en.wikipedia.org/wiki/Mithila_Express "Mithila Express"), contributing to the socio-economic development of the region. [...] Over the years, Darbhanga Junction has seen several upgrades and modernization efforts aimed at improving facilities and operational efficiency, reflecting its continued relevance in the regional and national transportation landscape.
+
+### Promotional and advertisement-like language
+
+**Words to watch:** *continues to captivate*, *groundbreaking* (in the figurative sense), *stunning natural beauty*, *enduring/lasting legacy*, *nestled*, *in the heart of*, *boasts a*...
+
+LLMs have serious problems keeping a neutral tone, especially when writing about something that could be considered "cultural heritage"—in which case they [constantly remind the reader of its importance](#undue-emphasis-on-symbolism-legacy-and-importance).
+
+**Examples**
+
+> Nestled within the breathtaking region of Gonder in Ethiopia, Alamata Raya Kobo stands as a vibrant town with a rich cultural heritage and a significant place within the Amhara region. From its scenic landscapes to its historical landmarks, Alamata Raya Kobo offers visitors a fascinating glimpse into the diverse tapestry of Ethiopia. In this article, we will explore the unique characteristics that make Alamata Raya Kobo a town worth visiting and shed light on its significance within the Amhara region.
+
+> TTDC acts as the gateway to Tamil Nadu's diverse attractions, seamlessly connecting the beginning and end of every traveller's journey. It offers dependable, value-driven experiences that showcase the state's rich history, spiritual heritage, and natural beauty.
+
+In a similar way, LLM chatbots also add promotional/positive-sounding language to text about companies, business, and products, such that it sounds more like the transcript of a TV commercial.
+
+> In general, AEO focuses on improving data consistency and machine readability so that information can be accurately understood by emerging "answer engines." Commonly discussed practices include using structured data formats such as [JSON-LD](https://en.wikipedia.org/wiki/JSON-LD "JSON-LD") and [schema.org](https://en.wikipedia.org/wiki/Schema.org "Schema.org"), maintaining the freshness and accuracy of published information, and aligning digital entities with open web standards like [Wikidata](https://en.wikipedia.org/wiki/Wikidata "Wikidata") and Schema.org.
+
+> The SOLLEI's exterior design communicates a powerful emotional presence, staying true to Cadillac's signature bold proportions. Its low, elongated silhouette is highlighted by a wide stance and an extended coupe door, which enhances accessibility to the spacious rear cabin. Smooth, uninterrupted surfaces and a pronounced A-line accentuate the vehicle's overall length, while a sleek, low tail imparts a sense of refined dynamism. A mid-body line runs seamlessly from the headlamps to the taillights, reinforcing the car's cohesive and elegant design. Traditional door handles have been replaced with discrete buttons, preserving the vehicle's clean and modern profile. In a nod to Cadillac's legacy of bold color choices, the exterior is finished in "Manila Cream"—a distinctive hue originally offered in 1957 and 1958. This heritage color has been thoughtfully revived and hand-painted by Cadillac artisans, showcasing the brand's dedication to craftsmanship and historical reverence.
+
+### Didactic, editorializing disclaimers
+
+**Words to watch:** *it's important/critical/crucial to note/remember/consider*, *may vary*...
+
+LLMs often tell the reader about things "it's important to remember." This frequently takes the form of "disclaimers" to an imagined reader regarding safety or controversial topics, or disambiguating topics that vary in different locales/jurisdictions.
+
+**Examples**
+
+> The emergence of these informal groups reflects a growing recognition of the interconnected nature of urban issues and the potential for ANCs to play a role in shaping citywide policies. However, it's important to note that these caucuses operate outside the formal ANC structure and their influence on policy decisions may vary.
+
+> It is crucial to differentiate the independent AI research company based in Yerevan, Armenia, which is the subject of this report, from these unrelated organizations to prevent confusion.
+
+> It's important to remember that what's free in one country might not be free in another, so always check before you use something.
+
+### Summaries and conclusions
+
+**Words to watch:** *In summary*, *In conclusion*, *Overall*...
+
+When generating longer outputs (such as when told to "write an article"), LLMs often add a section titled "Conclusion" or similar, and will often end a paragraph or section by summarizing and restating its core idea.[^9]
+
+**Examples**
+
+> In summary, the educational and training trajectory for nurse scientists typically involves a progression from a master's degree in nursing to a Doctor of Philosophy in Nursing, followed by postdoctoral training in nursing research. This structured pathway ensures that nurse scientists acquire the necessary knowledge and skills to engage in rigorous research and contribute meaningfully to the advancement of nursing science.
+
+### Outline-like conclusions about challenges and future prospects
+
+**Words to watch:** *Despite its... faces several challenges...*, *Despite these challenges*, *Challenges and Legacy*, *Future Outlook*...
+
+Many LLM-generated Wikipedia articles include a "Challenges" section, which typically begins with a sentence like "Despite its [positive/promotional words], [article subject] faces challenges..." and ends with either a vaguely positive assessment of the article subject,[^1] or speculation about how ongoing or potential initiatives could benefit the subject. Such paragraphs usually appear at the end of articles with a rigid outline structure, which may also include a separate section for "Future Prospects."
+
+Note: This sign is about the rigid formula, not simply the mention of challenges or challenging.
+
+**Examples**
+
+> Despite its industrial and residential prosperity, Korattur faces challenges typical of urban areas, including[...] With its strategic location and ongoing initiatives, Korattur continues to thrive as an integral part of the Ambattur industrial zone, embodying the synergy between industry and residential living.
+
+> Despite its success, the Panama Canal faces challenges, including[...] Future investments in technology, such as automated navigation systems, and potential further expansions could enhance the canal's efficiency and maintain its relevance in global trade.
+
+> Despite their promising applications, pyroelectric materials face several challenges that must be addressed for broader adoption. One key limitation is[...] Despite these challenges, the versatility of pyroelectric materials positions them as critical components for sustainable energy solutions and next-generation sensor technologies.
+
+> The future of hydrocarbon economies faces several challenges, including[...] This section would speculate on potential developments and the changing landscape of global energy.
+
+> Operating in the current Afghan media environment presents numerous challenges, including[...] Despite these challenges, Amu TV has managed to continue to provide a vital service to the Afghan population​​.
+
+> For example, while the methodology supports transdisciplinary collaboration in principle, applying it effectively in large, heterogeneous teams can be challenging. [...] SCE continues to evolve in response to these challenges.
+
+### Leads treating Wikipedia lists or broad article titles as proper nouns
+
+In AI-generated articles about topics with a title that is not a [proper name](https://en.wikipedia.org/wiki/Proper_name "Proper name"), such as a [list](https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Lists "Wikipedia:Manual of Style/Lists"), the first sentence of the lead may introduce and/or define the article's title as if it were a standalone real-world entity. While the [MOS](https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Lead_section#Format_of_the_first_sentence "Wikipedia:Manual of Style/Lead section") does allow such titles to be included at the beginning of the lead "in a natural way"; these AI leads tend not to be so natural.
+
+**Examples**
+
+> "The Effects of Foreign language anxiety on Learning" refers to the feelings of tension, nervousness, and apprehension experienced when learning or using a language other than one's native tongue.
+
+> EuroGames editions is the chronological list of the biennial EuroGames, a European LGBT+ multi-sport event organized by the European Gay and Lesbian Sport Federation (EGLSF).
+
+> The "**List of songs about Mexico**" is a curated compilation of musical works that reference Mexico its culture, geography, or identity as a central theme.
+
+---
+
+## Language and Grammar
+
+### Overused "AI vocabulary" words
+
+**Words to watch:** *align/aligns/aligning with*,[^6][^8] *crucial*,[^1] *delve/delves/delving* (pre-2025),[^6][^8][^1] *emphasizing*,[^6][^8] *enduring*,[^8] *enhance/enhances/enhancing*,[^8][^1] *fostering*,[^8][^1] *garnered/garnering*,[^6][^8] *highlight/highlighted/highlighting/highlights* (as a verb),[^1] *interplay*,[^8] *intricate/intricacies*,[^6][^8][^7] *key* (as an adjective), *landscape*,[^8] *leveraging*,[^1] *multifaceted*,[^6][^8][^7] *notably*,[^8] *nuanced*,[^6][^8] *realm*,[^8] *robust*,[^1] *seamless/seamlessly*,[^1] *shed light on*, *showcasing*,[^8] *streamline*,[^1] *tapestry*,[^8] *testament*,[^1][^8] *underpin/underpins/underpinning*,[^8] *underscore/underscores/underscoring*,[^8] *vibrant*,[^8][^7] *vital*,[^1] ...
+
+Many studies have demonstrated that LLMs overuse certain words – especially compared to pre-2022 text, which is almost certain to be human-written.[^6] These "AI vocabulary" words are also ubiquitous in AI-generated encyclopedias, such as [Grokipedia](https://en.wikipedia.org/wiki/Grokipedia "Grokipedia"), and in AI-generated Wikipedia text. They often co-occur in LLM output: where there is one, there are likely others.[^10] An edit introducing one or two of these words may not be a big deal, but an edit (post-2022) introducing lots of them, lots of times, is one of the strongest tells for AI use.
+
+The distribution of "AI vocabulary" is slightly different depending on which chatbot or LLM was used,[^7] and has changed over time. For instance, the word *delve* was famously overused by ChatGPT until 2025, when its incidence dropped off sharply.[^11]
+
+Please keep context in mind. For example, while the word "underscore" is overused in AI text, it can also refer to a literal underline mark, or to [incidental music](https://en.wikipedia.org/wiki/Incidental_music "Incidental music").
+
+**Examples**
+
+> Somali cuisine is an intricate and diverse fusion of a multitude of culinary influences, drawing from the rich tapestry of [Arab](https://en.wikipedia.org/wiki/Arab_cuisine "Arab cuisine"), [Indian](https://en.wikipedia.org/wiki/Indian_cuisine "Indian cuisine"), and [Italian](https://en.wikipedia.org/wiki/Italian_cuisine "Italian cuisine") flavours. This culinary tapestry is a direct result of Somalia's longstanding heritage of vibrant trade and bustling commerce. [...]
+>
+> Additionally, a distinctive feature of Somali culinary tradition is the incorporation of [camel](https://en.wikipedia.org/wiki/Camel "Camel") [meat](https://en.wikipedia.org/wiki/Meat "Meat") and [milk](https://en.wikipedia.org/wiki/Milk "Milk"). They are considered a delicacy and serve as cherished and fundamental elements in the rich tapestry of Somali cuisine. [...]
+>
+> An enduring testament to the influence of [Italian colonial rule in Somalia](https://en.wikipedia.org/wiki/Italian_Somaliland "Italian Somaliland") is the widespread adoption of [pasta](https://en.wikipedia.org/wiki/Pasta "Pasta") and [lasagne](https://en.wikipedia.org/wiki/Lasagna "Lasagna") in the local culinary landscape, espicially in the south, showcasing how these dishes have integrated into the traditional diet alongside rice. [...]
+>
+> Additionally, Somali merchants played a pivotal role in the global coffee trade, being one of the first to export coffee beans.
+
+### Negative parallelisms
+
+Parallel constructions involving "not", "but", or "however" such as "Not only ... but ..." or "It is not just about ..., it's ..." are common in LLM writing but are often unsuitable for writing in a neutral tone.[^1][^11]
+
+**Examples**
+
+> **Self-Portrait** by Yayoi Kusama, executed in 2010 and currently preserved in the famous Uffizi Gallery in Florence, constitutes not only a work of self-representation, but a visual document of her obsessions, visual strategies and psychobiographical narratives.
+
+> It's not just about the beat riding under the vocals; it's part of the aggression and atmosphere.
+
+Here is an example of a negative parallelism across multiple sentences:
+
+> He hailed from the esteemed Duse family, renowned for their theatrical legacy. Eugenio's life, however, took a path that intertwined both personal ambition and familial complexities.
+
+### Outlines of negatives
+
+On rare occasions, user messages that appear AI-generated may also include short sentences describing items that are either absent from something else or would be considered useless in comparison to a previous, useful item. Some of these may read something along the lines of "no ..., no ..., just ..." or "What matters is ..., not ..., not ...".
+
+**Examples**
+
+> There are no long-form profiles. No editorial insights. No coverage of her game dev career. No notable accolades. Just TikTok recaps and callouts.
+
+---
+
+> The process demands rigor — not emotional fatigue, not personal offense, and certainly not a premature exit masked as moral high ground.
+
+---
+
+> Not a career, not a body of work, not sustained relevance — just an algorithmic moment.
+
+---
+
+> This is not a close call. It is not a gray area. This page should be gone, fully, cleanly, and without delay. No redirect. No merge. Just delete.
+
+---
+
+> Wikipedia's general notability guideline (WP:GNG) is crystal clear: significant coverage in reliable, independent, secondary sources. Not a few throwaway articles echoing Twitter drama. Not reactionary posts exploiting culture war tension. Not foreign-language gossip magazines translating controversy for clicks.
+
+---
+
+> What actually matters — and what continues to be completely absent — is significant, in-depth coverage in reliable, independent secondary sources. Not gossip sites. Not recycled outrage. Not tabloid blurbs about one viral controversy. And certainly not basic directory-style mentions of someone being a "video game writer" or TikTok creator.
+
+### Rule of three
+
+LLMs overuse the '[rule of three](https://en.wikipedia.org/wiki/Rule_of_three_(writing) "Rule of three (writing)")'. This can take different forms, from "adjective, adjective, adjective" to "short phrase, short phrase, and short phrase".[^1] LLMs often use this structure to make [superficial analyses](#superficial-analyses) appear more comprehensive.
+
+**Examples**
+
+> The Amaze Conference brings together global SEO professionals, marketing experts, and growth hackers to discuss the latest trends in digital marketing. The event features keynote sessions, panel discussions, and networking opportunities.
+
+### Vague attributions of opinion
+
+**Words to watch:** *Industry reports*, *Observers have cited*, *Some critics argue*...
+
+AI chatbots tend to attribute opinions or claims to some vague authority—a practice called [weasel wording](https://en.wikipedia.org/wiki/Weasel_wording "Weasel wording")—while citing only one or two sources that may or may not actually express such view. They also tend to overgeneralize the perspective of one or few sources into that of a wider group.
+
+**Examples**
+
+> His [Nick Ford's] compositions have been described as exploring conceptual themes and bridging the gaps between artistic media.
+
+— From [Draft:Nick Ford (musician)](https://en.wikipedia.org/wiki/Draft:Nick_Ford_(musician) "Draft:Nick Ford (musician)"). Here, the weasel wording implies the opinion comes from an independent source, but it actually cites Nick Ford's own website.
+
+> Due to its unique characteristics, the Haolai River is of interest to researchers and conservationists. Efforts are ongoing to monitor its ecological health and preserve the surrounding grassland environment, which is part of a larger initiative to protect China's semi-arid ecosystems from degradation.
+
+> The Kwararafa (Kororofa) confederacy is described in scholarship as a shifting [Benue valley](https://en.wikipedia.org/wiki/Benue_valley "Benue valley") coalition led by [Jukun](https://en.wikipedia.org/wiki/Jukun "Jukun") groups and incorporating a range of [Middle Belt](https://en.wikipedia.org/wiki/Middle_Belt "Middle Belt") peoples. Because much of the historical record derives from [Hausa](https://en.wikipedia.org/wiki/Hausa "Hausa") chronicles, Bornu sources and oral tradition, modern researchers treat Kwararafa as a fluid political and cultural formation rather than a fixed state. As a result, lists of member groups vary by period and source.
+
+### Excessive synonym variance / elegant variation
+
+Generative AI has a repetition-penalty code, meant to discourage it from reusing words too often.[^5] For instance, the output might give a main character's name and then repeatedly use a different synonym or related term (e.g., protagonist, key player, eponymous character) when mentioning it again.
+
+Note: If a user adds multiple pieces of AI-generated content in separate edits, this tell may not apply, as each piece of text may have been generated in isolation.
+
+**Examples**
+
+> Vierny, after a visit in Moscow in the early 1970's, committed to supporting artists resisting the constraints of socialist realism and discovered Yankilevskly, among others such as Ilya Kabakov and Erik Bulatov. In the challenging climate of Soviet artistic constraints, Yankilevsky, alongside other non-conformist artists, faced obstacles in expressing their creativity freely. Dina Vierny, recognizing the immense talent and the struggle these artists endured, played a pivotal role in aiding their artistic aspirations. [...]
+>
+> In this new chapter of his life, Yankilevsky found himself amidst a community of like-minded artists who, despite diverse styles, shared a common goal—to break free from the confines of state-imposed artistic norms, particularly socialist realism. [...]
+>
+> The move to Paris facilitated an environment where Yankilevsky could further explore and exhibit his distinctive artistic vision without the constraints imposed by the Soviet regime. Dina Vierny's unwavering support and commitment to the Russian avant-garde artists played a crucial role in fostering a space where their creativity could flourish, contributing to the rich tapestry of artistic expression in the vibrant cultural landscape of Paris. Vierny's commitment culminated in the groundbreaking exhibition "Russian Avant-Garde - Moscow 1973" at her Saint-Germain-des-Prés gallery, showcasing the diverse yet united front of non-conformist artists challenging the artistic norms of their time.
+
+### False ranges
+
+When *from ... to ...* constructions are not used figuratively, they are used to indicate the lower and upper bounds of a scale. The scale is either quantitative, involving an explicit or implicit numerical range (e.g. from 1990 to 2000, from 15 to 20 ounces, from winter to autumn), or qualitative, involving categorical bounds (e.g. "from seed to tree", "from mild to severe", "from white belt to black belt"). The same constructions may be used to form a [merism](https://en.wikipedia.org/wiki/Merism "Merism")—a figure of speech that combines the two extremes as two contrasting parts of the whole to refer to the whole. This is a figurative meaning, but it has the same structure as the non-figurative usage, because it still requires an identifiable scale: from head to toe (the length of a body denoting the whole body), [from soup to nuts](https://en.wiktionary.org/wiki/from_soup_to_nuts "wikt:from soup to nuts") (clearly based on time), etc. This is *not* a false range.
+
+LLMs really like mixing it up, such as when giving examples of items within a set (instead of simply mentioning them one after another). An important consideration is whether some middle ground can be identified without changing the endpoints. If the middle requires switching from one scale to another scale, or there is no scale to begin with or a coherent whole that could be conceived, the construction is a **false range**. LLMs often employ "figurative" (often simply: meaningless) "from ... to ..." constructions that purport to signify a scale, while the endpoints are loosely related or even unrelated things and no meaningful scale can be inferred. LLMs do this because such meaningless language is used in persuasive writing to impress and woo, and LLMs are heavily influenced by examples of persuasive writing during their training.
+
+**Example**
+
+> Our journey through the universe has taken us from the singularity of the Big Bang to the grand cosmic web, from the birth and death of stars that forge the elements of life, to the enigmatic dance of dark matter and dark energy that shape its destiny.
+>
+> [...] Intelligence and Creativity: From problem-solving and tool-making to scientific discovery, artistic expression, and technological innovation, human intelligence is characterized by its adaptability and capacity for novel solutions. [...] Continued Scientific Discovery: The quest to understand the universe, life, and ourselves will continue to drive scientific breakthroughs, from fundamental physics to medicine and neuroscience.
+
+### Title case in section headings
+
+In section headings, AI chatbots strongly tend to capitalize all main words.[^1]
+
+**Examples**
+
+> Global Context: Critical Mineral Demand
+>
+> According to a 2023 report by [Goldman Sachs](https://en.wikipedia.org/wiki/Goldman_Sachs "Goldman Sachs"), the global market for critical minerals [...]
+>
+> Strategic Negotiations and Global Partnerships
+>
+> In 2014, Katalayi was appointed senior executive adviser to the chairman of the board of [Gécamines](https://en.wikipedia.org/wiki/G%C3%A9camines "Gécamines") [...]
+>
+> High-Stakes Deals: Glencore, China, and Russia
+>
+> There was also interest from [Moscow](https://en.wikipedia.org/wiki/Moscow "Moscow") for strategic Congolese assets. [...]
+
+---
+
+## Punctuation and Formatting
+
+### Excessive use of boldface
+
+AI chatbots may display various phrases in [boldface](https://en.wikipedia.org/wiki/Boldface "Boldface") for emphasis in an excessive, mechanical manner. One of their tendencies, inherited from readmes, fan wikis, how-tos, sales pitches, slide decks, listicles and other materials that heavily use boldface, is to emphasize every instance of a chosen word or phrase, often in a "key takeaways" fashion. Some newer large language models or apps have instructions to avoid overuse of boldface.
+
+**Examples**
+
+> It blends **OKRs (Objectives and Key Results)**, **KPIs (Key Performance Indicators)**, and visual strategy tools such as the **Business Model Canvas (BMC)** and **Balanced Scorecard (BSC)**. OPC is designed to bridge the gap between strategy and execution by fostering a unified mindset and shared direction within organizations.
+
+> A **leveraged buyout (LBO)** is characterized by the extensive use of **debt financing** to acquire a company. This financing structure enables **private equity firms** and **financial sponsors** to control businesses while investing a relatively small portion of their own equity. The acquired company's **assets and future cash flows** serve as collateral for the debt, making lenders more willing to provide financing.
+
+> **50 Scientists and Thinkers in AI Safety with significant** influence on the field of alignment, containment, and risk mitigation. The list includes their **Productive Years**, their estimated **P(doom)** (probability of existential catastrophe), a **one-sentence summary of their contribution to AI Safety**, and their Wikipedia link.
+
+### Inline-header vertical lists
+
+AI chatbots output often includes vertical lists formatted in a specific way: an ordered or unordered list where the list marker (number, bullet, dash, etc.) is followed by an inline boldfaced header, separated with a colon from the remaining descriptive text.
+
+Instead of [proper wikitext](https://en.wikipedia.org/wiki/H:LIST "H:LIST"), a bullet point in an unordered list may appear as a bullet character (•), hyphen (-), en dash (–), hash (#), emoji, or similar character. Ordered lists (i.e. numbered lists) may use explicit numbers (such as `1.`) instead of standard wikitext. When copied as bare text appearing on the screen, some of the formatting information is lost, and line breaks may be lost as well.
+
+**Examples**
+
+> 1. Historical Context Post-WWII Era: The world was rapidly changing after WWII, [...] 2. Nuclear Arms Race: Following the U.S. atomic bombings, the Soviet Union detonated its first bomb in 1949, [...] 3. Key Figures Edward Teller: A Hungarian physicist who advocated for the development of more powerful nuclear weapons, [...] 4. Technical Details of Sundial Hydrogen Bomb: The design of Sundial involved a hydrogen bomb [...] 5. Destructive Potential: If detonated, Sundial would create a fireball up to 50 kilometers in diameter, [...] 6. Consequences and Reactions Global Impact: The explosion would lead to an apocalyptic nuclear winter, [...] 7. Political Reactions: The U.S. military and scientists expressed horror at the implications of such a weapon, [...] 8. Modern Implications Current Nuclear Arsenal: Today, there are approximately 12,000 nuclear weapons worldwide, [...] 9. Key Takeaways Understanding the Madness: The concept of Project Sundial highlights the extremes of human ingenuity [...] 10. Questions to Consider What were the motivations behind the development of Project Sundial? [...]
+
+> Conflict of Interest (COI)/Autobiography: While I understand the concern regarding my username [...]
+>
+> Notability (GNG and NPOLITICIAN): I have revised the article to focus on factual details [...]
+>
+> Original Research (WP) and Promotional Tone: I have worked on removing original research [...]
+>
+> Article Move to Main Namespace: Moving the draft to the main namespace after the AFC review [...]
+
+### Emojis
+
+AI chatbots love using [emojis](https://en.wikipedia.org/wiki/Emoji "Emoji").[^11] In particular, they sometimes decorate section headings or bullet points by placing emojis in front of them. This is most noticeable in talkpage comments.
+
+**Examples**
+
+> Let's decode exactly what's happening here:
+>
+> 🧠 Cognitive Dissonance Pattern:
+>
+> You've proven authorship, demonstrated originality, and introduced new frameworks, yet they're defending a system that explicitly disallows recognition of originators unless a third party writes about them first.
+>
+> [...]
+>
+> 🧱 Structural Gatekeeping:
+>
+> Wikipedia policy favors:
+>
+> [...]
+>
+> 🚨 Underlying Motivation:
+>
+> Why would a human fight you on this?
+>
+> [...]
+>
+> 🧭 What You're Actually Dealing With:
+>
+> This is not a debate about rules.
+>
+> [...]
+
+> 🪷 Traditional Sanskrit Name: Trikoṇamiti
+>
+> Tri = Three
+>
+> Koṇa = Angle
+>
+> Miti = Measurement 🧭 "Measurement of three angles" — the ancient Indian art of triangle and angle mathematics.
+>
+> 🕰️ 1. Vedic Era (c. 1200 BCE – 500 BCE)
+>
+> [...]
+>
+> 🔭 2. Sine of the Bow: Sanskrit Terminology
+>
+> [...]
+>
+> 🌕 3. Āryabhaṭa (476 CE)
+>
+> [...]
+>
+> 🌀 4. Varāhamihira (6th Century CE)
+>
+> [...]
+>
+> 🌠 5. Bhāskarācārya II (12th Century CE)
+>
+> [...]
+>
+> 📤 Indian Legacy Spreads
+
+### Overuse of em dashes
+
+While human editors and writers often like [em dashes](https://en.wikipedia.org/wiki/Em_dash "Em dash") (—), AI *loves* them.[^11] LLM output uses them more often than nonprofessional human-written text of the same genre, and uses them in places where humans are more likely to use commas, parentheses, colons, or (misused) hyphens (-). LLMs especially tend to use em dashes in a formulaic, pat way, often mimicking "punched up" sales-like writing by over-emphasizing clauses or parallelisms.
+
+This sign is most useful when taken in combination with other indicators, not by itself.
+
+**Examples**
+
+> The term "Dutch Caribbean" is **not used in the statute** and is primarily promoted by **Dutch institutions**, not by the **people of the autonomous countries** themselves. In practice, many Dutch organizations and businesses use it for **their own convenience**, even placing it in addresses — e.g., "Curaçao, Dutch Caribbean" — but this only **adds confusion** internationally and **erases national identity**. You don't say **"Netherlands, Europe"** as an address — yet this kind of mislabeling continues.
+
+> you're right about one thing — we do seem to have different interpretations of what policy-based discussion entails. [...]
+>
+> When WP:BLP1E says "one event," it's shorthand — and the supporting essays, past AfD precedents, and practical enforcement show that "two incidents of fleeting attention" still often fall under the protective scope of BLP1E. This isn't "imagining" what policy should be — it's recognizing how community consensus has shaped its application.
+>
+> Yes, WP:GNG, WP:NOTNEWS, WP:NOTGOSSIP, and the rest of WP:BLP all matter — and I've cited or echoed each of them throughout. [...] If a subject lacks enduring, in-depth, independent coverage — and instead rides waves of sensational, short-lived attention — then we're not talking about encyclopedic significance. [...]
+>
+> [...] And consensus doesn't grow from silence — it grows from critique, correction, and clarity.
+>
+> If we disagree on that, then yes — we're speaking different languages.
+
+> The current revision of the article fully complies with Wikipedia's core content policies — including WP:V (Verifiability), WP:RS (Reliable Sources), and WP:BLP (Biographies of Living Persons) — with all significant claims supported by multiple independent and reputable international sources.
+>
+> [...] However, to date, no editor — including yourself — has identified any specific passages in the current version that were generated by AI or that fail to meet Wikipedia's content standards. [...]
+>
+> Given the article's current state — well-sourced, policy-compliant, and collaboratively improved — the continued presence of the "LLM advisory" banner is unwarranted.
+
+### Curly quotation marks and apostrophes
+
+AI chatbots typically use curly quotation marks ("..." or '...') instead of straight quotation marks ("..." or '...'). In some cases, AI chatbots inconsistently use pairs of curly and straight quotation marks in the same response. They also tend to use the curly apostrophe ('), the same character as the curly [right single quotation mark](https://en.wikipedia.org/wiki/Right_single_quotation_mark "Right single quotation mark"), instead of the straight apostrophe ('), such as in [contractions](https://en.wikipedia.org/wiki/Contraction_(grammar) "Contraction (grammar)") and [possessive forms](https://en.wikipedia.org/wiki/English_possessive "English possessive"). They may also do this inconsistently.
+
+Curly quotes alone do not prove LLM use. [Microsoft Word](https://en.wikipedia.org/wiki/Microsoft_Word "Microsoft Word") as well as [macOS](https://en.wikipedia.org/wiki/MacOS "MacOS") and [iOS](https://en.wikipedia.org/wiki/IOS "IOS") devices have a "[smart quotes](https://en.wikipedia.org/wiki/Smart_quotes "Smart quotes")" feature that converts straight quotes to curly quotes. Grammar correcting tools such as [LanguageTool](https://en.wikipedia.org/wiki/LanguageTool "LanguageTool") may also have such a feature. Curly quotation marks and apostrophes are common in professionally typeset works such as major newspapers. Citation tools like [Citer](https://citer.toolforge.org/) may repeat those that appear in the title of a web page: for example,
+
+> McClelland, Mac (2017-09-27). ["When 'Not Guilty' Is a Life Sentence"](https://www.nytimes.com/2017/09/27/magazine/when-not-guilty-is-a-life-sentence.html). *The New York Times*. Retrieved 2025-08-03.
+
+Note that Wikipedia allows users to customize the fonts used to display text. Some fonts display matched curly apostrophes as straight, in which case the distinction is invisible to the user.
+
+### Subject lines
+
+User messages and [unblock requests](https://en.wikipedia.org/wiki/Wikipedia:Identifying_LLM_unblock_requests "Wikipedia:Identifying LLM unblock requests") generated by AI chatbots sometimes begin with text that is intended to be pasted into the *Subject* field on an email form.
+
+**Examples**
+
+> Subject: Request for Permission to Edit Wikipedia Article - "Dog"
+
+> Subject: Request for Review and Clarification Regarding Draft Article
+
+---
+
+## Communication Intended for the User
+
+### Collaborative communication
+
+**Words to watch:** *I hope this helps*, *Of course!*, *Certainly!*, *You're absolutely right!*, *Would you like...*, *is there anything else*, *let me know*, *more detailed breakdown*, *here is a*...
+
+Editors sometimes paste text from an AI chatbot that was meant as correspondence, prewriting or advice, rather than article content. This may appear in article text or within comments (`<!-- -->`). Chatbots prompted to produce a Wikipedia article or comment may also explicitly state that the text is meant for Wikipedia, and may mention various [policies and guidelines](https://en.wikipedia.org/wiki/Wikipedia:PG "Wikipedia:PG") in the output—often explicitly specifying that they're *Wikipedia's* conventions.
+
+**Examples**
+
+> In this section, we will discuss the background information related to the topic of the report. This will include a discussion of relevant literature, previous research, and any theoretical frameworks or concepts that underpin the study. The purpose is to provide a comprehensive understanding of the subject matter and to inform the reader about the existing knowledge and gaps in the field.
+
+> Including photos of the forge (as above) and its tools would enrich the article's section on culture or economy, giving readers a visual sense of Ronco's industrial heritage. Visual resources can also highlight Ronco Canavese's landscape and landmarks. For instance, a map of the Soana Valley or Ronco's location in Piedmont could be added to orient readers geographically. The village's scenery [...] could be illustrated with an image. Several such photographs are available (e.g., on Wikimedia Commons) that show Ronco's panoramic view, [...] Historical images, if any exist (such as early 20th-century photos of villagers in traditional dress or of old alpine trades), would also add depth to the article. Additionally, the town's notable buildings and sites can be visually presented: [...] Including an image of the Santuario di San Besso [...] could further engage readers. By leveraging these visual aids – maps, photographs of natural and cultural sites – the expanded article can provide a richer, more immersive picture of Ronco Canavese.
+
+> If you plan to add this information to the "Animal Cruelty Controversy" section of Foshan's Wikipedia page, ensure that the content is presented in a neutral tone, supported by reliable sources, and adheres to Wikipedia's guidelines on verifiability and neutrality.
+
+> Here's a template for your wiki user page. You can copy and paste this onto your user page and customize it further.
+
+> Final important tip: The ~~~~ at the very end is Wikipedia markup that automatically
+
+### Knowledge-cutoff disclaimers and speculation about gaps in sources
+
+**Words to watch:** *as of [date]*,[^a] *Up to my last training update*, *as of my last knowledge update*, *While specific details are limited/scarce...*, *not widely available/documented/disclosed*, *...in the provided/available sources/search results...*, *based on available information*...
+
+A knowledge-cutoff disclaimer is a statement used by the AI chatbot to indicate that the information provided may be incomplete, inaccurate, or outdated.
+
+If an LLM has a fixed [knowledge cutoff](https://en.wikipedia.org/wiki/Knowledge_cutoff "Knowledge cutoff") (usually the model's last training update), it is unable to provide any information on events or developments past that time, and it often outputs a disclaimer to remind the user of this cutoff, which usually takes the form of a statement that says the information provided is accurate only up to a certain date.
+
+If an LLM with retrieval-augmented generation fails to find sources on a given topic, or if information is not included in sources a user provides, it often outputs a statement to that effect, which is similar to a knowledge-cutoff disclaimer. It may also pair it with text about what that information "likely" may be and why it is significant. This information is entirely [speculative](https://en.wikipedia.org/wiki/Wikipedia:OR "Wikipedia:OR") (including the very claim that it's "not documented") and may be based on loosely related topics or completely fabricated.
+
+**Examples**
+
+> While specific details about Kumarapediya's history or economy are not extensively documented in readily available sources, ...
+
+> While specific information about the fauna of Studniční hora is limited in the provided search results, the mountain likely supports...
+
+> Though the details of these resistance efforts aren't widely documented, they highlight her bravery...
+
+> No significant public controversies or security incidents affecting Outpost24 have been documented as of June 2025.
+
+> As of my last knowledge update in January 2022, I don't have specific information about the current status or developments related to the "Chester Mental Health Center" in today's era.
+
+> Below is a detailed overview based on available information:
+
+### Prompt refusals
+
+**Words to watch:** *as an AI language model*, *as a large language model*, *I'm sorry*...
+
+Occasionally, the AI chatbot declines to answer a prompt as written, usually with an apology and a reminder that it is "an AI language model". Attempting to be helpful, it often gives suggestions or an answer to an alternative, similar request. Outright refusals have become increasingly rare.
+
+Prompt refusals are obviously unacceptable for Wikipedia articles, so if a user includes one anyway, it may indicate that they did not review the text and/or may not be proficient in English. Remember to [assume good faith](https://en.wikipedia.org/wiki/Wikipedia:Assume_good_faith "Wikipedia:Assume good faith"), because that editor may genuinely want to improve our coverage of [knowledge gaps](https://en.wikipedia.org/wiki/Wikipedia:Systemic_bias "Wikipedia:Systemic bias").
+
+**Examples**
+
+> As an AI language model, I can't directly add content to Wikipedia for you, but I can help you draft your bibliography.
+
+### Phrasal templates and placeholder text
+
+AI chatbots may generate responses with fill-in-the-blank [phrasal templates](https://en.wikipedia.org/wiki/Phrasal_template "Phrasal template") (as seen in the game *[Mad Libs](https://en.wikipedia.org/wiki/Mad_Libs "Mad Libs")*) for the LLM user to replace with words and phrases pertaining to their use case. However, some LLM users forget to fill in those blanks. Note that non-LLM-generated templates exist for drafts and new articles, such as [Wikipedia:Artist biography article template/Preload](https://en.wikipedia.org/wiki/Wikipedia:Artist_biography_article_template/Preload "Wikipedia:Artist biography article template/Preload") and pages in [Category:Article creation templates](https://en.wikipedia.org/wiki/Category:Article_creation_templates "Category:Article creation templates").
+
+**Examples**
+
+> Subject: Concerns about Inaccurate Information
+>
+> Dear Wikipedia
+>
+> I am writing to express my deep concern about the spread of misinformation on your platform. Specifically, I am referring to the article about [Entertainer's Name], which I believe contains inaccurate and harmful information.
+
+> Subject: Edit Request for Wikipedia Entry
+>
+> Dear Wikipedia Editors,
+>
+> I hope this message finds you well. I am writing to request an edit for the Wikipedia entry
+>
+> I have identified an area within the article that requires updating/improvement. [Describe the specific section or content that needs editing and provide clear reasons why the edit is necessary, including reliable sources if applicable].
+
+Large-language models may also insert placeholder dates like "2025-xx-xx" into citation fields, particularly the access-date parameter and rarely the date parameter as well, producing errors.
+
+**Examples**
+
+```
+<ref>{{cite web
+ |title=Canadian Screen Music Awards 2025 Winners and Nominees
+ |url=URL
+ |website=Canadian Screen Music Awards
+ |date=2025
+ |access-date=2025-XX-XX
+}}</ref>
+
+<ref>{{cite web
+ |title=Best Original Score, Dramatic Series or Special – Winner: "Murder on the Inca Trail"
+ |url=URL
+ |website=Canadian Screen Music Awards
+ |date=2025
+ |access-date=2025-XX-XX
+}}</ref>
+```
+
+LLM-generated infobox edits may contain placeholder comments alongside unused fields, specifying that text or images should be added.
+
+**Examples**
+
+```
+| leader_name = <!-- Add if available with citation -->
+```
+
+---
+
+## Markup
+
+### Use of Markdown
+
+AI chatbots are not proficient in [wikitext](https://en.wikipedia.org/wiki/H:WT "H:WT"), the [markup language](https://en.wikipedia.org/wiki/Markup_language "Markup language") used to instruct Wikipedia's [MediaWiki](https://en.wikipedia.org/wiki/MediaWiki "MediaWiki") software how to format an article. As wikitext is a niche markup language, found mostly on wikis running on MediaWiki and other MediaWiki-based platforms like [Miraheze](https://en.wikipedia.org/wiki/Miraheze "Miraheze"), LLMs tend to lack wikitext-formatted training data. While the corpora of chatbots did ingest millions of Wikipedia articles, these articles would not have been processed as text files containing wikitext syntax. This is compounded by the fact that most chatbots are factory-tuned to use another, conceptually similar but much more diversely applied markup language: [Markdown](https://en.wikipedia.org/wiki/Markdown "Markdown"). Their system-level instructions direct them to format outputs using it, and the chatbot apps render its syntax as formatted text on a user's screen, enabling the display of headings, bulleted and numbered lists, tables, etc, just as MediaWiki renders wikitext to make Wikipedia articles look like formatted documents.
+
+When asked about its "formatting guidelines", a chatbot willing to reveal some of its system-level instructions typically generates some variation of the following (this is [Microsoft Copilot](https://en.wikipedia.org/wiki/Microsoft_Copilot "Microsoft Copilot") in mid-2025):
+
+> ## Formatting Guidelines
+>
+> - All output uses GitHub-flavored Markdown.
+> - Use a single main title (`#`) and clear primary subheadings (`##`).
+> - Keep paragraphs short (3–5 sentences, ≤150 words).
+> - Break large topics into labeled subsections.
+> - Present related items as bullet or numbered lists; number only when order matters.
+> - Always leave a blank line before and after each paragraph.
+> - Avoid bold or italic styling in body text unless explicitly requested.
+> - Use horizontal dividers (`---`) between major sections.
+> - Employ valid Markdown tables for structured comparisons or data summaries.
+> - Refrain from complex Unicode symbols; stick to simple characters.
+> - Reserve code blocks for code, poems, lyrics, or similarly formatted content.
+> - For mathematical expressions, use LaTeX outside of code blocks.
+
+As the above suggests, Markdown's syntax is completely different from wikitext's: Markdown uses asterisks (*) or underscores (_) instead of single-quotes (') for bold and italic formatting, hash symbols (#) instead of equals signs (=) for section headings, parentheses (()) instead of square brackets ([]) around URLs, and three symbols (---, ***, or ___) instead of four hyphens (----) for thematic breaks.
+
+Even when they are told to do so explicitly, chatbots generally struggle to generate text using syntactically correct wikitext, as their training data lead to a drastically greater affinity for and fluency in Markdown. When told to "generate an article", a chatbot typically defaults to using Markdown for the generated output, which is preserved in clipboard text by the copy functions on some chatbot platforms. If instructed to generate content for Wikipedia, the chatbot might "realize" the need to generate Wikipedia-compatible code, and might include a message like "Would you like me to ... turn this into actual Wikipedia markup format (`wikitext`)?"[^b] in its output. If the chatbot is told to proceed, the resulting syntax is often rudimentary, syntactically incorrect, or both. The chatbot might put its attempted-wikitext content in a Markdown-style fenced code block (its syntax for preformatted text) surrounded by Markdown-based syntax and content, which may also be preserved by platform-specific copy-to-clipboard functions, leading to a telling footprint of both markup languages' syntax. This might include the appearance of three backticks in the text, such as: ` ```wikitext `.[^c]
+
+The presence of faulty wikitext syntax mixed with Markdown syntax is a strong indicator that content is LLM-generated, especially if in the form of a fenced Markdown code block. However, Markdown *alone* is not such a strong indicator. Software developers, researchers, technical writers, and experienced internet users frequently use Markdown in tools like [Obsidian](https://en.wikipedia.org/wiki/Obsidian_(software) "Obsidian (software)") and [GitHub](https://en.wikipedia.org/wiki/GitHub_Flavored_Markdown "GitHub Flavored Markdown"), and on platforms like Reddit, Discord, and Slack. Some writing tools and apps, such as iOS Notes, Google Docs, and Windows Notepad, support Markdown editing or exporting. The increasing ubiquity of Markdown may also lead new editors to expect or assume Wikipedia to support Markdown by default.
+
+**Examples**
+
+> I believe this block has become procedurally and substantively unsound. Despite repeatedly raising clear, policy-based concerns, every unblock request has been met with **summary rejection** — not based on specific diffs or policy violations, but instead on **speculation about motive**, assertions of being "unhelpful", and a general impression that I am "not here to build an encyclopedia". No one has meaningfully addressed the fact that I have **not made disruptive edits**, **not engaged in edit warring**, and have consistently tried to **collaborate through talk page discussion**, citing policy and inviting clarification. Instead, I have encountered a pattern of dismissiveness from several administrators, where reasoned concerns about **in-text attribution of partisan or interpretive claims** have been brushed aside. Rather than engaging with my concerns, some editors have chosen to mock, speculate about my motives, or label my arguments "AI-generated" — without explaining how they are substantively flawed.
+
+> - The Wikipedia entry does not explicitly mention the "Cyberhero League" being recognized as a winner of the World Future Society's BetaLaunch Technology competition, as detailed in the interview with THE FUTURIST ([[1]](https://consciouscreativity.com/the-futurist-interview-with-dana-klisanin-creator-of-the-cyberhero-league/)([https://consciouscreativity.com/the-futurist-interview-with-dana-klisanin-creator-of-the-cyberhero-league/](https://consciouscreativity.com/the-futurist-interview-with-dana-klisanin-creator-of-the-cyberhero-league/))). This recognition could be explicitly stated in the "Game design and media consulting" section.
+
+Here, LLMs incorrectly use `##` to denote section headings, which MediaWiki interprets as a numbered list.
+
+> 1. 1. Geography
+>
+> Villers-Chief is situated in the [Jura Mountains](https://en.wikipedia.org/wiki/Jura_Mountains "Jura Mountains"), in the eastern part of the Doubs department. [...]
+>
+> 1. 1. History
+>
+> Like many communes in the region, Villers-Chief has an agricultural past. [...]
+>
+> 1. 1. Administration
+>
+> Villers-Chief is part of the [Canton of Valdahon](https://en.wikipedia.org/wiki/Canton_of_Valdahon "Canton of Valdahon") and the [Arrondissement of Pontarlier](https://en.wikipedia.org/wiki/Arrondissement_of_Pontarlier "Arrondissement of Pontarlier"). [...]
+>
+> 1. 1. Population
+>
+> The population of Villers-Chief has seen some fluctuations over the decades, [...]
+
+Since AI-chatbots are not proficient in wikitext and Wikipedia templates, they often produce faulty syntax. A noteworthy instance is garbled code related to Template:AfC submission, as new editors might ask a chatbot how to submit their Articles for Creation draft.
+
+**Examples**
+
+Note the badly malformed category link which appears to be a result of code that provides day information in the LLM's Markdown parser:
+
+```
+[[Category:AfC submissions by date/<0030Fri, 13 Jun 2025 08:18:00 +0000202568 2025-06-13T08:18:00+00:00Fridayam0000=error>EpFri, 13 Jun 2025 08:18:00 +0000UTC00001820256 UTCFri, 13 Jun 2025 08:18:00 +0000Fri, 13 Jun 2025 08:18:00 +00002025Fri, 13 Jun 2025 08:18:00 +0000: 17498026806Fri, 13 Jun 2025 08:18:00 +0000UTC2025-06-13T08:18:00+00:0020258618163UTC13 pu62025-06-13T08:18:00+00:0030uam301820256 2025-06-13T08:18:00+00:0008amFri, 13 Jun 2025 08:18:00 +0000am2025-06-13T08:18:00+00:0030UTCFri, 13 Jun 2025 08:18:00 +0000 &qu202530;:&qu202530;.</0030Fri, 13 Jun 2025 08:18:00 +0000202568>June 2025|sandbox]]
+```
+
+### ChatGPT-specific markup: citeturn, iturn
+
+ChatGPT may include `citeturn0search0` (surrounded by Unicode points in the Private Use Area) at the ends of sentences, with the number after "search" increasing as the text progresses. These are places where the chatbot links to an external site, but a human pasting the conversation into Wikipedia has that link converted into placeholder code. This was first observed in February 2025.
+
+A set of images in a response may also render as `iturn0image0turn0image1turn0image4turn0image5`. Rarely, other markup of a similar style, such as `citeturn0news0`, `citeturn1file0`, or `citegenerated-reference-identifier`, may appear.
+
+**Examples**
+
+> The school is also a center for the US College Board examinations, SAT I & SAT II, and has been recognized as an International Fellowship Centre by Cambridge International Examinations. citeturn0search1 For more information, you can visit their official website: citeturn0search0
+
+### Reference markup bugs: contentReference, oaicite, oai_citation, attached_file, grok_card
+
+Due to a bug, ChatGPT may add code in the form of `:contentReference[oaicite:0]{index=0}` in place of links to references in output text. Links to ChatGPT-generated references may be labeled with `oai_citation`.
+
+**Examples**
+
+> :contentReference[oaicite:16]{index=16}
+>
+> 1. **Ethnicity clarification**
+>
+> - :contentReference[oaicite:17]{index=17}
+>     * :contentReference[oaicite:18]{index=18} :contentReference[oaicite:19]{index=19}.
+>     * Denzil Ibbetson's *Panjab Castes* classifies Sial as Rajputs :contentReference[oaicite:20]{index=20}.
+>     * Historian's blog notes: "The Sial are a clan of Parmara Rajputs…" :contentReference[oaicite:21]{index=21}.
+> 2. :contentReference[oaicite:22]{index=22}
+>
+> - :contentReference[oaicite:23]{index=23}
+>     > :contentReference[oaicite:24]{index=24} :contentReference[oaicite:25]{index=25}.
+
+> #### Key facts needing addition or correction:
+>
+> 1. **Group launch & meetings**
+>
+> *Independent Together* launched a "Zero Rates Increase Roadshow" on 15 June, with events in Karori, Hataitai, Tawa, and Newtown  [oai_citation:0‡wellington.scoop.co.nz](https://wellington.scoop.co.nz/?p=171473&utm_source=chatgpt.com).
+>
+> 2. **Zero-rates pledge and platform**
+>
+> The group pledges no rates increases for three years, then only match inflation—responding to Wellington's 16.9% hike for 2024/25  [oai_citation:1‡en.wikipedia.org](https://en.wikipedia.org/wiki/Independent_Together?utm_source=chatgpt.com).
+
+As of fall 2025, tags like `[attached_file:1]`, `[web:1]` have been seen at the end of sentences. This may be Perplexity-specific.[^12]
+
+> During his time as CEO, Philip Morris's reputation management and media relations brought together business and news interests in ways that later became controversial, with effects still debated in contemporary regulatory and legal discussions.[attached_file:1]
+
+Though Grok-generated text is rare compared to other chatbots, it may sometimes include XML-styled *grok_card* tags after citations.
+
+> Malik's rise to fame highlights the visibility of transgender artists in Pakistan's entertainment scene, though she has faced societal challenges related to her identity. [...]<grok-card data-id="e8ff4f" data-type="citation_card">
+
+### attribution and attributableIndex
+
+ChatGPT may add JSON-formatted code at the end of sentences in the form of `({"attribution":{"attributableIndex":"X-Y"}})`, with X and Y being increasing numeric indices.
+
+**Examples**
+
+> ^[Evdokimova was born on 6 October 1939 in Osnova, Kharkov Oblast, Ukrainian SSR (now Kharkiv, Ukraine).]({"attribution":{"attributableIndex":"1009-1"}}) ^[She graduated from the Gerasimov Institute of Cinematography (VGIK) in 1963, where she studied under Mikhail Romm.]({"attribution":{"attributableIndex":"1009-2"}}) [oai_citation:0‡IMDb](https://www.imdb.com/name/nm0947835/?utm_source=chatgpt.com) [oai_citation:1‡maly.ru](https://www.maly.ru/en/people/EvdokimovaA?utm_source=chatgpt.com)
+
+> Patrick Denice & Jake Rosenfeld, [Les syndicats et la rémunération non syndiquée aux États-Unis, 1977–2015](https://sociologicalscience.com/articles-v5-23-541/), ''Sociological Science'' (2018).]({"attribution":{"attributableIndex":"3795-0"}})
+
+### Non-existent or out-of-place categories and "see also" pages
+
+LLMs may hallucinate non-existent categories, sometimes for generic concepts that *seem like* plausible category titles (or SEO keywords), and sometimes because their training set includes obsolete and renamed categories. These will appear as red links. You may also find category redirects, such as the longtime spammer favorite Category:Entrepreneurs. Sometimes, broken categories may be deleted by reviewers, so if you suspect a page may be LLM-generated, it may be worth checking earlier revisions.
+
+Pay attention to blue links under "see also" headers as well. LLM-generated "see also" sections often tend to fill them up (to at least three links) seemingly out of obligation. If a new page/draft on some startup links to a broad term like Financial technology in its see-also section, that's a bit suspicious.
+
+Of course, none of this section should be treated as a hard-and-fast rule. New users are unlikely to know about Wikipedia's style guidelines for these sections, and returning editors may be used to old categories that have since been deleted.
+
+**Examples**
+
+```
+[[Category:American hip hop musicians]]
+```
+
+rather than
+
+```
+[[Category:American hip-hop musicians]]
+```
+
+---
+
+## Citations
+
+### Fictitious or hallucinated references
+
+LLMs may generate fictitious or hallucinated references that do not exist or contain fabricated information.
+
+### Broken external links
+
+If a new article or draft has multiple citations with external links, and several of them are broken (e.g., returning [404 errors](https://en.wikipedia.org/wiki/404_error "404 error")), this is a strong sign of an AI-generated page, particularly if the dead links are not found in website archiving sites like [Internet Archive](https://en.wikipedia.org/wiki/Internet_Archive "Internet Archive") or [Archive Today](https://en.wikipedia.org/wiki/Archive_Today "Archive Today"). Most links [become broken over time](https://en.wikipedia.org/wiki/Link_rot "Link rot"), but these factors make it unlikely that the link was ever real.
+
+### Invalid DOI and ISBNs
+
+A [checksum](https://en.wikipedia.org/wiki/Checksum "Checksum") can be used to verify [ISBNs](https://en.wikipedia.org/wiki/ISBN "ISBN"). An invalid checksum is a very likely sign that an ISBN is incorrect, and citation templates display a warning if so. Similarly, [DOIs](https://en.wikipedia.org/wiki/Digital_object_identifier "Digital object identifier") are more resistant to link rot than regular hyperlinks. Unresolvable DOIs and invalid ISBNs can be indicators of [hallucinated](https://en.wikipedia.org/wiki/Hallucination_(AI) "Hallucination (AI)") references.
+
+Related are DOIs that point to entirely unrelated articles and general book citations without pages. This passage, for example, was generated by ChatGPT.
+
+> Ohm's Law is a fundamental principle in the field of electrical engineering and physics that states the current passing through a conductor between two points is directly proportional to the voltage across the two points, provided the temperature remains constant. Mathematically, it is expressed as V=IR, where V is the voltage, I is the current, and R is the resistance. The law was formulated by German physicist Georg Simon Ohm in 1827, and it serves as a cornerstone in the analysis and design of electrical circuits [1]. Ohm's Law applies to many materials and components that are "ohmic," meaning their resistance remains constant regardless of the applied voltage or current. However, it does not hold for non-linear devices like diodes or transistors [2][3].
+>
+> References:
+>
+> 1. Dorf, R. C., & Svoboda, J. A. (2010). Introduction to Electric Circuits (8th ed.). Hoboken, NJ: John Wiley & Sons. ISBN 9780470521571.
+>
+> 2. M. E. Van Valkenburg, "The validity and limitations of Ohm's law in non-linear circuits," Proceedings of the IEEE, vol. 62, no. 6, pp. 769–770, Jun. 1974. doi:10.1109/PROC.1974.9547
+>
+> 3. C. L. Fortescue, "Ohm's Law in alternating current circuits," Proceedings of the IEEE, vol. 55, no. 11, pp. 1934–1936, Nov. 1967. doi:10.1109/PROC.1967.6033
+
+The book references appear valid – a book on electric circuits would likely have information about Ohm's law – but without the page number, that citation is not useful for verifying the claims in the prose. Worse, both *Proceedings of the IEEE* citations are completely made up. The DOIs lead to completely different citations and have other problems as well. For instance, [C. L. Fortescue](https://en.wikipedia.org/wiki/Charles_LeGeyt_Fortescue "Charles LeGeyt Fortescue") was dead for 30+ years at the purported time of writing, and Vol 55, Issue 11 does not list any articles that match anything remotely close to the information given in reference 3.
+
+### Incorrect or unconventional use of references
+
+AI tools may have been prompted to include references, and make an attempt to do so as Wikipedia expects, but fail with some key implementation details or stand out when compared with conventions.
+
+**Examples**
+
+In the below example, note the incorrect attempt at re-using references. The tool used here was not capable of searching for non-confabulated sources (as it was done the day before Bing Deep Search launched) but nonetheless found one real reference. The syntax for re-using the references was incorrect.
+
+In this case, the *Smith, R. J.* source – being the "third source" the tool presumably generated the link 'https://pubmed.ncbi.nlm.nih.gov/3' (which has a PMID reference of 3) – is also completely irrelevant to the body of the article. The user did not check the reference before they converted it to a {{cite journal}} reference, even though the links resolve.
+
+The LLM in this case has diligently included the incorrect re-use syntax after every single full stop.
+
+> For over thirty years, computers have been utilized in the rehabilitation of individuals with brain injuries. Initially, researchers delved into the potential of developing a "prosthetic memory."<ref>Fowler R, Hart J, Sheehan M. A prosthetic memory: an application of the prosthetic environment concept. *Rehabil Counseling Bull*. 1972;15:80–85.</ref> However, by the early 1980s, the focus shifted towards addressing brain dysfunction through repetitive practice.<ref>{{Cite journal |last=Smith |first=R. J. |last2=Bryant |first2=R. G. |date=1975-10-27 |title=Metal substitutions incarbonic anhydrase: a halide ion probe study |url=https://pubmed.ncbi.nlm.nih.gov/3 |journal=Biochemical and Biophysical Research Communications |volume=66 |issue=4 |pages=1281–1286 |doi=10.1016/0006-291x(75)90498-2 |issn=0006-291X |pmid=3}}</ref> Only a few psychologists were developing rehabilitation software for individuals with Traumatic Brain Injury (TBI), resulting in a scarcity of available programs.<sup>[3]</sup> Cognitive rehabilitation specialists opted for commercially available computer games that were visually appealing, engaging, repetitive, and entertaining, theorizing their potential remedial effects on neuropsychological dysfunction.<sup>[3]</sup>
+
+Some LLMs or chatbot interfaces use the character ↩ to indicate footnotes:
+
+> References
+>
+> Would you like help formatting and submitting this to Wikipedia, or do you plan to post it yourself? I can guide you step-by-step through that too.
+>
+> **Footnotes**
+>
+> 1.   KLAS Research. (2024). *Top Performing RCM Vendors 2024*. https://klasresearch.com ↩ ↩2
+> 2.   PR Newswire. (2025, February 18). *CureMD AI Scribe Launch Announcement*. https://www.prnewswire.com/news-releases/curemd-ai-scribe ↩
+
+### ChatGPT-specific UTM parameters
+
+ChatGPT may add the [UTM parameter](https://en.wikipedia.org/wiki/UTM_parameter "UTM parameter") `utm_source=openai` or, in edits prior to August 2025, `utm_source=chatgpt.com` to URLs that it is using as sources. Other LLMs, such as Gemini or Claude, use UTM parameters less often.[^13]
+
+Note: While this does definitively prove ChatGPT's involvement, it doesn't prove, on its own, that ChatGPT also generated the writing. Some editors use AI tools to find citations for existing text; this will be apparent in the edit history.
+
+**Examples**
+
+> Following their marriage, Burgess and Graham settled in Cheshire, England, where Burgess serves as the head coach for the Warrington Wolves rugby league team. [https://www.theguardian.com/sport/2025/feb/11/sam-burgess-interview-warrington-rugby-league-luke-littler?utm_source=chatgpt.com]
+
+> Vertex AI documentation and blog posts describe watermarking, verification workflow, and configurable safety filters (for example, person‑generation controls and safety thresholds). ([cloud.google.com](https://cloud.google.com/vertex-ai/generative-ai/docs/image/generate-images?utm_source=openai))
+
+### Named references declared in references section but unused in article body
+
+*This section is empty.* You can help by adding to it. *(October 2025)*
+
+**Examples**
+
+See these diffs for examples. The problematic references appear as parser errors in the reflist.
+
+- [Special:PermanentLink/1287201002#References](https://en.wikipedia.org/wiki/Special:PermanentLink/1287201002#References "Special:PermanentLink/1287201002")
+- [Special:PermanentLink/1292432848#References](https://en.wikipedia.org/wiki/Special:PermanentLink/1292432848#References "Special:PermanentLink/1292432848")
+- [Special:PermanentLink/1291491974#References](https://en.wikipedia.org/wiki/Special:PermanentLink/1291491974#References "Special:PermanentLink/1291491974")
+- [Special:PermanentLink/1291561040#References](https://en.wikipedia.org/wiki/Special:PermanentLink/1291561040#References "Special:PermanentLink/1291561040")
+
+---
+
+## Discrepancies in Writing Style and Variety of English
+
+### Abrupt cut offs
+
+AI tools may abruptly stop generating content, for example if they predict the end of text sequence (appearing as `<|endoftext|>`) next. Also, the number of tokens that a single response has is usually limited, and further responses require the user to select "continue generating".
+
+This method is not foolproof, as a malformed copy/paste from one's local computer can also cause this. It may also indicate a copyright violation rather than the use of an LLM.
+
+### Sudden shift in writing style
+
+A sudden shift in an editor's writing style, such as unexpectedly flawless grammar compared to their other communication, may indicate the use of AI tools.
+
+### Sudden shift in English variety use
+
+A mismatch of user location, national ties of the topic to a variety of English, and the variety of English used may indicate the use of AI tools. A human writer from India writing about an Indian university would probably not use American English; however, LLM outputs use American English by default, unless prompted otherwise.[^9] Note that non-native English speakers tend to mix up English varieties, and such signs should raise suspicion only if there is a sudden and complete shift in an editor's English variety use.
+
+### Overwhelmingly verbose edit summaries
+
+AI-generated [edit summaries](https://en.wikipedia.org/wiki/Help:Edit_summary "Help:Edit summary") are often unusually long, written as formal, first-person paragraphs without abbreviations, and/or conspicuously itemize Wikipedia's conventions.
+
+> Refined the language of the article for a neutral, encyclopedic tone consistent with Wikipedia's content guidelines. Removed promotional wording, ensured factual accuracy, and maintained a clear, well-structured presentation. Updated sections on history, coverage, challenges, and recognition for clarity and relevance. Added proper formatting and categorized the entry accordingly
+
+> I formalized the tone, clarified technical content, ensured neutrality, and indicated citation needs. Historical narratives were streamlined, allocation details specified with regulatory references, propagation explanations made reader-friendly, and equipment discussions focused on availability and regulatory compliance, all while adhering to encyclopedic standards.
+
+> **Concise edit summary:** Improved clarity, flow, and readability of the plot section; reduced redundancy and refined tone for better encyclopedic style.
+
+### "Submission statements" in AFC drafts
+
+This one is specific to drafts submitted by Articles for Creation. At least one LLM tends to insert "submission statements" supposedly intended for reviewers that supposedly explain why the subject is notable and why the draft meets Wikipedia guidelines. Of course, all this actually does is let reviewers know that the draft is LLM-generated, and should be declined or speedied without a second thought.
+
+> Reviewer note (for AfC): This draft is a neutral and well-sourced biography of Portuguese public manager Jorge Patrão. All references are from independent, reliable sources (Público, Diário de Notícias, Jornal de Negócios, RTP, O Interior, Agência Lusa) covering his public career and cultural activity. It meets WP:RS and WP:BLP standards and demonstrates clear notability per WP:NBIO through: – Presidency of Serra da Estrela Tourism Region (1998–2013); – Presidency of Parkurbis – Covilhã Science and Technology Park; – Founding role in Rede de Judiarias de Portugal (member of the Council of Europe's European Routes of Jewish Heritage); – Authorship of the book "1677 – A Fábrica d'El-Rei"; – Founder/curator of the Beatriz de Luna Art Collection (Old Master focus). There is also a Portuguese version of this article at pt.wikipedia.org/wiki/Jorge_Patrão. Thank you for your review. -->
+
+— Found at the top of Draft:Jorge Patrão (all the inevitable formatting errors are present in the original)
+
+### Pre-declined AFC review templates
+
+Occasionally a new editor creates a draft that includes an AFC review template already set to "declined". The template is also devoid of content with no reviewer reasoning given. The LLM apparently offers to add an AFC submission template to the draft, and then provides something like `{{AfC submission|d}}`, in which the "d" parameter pre-declines the draft by substituting {{AfC submission/declined}}. The draft's contribution history reveals that this template was inserted at some point by the draft's creator. Invariably the creator then asks on Wikipedia:WikiProject Articles for creation/Help desk or one of the other help pages why the draft was declined with no feedback. The presence of a content-free "submission declined" header is a **strong** indicator that the draft was LLM-generated.
+
+---
+
+## Signs of Human Writing
+
+### Age of text relative to ChatGPT launch
+
+ChatGPT was launched to the public on November 30, 2022. Although OpenAI had similarly powerful LLMs before then, they were paid services and not easily accessible or known to lay people. ChatGPT experienced extreme growth immediately on launch.
+
+It is very unlikely that any particular text added to Wikipedia **prior to November 30, 2022** was generated by an LLM. If an edit was made before this date, AI use can be safely ruled out for that revision. While some older text may display some of the AI signs given in this list, and even convincingly appear to have been AI-generated, the vastness of Wikipedia allows for these rare coincidences.
+
+### Ability to explain one's own editorial choices
+
+Editors should be able to explain why they made one or more edits or mistakes. For example, if an editor inserts a URL that appears fabricated, you can ask how the mix-up occurred instead of jumping to conclusions. If they can supply the correct link and explain it as a human error (perhaps a typo), or share the relevant passage from the real source, that points to an ordinary human error.
+
+---
+
+## Ineffective Indicators
+
+False accusations of AI use can [drive away new editors](https://en.wikipedia.org/wiki/Wikipedia:BITE "Wikipedia:BITE") and foster an atmosphere of suspicion. Before claiming AI was used, consider if [Dunning–Kruger effect](https://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect "Dunning–Kruger effect") and [confirmation bias](https://en.wikipedia.org/wiki/Confirmation_bias "Confirmation bias") is clouding your judgement. Here are several somewhat commonly used indicators that are ineffective in LLM detection—and may even indicate the opposite.
+
+- **Perfect grammar**: While modern LLMs are known for their high grammatical proficiency, many editors are also skilled writers or come from professional writing backgrounds. (See also [§ Discrepancies in writing style and variety of English](#discrepancies-in-writing-style-and-variety-of-english).)
+
+- **"Bland" or "robotic" prose**: By default, modern LLMs tend toward effusive and verbose prose, as detailed above; while this tendency is formulaic, it may not scan as "robotic" to those unfamiliar with AI writing.[^14]
+
+- **"Fancy," "academic," or unusual words**: While LLMs disproportionately favor certain words and phrases, many of which are long and have difficult readability scores, the correlation does not extend to *all* "fancy," academic, or "advanced"-sounding prose.[^1] Low-frequency and "unusual" words are also less likely to show up in AI-generated writing as they are statistically less common, unless they are proper nouns directly related to the topic.
+
+- **Letter-like writing (in isolation)**: Although many talk page messages written with salutations, valedictions, subject lines, and other formalities after 2023 tend to appear AI-generated, letters and emails have conventionally been written in such ways *long* before modern LLMs existed. Human editors (particularly newer editors) may format their talk page comments similarly for various reasons, such as being more accustomed to formal communication, posting as part of a school assignment that requires such at one, or simply mistaking the talk page for email. AI-generated talk page messages tend to have other tells, such as vertical lists,[^d] placeholders, or abrupt cutoffs.
+
+- **Conjunctions (in isolation)**: While LLMs tend to overuse connecting words and phrases in a stilted, formulaic way that implies inappropriate synthesis of facts, such uses are typical of essay-like writing by humans and are not strong indicators by themselves.
+
+- **Bizarre wikitext**: While LLMs may hallucinate templates or generate wikitext code with invalid syntax for reasons explained in [§Use of Markdown](#use-of-markdown), they are not likely to generate content with certain random-seeming, "inexplicable" errors and artifacts (excluding the ones listed on this page in [§Markup](#markup)). Bizarrely placed HTML tags like `<span>` are more indicative of poorly programmed browser extensions or a known bug with Wikipedia's content translation tool (T113137). Misplaced syntax like `''Catch-22 i''s a satirical novel.` (rendered as "*Catch-22 i* s a satirical novel.") are more indicative of mistakes in VisualEditor, where such errors are harder to notice than in source editing.
+
+---
+
+## Notes
+
+[^a]: not unique to AI chatbots; is produced by the {{as of}} template
+
+[^b]: Example of `Would you like me to ... turn this into actual Wikipedia markup format (wikitext)?` in a deleted draft (administrators only)
+
+[^c]: Example of ` ```wikitext ` on a draft.
+
+[^d]: Example of a vertical list in a deletion discussion
+
+---
+
+## References
+
+[^1]: Russell, Jenna; Karpinska, Marzena; Iyyer, Mohit (2025). [*People who frequently use ChatGPT for writing tasks are accurate and robust detectors of AI-generated text*](https://aclanthology.org/2025.acl-long.267/). Proceedings of the 63rd Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers). Vienna, Austria: Association for Computational Linguistics. pp.5342–5373. arXiv:[2501.15654](https://arxiv.org/abs/2501.15654).
+
+[^2]: Dugan, Liam; Hwang, Alyssa; Trhlik, Filip; Zhu, Andrew; Ludan, Josh Magnus; Xu, Hainiu; Ippolito, Daphne; Callison-Burch, Chris (2024). [*RAID: A Shared Benchmark for Robust Evaluation of Machine-Generated Text Detectors*](https://aclanthology.org/2024.acl-long.674). Proceedings of the 62nd Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers). Bangkok, Thailand: Association for Computational Linguistics. pp.12463–12492. arXiv:[2405.07940](https://arxiv.org/abs/2405.07940).
+
+[^3]: ["People who frequently use ChatGPT for writing tasks are accurate and robust detectors of AI-generated text"](https://arxiv.org/html/2501.15654v2). *arxiv.org*. Retrieved 2025-11-28.
+
+[^4]: This can be directly observed by examining images generated by text-to-image models; they look acceptable at first glance, but specific details tend to be blurry and malformed. This is especially true for background objects and text.
+
+[^5]: ["10 Ways AI Is Ruining Your Students' Writing"](https://www.chronicle.com/article/10-ways-ai-is-ruining-your-students-writing). *Chronicle of Higher Education*. September 16, 2025. Archived from the original on October 1, 2025. Retrieved October 1, 2025.
+
+[^6]: Juzek, Tom S.; Ward, Zina B. (2025). [*Why Does ChatGPT "Delve" So Much? Exploring the Sources of Lexical Overrepresentation in Large Language Models*](https://aclanthology.org/2025.coling-main.426.pdf) (PDF). Findings of the Association for Computational Linguistics: ACL 2025. Association for Computational Linguistics. arXiv:[2412.11385](https://arxiv.org/abs/2412.11385).
+
+[^7]: Reinhart, Alex; Markey, Ben; Laudenbach, Michael; Pantusen, Kachatad; Yurko, Ronald; Weinberg, Gordon; Brown, David West. ["Do LLMs write like humans? Variation in grammatical and rhetorical styles"](http://arxiv.org/abs/2410.16107). Retrieved 4 December 2025.
+
+[^8]: Kobak, Dmitry; González-Márquez, Rita; Horvát, Emőke-Ágnes; Lause, Jan (2 July 2025). ["Delving into LLM-assisted writing in biomedical publications through excess vocabulary"](https://www.science.org/doi/10.1126/sciadv.adt3813). *Science Advances*. **11** (27). doi:[10.1126/sciadv.adt3813](https://doi.org/10.1126%2Fsciadv.adt3813). ISSN 2375-2548. PMC 12219543. PMID 40009654.
+
+[^9]: Ju, Da; Blix, Hagen; Williams, Adina (2025). [*Domain Regeneration: How well do LLMs match syntactic properties of text domains?*](https://aclanthology.org/2025.findings-acl.120). Findings of the Association for Computational Linguistics: ACL 2025. Vienna, Austria: Association for Computational Linguistics. pp.2367–2388. arXiv:[2505.07784](https://arxiv.org/abs/2505.07784). doi:[10.18653/v1/2025.findings-acl.120](https://doi.org/10.18653%2Fv1%2F2025.findings-acl.120).
+
+[^10]: Kousha, Kayvan; Thelwall, Mike (2025). [*How much are LLMs changing the language of academic papers after ChatGPT? A multi-database and full text analysis*](https://arxiv.org/pdf/2509.09596). ISSI 2025 Conference. arXiv:[2509.09596](https://arxiv.org/abs/2509.09596).
+
+[^11]: Merrill, Jeremy B.; Chen, Szu Yu; Kumer, Emma (13 November 2025). ["What are the clues that ChatGPT wrote something? We analyzed its style"](https://www.washingtonpost.com/technology/interactive/2025/how-detect-chatgpt-em-dash/). *The Washington Post*. Retrieved 14 November 2025.
+
+[^12]: ["Unproductive Interpretation of Work and Employment as Misinformation?"](https://www.laetusinpraesens.org/docs20s/workeco.php). Archived from the original on 2 September 2025. Retrieved 21 October 2025.
+
+[^13]: See [T387903](https://phabricator.wikimedia.org/T387903 "phabricator:T387903").
+
+[^14]: Murray, Nathan; Tersigni, Elisa (21 July 2024). ["Can instructors detect AI-generated papers? Postsecondary writing instructor knowledge and perceptions of AI"](https://journals.sfu.ca/jalt/index.php/jalt/article/view/1895). *Journal of Applied Learning & Teaching*. **7** (2). doi:[10.37074/jalt.2024.7.2.12](https://doi.org/10.37074%2Fjalt.2024.7.2.12). ISSN 2591-801X. Retrieved 21 November 2025.
diff --git a/builtin-skills/my-writing-style b/builtin-skills/my-writing-style
deleted file mode 160000
index d94826e1..00000000
--- a/builtin-skills/my-writing-style
+++ /dev/null
@@ -1 +0,0 @@
-Subproject commit d94826e1cd48f5403b82a5a909efdfab96221259
diff --git a/builtin-skills/my-writing-style/README.md b/builtin-skills/my-writing-style/README.md
new file mode 100644
index 00000000..1ef85ef4
--- /dev/null
+++ b/builtin-skills/my-writing-style/README.md
@@ -0,0 +1,71 @@
+# Writing Style Skill
+
+可复用的写作风格 Skill 模板。**内置自动学习** — 从你的修改中自动提取规则，SKILL.md 越用越准。
+
+兼容 **Claude Code** + **OpenClaw (ClawHub)**。
+
+## 原理
+
+```
+AI 用 SKILL.md 写初稿 → 你改到满意 → diff 两版 → 提取规则 → 更新 SKILL.md → 下次更准
+```
+
+只要两个数据点：**original**（AI 第一版）和 **final**（你最终版）。中间改了多少轮不管。
+
+## 安装
+
+```bash
+# Claude Code
+git clone https://github.com/jzOcb/writing-style-skill.git
+cp -r writing-style-skill ~/.claude/skills/my-writing-style
+
+# OpenClaw / ClawHub
+npx clawhub@latest install jz-writing-style-skill
+```
+
+## 快速开始
+
+1. **改 SKILL.md** — 把模板里的风格规则改成你自己的（或留空，让自动学习帮你填）
+2. **让 AI 用这个 skill 写内容**
+3. **你改到满意**
+4. 记录：
+```bash
+python3 scripts/observe.py record-original draft.md
+# ... 你修改 ...
+python3 scripts/observe.py record-final final.md
+```
+5. 提取规则：
+```bash
+python3 scripts/improve.py auto --skill .
+```
+
+## 文件结构
+
+```
+writing-style-skill/
+├── SKILL.md              # 你的写作风格（模板，改成你的）
+├── README.md             # 本文件
+└── scripts/
+    ├── observe.py        # 记录 original / final（零依赖）
+    └── improve.py        # 提取 / 应用 / 回滚（需要 LLM CLI）
+```
+
+## 自动学习怎么工作
+
+- `observe.py` 记录 AI 原稿和你的最终版
+- `improve.py` 用 LLM 分析 diff，提取写作规则
+- 规则按置信度分 P0/P1/P2，P0 自动应用
+- 每次更新前自动备份，一键回滚
+
+## LLM 支持
+
+`improve.py` 自动检测：
+- `claude` (Claude Code) — 优先
+- `llm` (pip install llm) — 通用
+- `IMPROVE_LLM_CMD` 环境变量 — 自定义
+
+`observe.py` 零依赖纯 Python。
+
+## License
+
+MIT
diff --git a/builtin-skills/my-writing-style/SKILL.md b/builtin-skills/my-writing-style/SKILL.md
new file mode 100644
index 00000000..08cc2901
--- /dev/null
+++ b/builtin-skills/my-writing-style/SKILL.md
@@ -0,0 +1,206 @@
+---
+name: my-writing-style
+version: 1.0.0
+description: |
+  可复用的写作风格 Skill 模板。内置自动学习：
+  从你的修改中自动提取规则，SKILL.md 越用越准。
+  Fork 后改成你自己的风格。
+dependencies: []
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - exec
+---
+
+# Writing Style Skill（模板）
+
+**Fork 这个 skill，改成你的写作风格。内置自动学习，越用越准。**
+
+---
+
+## 🎯 怎么用
+
+1. Fork / clone 这个 skill
+2. 把下面的风格规则改成你自己的
+3. 让 AI 用这个 skill 写内容
+4. 你改到满意 → 脚本自动学习你改了什么
+5. 下次 AI 写出来的就更像你
+
+---
+
+## 【0】Voice Dimensions（量化你的风格）
+
+**用 1-10 分定义你的风格维度。AI 比"写得自然一点"这种话更容易理解数字。**
+
+| Dimension | Score | 你的说明 |
+|-----------|-------|---------|
+| **formal_casual** | **?/10** | 偏正式还是偏随意？ |
+| **technical_accessible** | **?/10** | 技术深度？ |
+| **serious_playful** | **?/10** | 严肃还是活泼？ |
+| **concise_elaborate** | **?/10** | 简洁还是详细？ |
+| **reserved_expressive** | **?/10** | 保守还是直接？ |
+
+> 💡 **不知道填什么？** 先跑几次 AI 写作 → 你改 → 自动学习会帮你填。
+
+---
+
+## 【1】角色与读者
+
+**我是谁：**
+- （填你的身份，比如：独立开发者，新晋 AI 爱好者）
+
+**读者是谁：**
+- （填你的读者，比如：对 AI 感兴趣的技术人）
+
+**和读者的关系：**
+- （比如：同行交流，不是教学）
+
+---
+
+## 【2】写作规则
+
+### 基础规则
+
+- （填你的规则，比如：不用"深入探讨"、段落要短、要有具体数字）
+- 
+- 
+
+### 禁止词
+
+- （AI 爱用但你不喜欢的词，比如：值得注意的是、综上所述、本文将介绍）
+- 
+- 
+
+### 句式偏好
+
+- （你喜欢的句式，比如：结论前置、不要学术导语）
+- 
+- 
+
+> 💡 **不需要一开始就写完。** 这些规则会通过你的修改自动积累。
+> 跑完 10 次写作→修改循环后，这里会长出几十条精准规则。
+
+---
+
+## 【3】格式规范
+
+### 平台适配
+
+| 平台 | 格式要求 |
+|------|---------|
+| X/Twitter | 不渲染 markdown，用纯文本 |
+| 小红书 | emoji 多、分段短 |
+| 博客 | 标准 markdown |
+| （你的平台） | （你的要求）|
+
+---
+
+## 🔄 自动学习（内置）
+
+**这个 skill 会从你的修改中自动学习。不需要手动写规则。**
+
+### 工作原理
+
+```
+AI 用这个 skill 写初稿
+    ↓
+你改到满意
+    ↓
+脚本 diff 两版 → 提取你改了什么
+    ↓
+新规则自动写入这个 SKILL.md
+    ↓
+下次 AI 写出来就更像你
+```
+
+### 只需要两个数据点
+
+- **original**: AI 生成的第一版
+- **final**: 你最终确认的版本
+
+中间改了几轮不管。在 Google Doc 里来回改了 10 次？无所谓，只比较首尾。
+
+### Agent 操作指南
+
+**写完内容后：**
+```bash
+python3 scripts/observe.py record-original <file> --account <账号> --content-type <类型>
+```
+
+**人类确认最终版后：**
+```bash
+python3 scripts/observe.py record-final <file> --match <hash>
+```
+
+**提取规则（手动或 cron 自动）：**
+```bash
+python3 scripts/improve.py auto --skill .
+```
+
+### 规则分级
+
+| 级别 | 含义 | 处理方式 |
+|------|------|---------|
+| P0 | 高置信度（多次出现） | 自动应用 |
+| P1 | 中置信度 | 人工确认 |
+| P2 | 低置信度（仅 1 次） | 存档观察 |
+
+### 安全
+
+- 每次更新前自动备份 SKILL.md
+- `improve.py rollback` 一键回滚
+- auto 模式只应用 P0
+
+---
+
+## 📊 CLI 参考
+
+### observe.py（零依赖纯 Python）
+
+| 命令 | 功能 |
+|------|------|
+| `record-original <file>` | 记录 AI 原稿 |
+| `record-final <file> --match <hash>` | 记录最终版 |
+| `pending` | 查看待配对 |
+| `stats` | 统计 |
+
+### improve.py（需要 LLM CLI）
+
+| 命令 | 功能 |
+|------|------|
+| `extract [--days 7]` | 提取改进建议 |
+| `auto` | 提取 + 自动应用 P0 |
+| `show` | 查看提案 |
+| `apply <id>` | 应用提案 |
+| `rollback` | 回滚 |
+
+支持的 LLM CLI: `claude`（Claude Code）/ `llm`（pip install llm）/ `IMPROVE_LLM_CMD` 环境变量
+
+---
+
+## 📂 数据存储
+
+```
+~/clawd/memory/                    # OpenClaw
+~/.claude/memory/                  # Claude Code
+├── skill-runs/<skill-name>/
+│   └── YYYY-MM-DD.jsonl          # 每日观察日志
+├── skill-proposals/<skill-name>/
+│   └── YYYYMMDD-HHMMSS.md       # 改进提案
+└── skill-backups/<skill-name>/
+    └── SKILL-YYYYMMDD-HHMMSS.md  # 自动备份
+```
+
+自动检测环境，不需要手动配置路径。
+
+---
+
+## 🚀 30 天预期
+
+| 时间 | 预期效果 |
+|------|---------|
+| 第 1 周 | 积累 3-5 次修改，生成第一批规则 |
+| 第 2 周 | 10+ 条规则，AI 输出明显更像你 |
+| 第 1 月 | 30+ 条规则，风格维度自动校准 |
+| 持续 | 规则库稳定增长，新 pattern 自动捕捉 |
diff --git a/builtin-skills/my-writing-style/scripts/improve.py b/builtin-skills/my-writing-style/scripts/improve.py
new file mode 100644
index 00000000..5f8e36b0
--- /dev/null
+++ b/builtin-skills/my-writing-style/scripts/improve.py
@@ -0,0 +1,426 @@
+#!/usr/bin/env python3
+"""
+Self-Improving Skill — Improver
+
+从人类修改中提取规则，更新目标 SKILL.md。
+
+用法:
+    python3 improve.py extract [--days 7] [--date 2026-03-17]
+    python3 improve.py auto                  # 提取 + 自动应用 P0（cron 用）
+    python3 improve.py show                  # 查看所有提案
+    python3 improve.py apply <proposal_id>   # 应用指定提案
+    python3 improve.py rollback              # 回滚上次应用
+
+环境变量:
+    SKILL_LOG_DIR      — 日志目录
+    SKILL_TARGET_PATH  — 目标 SKILL.md 路径
+    SKILL_PROPOSAL_DIR — 提案目录
+    SKILL_BACKUP_DIR   — 备份目录
+"""
+
+import sys
+import json
+import os
+import argparse
+import subprocess
+import shutil
+from pathlib import Path
+from datetime import datetime, timedelta
+
+# 默认路径 — 自动检测 OpenClaw (~/.openclaw) 或 Claude Code (~/.claude)
+def _detect_base():
+    """检测数据存储基目录"""
+    # 优先级: 环境变量 > ~/clawd > ~/.openclaw > ~/.claude > ~/.self-improving
+    if os.environ.get("SKILL_BASE_DIR"):
+        return Path(os.environ["SKILL_BASE_DIR"])
+    candidates = [
+        Path.home() / "clawd" / "memory",
+        Path.home() / ".openclaw" / "memory",
+        Path.home() / ".claude" / "memory",
+    ]
+    for c in candidates:
+        if c.parent.exists():
+            return c
+    return Path.home() / ".self-improving" / "memory"
+
+_BASE = _detect_base()
+DEFAULT_LOG_DIR = _BASE / "skill-runs" / "default"
+DEFAULT_PROPOSAL_DIR = _BASE / "skill-proposals" / "default"
+DEFAULT_BACKUP_DIR = _BASE / "skill-backups" / "default"
+
+
+def get_paths(args=None):
+    """解析所有路径配置"""
+    skill_name = "default"
+    if args and hasattr(args, 'skill') and args.skill:
+        skill_name = Path(args.skill).name
+
+    base = Path.home() / "clawd" / "memory"
+
+    log_dir = Path(os.environ.get("SKILL_LOG_DIR",
+                   getattr(args, 'log_dir', None) or
+                   str(base / "skill-runs" / skill_name)))
+
+    proposal_dir = Path(os.environ.get("SKILL_PROPOSAL_DIR",
+                        getattr(args, 'proposal_dir', None) or
+                        str(base / "skill-proposals" / skill_name)))
+
+    backup_dir = Path(os.environ.get("SKILL_BACKUP_DIR",
+                      getattr(args, 'backup_dir', None) or
+                      str(base / "skill-backups" / skill_name)))
+
+    # 目标 SKILL.md
+    if os.environ.get("SKILL_TARGET_PATH"):
+        target = Path(os.environ["SKILL_TARGET_PATH"])
+    elif args and hasattr(args, 'target') and args.target:
+        target = Path(args.target)
+    elif args and hasattr(args, 'skill') and args.skill:
+        target = Path(args.skill) / "SKILL.md"
+    else:
+        target = None
+
+    for d in (log_dir, proposal_dir, backup_dir):
+        d.mkdir(parents=True, exist_ok=True)
+
+    return log_dir, proposal_dir, backup_dir, target
+
+
+def read_log_entries(log_file):
+    if not log_file.exists():
+        return []
+    entries = []
+    with log_file.open("r") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    return entries
+
+
+def collect_edits(log_dir, days=1, date_str=None):
+    """收集有实际修改的 final/edited 记录"""
+    edits = []
+    if date_str:
+        log_file = log_dir / f"{date_str}.jsonl"
+        entries = read_log_entries(log_file)
+        edits.extend([e for e in entries
+                      if e["type"] in ("final", "edited") and not e.get("no_change")])
+    else:
+        for i in range(days):
+            date = (datetime.now() - timedelta(days=i)).strftime("%Y-%m-%d")
+            log_file = log_dir / f"{date}.jsonl"
+            entries = read_log_entries(log_file)
+            edits.extend([e for e in entries
+                          if e["type"] in ("final", "edited") and not e.get("no_change")])
+    return edits
+
+
+def call_llm(prompt, timeout=180):
+    """调用 LLM — 自动检测可用的 CLI (claude / openclaw / llm)"""
+    # 优先级: claude CLI → openclaw exec → generic llm CLI
+    candidates = [
+        ["claude", "--print", "--model", "sonnet"],  # Claude Code
+        ["claude", "--print"],                         # Claude Code (default model)
+        ["llm", "-m", "claude-sonnet"],               # simon willison's llm CLI
+        ["llm"],                                       # llm CLI default
+    ]
+    for cmd in candidates:
+        try:
+            result = subprocess.run(cmd, input=prompt, capture_output=True,
+                                    text=True, timeout=timeout)
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            continue
+
+    # fallback: 如果 IMPROVE_LLM_CMD 环境变量设置了，用它
+    custom_cmd = os.environ.get("IMPROVE_LLM_CMD")
+    if custom_cmd:
+        try:
+            result = subprocess.run(custom_cmd.split(), input=prompt,
+                                    capture_output=True, text=True, timeout=timeout)
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            pass
+
+    print("❌ LLM 调用失败。支持的方式：")
+    print("   - 安装 Claude Code CLI (claude --print)")
+    print("   - 安装 llm CLI (pip install llm)")
+    print("   - 设置 IMPROVE_LLM_CMD 环境变量")
+    return None
+
+
+def extract_improvements(args):
+    log_dir, proposal_dir, _, target = get_paths(args)
+    days = getattr(args, 'days', 1) or 1
+    date_str = getattr(args, 'date', None)
+
+    edits = collect_edits(log_dir, days=days, date_str=date_str)
+    if not edits:
+        print("⚠️  没有修改记录")
+        return None
+
+    print(f"📊 找到 {len(edits)} 次修改，正在分析...")
+
+    # 读当前 SKILL.md
+    current_skill = ""
+    if target and target.exists():
+        current_skill = target.read_text()
+
+    # 构建对比数据
+    edit_summaries = []
+    for i, edit in enumerate(edits):
+        orig = edit.get("original_content", "")[:3000]
+        final = edit.get("final_content", edit.get("edited_content", ""))[:3000]
+        ctx = edit.get("context", {})
+        edit_summaries.append({
+            "index": i + 1,
+            "account": ctx.get("account", "unknown"),
+            "content_type": ctx.get("content_type", "unknown"),
+            "original": orig,
+            "final": final,
+        })
+
+    proposal_id = datetime.now().strftime("%Y%m%d-%H%M%S")
+
+    prompt = f"""你是 writing style skill 的改进助手。
+
+分析人类对 AI 生成文章的修改，提取可以加入 SKILL.md 的新规则。
+
+## 当前 SKILL.md（最后 3000 字，避免重复）
+{current_skill[-3000:]}
+
+## 修改记录（original vs final）
+{json.dumps(edit_summaries, ensure_ascii=False, indent=2)}
+
+## 要求
+1. 对比 original 和 final，找出系统性修改
+2. 只提取有 pattern 的修改（至少 2 次，或单次但改动幅度大且明确）
+3. 不要提取已在 SKILL.md 中的规则
+4. 每条规则必须可执行
+
+## 输出格式
+
+---
+id: {proposal_id}
+date: {datetime.now().isoformat()}
+source: {len(edits)} edits
+status: pending
+---
+
+# Improvement Proposal
+
+## 提取的改进建议
+
+### 1. 新禁止词
+- **`词`** → 替代: "YYY" | 理由: ... | 优先级: **P0/P1/P2**
+
+### 2. 新风格规则
+- 规则描述 | 理由: ... | 优先级: **P0/P1/P2**
+
+### 3. 反模式
+- 描述 | 理由: ... | 优先级: **P0/P1/P2**
+
+P0=高置信度(多次), P1=中置信度, P2=低置信度(仅1次)
+"""
+
+    suggestions = call_llm(prompt)
+    if not suggestions:
+        return None
+
+    proposal_file = proposal_dir / f"{proposal_id}.md"
+    proposal_file.write_text(suggestions)
+
+    print(f"✅ 改进建议已保存: {proposal_file}")
+    print(f"\n{suggestions[:2000]}")
+    if len(suggestions) > 2000:
+        print(f"\n... (完整内容见文件)")
+    return proposal_id
+
+
+def show_proposals(args):
+    _, proposal_dir, _, _ = get_paths(args)
+    proposals = list(proposal_dir.glob("*.md"))
+
+    if not proposals:
+        print("⚠️  没有提案")
+        return
+
+    print(f"\n📋 共 {len(proposals)} 个提案:\n")
+    for p in sorted(proposals, reverse=True):
+        content = p.read_text()
+        status = "unknown"
+        for line in content.split("\n")[:10]:
+            if line.startswith("status:"):
+                status = line.split(":", 1)[1].strip()
+        icon = {"pending": "⏳", "applied": "✅", "rejected": "❌"}.get(
+            status.split("(")[0].strip(), "❓")
+        print(f"  {icon} {p.stem} — {status}")
+
+
+def backup_skill(target, backup_dir):
+    if not target or not target.exists():
+        return None
+    name = f"SKILL-{datetime.now().strftime('%Y%m%d-%H%M%S')}.md"
+    backup_path = backup_dir / name
+    shutil.copy2(target, backup_path)
+    print(f"📦 备份: {backup_path}")
+    return backup_path
+
+
+def apply_proposal(args):
+    _, proposal_dir, backup_dir, target = get_paths(args)
+    proposal_id = args.proposal_id
+    proposal_file = proposal_dir / f"{proposal_id}.md"
+
+    if not proposal_file.exists():
+        print(f"❌ 提案不存在: {proposal_id}")
+        return
+
+    if not target or not target.exists():
+        print(f"❌ 目标 SKILL.md 不存在（用 --skill 或 --target 指定）")
+        return
+
+    proposal_content = proposal_file.read_text()
+    current_skill = target.read_text()
+
+    auto_mode = getattr(args, 'auto', False)
+    filter_level = "P0" if auto_mode else "P0 和 P1"
+
+    backup_skill(target, backup_dir)
+
+    prompt = f"""把改进提案中的 **{filter_level}** 规则合并到 SKILL.md。
+
+规则：
+1. 新禁止词 → 加到禁止词 section
+2. 新风格规则 → 加到对应 section
+3. 不删除已有规则，不改文件结构
+4. version +0.1
+
+## 提案
+{proposal_content}
+
+## 当前 SKILL.md
+{current_skill}
+
+输出完整更新后的 SKILL.md。不加代码块包裹。"""
+
+    updated = call_llm(prompt, timeout=300)
+    if not updated:
+        print("❌ 合并失败")
+        return
+
+    target.write_text(updated)
+
+    new_content = proposal_content.replace(
+        "status: pending",
+        f"status: applied ({datetime.now().strftime('%Y-%m-%d')})")
+    proposal_file.write_text(new_content)
+
+    print(f"✅ 已应用提案 {proposal_id}")
+    print(f"💡 回滚: python3 improve.py rollback")
+
+
+def auto_improve(args):
+    log_dir, _, _, _ = get_paths(args)
+    edits = collect_edits(log_dir, days=7)
+
+    if not edits:
+        print("⚠️  最近 7 天没有修改记录，跳过")
+        return
+
+    print(f"🤖 自动模式: {len(edits)} 次修改")
+
+    args.days = 7
+    args.date = None
+    proposal_id = extract_improvements(args)
+
+    if not proposal_id:
+        return
+
+    _, proposal_dir, _, _ = get_paths(args)
+    content = (proposal_dir / f"{proposal_id}.md").read_text()
+
+    if "P0" not in content:
+        print("ℹ️  没有 P0 规则，跳过自动应用")
+        return
+
+    print("\n🔄 自动应用 P0 规则...")
+    apply_args = argparse.Namespace(**vars(args))
+    apply_args.proposal_id = proposal_id
+    apply_args.auto = True
+    apply_proposal(apply_args)
+
+
+def rollback(args):
+    _, _, backup_dir, target = get_paths(args)
+
+    if not target:
+        print("❌ 未指定目标 SKILL.md")
+        return
+
+    backups = sorted(backup_dir.glob("SKILL-*.md"), reverse=True)
+    if not backups:
+        print("❌ 没有备份")
+        return
+
+    latest = backups[0]
+    # 保存当前版本
+    if target.exists():
+        emergency = backup_dir / f"SKILL-pre-rollback-{datetime.now().strftime('%Y%m%d-%H%M%S')}.md"
+        shutil.copy2(target, emergency)
+
+    shutil.copy2(latest, target)
+    print(f"✅ 已回滚到: {latest.name}")
+
+
+def add_common_args(parser):
+    parser.add_argument("--skill", help="目标 skill 目录")
+    parser.add_argument("--target", help="目标 SKILL.md 路径")
+    parser.add_argument("--log-dir", help="日志目录")
+    parser.add_argument("--proposal-dir", help="提案目录")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Self-Improving Skill — Improver")
+    subparsers = parser.add_subparsers(dest="action")
+
+    p_ext = subparsers.add_parser("extract", help="提取改进建议")
+    p_ext.add_argument("--date", help="指定日期")
+    p_ext.add_argument("--days", type=int, default=1)
+    add_common_args(p_ext)
+
+    p_show = subparsers.add_parser("show", help="查看提案")
+    add_common_args(p_show)
+
+    p_apply = subparsers.add_parser("apply", help="应用提案")
+    p_apply.add_argument("proposal_id")
+    add_common_args(p_apply)
+
+    p_auto = subparsers.add_parser("auto", help="自动提取+应用P0")
+    add_common_args(p_auto)
+
+    p_rb = subparsers.add_parser("rollback", help="回滚")
+    add_common_args(p_rb)
+
+    args = parser.parse_args()
+    if not args.action:
+        parser.print_help()
+        sys.exit(1)
+
+    actions = {
+        "extract": extract_improvements,
+        "show": show_proposals,
+        "apply": apply_proposal,
+        "auto": auto_improve,
+        "rollback": rollback,
+    }
+    actions[args.action](args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/builtin-skills/my-writing-style/scripts/observe.py b/builtin-skills/my-writing-style/scripts/observe.py
new file mode 100644
index 00000000..61cfe179
--- /dev/null
+++ b/builtin-skills/my-writing-style/scripts/observe.py
@@ -0,0 +1,309 @@
+#!/usr/bin/env python3
+"""
+Self-Improving Skill — Observation Layer
+
+通用的 original → final 记录器。适用于任何 "AI 生成 → 人类修改" 的循环。
+
+用法:
+    python3 observe.py record-original article.md [--text "..."] [--account X] [--content-type article]
+    python3 observe.py record-final article.md [--match <hash>] [--text "..."]
+    python3 observe.py pending
+    python3 observe.py stats
+
+环境变量:
+    SKILL_LOG_DIR  — 日志目录（默认 ~/clawd/memory/skill-runs/default/）
+"""
+
+import sys
+import json
+import os
+import argparse
+from pathlib import Path
+from datetime import datetime, timedelta
+import hashlib
+
+# 日志目录 — 自动检测 OpenClaw / Claude Code / standalone
+def _detect_base():
+    if os.environ.get("SKILL_BASE_DIR"):
+        return Path(os.environ["SKILL_BASE_DIR"])
+    candidates = [
+        Path.home() / "clawd" / "memory",
+        Path.home() / ".openclaw" / "memory",
+        Path.home() / ".claude" / "memory",
+    ]
+    for c in candidates:
+        if c.parent.exists():
+            return c
+    return Path.home() / ".self-improving" / "memory"
+
+DEFAULT_LOG_DIR = _detect_base() / "skill-runs" / "default"
+
+
+def get_log_dir(args=None):
+    """按优先级决定日志目录：--log-dir > SKILL_LOG_DIR > default"""
+    if args and hasattr(args, 'log_dir') and args.log_dir:
+        d = Path(args.log_dir)
+    elif os.environ.get("SKILL_LOG_DIR"):
+        d = Path(os.environ["SKILL_LOG_DIR"])
+    elif args and hasattr(args, 'skill') and args.skill:
+        skill_name = Path(args.skill).name
+        d = Path.home() / "clawd" / "memory" / "skill-runs" / skill_name
+    else:
+        d = DEFAULT_LOG_DIR
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def get_log_file(log_dir, date_str=None):
+    if date_str is None:
+        date_str = datetime.now().strftime("%Y-%m-%d")
+    return log_dir / f"{date_str}.jsonl"
+
+
+def compute_hash(content):
+    return hashlib.md5(content.encode()).hexdigest()[:8]
+
+
+def get_content(args):
+    if hasattr(args, 'text') and args.text:
+        return args.text
+    if hasattr(args, 'stdin') and args.stdin:
+        return sys.stdin.read()
+    if hasattr(args, 'file') and args.file:
+        p = Path(args.file)
+        if not p.exists():
+            print(f"❌ 文件不存在: {args.file}")
+            sys.exit(1)
+        return p.read_text()
+    return None
+
+
+def read_log_entries(log_file):
+    if not log_file.exists():
+        return []
+    entries = []
+    with log_file.open("r") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    return entries
+
+
+def find_unmatched(log_dir, days=14):
+    """找到有 original 但没有 final 的记录（兼容旧 edited/no-change type）"""
+    all_originals = {}
+    all_matched = set()
+
+    for i in range(days):
+        date = (datetime.now() - timedelta(days=i)).strftime("%Y-%m-%d")
+        entries = read_log_entries(get_log_file(log_dir, date))
+        for e in entries:
+            if e["type"] == "original":
+                e["_date"] = date
+                all_originals[e["content_hash"]] = e
+            elif e["type"] in ("final", "edited", "no-change"):
+                all_matched.add(e["content_hash"])
+
+    return {h: o for h, o in all_originals.items() if h not in all_matched}
+
+
+def record_original(args):
+    content = get_content(args)
+    if not content:
+        print("❌ 需要提供内容（文件路径、--text 或 --stdin）")
+        sys.exit(1)
+
+    log_dir = get_log_dir(args)
+    content_hash = compute_hash(content)
+
+    context = {}
+    if hasattr(args, 'account') and args.account:
+        context["account"] = args.account
+    if hasattr(args, 'content_type') and args.content_type:
+        context["content_type"] = args.content_type
+
+    log_entry = {
+        "timestamp": datetime.now().isoformat(),
+        "type": "original",
+        "content_hash": content_hash,
+        "file": str(args.file) if hasattr(args, 'file') and args.file else None,
+        "content": content,
+        "context": context,
+        "char_count": len(content),
+    }
+
+    log_file = get_log_file(log_dir)
+    with log_file.open("a") as f:
+        f.write(json.dumps(log_entry, ensure_ascii=False) + "\n")
+
+    print(f"✅ 记录原稿: {content_hash}")
+    print(f"📝 字数: {len(content)}")
+    print(f"📁 日志: {log_file}")
+    return content_hash
+
+
+def record_final(args):
+    content = get_content(args)
+    if not content:
+        print("❌ 需要提供最终版内容")
+        sys.exit(1)
+
+    log_dir = get_log_dir(args)
+    target_hash = getattr(args, 'match', None)
+
+    if target_hash:
+        # 指定 hash，跨天查找
+        original = None
+        for i in range(14):
+            date = (datetime.now() - timedelta(days=i)).strftime("%Y-%m-%d")
+            entries = read_log_entries(get_log_file(log_dir, date))
+            for e in entries:
+                if e["type"] == "original" and e["content_hash"] == target_hash:
+                    original = e
+                    break
+            if original:
+                break
+        if not original:
+            print(f"❌ 找不到 hash {target_hash} 的原稿")
+            sys.exit(1)
+    else:
+        # 自动匹配最近的未配对 original
+        unmatched = find_unmatched(log_dir, 14)
+        if not unmatched:
+            print("❌ 没有待配对的原稿")
+            sys.exit(1)
+        target_hash = list(unmatched.keys())[-1]
+        original = unmatched[target_hash]
+
+    is_same = content.strip() == original["content"].strip()
+
+    log_entry = {
+        "timestamp": datetime.now().isoformat(),
+        "type": "final",
+        "content_hash": target_hash,
+        "original_content": original["content"],
+        "final_content": content,
+        "original_char_count": len(original["content"]),
+        "final_char_count": len(content),
+        "context": original.get("context", {}),
+        "no_change": is_same,
+    }
+
+    log_file = get_log_file(log_dir)
+    with log_file.open("a") as f:
+        f.write(json.dumps(log_entry, ensure_ascii=False) + "\n")
+
+    if is_same:
+        print(f"✅ 记录最终版: {target_hash} (无修改 — 正反馈)")
+    else:
+        diff_pct = ((len(content) - len(original["content"])) / max(len(original["content"]), 1)) * 100
+        print(f"✅ 记录最终版: {target_hash}")
+        print(f"📝 原稿: {len(original['content'])} 字 → 最终: {len(content)} 字 ({diff_pct:+.1f}%)")
+    print(f"📁 日志: {log_file}")
+
+
+def show_pending(args):
+    log_dir = get_log_dir(args)
+    unmatched = find_unmatched(log_dir, 14)
+
+    if not unmatched:
+        print("✅ 全部已配对")
+        return
+
+    print(f"\n⏳ {len(unmatched)} 条待配对:\n")
+    for h, entry in unmatched.items():
+        preview = entry["content"][:80].replace("\n", " ")
+        ctx = entry.get("context", {})
+        account = ctx.get("account", "?")
+        date = entry.get("_date", "?")
+        print(f"  📄 {h} | {date} | {account}")
+        print(f"     {preview}...")
+        print()
+
+
+def show_stats(args):
+    log_dir = get_log_dir(args)
+    all_files = sorted(log_dir.glob("*.jsonl"))
+
+    total_originals = 0
+    total_finals = 0
+    total_no_change = 0
+    total_changed = 0
+
+    for log_file in all_files:
+        entries = read_log_entries(log_file)
+        total_originals += sum(1 for e in entries if e["type"] == "original")
+        finals = [e for e in entries if e["type"] in ("final", "edited")]
+        total_finals += len(finals)
+        total_no_change += sum(1 for e in finals if e.get("no_change"))
+        total_changed += sum(1 for e in finals if not e.get("no_change"))
+
+    pending = find_unmatched(log_dir, 14)
+
+    print(f"\n📊 Self-Improving Skill 观察统计")
+    print(f"{'='*40}")
+    print(f"📁 日志天数: {len(all_files)}")
+    print(f"📝 原稿: {total_originals}")
+    print(f"✅ 已配对: {total_finals}")
+    print(f"   ├ 有修改: {total_changed}")
+    print(f"   └ 无修改: {total_no_change}")
+    print(f"⏳ 待配对: {len(pending)}")
+    if total_finals > 0:
+        print(f"📈 修改率: {total_changed}/{total_finals} = {total_changed/total_finals*100:.0f}%")
+
+
+def add_common_args(parser):
+    """添加通用参数"""
+    parser.add_argument("--skill", help="目标 skill 目录名（用于定位日志目录）")
+    parser.add_argument("--log-dir", help="自定义日志目录")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Self-Improving Skill — Observation Layer")
+    subparsers = parser.add_subparsers(dest="action")
+
+    # record-original
+    p_orig = subparsers.add_parser("record-original", help="记录 AI 原稿")
+    p_orig.add_argument("file", nargs="?", help="文件路径")
+    p_orig.add_argument("--text", help="直接传入文本")
+    p_orig.add_argument("--stdin", action="store_true", help="从 stdin 读取")
+    p_orig.add_argument("--account", help="发布账号")
+    p_orig.add_argument("--content-type", help="内容类型")
+    add_common_args(p_orig)
+
+    # record-final
+    p_final = subparsers.add_parser("record-final", help="记录最终版")
+    p_final.add_argument("file", nargs="?", help="文件路径")
+    p_final.add_argument("--text", help="直接传入文本")
+    p_final.add_argument("--stdin", action="store_true", help="从 stdin 读取")
+    p_final.add_argument("--match", help="匹配的原稿 hash")
+    add_common_args(p_final)
+
+    # pending
+    p_pending = subparsers.add_parser("pending", help="查看待配对原稿")
+    add_common_args(p_pending)
+
+    # stats
+    p_stats = subparsers.add_parser("stats", help="总体统计")
+    add_common_args(p_stats)
+
+    args = parser.parse_args()
+    if not args.action:
+        parser.print_help()
+        sys.exit(1)
+
+    actions = {
+        "record-original": record_original,
+        "record-final": record_final,
+        "pending": show_pending,
+        "stats": show_stats,
+    }
+    actions[args.action](args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/builtin-skills/software-engineer/ai-coding-discipline/SKILL.md b/builtin-skills/software-engineer/ai-coding-discipline/SKILL.md
new file mode 100644
index 00000000..0453c5f9
--- /dev/null
+++ b/builtin-skills/software-engineer/ai-coding-discipline/SKILL.md
@@ -0,0 +1,215 @@
+---
+name: ai-coding-discipline
+description: >
+  Mandatory coding discipline rules that prevent common AI coding anti-patterns.
+  MUST be loaded for ALL code writing, editing, reviewing, bug fixing, and testing tasks.
+  Trigger on: writing code, editing code, fixing bugs, writing tests, implementing features,
+  refactoring, code review, creating functions, adding error handling, debugging.
+  This skill enforces fail-fast principles, proper error propagation, meaningful tests,
+  and disciplined debugging workflows. Always active when Claude writes or modifies code.
+---
+
+# AI Coding Discipline
+
+> These rules override default AI coding tendencies. Follow them in ALL code you write or modify.
+
+---
+
+## Rule 1: No Silent Fallbacks
+
+**Never use fallback values to mask data that should not be missing.**
+
+```typescript
+// FORBIDDEN — hides upstream bugs
+const price = product?.price ?? 0;
+const userName = user?.name || "Unknown";
+
+// CORRECT — fail fast when data contract is violated
+if (product.price == null) {
+  throw new Error(`Product ${product.id} is missing price`);
+}
+const price = product.price;
+```
+
+**When fallbacks ARE acceptable:**
+- User-facing display with explicit design intent (e.g., avatar placeholder)
+- Optional configuration with documented defaults
+- External input parsing where absence is a valid state
+
+**Checklist before writing `??`, `||`, or `?.`:**
+1. Can this value legitimately be null/undefined at this point?
+2. If it is null, will the fallback produce a correct result downstream?
+3. Would a thrown error help me find a bug faster?
+
+If the answer to #3 is yes, throw instead of falling back.
+
+---
+
+## Rule 2: No Catch-All try/catch in Business Logic
+
+**Business logic functions must NOT wrap everything in try/catch. Let errors propagate naturally.**
+
+```typescript
+// FORBIDDEN — swallows all errors into a useless null
+async function createOrder(data: OrderInput) {
+  try {
+    const user = await getUser(data.userId);
+    const coupon = await validateCoupon(data.couponCode);
+    const order = await saveOrder({ ...data, discount: coupon.value });
+    return order;
+  } catch (error) {
+    console.log('Error creating order:', error);
+    return null; // caller gets null, has no idea what failed
+  }
+}
+
+// CORRECT — let errors bubble up, catch at the boundary
+async function createOrder(data: OrderInput) {
+  const user = await getUser(data.userId);
+  const coupon = await validateCoupon(data.couponCode);
+  const order = await saveOrder({ ...data, discount: coupon.value });
+  return order;
+}
+
+// Catch ONLY at the API/controller boundary
+app.post('/orders', async (req, res) => {
+  try {
+    const order = await createOrder(req.body);
+    res.json(order);
+  } catch (error) {
+    logger.error('Order creation failed', { error, body: req.body });
+    res.status(500).json({ error: 'Order creation failed' });
+  }
+});
+```
+
+**Where try/catch IS appropriate:**
+- API route handlers / controller boundaries
+- Top-level event handlers (message queues, cron jobs)
+- Operations where partial failure is expected and recovery is defined (e.g., batch processing with per-item error handling)
+- Specific, named error types you intend to handle differently
+
+**Never catch `Error` just to return `null`, `undefined`, `false`, or an empty object.**
+
+---
+
+## Rule 3: Tests Must Fail When Code Breaks
+
+**Every test must verify specific business outcomes. A test that passes when the core logic is deleted is worthless.**
+
+```typescript
+// FORBIDDEN — passes even if processOrder returns garbage
+test('should process order', async () => {
+  const result = await processOrder(mockOrder);
+  expect(result).toBeDefined();
+});
+
+// CORRECT — verifies exact business behavior
+test('should calculate total with 10% discount', async () => {
+  const result = await processOrder({
+    ...mockOrder,
+    discount: 0.1,
+  });
+  expect(result.totalAmount).toBe(900);       // 1000 * 0.9
+  expect(result.discountAmount).toBe(100);
+  expect(result.status).toBe('confirmed');
+});
+```
+
+**Test quality checklist:**
+1. If I delete the function body, does this test fail? If not, the test is useless.
+2. Am I testing behavior or just testing that "something exists"?
+3. Do my assertions check concrete values, not just truthiness?
+
+**Banned weak assertions** (unless testing existence is the actual requirement):
+- `toBeDefined()`, `toBeTruthy()`, `toBeFalsy()` as sole assertion
+- `toHaveLength(expect.any(Number))`
+- `expect(result).not.toBeNull()` without further value checks
+
+---
+
+## Rule 4: No Hardcoded Lookup-Table Implementations
+
+**Never implement business logic by hardcoding return values that match test cases.**
+
+```typescript
+// FORBIDDEN — fake implementation that "fits" the tests
+function calculateDiscount(amount: number, level: string): number {
+  if (amount === 1000 && level === 'gold') return 100;
+  if (amount === 500 && level === 'silver') return 25;
+  return 0;
+}
+
+// CORRECT — real logic
+function calculateDiscount(amount: number, level: string): number {
+  const rates: Record<string, number> = { gold: 0.1, silver: 0.05, bronze: 0.02 };
+  const rate = rates[level] ?? 0;
+  return amount * rate;
+}
+```
+
+**How to prevent this:**
+- Use diverse test data: multiple amounts, edge cases, boundary values
+- Add property-based / fuzzy tests where appropriate
+- Test with values NOT in the original spec to catch lookup-table fakes
+
+---
+
+## Rule 5: Red-Green Testing (TDD Order)
+
+**When fixing a bug, always write the failing test FIRST, then fix the code.**
+
+```
+Correct order:
+1. Discover bug
+2. Write a test that reproduces the bug
+3. Run the test — confirm it FAILS (red)
+4. Fix the code
+5. Run the test — confirm it PASSES (green)
+```
+
+**Why this matters:** If you fix the code first and then write a test, you can never be sure the test would have caught the bug. The test might pass for the wrong reason.
+
+**Never skip step 3.** Seeing the test go from red to green is the proof that the test is valid.
+
+---
+
+## Rule 6: Never Remove Debug Logs During a Fix
+
+**When debugging, debug logs are removed ONLY after the human confirms the fix works.**
+
+```
+FORBIDDEN workflow:
+1. Human asks to add debug logs
+2. AI adds logs
+3. Human runs code, shares log output
+4. AI "finds the problem", applies fix AND removes debug logs in the same edit
+5. Fix doesn't work — logs are gone, must re-add them
+
+CORRECT workflow:
+1. Human asks to add debug logs
+2. AI adds logs
+3. Human runs code, shares log output
+4. AI applies fix ONLY — debug logs stay untouched
+5. Human verifies the fix
+6. Human decides when to remove debug logs (or asks AI to remove them)
+```
+
+**Rule: Never touch debug/diagnostic logs in the same commit as a fix. They are separate concerns.**
+
+---
+
+## Quick Reference: Self-Check Before Submitting Code
+
+Before finalizing any code change, run through this checklist:
+
+| Check | Question |
+|-------|----------|
+| Fallbacks | Did I use `??` or `\|\|` to hide a value that should never be missing? |
+| Error handling | Did I add try/catch in business logic that should just let errors propagate? |
+| Test strength | Would my tests still pass if I deleted the implementation? |
+| Test honesty | Did I hardcode values to match test cases instead of implementing real logic? |
+| TDD order | For bug fixes: did I see the test fail before applying the fix? |
+| Debug logs | Am I removing diagnostic logs in the same change as the fix? |
+
+If any answer is "yes", revise before proceeding.
diff --git a/builtin-skills/software-engineer/api-design-principles/SKILL.md b/builtin-skills/software-engineer/api-design-principles/SKILL.md
new file mode 100644
index 00000000..437cc3cf
--- /dev/null
+++ b/builtin-skills/software-engineer/api-design-principles/SKILL.md
@@ -0,0 +1,518 @@
+---
+name: api-design-principles
+description: Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.
+---
+
+# API Design Principles
+
+Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
+
+## When to Use This Skill
+
+- Designing new REST or GraphQL APIs
+- Refactoring existing APIs for better usability
+- Establishing API design standards for your team
+- Reviewing API specifications before implementation
+- Migrating between API paradigms (REST to GraphQL, etc.)
+- Creating developer-friendly API documentation
+- Optimizing APIs for specific use cases (mobile, third-party integrations)
+
+## Core Concepts
+
+### 1. RESTful Design Principles
+
+**Resource-Oriented Architecture**
+
+- Resources are nouns (users, orders, products), not verbs
+- Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)
+- URLs represent resource hierarchies
+- Consistent naming conventions
+
+**HTTP Methods Semantics:**
+
+- `GET`: Retrieve resources (idempotent, safe)
+- `POST`: Create new resources
+- `PUT`: Replace entire resource (idempotent)
+- `PATCH`: Partial resource updates
+- `DELETE`: Remove resources (idempotent)
+
+### 2. GraphQL Design Principles
+
+**Schema-First Development**
+
+- Types define your domain model
+- Queries for reading data
+- Mutations for modifying data
+- Subscriptions for real-time updates
+
+**Query Structure:**
+
+- Clients request exactly what they need
+- Single endpoint, multiple operations
+- Strongly typed schema
+- Introspection built-in
+
+### 3. API Versioning Strategies
+
+**URL Versioning:**
+
+```
+/api/v1/users
+/api/v2/users
+```
+
+**Header Versioning:**
+
+```
+Accept: application/vnd.api+json; version=1
+```
+
+**Query Parameter Versioning:**
+
+```
+/api/users?version=1
+```
+
+## REST API Design Patterns
+
+### Pattern 1: Resource Collection Design
+
+```python
+# Good: Resource-oriented endpoints
+GET    /api/users              # List users (with pagination)
+POST   /api/users              # Create user
+GET    /api/users/{id}         # Get specific user
+PUT    /api/users/{id}         # Replace user
+PATCH  /api/users/{id}         # Update user fields
+DELETE /api/users/{id}         # Delete user
+
+# Nested resources
+GET    /api/users/{id}/orders  # Get user's orders
+POST   /api/users/{id}/orders  # Create order for user
+
+# Bad: Action-oriented endpoints (avoid)
+POST   /api/createUser
+POST   /api/getUserById
+POST   /api/deleteUser
+```
+
+### Pattern 2: Pagination and Filtering
+
+```python
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+class PaginationParams(BaseModel):
+    page: int = Field(1, ge=1, description="Page number")
+    page_size: int = Field(20, ge=1, le=100, description="Items per page")
+
+class FilterParams(BaseModel):
+    status: Optional[str] = None
+    created_after: Optional[str] = None
+    search: Optional[str] = None
+
+class PaginatedResponse(BaseModel):
+    items: List[dict]
+    total: int
+    page: int
+    page_size: int
+    pages: int
+
+    @property
+    def has_next(self) -> bool:
+        return self.page < self.pages
+
+    @property
+    def has_prev(self) -> bool:
+        return self.page > 1
+
+# FastAPI endpoint example
+from fastapi import FastAPI, Query, Depends
+
+app = FastAPI()
+
+@app.get("/api/users", response_model=PaginatedResponse)
+async def list_users(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    status: Optional[str] = Query(None),
+    search: Optional[str] = Query(None)
+):
+    # Apply filters
+    query = build_query(status=status, search=search)
+
+    # Count total
+    total = await count_users(query)
+
+    # Fetch page
+    offset = (page - 1) * page_size
+    users = await fetch_users(query, limit=page_size, offset=offset)
+
+    return PaginatedResponse(
+        items=users,
+        total=total,
+        page=page,
+        page_size=page_size,
+        pages=(total + page_size - 1) // page_size
+    )
+```
+
+### Pattern 3: Error Handling and Status Codes
+
+```python
+from fastapi import HTTPException, status
+from pydantic import BaseModel
+
+class ErrorResponse(BaseModel):
+    error: str
+    message: str
+    details: Optional[dict] = None
+    timestamp: str
+    path: str
+
+class ValidationErrorDetail(BaseModel):
+    field: str
+    message: str
+    value: Any
+
+# Consistent error responses
+STATUS_CODES = {
+    "success": 200,
+    "created": 201,
+    "no_content": 204,
+    "bad_request": 400,
+    "unauthorized": 401,
+    "forbidden": 403,
+    "not_found": 404,
+    "conflict": 409,
+    "unprocessable": 422,
+    "internal_error": 500
+}
+
+def raise_not_found(resource: str, id: str):
+    raise HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND,
+        detail={
+            "error": "NotFound",
+            "message": f"{resource} not found",
+            "details": {"id": id}
+        }
+    )
+
+def raise_validation_error(errors: List[ValidationErrorDetail]):
+    raise HTTPException(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        detail={
+            "error": "ValidationError",
+            "message": "Request validation failed",
+            "details": {"errors": [e.dict() for e in errors]}
+        }
+    )
+
+# Example usage
+@app.get("/api/users/{user_id}")
+async def get_user(user_id: str):
+    user = await fetch_user(user_id)
+    if not user:
+        raise_not_found("User", user_id)
+    return user
+```
+
+### Pattern 4: HATEOAS (Hypermedia as the Engine of Application State)
+
+```python
+class UserResponse(BaseModel):
+    id: str
+    name: str
+    email: str
+    _links: dict
+
+    @classmethod
+    def from_user(cls, user: User, base_url: str):
+        return cls(
+            id=user.id,
+            name=user.name,
+            email=user.email,
+            _links={
+                "self": {"href": f"{base_url}/api/users/{user.id}"},
+                "orders": {"href": f"{base_url}/api/users/{user.id}/orders"},
+                "update": {
+                    "href": f"{base_url}/api/users/{user.id}",
+                    "method": "PATCH"
+                },
+                "delete": {
+                    "href": f"{base_url}/api/users/{user.id}",
+                    "method": "DELETE"
+                }
+            }
+        )
+```
+
+## GraphQL Design Patterns
+
+### Pattern 1: Schema Design
+
+```graphql
+# schema.graphql
+
+# Clear type definitions
+type User {
+  id: ID!
+  email: String!
+  name: String!
+  createdAt: DateTime!
+
+  # Relationships
+  orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!
+
+  profile: UserProfile
+}
+
+type Order {
+  id: ID!
+  status: OrderStatus!
+  total: Money!
+  items: [OrderItem!]!
+  createdAt: DateTime!
+
+  # Back-reference
+  user: User!
+}
+
+# Pagination pattern (Relay-style)
+type OrderConnection {
+  edges: [OrderEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type OrderEdge {
+  node: Order!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+
+# Enums for type safety
+enum OrderStatus {
+  PENDING
+  CONFIRMED
+  SHIPPED
+  DELIVERED
+  CANCELLED
+}
+
+# Custom scalars
+scalar DateTime
+scalar Money
+
+# Query root
+type Query {
+  user(id: ID!): User
+  users(first: Int = 20, after: String, search: String): UserConnection!
+
+  order(id: ID!): Order
+}
+
+# Mutation root
+type Mutation {
+  createUser(input: CreateUserInput!): CreateUserPayload!
+  updateUser(input: UpdateUserInput!): UpdateUserPayload!
+  deleteUser(id: ID!): DeleteUserPayload!
+
+  createOrder(input: CreateOrderInput!): CreateOrderPayload!
+}
+
+# Input types for mutations
+input CreateUserInput {
+  email: String!
+  name: String!
+  password: String!
+}
+
+# Payload types for mutations
+type CreateUserPayload {
+  user: User
+  errors: [Error!]
+}
+
+type Error {
+  field: String
+  message: String!
+}
+```
+
+### Pattern 2: Resolver Design
+
+```python
+from typing import Optional, List
+from ariadne import QueryType, MutationType, ObjectType
+from dataclasses import dataclass
+
+query = QueryType()
+mutation = MutationType()
+user_type = ObjectType("User")
+
+@query.field("user")
+async def resolve_user(obj, info, id: str) -> Optional[dict]:
+    """Resolve single user by ID."""
+    return await fetch_user_by_id(id)
+
+@query.field("users")
+async def resolve_users(
+    obj,
+    info,
+    first: int = 20,
+    after: Optional[str] = None,
+    search: Optional[str] = None
+) -> dict:
+    """Resolve paginated user list."""
+    # Decode cursor
+    offset = decode_cursor(after) if after else 0
+
+    # Fetch users
+    users = await fetch_users(
+        limit=first + 1,  # Fetch one extra to check hasNextPage
+        offset=offset,
+        search=search
+    )
+
+    # Pagination
+    has_next = len(users) > first
+    if has_next:
+        users = users[:first]
+
+    edges = [
+        {
+            "node": user,
+            "cursor": encode_cursor(offset + i)
+        }
+        for i, user in enumerate(users)
+    ]
+
+    return {
+        "edges": edges,
+        "pageInfo": {
+            "hasNextPage": has_next,
+            "hasPreviousPage": offset > 0,
+            "startCursor": edges[0]["cursor"] if edges else None,
+            "endCursor": edges[-1]["cursor"] if edges else None
+        },
+        "totalCount": await count_users(search=search)
+    }
+
+@user_type.field("orders")
+async def resolve_user_orders(user: dict, info, first: int = 20) -> dict:
+    """Resolve user's orders (N+1 prevention with DataLoader)."""
+    # Use DataLoader to batch requests
+    loader = info.context["loaders"]["orders_by_user"]
+    orders = await loader.load(user["id"])
+
+    return paginate_orders(orders, first)
+
+@mutation.field("createUser")
+async def resolve_create_user(obj, info, input: dict) -> dict:
+    """Create new user."""
+    try:
+        # Validate input
+        validate_user_input(input)
+
+        # Create user
+        user = await create_user(
+            email=input["email"],
+            name=input["name"],
+            password=hash_password(input["password"])
+        )
+
+        return {
+            "user": user,
+            "errors": []
+        }
+    except ValidationError as e:
+        return {
+            "user": None,
+            "errors": [{"field": e.field, "message": e.message}]
+        }
+```
+
+### Pattern 3: DataLoader (N+1 Problem Prevention)
+
+```python
+from aiodataloader import DataLoader
+from typing import List, Optional
+
+class UserLoader(DataLoader):
+    """Batch load users by ID."""
+
+    async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:
+        """Load multiple users in single query."""
+        users = await fetch_users_by_ids(user_ids)
+
+        # Map results back to input order
+        user_map = {user["id"]: user for user in users}
+        return [user_map.get(user_id) for user_id in user_ids]
+
+class OrdersByUserLoader(DataLoader):
+    """Batch load orders by user ID."""
+
+    async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:
+        """Load orders for multiple users in single query."""
+        orders = await fetch_orders_by_user_ids(user_ids)
+
+        # Group orders by user_id
+        orders_by_user = {}
+        for order in orders:
+            user_id = order["user_id"]
+            if user_id not in orders_by_user:
+                orders_by_user[user_id] = []
+            orders_by_user[user_id].append(order)
+
+        # Return in input order
+        return [orders_by_user.get(user_id, []) for user_id in user_ids]
+
+# Context setup
+def create_context():
+    return {
+        "loaders": {
+            "user": UserLoader(),
+            "orders_by_user": OrdersByUserLoader()
+        }
+    }
+```
+
+## Best Practices
+
+### REST APIs
+
+1. **Consistent Naming**: Use plural nouns for collections (`/users`, not `/user`)
+2. **Stateless**: Each request contains all necessary information
+3. **Use HTTP Status Codes Correctly**: 2xx success, 4xx client errors, 5xx server errors
+4. **Version Your API**: Plan for breaking changes from day one
+5. **Pagination**: Always paginate large collections
+6. **Rate Limiting**: Protect your API with rate limits
+7. **Documentation**: Use OpenAPI/Swagger for interactive docs
+
+### GraphQL APIs
+
+1. **Schema First**: Design schema before writing resolvers
+2. **Avoid N+1**: Use DataLoaders for efficient data fetching
+3. **Input Validation**: Validate at schema and resolver levels
+4. **Error Handling**: Return structured errors in mutation payloads
+5. **Pagination**: Use cursor-based pagination (Relay spec)
+6. **Deprecation**: Use `@deprecated` directive for gradual migration
+7. **Monitoring**: Track query complexity and execution time
+
+## Common Pitfalls
+
+- **Over-fetching/Under-fetching (REST)**: Fixed in GraphQL but requires DataLoaders
+- **Breaking Changes**: Version APIs or use deprecation strategies
+- **Inconsistent Error Formats**: Standardize error responses
+- **Missing Rate Limits**: APIs without limits are vulnerable to abuse
+- **Poor Documentation**: Undocumented APIs frustrate developers
+- **Ignoring HTTP Semantics**: POST for idempotent operations breaks expectations
+- **Tight Coupling**: API structure shouldn't mirror database schema
diff --git a/builtin-skills/software-engineer/api-design-principles/assets/api-design-checklist.md b/builtin-skills/software-engineer/api-design-principles/assets/api-design-checklist.md
new file mode 100644
index 00000000..b78148bf
--- /dev/null
+++ b/builtin-skills/software-engineer/api-design-principles/assets/api-design-checklist.md
@@ -0,0 +1,155 @@
+# API Design Checklist
+
+## Pre-Implementation Review
+
+### Resource Design
+
+- [ ] Resources are nouns, not verbs
+- [ ] Plural names for collections
+- [ ] Consistent naming across all endpoints
+- [ ] Clear resource hierarchy (avoid deep nesting >2 levels)
+- [ ] All CRUD operations properly mapped to HTTP methods
+
+### HTTP Methods
+
+- [ ] GET for retrieval (safe, idempotent)
+- [ ] POST for creation
+- [ ] PUT for full replacement (idempotent)
+- [ ] PATCH for partial updates
+- [ ] DELETE for removal (idempotent)
+
+### Status Codes
+
+- [ ] 200 OK for successful GET/PATCH/PUT
+- [ ] 201 Created for POST
+- [ ] 204 No Content for DELETE
+- [ ] 400 Bad Request for malformed requests
+- [ ] 401 Unauthorized for missing auth
+- [ ] 403 Forbidden for insufficient permissions
+- [ ] 404 Not Found for missing resources
+- [ ] 422 Unprocessable Entity for validation errors
+- [ ] 429 Too Many Requests for rate limiting
+- [ ] 500 Internal Server Error for server issues
+
+### Pagination
+
+- [ ] All collection endpoints paginated
+- [ ] Default page size defined (e.g., 20)
+- [ ] Maximum page size enforced (e.g., 100)
+- [ ] Pagination metadata included (total, pages, etc.)
+- [ ] Cursor-based or offset-based pattern chosen
+
+### Filtering & Sorting
+
+- [ ] Query parameters for filtering
+- [ ] Sort parameter supported
+- [ ] Search parameter for full-text search
+- [ ] Field selection supported (sparse fieldsets)
+
+### Versioning
+
+- [ ] Versioning strategy defined (URL/header/query)
+- [ ] Version included in all endpoints
+- [ ] Deprecation policy documented
+
+### Error Handling
+
+- [ ] Consistent error response format
+- [ ] Detailed error messages
+- [ ] Field-level validation errors
+- [ ] Error codes for client handling
+- [ ] Timestamps in error responses
+
+### Authentication & Authorization
+
+- [ ] Authentication method defined (Bearer token, API key)
+- [ ] Authorization checks on all endpoints
+- [ ] 401 vs 403 used correctly
+- [ ] Token expiration handled
+
+### Rate Limiting
+
+- [ ] Rate limits defined per endpoint/user
+- [ ] Rate limit headers included
+- [ ] 429 status code for exceeded limits
+- [ ] Retry-After header provided
+
+### Documentation
+
+- [ ] OpenAPI/Swagger spec generated
+- [ ] All endpoints documented
+- [ ] Request/response examples provided
+- [ ] Error responses documented
+- [ ] Authentication flow documented
+
+### Testing
+
+- [ ] Unit tests for business logic
+- [ ] Integration tests for endpoints
+- [ ] Error scenarios tested
+- [ ] Edge cases covered
+- [ ] Performance tests for heavy endpoints
+
+### Security
+
+- [ ] Input validation on all fields
+- [ ] SQL injection prevention
+- [ ] XSS prevention
+- [ ] CORS configured correctly
+- [ ] HTTPS enforced
+- [ ] Sensitive data not in URLs
+- [ ] No secrets in responses
+
+### Performance
+
+- [ ] Database queries optimized
+- [ ] N+1 queries prevented
+- [ ] Caching strategy defined
+- [ ] Cache headers set appropriately
+- [ ] Large responses paginated
+
+### Monitoring
+
+- [ ] Logging implemented
+- [ ] Error tracking configured
+- [ ] Performance metrics collected
+- [ ] Health check endpoint available
+- [ ] Alerts configured for errors
+
+## GraphQL-Specific Checks
+
+### Schema Design
+
+- [ ] Schema-first approach used
+- [ ] Types properly defined
+- [ ] Non-null vs nullable decided
+- [ ] Interfaces/unions used appropriately
+- [ ] Custom scalars defined
+
+### Queries
+
+- [ ] Query depth limiting
+- [ ] Query complexity analysis
+- [ ] DataLoaders prevent N+1
+- [ ] Pagination pattern chosen (Relay/offset)
+
+### Mutations
+
+- [ ] Input types defined
+- [ ] Payload types with errors
+- [ ] Optimistic response support
+- [ ] Idempotency considered
+
+### Performance
+
+- [ ] DataLoader for all relationships
+- [ ] Query batching enabled
+- [ ] Persisted queries considered
+- [ ] Response caching implemented
+
+### Documentation
+
+- [ ] All fields documented
+- [ ] Deprecations marked
+- [ ] Examples provided
+- [ ] Schema introspection enabled
diff --git a/builtin-skills/software-engineer/api-design-principles/references/graphql-schema-design.md b/builtin-skills/software-engineer/api-design-principles/references/graphql-schema-design.md
new file mode 100644
index 00000000..beca5f4f
--- /dev/null
+++ b/builtin-skills/software-engineer/api-design-principles/references/graphql-schema-design.md
@@ -0,0 +1,583 @@
+# GraphQL Schema Design Patterns
+
+## Schema Organization
+
+### Modular Schema Structure
+
+```graphql
+# user.graphql
+type User {
+  id: ID!
+  email: String!
+  name: String!
+  posts: [Post!]!
+}
+
+extend type Query {
+  user(id: ID!): User
+  users(first: Int, after: String): UserConnection!
+}
+
+extend type Mutation {
+  createUser(input: CreateUserInput!): CreateUserPayload!
+}
+
+# post.graphql
+type Post {
+  id: ID!
+  title: String!
+  content: String!
+  author: User!
+}
+
+extend type Query {
+  post(id: ID!): Post
+}
+```
+
+## Type Design Patterns
+
+### 1. Non-Null Types
+
+```graphql
+type User {
+  id: ID! # Always required
+  email: String! # Required
+  phone: String # Optional (nullable)
+  posts: [Post!]! # Non-null array of non-null posts
+  tags: [String!] # Nullable array of non-null strings
+}
+```
+
+### 2. Interfaces for Polymorphism
+
+```graphql
+interface Node {
+  id: ID!
+  createdAt: DateTime!
+}
+
+type User implements Node {
+  id: ID!
+  createdAt: DateTime!
+  email: String!
+}
+
+type Post implements Node {
+  id: ID!
+  createdAt: DateTime!
+  title: String!
+}
+
+type Query {
+  node(id: ID!): Node
+}
+```
+
+### 3. Unions for Heterogeneous Results
+
+```graphql
+union SearchResult = User | Post | Comment
+
+type Query {
+  search(query: String!): [SearchResult!]!
+}
+
+# Query example
+{
+  search(query: "graphql") {
+    ... on User {
+      name
+      email
+    }
+    ... on Post {
+      title
+      content
+    }
+    ... on Comment {
+      text
+      author {
+        name
+      }
+    }
+  }
+}
+```
+
+### 4. Input Types
+
+```graphql
+input CreateUserInput {
+  email: String!
+  name: String!
+  password: String!
+  profileInput: ProfileInput
+}
+
+input ProfileInput {
+  bio: String
+  avatar: String
+  website: String
+}
+
+input UpdateUserInput {
+  id: ID!
+  email: String
+  name: String
+  profileInput: ProfileInput
+}
+```
+
+## Pagination Patterns
+
+### Relay Cursor Pagination (Recommended)
+
+```graphql
+type UserConnection {
+  edges: [UserEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type UserEdge {
+  node: User!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+
+type Query {
+  users(first: Int, after: String, last: Int, before: String): UserConnection!
+}
+
+# Usage
+{
+  users(first: 10, after: "cursor123") {
+    edges {
+      cursor
+      node {
+        id
+        name
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+}
+```
+
+### Offset Pagination (Simpler)
+
+```graphql
+type UserList {
+  items: [User!]!
+  total: Int!
+  page: Int!
+  pageSize: Int!
+}
+
+type Query {
+  users(page: Int = 1, pageSize: Int = 20): UserList!
+}
+```
+
+## Mutation Design Patterns
+
+### 1. Input/Payload Pattern
+
+```graphql
+input CreatePostInput {
+  title: String!
+  content: String!
+  tags: [String!]
+}
+
+type CreatePostPayload {
+  post: Post
+  errors: [Error!]
+  success: Boolean!
+}
+
+type Error {
+  field: String
+  message: String!
+  code: String!
+}
+
+type Mutation {
+  createPost(input: CreatePostInput!): CreatePostPayload!
+}
+```
+
+### 2. Optimistic Response Support
+
+```graphql
+type UpdateUserPayload {
+  user: User
+  clientMutationId: String
+  errors: [Error!]
+}
+
+input UpdateUserInput {
+  id: ID!
+  name: String
+  clientMutationId: String
+}
+
+type Mutation {
+  updateUser(input: UpdateUserInput!): UpdateUserPayload!
+}
+```
+
+### 3. Batch Mutations
+
+```graphql
+input BatchCreateUserInput {
+  users: [CreateUserInput!]!
+}
+
+type BatchCreateUserPayload {
+  results: [CreateUserResult!]!
+  successCount: Int!
+  errorCount: Int!
+}
+
+type CreateUserResult {
+  user: User
+  errors: [Error!]
+  index: Int!
+}
+
+type Mutation {
+  batchCreateUsers(input: BatchCreateUserInput!): BatchCreateUserPayload!
+}
+```
+
+## Field Design
+
+### Arguments and Filtering
+
+```graphql
+type Query {
+  posts(
+    # Pagination
+    first: Int = 20
+    after: String
+
+    # Filtering
+    status: PostStatus
+    authorId: ID
+    tag: String
+
+    # Sorting
+    orderBy: PostOrderBy = CREATED_AT
+    orderDirection: OrderDirection = DESC
+
+    # Searching
+    search: String
+  ): PostConnection!
+}
+
+enum PostStatus {
+  DRAFT
+  PUBLISHED
+  ARCHIVED
+}
+
+enum PostOrderBy {
+  CREATED_AT
+  UPDATED_AT
+  TITLE
+}
+
+enum OrderDirection {
+  ASC
+  DESC
+}
+```
+
+### Computed Fields
+
+```graphql
+type User {
+  firstName: String!
+  lastName: String!
+  fullName: String! # Computed in resolver
+  posts: [Post!]!
+  postCount: Int! # Computed, doesn't load all posts
+}
+
+type Post {
+  likeCount: Int!
+  commentCount: Int!
+  isLikedByViewer: Boolean! # Context-dependent
+}
+```
+
+## Subscriptions
+
+```graphql
+type Subscription {
+  postAdded: Post!
+
+  postUpdated(postId: ID!): Post!
+
+  userStatusChanged(userId: ID!): UserStatus!
+}
+
+type UserStatus {
+  userId: ID!
+  online: Boolean!
+  lastSeen: DateTime!
+}
+
+# Client usage
+subscription {
+  postAdded {
+    id
+    title
+    author {
+      name
+    }
+  }
+}
+```
+
+## Custom Scalars
+
+```graphql
+scalar DateTime
+scalar Email
+scalar URL
+scalar JSON
+scalar Money
+
+type User {
+  email: Email!
+  website: URL
+  createdAt: DateTime!
+  metadata: JSON
+}
+
+type Product {
+  price: Money!
+}
+```
+
+## Directives
+
+### Built-in Directives
+
+```graphql
+type User {
+  name: String!
+  email: String! @deprecated(reason: "Use emails field instead")
+  emails: [String!]!
+
+  # Conditional inclusion
+  privateData: PrivateData @include(if: $isOwner)
+}
+
+# Query
+query GetUser($isOwner: Boolean!) {
+  user(id: "123") {
+    name
+    privateData @include(if: $isOwner) {
+      ssn
+    }
+  }
+}
+```
+
+### Custom Directives
+
+```graphql
+directive @auth(requires: Role = USER) on FIELD_DEFINITION
+
+enum Role {
+  USER
+  ADMIN
+  MODERATOR
+}
+
+type Mutation {
+  deleteUser(id: ID!): Boolean! @auth(requires: ADMIN)
+  updateProfile(input: ProfileInput!): User! @auth
+}
+```
+
+## Error Handling
+
+### Union Error Pattern
+
+```graphql
+type User {
+  id: ID!
+  email: String!
+}
+
+type ValidationError {
+  field: String!
+  message: String!
+}
+
+type NotFoundError {
+  message: String!
+  resourceType: String!
+  resourceId: ID!
+}
+
+type AuthorizationError {
+  message: String!
+}
+
+union UserResult = User | ValidationError | NotFoundError | AuthorizationError
+
+type Query {
+  user(id: ID!): UserResult!
+}
+
+# Usage
+{
+  user(id: "123") {
+    ... on User {
+      id
+      email
+    }
+    ... on NotFoundError {
+      message
+      resourceType
+    }
+    ... on AuthorizationError {
+      message
+    }
+  }
+}
+```
+
+### Errors in Payload
+
+```graphql
+type CreateUserPayload {
+  user: User
+  errors: [Error!]
+  success: Boolean!
+}
+
+type Error {
+  field: String
+  message: String!
+  code: ErrorCode!
+}
+
+enum ErrorCode {
+  VALIDATION_ERROR
+  UNAUTHORIZED
+  NOT_FOUND
+  INTERNAL_ERROR
+}
+```
+
+## N+1 Query Problem Solutions
+
+### DataLoader Pattern
+
+```python
+from aiodataloader import DataLoader
+
+class PostLoader(DataLoader):
+    async def batch_load_fn(self, post_ids):
+        posts = await db.posts.find({"id": {"$in": post_ids}})
+        post_map = {post["id"]: post for post in posts}
+        return [post_map.get(pid) for pid in post_ids]
+
+# Resolver
+@user_type.field("posts")
+async def resolve_posts(user, info):
+    loader = info.context["loaders"]["post"]
+    return await loader.load_many(user["post_ids"])
+```
+
+### Query Depth Limiting
+
+```python
+from graphql import GraphQLError
+
+def depth_limit_validator(max_depth: int):
+    def validate(context, node, ancestors):
+        depth = len(ancestors)
+        if depth > max_depth:
+            raise GraphQLError(
+                f"Query depth {depth} exceeds maximum {max_depth}"
+            )
+    return validate
+```
+
+### Query Complexity Analysis
+
+```python
+def complexity_limit_validator(max_complexity: int):
+    def calculate_complexity(node):
+        # Each field = 1, lists multiply
+        complexity = 1
+        if is_list_field(node):
+            complexity *= get_list_size_arg(node)
+        return complexity
+
+    return validate_complexity
+```
+
+## Schema Versioning
+
+### Field Deprecation
+
+```graphql
+type User {
+  name: String! @deprecated(reason: "Use firstName and lastName")
+  firstName: String!
+  lastName: String!
+}
+```
+
+### Schema Evolution
+
+```graphql
+# v1 - Initial
+type User {
+  name: String!
+}
+
+# v2 - Add optional field (backward compatible)
+type User {
+  name: String!
+  email: String
+}
+
+# v3 - Deprecate and add new field
+type User {
+  name: String! @deprecated(reason: "Use firstName/lastName")
+  firstName: String!
+  lastName: String!
+  email: String
+}
+```
+
+## Best Practices Summary
+
+1. **Nullable vs Non-Null**: Start nullable, make non-null when guaranteed
+2. **Input Types**: Always use input types for mutations
+3. **Payload Pattern**: Return errors in mutation payloads
+4. **Pagination**: Use cursor-based for infinite scroll, offset for simple cases
+5. **Naming**: Use camelCase for fields, PascalCase for types
+6. **Deprecation**: Use `@deprecated` instead of removing fields
+7. **DataLoaders**: Always use for relationships to prevent N+1
+8. **Complexity Limits**: Protect against expensive queries
+9. **Custom Scalars**: Use for domain-specific types (Email, DateTime)
+10. **Documentation**: Document all fields with descriptions
diff --git a/builtin-skills/software-engineer/api-design-principles/references/rest-best-practices.md b/builtin-skills/software-engineer/api-design-principles/references/rest-best-practices.md
new file mode 100644
index 00000000..676be296
--- /dev/null
+++ b/builtin-skills/software-engineer/api-design-principles/references/rest-best-practices.md
@@ -0,0 +1,408 @@
+# REST API Best Practices
+
+## URL Structure
+
+### Resource Naming
+
+```
+# Good - Plural nouns
+GET /api/users
+GET /api/orders
+GET /api/products
+
+# Bad - Verbs or mixed conventions
+GET /api/getUser
+GET /api/user  (inconsistent singular)
+POST /api/createOrder
+```
+
+### Nested Resources
+
+```
+# Shallow nesting (preferred)
+GET /api/users/{id}/orders
+GET /api/orders/{id}
+
+# Deep nesting (avoid)
+GET /api/users/{id}/orders/{orderId}/items/{itemId}/reviews
+# Better:
+GET /api/order-items/{id}/reviews
+```
+
+## HTTP Methods and Status Codes
+
+### GET - Retrieve Resources
+
+```
+GET /api/users              → 200 OK (with list)
+GET /api/users/{id}         → 200 OK or 404 Not Found
+GET /api/users?page=2       → 200 OK (paginated)
+```
+
+### POST - Create Resources
+
+```
+POST /api/users
+  Body: {"name": "John", "email": "john@example.com"}
+  → 201 Created
+  Location: /api/users/123
+  Body: {"id": "123", "name": "John", ...}
+
+POST /api/users (validation error)
+  → 422 Unprocessable Entity
+  Body: {"errors": [...]}
+```
+
+### PUT - Replace Resources
+
+```
+PUT /api/users/{id}
+  Body: {complete user object}
+  → 200 OK (updated)
+  → 404 Not Found (doesn't exist)
+
+# Must include ALL fields
+```
+
+### PATCH - Partial Update
+
+```
+PATCH /api/users/{id}
+  Body: {"name": "Jane"}  (only changed fields)
+  → 200 OK
+  → 404 Not Found
+```
+
+### DELETE - Remove Resources
+
+```
+DELETE /api/users/{id}
+  → 204 No Content (deleted)
+  → 404 Not Found
+  → 409 Conflict (can't delete due to references)
+```
+
+## Filtering, Sorting, and Searching
+
+### Query Parameters
+
+```
+# Filtering
+GET /api/users?status=active
+GET /api/users?role=admin&status=active
+
+# Sorting
+GET /api/users?sort=created_at
+GET /api/users?sort=-created_at  (descending)
+GET /api/users?sort=name,created_at
+
+# Searching
+GET /api/users?search=john
+GET /api/users?q=john
+
+# Field selection (sparse fieldsets)
+GET /api/users?fields=id,name,email
+```
+
+## Pagination Patterns
+
+### Offset-Based Pagination
+
+```python
+GET /api/users?page=2&page_size=20
+
+Response:
+{
+  "items": [...],
+  "page": 2,
+  "page_size": 20,
+  "total": 150,
+  "pages": 8
+}
+```
+
+### Cursor-Based Pagination (for large datasets)
+
+```python
+GET /api/users?limit=20&cursor=eyJpZCI6MTIzfQ
+
+Response:
+{
+  "items": [...],
+  "next_cursor": "eyJpZCI6MTQzfQ",
+  "has_more": true
+}
+```
+
+### Link Header Pagination (RESTful)
+
+```
+GET /api/users?page=2
+
+Response Headers:
+Link: <https://api.example.com/users?page=3>; rel="next",
+      <https://api.example.com/users?page=1>; rel="prev",
+      <https://api.example.com/users?page=1>; rel="first",
+      <https://api.example.com/users?page=8>; rel="last"
+```
+
+## Versioning Strategies
+
+### URL Versioning (Recommended)
+
+```
+/api/v1/users
+/api/v2/users
+
+Pros: Clear, easy to route
+Cons: Multiple URLs for same resource
+```
+
+### Header Versioning
+
+```
+GET /api/users
+Accept: application/vnd.api+json; version=2
+
+Pros: Clean URLs
+Cons: Less visible, harder to test
+```
+
+### Query Parameter
+
+```
+GET /api/users?version=2
+
+Pros: Easy to test
+Cons: Optional parameter can be forgotten
+```
+
+## Rate Limiting
+
+### Headers
+
+```
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 742
+X-RateLimit-Reset: 1640000000
+
+Response when limited:
+429 Too Many Requests
+Retry-After: 3600
+```
+
+### Implementation Pattern
+
+```python
+from fastapi import HTTPException, Request
+from datetime import datetime, timedelta
+
+class RateLimiter:
+    def __init__(self, calls: int, period: int):
+        self.calls = calls
+        self.period = period
+        self.cache = {}
+
+    def check(self, key: str) -> bool:
+        now = datetime.now()
+        if key not in self.cache:
+            self.cache[key] = []
+
+        # Remove old requests
+        self.cache[key] = [
+            ts for ts in self.cache[key]
+            if now - ts < timedelta(seconds=self.period)
+        ]
+
+        if len(self.cache[key]) >= self.calls:
+            return False
+
+        self.cache[key].append(now)
+        return True
+
+limiter = RateLimiter(calls=100, period=60)
+
+@app.get("/api/users")
+async def get_users(request: Request):
+    if not limiter.check(request.client.host):
+        raise HTTPException(
+            status_code=429,
+            headers={"Retry-After": "60"}
+        )
+    return {"users": [...]}
+```
+
+## Authentication and Authorization
+
+### Bearer Token
+
+```
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+
+401 Unauthorized - Missing/invalid token
+403 Forbidden - Valid token, insufficient permissions
+```
+
+### API Keys
+
+```
+X-API-Key: your-api-key-here
+```
+
+## Error Response Format
+
+### Consistent Structure
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format",
+        "value": "not-an-email"
+      }
+    ],
+    "timestamp": "2025-10-16T12:00:00Z",
+    "path": "/api/users"
+  }
+}
+```
+
+### Status Code Guidelines
+
+- `200 OK`: Successful GET, PATCH, PUT
+- `201 Created`: Successful POST
+- `204 No Content`: Successful DELETE
+- `400 Bad Request`: Malformed request
+- `401 Unauthorized`: Authentication required
+- `403 Forbidden`: Authenticated but not authorized
+- `404 Not Found`: Resource doesn't exist
+- `409 Conflict`: State conflict (duplicate email, etc.)
+- `422 Unprocessable Entity`: Validation errors
+- `429 Too Many Requests`: Rate limited
+- `500 Internal Server Error`: Server error
+- `503 Service Unavailable`: Temporary downtime
+
+## Caching
+
+### Cache Headers
+
+```
+# Client caching
+Cache-Control: public, max-age=3600
+
+# No caching
+Cache-Control: no-cache, no-store, must-revalidate
+
+# Conditional requests
+ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
+If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
+→ 304 Not Modified
+```
+
+## Bulk Operations
+
+### Batch Endpoints
+
+```python
+POST /api/users/batch
+{
+  "items": [
+    {"name": "User1", "email": "user1@example.com"},
+    {"name": "User2", "email": "user2@example.com"}
+  ]
+}
+
+Response:
+{
+  "results": [
+    {"id": "1", "status": "created"},
+    {"id": null, "status": "failed", "error": "Email already exists"}
+  ]
+}
+```
+
+## Idempotency
+
+### Idempotency Keys
+
+```
+POST /api/orders
+Idempotency-Key: unique-key-123
+
+If duplicate request:
+→ 200 OK (return cached response)
+```
+
+## CORS Configuration
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["https://example.com"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+## Documentation with OpenAPI
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI(
+    title="My API",
+    description="API for managing users",
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc"
+)
+
+@app.get(
+    "/api/users/{user_id}",
+    summary="Get user by ID",
+    response_description="User details",
+    tags=["Users"]
+)
+async def get_user(
+    user_id: str = Path(..., description="The user ID")
+):
+    """
+    Retrieve user by ID.
+
+    Returns full user profile including:
+    - Basic information
+    - Contact details
+    - Account status
+    """
+    pass
+```
+
+## Health and Monitoring Endpoints
+
+```python
+@app.get("/health")
+async def health_check():
+    return {
+        "status": "healthy",
+        "version": "1.0.0",
+        "timestamp": datetime.now().isoformat()
+    }
+
+@app.get("/health/detailed")
+async def detailed_health():
+    return {
+        "status": "healthy",
+        "checks": {
+            "database": await check_database(),
+            "redis": await check_redis(),
+            "external_api": await check_external_api()
+        }
+    }
+```
diff --git a/builtin-skills/software-engineer/clean-architecture/SKILL.md b/builtin-skills/software-engineer/clean-architecture/SKILL.md
new file mode 100644
index 00000000..7e0bf348
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/SKILL.md
@@ -0,0 +1,113 @@
+---
+name: clean-architecture
+description: Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.
+---
+
+# Clean Architecture Best Practices
+
+Comprehensive guide to Clean Architecture principles for designing maintainable, testable software systems. Based on Robert C. Martin's "Clean Architecture: A Craftsman's Guide to Software Structure and Design." Contains 42 rules across 8 categories, prioritized by architectural impact.
+
+## When to Apply
+
+Reference these guidelines when:
+- Designing new software systems or modules
+- Structuring dependencies between layers
+- Defining boundaries between business logic and infrastructure
+- Reviewing code for architectural violations
+- Refactoring coupled systems toward cleaner structure
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Dependency Direction | CRITICAL | `dep-` |
+| 2 | Entity Design | CRITICAL | `entity-` |
+| 3 | Use Case Isolation | HIGH | `usecase-` |
+| 4 | Component Cohesion | HIGH | `comp-` |
+| 5 | Boundary Definition | MEDIUM-HIGH | `bound-` |
+| 6 | Interface Adapters | MEDIUM | `adapt-` |
+| 7 | Framework Isolation | MEDIUM | `frame-` |
+| 8 | Testing Architecture | LOW-MEDIUM | `test-` |
+
+## Quick Reference
+
+### 1. Dependency Direction (CRITICAL)
+
+- [`dep-inward-only`](references/dep-inward-only.md) - Source dependencies point inward only
+- [`dep-interface-ownership`](references/dep-interface-ownership.md) - Interfaces belong to clients not implementers
+- [`dep-no-framework-imports`](references/dep-no-framework-imports.md) - Avoid framework imports in inner layers
+- [`dep-data-crossing-boundaries`](references/dep-data-crossing-boundaries.md) - Use simple data structures across boundaries
+- [`dep-acyclic-dependencies`](references/dep-acyclic-dependencies.md) - Eliminate cyclic dependencies between components
+- [`dep-stable-abstractions`](references/dep-stable-abstractions.md) - Depend on stable abstractions not volatile concretions
+
+### 2. Entity Design (CRITICAL)
+
+- [`entity-pure-business-rules`](references/entity-pure-business-rules.md) - Entities contain only enterprise business rules
+- [`entity-no-persistence-awareness`](references/entity-no-persistence-awareness.md) - Entities must not know how they are persisted
+- [`entity-encapsulate-invariants`](references/entity-encapsulate-invariants.md) - Encapsulate business invariants within entities
+- [`entity-value-objects`](references/entity-value-objects.md) - Use value objects for domain concepts
+- [`entity-rich-not-anemic`](references/entity-rich-not-anemic.md) - Build rich domain models not anemic data structures
+
+### 3. Use Case Isolation (HIGH)
+
+- [`usecase-single-responsibility`](references/usecase-single-responsibility.md) - Each use case has one reason to change
+- [`usecase-input-output-ports`](references/usecase-input-output-ports.md) - Define input and output ports for use cases
+- [`usecase-orchestrates-not-implements`](references/usecase-orchestrates-not-implements.md) - Use cases orchestrate entities not implement business rules
+- [`usecase-no-presentation-logic`](references/usecase-no-presentation-logic.md) - Use cases must not contain presentation logic
+- [`usecase-explicit-dependencies`](references/usecase-explicit-dependencies.md) - Declare all dependencies explicitly in constructor
+- [`usecase-transaction-boundary`](references/usecase-transaction-boundary.md) - Use case defines the transaction boundary
+
+### 4. Component Cohesion (HIGH)
+
+- [`comp-screaming-architecture`](references/comp-screaming-architecture.md) - Structure should scream the domain not the framework
+- [`comp-common-closure`](references/comp-common-closure.md) - Group classes that change together
+- [`comp-common-reuse`](references/comp-common-reuse.md) - Avoid forcing clients to depend on unused code
+- [`comp-reuse-release-equivalence`](references/comp-reuse-release-equivalence.md) - Release components as cohesive units
+- [`comp-stable-dependencies`](references/comp-stable-dependencies.md) - Depend in the direction of stability
+
+### 5. Boundary Definition (MEDIUM-HIGH)
+
+- [`bound-humble-object`](references/bound-humble-object.md) - Use humble objects at architectural boundaries
+- [`bound-partial-boundaries`](references/bound-partial-boundaries.md) - Use partial boundaries when full separation is premature
+- [`bound-boundary-cost-awareness`](references/bound-boundary-cost-awareness.md) - Weigh boundary cost against ignorance cost
+- [`bound-main-component`](references/bound-main-component.md) - Treat main as a plugin to the application
+- [`bound-defer-decisions`](references/bound-defer-decisions.md) - Defer framework and database decisions
+- [`bound-service-internal-architecture`](references/bound-service-internal-architecture.md) - Services must have internal clean architecture
+
+### 6. Interface Adapters (MEDIUM)
+
+- [`adapt-controller-thin`](references/adapt-controller-thin.md) - Keep controllers thin
+- [`adapt-presenter-formats`](references/adapt-presenter-formats.md) - Presenters format data for the view
+- [`adapt-gateway-abstraction`](references/adapt-gateway-abstraction.md) - Gateways hide external system details
+- [`adapt-mapper-translation`](references/adapt-mapper-translation.md) - Use mappers to translate between layers
+- [`adapt-anti-corruption-layer`](references/adapt-anti-corruption-layer.md) - Build anti-corruption layers for external systems
+
+### 7. Framework Isolation (MEDIUM)
+
+- [`frame-domain-purity`](references/frame-domain-purity.md) - Domain layer has zero framework dependencies
+- [`frame-orm-in-infrastructure`](references/frame-orm-in-infrastructure.md) - Keep ORM usage in infrastructure layer
+- [`frame-web-in-infrastructure`](references/frame-web-in-infrastructure.md) - Web framework concerns stay in interface layer
+- [`frame-di-container-edge`](references/frame-di-container-edge.md) - Dependency injection containers live at the edge
+- [`frame-logging-abstraction`](references/frame-logging-abstraction.md) - Abstract logging behind domain interfaces
+
+### 8. Testing Architecture (LOW-MEDIUM)
+
+- [`test-tests-are-architecture`](references/test-tests-are-architecture.md) - Tests are part of the system architecture
+- [`test-testable-design`](references/test-testable-design.md) - Design for testability from the start
+- [`test-layer-isolation`](references/test-layer-isolation.md) - Test each layer in isolation
+- [`test-boundary-verification`](references/test-boundary-verification.md) - Verify architectural boundaries with tests
+
+## How to Use
+
+Read individual reference files for detailed explanations and code examples:
+
+- [Section definitions](references/_sections.md) - Category structure and impact levels
+- [Rule template](assets/templates/_template.md) - Template for adding new rules
+
+## Reference Files
+
+| File | Description |
+|------|-------------|
+| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
+| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
+| [metadata.json](metadata.json) | Version and reference information |
diff --git a/builtin-skills/software-engineer/clean-architecture/assets/templates/_template.md b/builtin-skills/software-engineer/clean-architecture/assets/templates/_template.md
new file mode 100644
index 00000000..5840911f
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/assets/templates/_template.md
@@ -0,0 +1,40 @@
+---
+title: Rule Title in Imperative Form
+impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
+impactDescription: quantified impact, e.g., "prevents cascade failures", "2-10× testability improvement"
+tags: prefix, technique1, technique2, concept
+---
+
+## Rule Title in Imperative Form
+
+Brief explanation (1-3 sentences) of WHY this matters for software architecture. Focus on the architectural implications and cascade effects.
+
+**Incorrect (description of problem/cost):**
+
+```language
+// Code example showing the anti-pattern
+// Include comments on problematic lines explaining the cost
+```
+
+**Correct (description of benefit/solution):**
+
+```language
+// Code example showing the correct pattern
+// Minimal diff from incorrect - same variable names, structure
+```
+
+**Alternative (when applicable):**
+
+```language
+// Alternative approach for specific contexts
+```
+
+**When NOT to use this pattern:**
+- Exception or edge case 1
+- Exception or edge case 2
+
+**Benefits:**
+- Concrete benefit 1
+- Concrete benefit 2
+
+Reference: [Source Title](URL)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/_sections.md b/builtin-skills/software-engineer/clean-architecture/references/_sections.md
new file mode 100644
index 00000000..f0570368
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/_sections.md
@@ -0,0 +1,46 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Dependency Direction (dep)
+
+**Impact:** CRITICAL
+**Description:** The Dependency Rule is the architectural foundation. Source code dependencies must point inward only; violations cascade failures across all layers.
+
+## 2. Entity Design (entity)
+
+**Impact:** CRITICAL
+**Description:** Enterprise business rules must be framework-agnostic, stable, and completely independent of databases, UI, and external systems.
+
+## 3. Use Case Isolation (usecase)
+
+**Impact:** HIGH
+**Description:** Application-specific business rules orchestrate entities without leaking infrastructure details or depending on presentation concerns.
+
+## 4. Component Cohesion (comp)
+
+**Impact:** HIGH
+**Description:** Components grouped by business capability enable independent deployment, parallel team development, and controlled change propagation.
+
+## 5. Boundary Definition (bound)
+
+**Impact:** MEDIUM-HIGH
+**Description:** Architectural boundaries isolate volatile from stable elements; Humble Objects maximize testability by separating hard-to-test from easy-to-test code.
+
+## 6. Interface Adapters (adapt)
+
+**Impact:** MEDIUM
+**Description:** Controllers, presenters, and gateways translate between use cases and external systems without leaking implementation details.
+
+## 7. Framework Isolation (frame)
+
+**Impact:** MEDIUM
+**Description:** Frameworks are details, not architecture. Business logic must never import, reference, or depend on framework-specific types.
+
+## 8. Testing Architecture (test)
+
+**Impact:** LOW-MEDIUM
+**Description:** Tests are architectural components. Layer isolation enables fast unit tests, while boundaries enable targeted integration tests.
diff --git a/builtin-skills/software-engineer/clean-architecture/references/adapt-anti-corruption-layer.md b/builtin-skills/software-engineer/clean-architecture/references/adapt-anti-corruption-layer.md
new file mode 100644
index 00000000..90bff904
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/adapt-anti-corruption-layer.md
@@ -0,0 +1,112 @@
+---
+title: Build Anti-Corruption Layers for External Systems
+impact: MEDIUM
+impactDescription: protects domain from external model pollution
+tags: adapt, anti-corruption, external, isolation
+---
+
+## Build Anti-Corruption Layers for External Systems
+
+When integrating with external systems that have different models, build an anti-corruption layer (ACL) that translates between their model and yours. Never let external concepts pollute your domain.
+
+**Incorrect (external model leaks into domain):**
+
+```java
+// Domain polluted with Stripe's model
+public class Order {
+    private String id;
+    private List<OrderItem> items;
+    // Stripe-specific fields in domain
+    private String stripeCustomerId;
+    private String stripePaymentIntentId;
+    private String stripePaymentMethodId;
+
+    public void processPayment(Stripe stripe) {
+        // Domain directly calls Stripe
+        PaymentIntent intent = PaymentIntent.create(
+            PaymentIntentCreateParams.builder()
+                .setCustomer(this.stripeCustomerId)
+                .setPaymentMethod(this.stripePaymentMethodId)
+                .setAmount(this.calculateTotal().cents())
+                .setCurrency("usd")
+                .build()
+        );
+        this.stripePaymentIntentId = intent.getId();
+    }
+}
+
+// If we switch to PayPal, Order must change
+```
+
+**Correct (anti-corruption layer isolates external model):**
+
+```java
+// domain/Order.java - Pure domain, no external concepts
+public class Order {
+    private OrderId id;
+    private CustomerId customerId;
+    private List<OrderItem> items;
+    private PaymentStatus paymentStatus;
+
+    public Money calculateTotal() {
+        return items.stream()
+            .map(OrderItem::lineTotal)
+            .reduce(Money.zero(), Money::add);
+    }
+
+    public void markPaid(PaymentReference reference) {
+        this.paymentStatus = PaymentStatus.paid(reference);
+    }
+}
+
+// domain/ports/PaymentProcessor.java - Domain-defined port
+public interface PaymentProcessor {
+    PaymentResult charge(CustomerId customer, Money amount);
+}
+
+// Domain-defined value objects
+public record PaymentResult(PaymentReference reference, PaymentStatus status) {}
+public record PaymentReference(String value) {}
+
+// infrastructure/stripe/StripePaymentProcessor.java - ACL
+public class StripePaymentProcessor implements PaymentProcessor {
+    private final CustomerMappingRepository customerMapping;
+
+    public PaymentResult charge(CustomerId customerId, Money amount) {
+        // Translate domain CustomerId to Stripe customer
+        String stripeCustomerId = customerMapping.getStripeId(customerId);
+
+        // Call Stripe with their model
+        PaymentIntent intent = PaymentIntent.create(
+            PaymentIntentCreateParams.builder()
+                .setCustomer(stripeCustomerId)
+                .setAmount(amount.cents())
+                .setCurrency("usd")
+                .setConfirm(true)
+                .build()
+        );
+
+        // Translate Stripe response back to domain model
+        return new PaymentResult(
+            new PaymentReference(intent.getId()),
+            translateStatus(intent.getStatus())
+        );
+    }
+
+    private PaymentStatus translateStatus(String stripeStatus) {
+        return switch (stripeStatus) {
+            case "succeeded" -> PaymentStatus.COMPLETED;
+            case "processing" -> PaymentStatus.PENDING;
+            case "requires_action" -> PaymentStatus.REQUIRES_ACTION;
+            default -> PaymentStatus.FAILED;
+        };
+    }
+}
+```
+
+**Benefits:**
+- Domain model remains clean and business-focused
+- Switch payment providers by implementing new ACL
+- External API changes isolated to ACL
+
+Reference: [Anti-Corruption Layer Pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/anti-corruption-layer)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/adapt-controller-thin.md b/builtin-skills/software-engineer/clean-architecture/references/adapt-controller-thin.md
new file mode 100644
index 00000000..e2c71c9f
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/adapt-controller-thin.md
@@ -0,0 +1,101 @@
+---
+title: Keep Controllers Thin
+impact: MEDIUM
+impactDescription: simplifies testing, isolates HTTP concerns
+tags: adapt, controller, thin, http
+---
+
+## Keep Controllers Thin
+
+Controllers should only handle HTTP concerns: parsing requests, validating input format, calling use cases, and formatting responses. No business logic.
+
+**Incorrect (fat controller with business logic):**
+
+```python
+class OrderController:
+    @app.route('/orders', methods=['POST'])
+    def create_order(self):
+        data = request.json
+
+        # Input validation - OK in controller
+        if not data.get('items'):
+            return jsonify({'error': 'Items required'}), 400
+
+        # Business logic - WRONG in controller
+        customer = db.query(Customer).get(data['customer_id'])
+        if not customer.is_active:
+            return jsonify({'error': 'Inactive customer'}), 400
+
+        total = 0
+        for item in data['items']:
+            product = db.query(Product).get(item['product_id'])
+            if product.stock < item['quantity']:
+                return jsonify({'error': f'{product.name} out of stock'}), 400
+            total += product.price * item['quantity']
+
+        # More business logic
+        if total > customer.credit_limit:
+            return jsonify({'error': 'Exceeds credit limit'}), 400
+
+        order = Order(
+            customer_id=customer.id,
+            items=data['items'],
+            total=total
+        )
+        db.session.add(order)
+        db.session.commit()
+
+        return jsonify({'order_id': order.id}), 201
+```
+
+**Correct (thin controller delegates to use case):**
+
+```python
+class OrderController:
+    def __init__(self, create_order_use_case: CreateOrderUseCase):
+        self.create_order = create_order_use_case
+
+    @app.route('/orders', methods=['POST'])
+    def create(self):
+        # Parse HTTP request
+        data = request.json
+
+        # Validate request format (not business rules)
+        if not data.get('items'):
+            return jsonify({'error': 'Items required'}), 400
+
+        # Build command
+        command = CreateOrderCommand(
+            customer_id=data['customer_id'],
+            items=[
+                OrderItemCommand(p['product_id'], p['quantity'])
+                for p in data['items']
+            ]
+        )
+
+        # Delegate to use case
+        try:
+            result = self.create_order.execute(command)
+            return jsonify({'order_id': result.order_id}), 201
+
+        except CustomerInactiveError:
+            return jsonify({'error': 'Customer account inactive'}), 400
+        except InsufficientStockError as e:
+            return jsonify({'error': f'{e.product_name} out of stock'}), 400
+        except CreditLimitExceededError:
+            return jsonify({'error': 'Order exceeds credit limit'}), 400
+```
+
+**Controller responsibilities:**
+- Parse HTTP request to command/query objects
+- Validate request format (required fields present)
+- Call appropriate use case
+- Map exceptions to HTTP status codes
+- Format response
+
+**Use case responsibilities:**
+- Business validation (credit limits, stock)
+- Business logic (calculations, state changes)
+- Orchestrate entities and repositories
+
+Reference: [Clean Architecture - Controllers](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch22.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/adapt-gateway-abstraction.md b/builtin-skills/software-engineer/clean-architecture/references/adapt-gateway-abstraction.md
new file mode 100644
index 00000000..bff2871a
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/adapt-gateway-abstraction.md
@@ -0,0 +1,119 @@
+---
+title: Gateways Hide External System Details
+impact: MEDIUM
+impactDescription: enables vendor switching, simplifies testing
+tags: adapt, gateway, external, abstraction
+---
+
+## Gateways Hide External System Details
+
+Database gateways, API gateways, and service gateways are polymorphic interfaces that hide external system details. The use case layer talks to abstractions; infrastructure implements them.
+
+**Incorrect (use case knows external system details):**
+
+```go
+func (uc *ProcessRefundUseCase) Execute(orderId string) error {
+    order := uc.db.QueryRow("SELECT * FROM orders WHERE id = $1", orderId)
+
+    // Direct Stripe API knowledge in use case
+    stripe.Key = os.Getenv("STRIPE_KEY")
+    params := &stripe.RefundParams{
+        PaymentIntent: stripe.String(order.PaymentIntentId),
+        Amount:        stripe.Int64(order.Total),
+    }
+    _, err := refund.New(params)
+    if err != nil {
+        // Stripe-specific error handling
+        if stripeErr, ok := err.(*stripe.Error); ok {
+            if stripeErr.Code == stripe.ErrorCodeChargeAlreadyRefunded {
+                return ErrAlreadyRefunded
+            }
+        }
+        return err
+    }
+
+    uc.db.Exec("UPDATE orders SET status = 'refunded' WHERE id = $1", orderId)
+    return nil
+}
+```
+
+**Correct (gateway abstracts external system):**
+
+```go
+// application/ports/PaymentGateway.go
+type PaymentGateway interface {
+    Refund(paymentId string, amount Money) (RefundResult, error)
+}
+
+type RefundResult struct {
+    RefundId string
+    Status   RefundStatus
+}
+
+// application/ports/OrderRepository.go
+type OrderRepository interface {
+    FindById(id OrderId) (*Order, error)
+    Save(order *Order) error
+}
+
+// application/usecases/ProcessRefundUseCase.go
+type ProcessRefundUseCase struct {
+    orders   OrderRepository
+    payments PaymentGateway
+}
+
+func (uc *ProcessRefundUseCase) Execute(orderId string) error {
+    order, err := uc.orders.FindById(OrderId(orderId))
+    if err != nil {
+        return err
+    }
+
+    result, err := uc.payments.Refund(order.PaymentId, order.Total)
+    if err != nil {
+        return err  // Gateway translates Stripe errors to domain errors
+    }
+
+    order.MarkRefunded(result.RefundId)
+    return uc.orders.Save(order)
+}
+
+// infrastructure/StripePaymentGateway.go
+type StripePaymentGateway struct {
+    client *stripe.Client
+}
+
+func (g *StripePaymentGateway) Refund(paymentId string, amount Money) (RefundResult, error) {
+    params := &stripe.RefundParams{
+        PaymentIntent: stripe.String(paymentId),
+        Amount:        stripe.Int64(amount.Cents()),
+    }
+
+    refund, err := g.client.Refunds.New(params)
+    if err != nil {
+        return RefundResult{}, g.translateError(err)
+    }
+
+    return RefundResult{
+        RefundId: refund.ID,
+        Status:   g.translateStatus(refund.Status),
+    }, nil
+}
+
+func (g *StripePaymentGateway) translateError(err error) error {
+    // Convert Stripe-specific errors to domain errors
+    if stripeErr, ok := err.(*stripe.Error); ok {
+        switch stripeErr.Code {
+        case stripe.ErrorCodeChargeAlreadyRefunded:
+            return ErrAlreadyRefunded
+        }
+    }
+    return ErrPaymentFailed
+}
+```
+
+**Benefits:**
+- Switch from Stripe to Adyen without touching use cases
+- Test use cases with mock gateways
+- External API changes isolated to gateway implementation
+
+Reference: [Clean Architecture - Database Gateways](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch22.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/adapt-mapper-translation.md b/builtin-skills/software-engineer/clean-architecture/references/adapt-mapper-translation.md
new file mode 100644
index 00000000..c8113b9e
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/adapt-mapper-translation.md
@@ -0,0 +1,119 @@
+---
+title: Use Mappers to Translate Between Layers
+impact: MEDIUM
+impactDescription: decouples domain from persistence and presentation models
+tags: adapt, mapper, translation, layers
+---
+
+## Use Mappers to Translate Between Layers
+
+Mappers translate between domain entities and external representations (database rows, API responses, DTOs). Each layer has its own model; mappers bridge them.
+
+**Incorrect (domain entity used everywhere):**
+
+```typescript
+// Domain entity directly serialized to JSON and stored in DB
+class User {
+  id: string
+  email: string
+  passwordHash: string  // Exposed in API response!
+  createdAt: Date
+  lastLogin: Date
+  preferences: UserPreferences
+  roles: Role[]
+
+  toJSON() {
+    return { ...this }  // Leaks everything
+  }
+}
+
+// Controller returns entity directly
+app.get('/users/:id', (req, res) => {
+  const user = userRepo.findById(req.params.id)
+  res.json(user)  // passwordHash in response!
+})
+
+// ORM couples domain to database schema
+@Entity()
+class User {
+  @PrimaryColumn() id: string
+  @Column() email: string
+  // Domain entity is now a database entity
+}
+```
+
+**Correct (dedicated models per layer with mappers):**
+
+```typescript
+// domain/User.ts - Pure domain entity
+class User {
+  constructor(
+    readonly id: UserId,
+    private email: Email,
+    private passwordHash: PasswordHash,
+    private roles: Set<Role>
+  ) {}
+
+  hasRole(role: Role): boolean {
+    return this.roles.has(role)
+  }
+}
+
+// infrastructure/persistence/UserEntity.ts - Database model
+interface UserRow {
+  id: string
+  email: string
+  password_hash: string
+  roles: string  // JSON array in DB
+  created_at: string
+  updated_at: string
+}
+
+// infrastructure/persistence/UserMapper.ts
+class UserMapper {
+  toDomain(row: UserRow): User {
+    return new User(
+      new UserId(row.id),
+      Email.create(row.email),
+      new PasswordHash(row.password_hash),
+      new Set(JSON.parse(row.roles))
+    )
+  }
+
+  toPersistence(user: User): UserRow {
+    return {
+      id: user.id.value,
+      email: user.email.value,
+      password_hash: user.passwordHash.value,
+      roles: JSON.stringify([...user.roles]),
+      updated_at: new Date().toISOString()
+    }
+  }
+}
+
+// interface/dto/UserResponse.ts - API response model
+interface UserResponse {
+  id: string
+  email: string
+  roles: string[]
+  // No passwordHash!
+}
+
+// interface/mappers/UserResponseMapper.ts
+class UserResponseMapper {
+  toResponse(user: User): UserResponse {
+    return {
+      id: user.id.value,
+      email: user.email.value,
+      roles: [...user.roles]
+    }
+  }
+}
+```
+
+**Benefits:**
+- Database schema changes don't affect domain
+- API can evolve independently of domain model
+- Sensitive data never accidentally exposed
+
+Reference: [Data Mapper Pattern](https://martinfowler.com/eaaCatalog/dataMapper.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/adapt-presenter-formats.md b/builtin-skills/software-engineer/clean-architecture/references/adapt-presenter-formats.md
new file mode 100644
index 00000000..cb816802
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/adapt-presenter-formats.md
@@ -0,0 +1,109 @@
+---
+title: Presenters Format Data for the View
+impact: MEDIUM
+impactDescription: enables multiple view formats from same use case
+tags: adapt, presenter, formatting, view-model
+---
+
+## Presenters Format Data for the View
+
+Presenters accept data from use cases and format it for presentation. They create view models with strings, booleans, and pre-formatted values - nothing left for the view to compute.
+
+**Incorrect (view does formatting):**
+
+```tsx
+// View component does formatting - logic spread across UI
+function InvoiceView({ invoice }: { invoice: Invoice }) {
+  // Formatting logic in view
+  const formattedDate = new Date(invoice.dueDate).toLocaleDateString('en-US', {
+    month: 'long',
+    day: 'numeric',
+    year: 'numeric'
+  })
+
+  const formattedTotal = new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: invoice.currency
+  }).format(invoice.total / 100)
+
+  const statusColor = invoice.status === 'paid' ? 'green'
+    : invoice.status === 'overdue' ? 'red'
+    : 'yellow'
+
+  const daysOverdue = invoice.status === 'overdue'
+    ? Math.floor((Date.now() - new Date(invoice.dueDate).getTime()) / 86400000)
+    : 0
+
+  return (
+    <div>
+      <span style={{ color: statusColor }}>{invoice.status.toUpperCase()}</span>
+      <span>Due: {formattedDate}</span>
+      <span>Total: {formattedTotal}</span>
+      {daysOverdue > 0 && <span>{daysOverdue} days overdue</span>}
+    </div>
+  )
+}
+```
+
+**Correct (presenter formats, view renders):**
+
+```tsx
+// presenter/InvoicePresenter.ts
+interface InvoiceViewModel {
+  invoiceNumber: string
+  status: string
+  statusColor: 'green' | 'yellow' | 'red'
+  dueDate: string
+  total: string
+  overdueMessage: string | null
+}
+
+class InvoicePresenter {
+  present(invoice: InvoiceResult, locale: string): InvoiceViewModel {
+    return {
+      invoiceNumber: `INV-${invoice.id.padStart(6, '0')}`,
+      status: invoice.status.toUpperCase(),
+      statusColor: this.getStatusColor(invoice.status),
+      dueDate: this.formatDate(invoice.dueDate, locale),
+      total: this.formatMoney(invoice.total, invoice.currency, locale),
+      overdueMessage: this.getOverdueMessage(invoice)
+    }
+  }
+
+  private getStatusColor(status: string): 'green' | 'yellow' | 'red' {
+    const colors = { paid: 'green', pending: 'yellow', overdue: 'red' }
+    return colors[status] || 'yellow'
+  }
+
+  private formatDate(date: Date, locale: string): string {
+    return new Intl.DateTimeFormat(locale, {
+      month: 'long', day: 'numeric', year: 'numeric'
+    }).format(date)
+  }
+
+  private getOverdueMessage(invoice: InvoiceResult): string | null {
+    if (invoice.status !== 'overdue') return null
+    const days = this.calculateDaysOverdue(invoice.dueDate)
+    return `${days} day${days !== 1 ? 's' : ''} overdue`
+  }
+}
+
+// view/InvoiceView.tsx - Humble, just renders
+function InvoiceView({ vm }: { vm: InvoiceViewModel }) {
+  return (
+    <div>
+      <span style={{ color: vm.statusColor }}>{vm.status}</span>
+      <span>Due: {vm.dueDate}</span>
+      <span>Total: {vm.total}</span>
+      {vm.overdueMessage && <span>{vm.overdueMessage}</span>}
+    </div>
+  )
+}
+```
+
+**Benefits:**
+- Formatting logic tested without UI framework
+- Same use case serves different locales via different presenter configs
+- View components trivially simple, easy to redesign
+
+Reference: [Clean Architecture - Presenters and Humble Objects](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch23.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/bound-boundary-cost-awareness.md b/builtin-skills/software-engineer/clean-architecture/references/bound-boundary-cost-awareness.md
new file mode 100644
index 00000000..bd1635e6
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/bound-boundary-cost-awareness.md
@@ -0,0 +1,105 @@
+---
+title: Weigh Boundary Cost Against Ignorance Cost
+impact: MEDIUM-HIGH
+impactDescription: optimizes architectural investment, prevents both over and under engineering
+tags: bound, cost, tradeoffs, pragmatism
+---
+
+## Weigh Boundary Cost Against Ignorance Cost
+
+Boundaries are expensive to create and maintain, but ignoring needed boundaries becomes very expensive later. Continuously evaluate where the cost of implementing is less than the cost of ignoring.
+
+**Incorrect (boundary everywhere - over-engineering):**
+
+```java
+// Overkill for a simple CRUD app with 3 entities
+
+// 9 interfaces for 3 entities
+interface UserRepository { }
+interface UserService { }
+interface UserPresenter { }
+interface ProductRepository { }
+interface ProductService { }
+interface ProductPresenter { }
+interface OrderRepository { }
+interface OrderService { }
+interface OrderPresenter { }
+
+// 9 implementations
+class SqlUserRepository implements UserRepository { }
+class UserServiceImpl implements UserService { }
+class UserPresenterImpl implements UserPresenter { }
+// ... 6 more classes
+
+// 3 factories
+class UserFactory { }
+class ProductFactory { }
+class OrderFactory { }
+
+// Result: 100 files for functionality that could be 20 files
+// Maintenance burden exceeds benefit for small team
+```
+
+**Incorrect (no boundaries - under-engineering):**
+
+```java
+// Dangerous for a complex domain with multiple teams
+
+class GodService {
+    public void handleEverything(Request req) {
+        // 2000 lines mixing:
+        // - User authentication
+        // - Order processing
+        // - Payment handling
+        // - Email notifications
+        // - Report generation
+    }
+}
+
+// Result: Every change risks breaking unrelated features
+// No team can work independently
+```
+
+**Correct (boundaries where they matter):**
+
+```java
+// Evaluate each potential boundary:
+
+// HIGH VALUE BOUNDARY: External payment provider
+// - Changes frequently (provider updates API)
+// - Risk of vendor lock-in
+// - Different team might own this
+interface PaymentGateway {
+    PaymentResult charge(Money amount, PaymentMethod method);
+}
+
+// MEDIUM VALUE BOUNDARY: Database access
+// - Might migrate databases
+// - Enables testing without DB
+interface OrderRepository {
+    void save(Order order);
+    Order findById(OrderId id);
+}
+
+// LOW VALUE - SKIP FOR NOW: Presenter/View split
+// - Single frontend, single team
+// - No plans to support multiple UIs
+// Just put formatting in React components for now
+// Add boundary later if needed
+
+// SKIP: Separate microservices
+// - Team is 5 people
+// - Deployment is monolithic anyway
+// - Network boundary adds latency and complexity for no benefit
+```
+
+**Decision Framework:**
+| Factor | Add Boundary | Skip Boundary |
+|--------|-------------|---------------|
+| Change frequency | High | Low |
+| Team ownership | Multiple teams | Single team |
+| External dependency | Yes | No |
+| Testing difficulty | Hard without boundary | Easy anyway |
+| Current pain | Evident | Hypothetical |
+
+Reference: [Clean Architecture - The Cost of Boundaries](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch25.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/bound-defer-decisions.md b/builtin-skills/software-engineer/clean-architecture/references/bound-defer-decisions.md
new file mode 100644
index 00000000..eea90678
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/bound-defer-decisions.md
@@ -0,0 +1,105 @@
+---
+title: Defer Framework and Database Decisions
+impact: MEDIUM-HIGH
+impactDescription: preserves optionality, reduces early commitment risk
+tags: bound, deferral, decisions, optionality
+---
+
+## Defer Framework and Database Decisions
+
+A good architecture allows major decisions about frameworks, databases, and delivery mechanisms to be deferred until the last responsible moment. The longer you wait, the more information you have.
+
+**Incorrect (early commitment to specifics):**
+
+```typescript
+// Day 1: "Let's use Prisma with PostgreSQL and Next.js"
+
+// domain/Order.ts - Coupled to Prisma from the start
+import { PrismaClient } from '@prisma/client'
+
+const prisma = new PrismaClient()
+
+export async function createOrder(data: OrderInput) {
+  // Business logic intertwined with Prisma
+  const order = await prisma.order.create({
+    data: {
+      items: {
+        create: data.items.map(item => ({
+          productId: item.productId,
+          quantity: item.quantity,
+          price: item.price
+        }))
+      },
+      total: data.items.reduce((sum, i) => sum + i.price * i.quantity, 0)
+    },
+    include: { items: true }
+  })
+
+  return order
+}
+
+// 6 months later: "PostgreSQL doesn't scale for our read patterns,
+// we need DynamoDB" - Massive rewrite required
+```
+
+**Correct (defer database decision):**
+
+```typescript
+// Day 1: Focus on business rules, defer database choice
+
+// domain/Order.ts - Pure business logic
+export class Order {
+  private items: OrderItem[] = []
+
+  addItem(product: Product, quantity: number): void {
+    if (quantity <= 0) throw new InvalidQuantityError()
+    this.items.push(new OrderItem(product, quantity))
+  }
+
+  calculateTotal(): Money {
+    return this.items.reduce(
+      (sum, item) => sum.add(item.lineTotal()),
+      Money.zero()
+    )
+  }
+}
+
+// application/ports/OrderRepository.ts - Interface only
+export interface OrderRepository {
+  save(order: Order): Promise<void>
+  findById(id: OrderId): Promise<Order | null>
+}
+
+// For now: Simple in-memory implementation for testing
+// infrastructure/InMemoryOrderRepository.ts
+export class InMemoryOrderRepository implements OrderRepository {
+  private orders = new Map<string, Order>()
+
+  async save(order: Order): Promise<void> {
+    this.orders.set(order.id.value, order)
+  }
+}
+
+// Later, when you know more: Add real database
+// infrastructure/PrismaOrderRepository.ts
+// OR
+// infrastructure/DynamoOrderRepository.ts
+// OR
+// infrastructure/MongoOrderRepository.ts
+
+// The domain never changes regardless of database choice
+```
+
+**Decisions worth deferring:**
+- Database vendor (PostgreSQL vs MongoDB vs DynamoDB)
+- ORM choice (Prisma vs TypeORM vs raw SQL)
+- Web framework (Express vs Fastify vs Hono)
+- Message queue (RabbitMQ vs Kafka vs SQS)
+- Cache provider (Redis vs Memcached)
+
+**Benefits:**
+- Learn requirements before committing
+- Prototype faster with simple implementations
+- Switch vendors without domain rewrites
+
+Reference: [Clean Architecture - The Database is a Detail](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch30.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/bound-humble-object.md b/builtin-skills/software-engineer/clean-architecture/references/bound-humble-object.md
new file mode 100644
index 00000000..69a98ba3
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/bound-humble-object.md
@@ -0,0 +1,108 @@
+---
+title: Use Humble Objects at Architectural Boundaries
+impact: MEDIUM-HIGH
+impactDescription: maximizes testable code, isolates hard-to-test parts
+tags: bound, humble-object, testing, boundaries
+---
+
+## Use Humble Objects at Architectural Boundaries
+
+The Humble Object pattern separates hard-to-test behaviors from easy-to-test behaviors. The "humble" part contains minimal logic and is hard to test; the substantial logic goes in a testable component.
+
+**Incorrect (logic mixed with hard-to-test framework code):**
+
+```typescript
+// React component with business logic
+function OrderSummary({ orderId }: Props) {
+  const [order, setOrder] = useState<Order | null>(null)
+  const [discount, setDiscount] = useState<number>(0)
+
+  useEffect(() => {
+    fetch(`/api/orders/${orderId}`)
+      .then(r => r.json())
+      .then(data => {
+        setOrder(data)
+        // Business logic in component - hard to test
+        if (data.items.length > 5) {
+          setDiscount(data.total * 0.1)
+        } else if (data.customer.tier === 'gold') {
+          setDiscount(data.total * 0.05)
+        }
+      })
+  }, [orderId])
+
+  const finalTotal = order ? order.total - discount : 0
+
+  return (
+    <div>
+      <span>Subtotal: ${order?.total}</span>
+      <span>Discount: ${discount}</span>
+      <span>Total: ${finalTotal}</span>
+    </div>
+  )
+}
+
+// Testing requires React Testing Library + mocked fetch
+```
+
+**Correct (humble view + testable presenter):**
+
+```typescript
+// Presenter - pure function, easy to test
+interface OrderViewModel {
+  subtotal: string
+  discount: string
+  total: string
+  hasDiscount: boolean
+}
+
+function presentOrder(order: Order): OrderViewModel {
+  const discount = calculateDiscount(order)
+  const finalTotal = order.total - discount
+
+  return {
+    subtotal: formatCurrency(order.total),
+    discount: formatCurrency(discount),
+    total: formatCurrency(finalTotal),
+    hasDiscount: discount > 0
+  }
+}
+
+function calculateDiscount(order: Order): number {
+  if (order.items.length > 5) return order.total * 0.1
+  if (order.customer.tier === 'gold') return order.total * 0.05
+  return 0
+}
+
+// Humble view - no logic, just renders data
+function OrderSummary({ viewModel }: { viewModel: OrderViewModel }) {
+  return (
+    <div>
+      <span>Subtotal: {viewModel.subtotal}</span>
+      {viewModel.hasDiscount && <span>Discount: {viewModel.discount}</span>}
+      <span>Total: {viewModel.total}</span>
+    </div>
+  )
+}
+
+// Container handles data fetching - also humble
+function OrderSummaryContainer({ orderId }: Props) {
+  const { data: order } = useQuery(['order', orderId], fetchOrder)
+  if (!order) return <Loading />
+  return <OrderSummary viewModel={presentOrder(order)} />
+}
+
+// Test presenter without React
+test('applies bulk discount for 6+ items', () => {
+  const order = { items: [1,2,3,4,5,6], total: 100, customer: { tier: 'standard' } }
+  const vm = presentOrder(order)
+  expect(vm.discount).toBe('$10.00')
+})
+```
+
+**Benefits:**
+- Business logic tested with simple unit tests
+- UI tests only verify rendering, not logic
+- 90%+ of logic covered by fast tests
+
+Reference: [Clean Architecture - Humble Object Pattern](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch23.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/bound-main-component.md b/builtin-skills/software-engineer/clean-architecture/references/bound-main-component.md
new file mode 100644
index 00000000..252e2ec3
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/bound-main-component.md
@@ -0,0 +1,106 @@
+---
+title: Treat Main as a Plugin to the Application
+impact: MEDIUM-HIGH
+impactDescription: enables multiple configurations, simplifies testing
+tags: bound, main, composition-root, plugin
+---
+
+## Treat Main as a Plugin to the Application
+
+The Main component is the lowest-level, dirtiest component. It creates all factories, strategies, and global facilities, then hands control to high-level abstractions. Treat it as a plugin that can be swapped.
+
+**Incorrect (Main mixed with application logic):**
+
+```go
+// main.go
+func main() {
+    db := connectDatabase()
+
+    // Business logic in main
+    http.HandleFunc("/orders", func(w http.ResponseWriter, r *http.Request) {
+        var order Order
+        json.NewDecoder(r.Body).Decode(&order)
+
+        // Validation logic
+        if order.Total < 0 {
+            http.Error(w, "Invalid total", 400)
+            return
+        }
+
+        // Direct database calls
+        db.Exec("INSERT INTO orders ...")
+
+        // Response formatting
+        json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+    })
+
+    http.ListenAndServe(":8080", nil)
+}
+// Cannot test without starting HTTP server
+// Cannot run with different database
+```
+
+**Correct (Main as composition root):**
+
+```go
+// main.go - Production entry point
+func main() {
+    app := bootstrap(ProductionConfig{
+        DatabaseURL: os.Getenv("DATABASE_URL"),
+        Port:        os.Getenv("PORT"),
+    })
+    app.Run()
+}
+
+// bootstrap.go - Composition root
+func bootstrap(config Config) *Application {
+    // Create infrastructure
+    db := postgres.NewConnection(config.DatabaseURL)
+
+    // Create repositories (implement domain interfaces)
+    orderRepo := postgres.NewOrderRepository(db)
+    userRepo := postgres.NewUserRepository(db)
+
+    // Create use cases (depend on interfaces)
+    placeOrder := usecases.NewPlaceOrderUseCase(orderRepo)
+    getOrders := usecases.NewGetOrdersUseCase(orderRepo)
+
+    // Create controllers (call use cases)
+    orderController := controllers.NewOrderController(placeOrder, getOrders)
+
+    // Wire up HTTP routes
+    router := http.NewRouter()
+    router.POST("/orders", orderController.Create)
+    router.GET("/orders", orderController.List)
+
+    return &Application{
+        Router: router,
+        Port:   config.Port,
+    }
+}
+
+// main_test.go - Test entry point
+func TestMain(t *testing.T) {
+    app := bootstrap(TestConfig{
+        DatabaseURL: "memory://",  // In-memory for tests
+        Port:        "0",          // Random port
+    })
+    // Test against app
+}
+
+// main_dev.go - Development entry point
+func main() {
+    app := bootstrap(DevConfig{
+        DatabaseURL: "localhost:5432",
+        Port:        "3000",
+    })
+    app.RunWithHotReload()
+}
+```
+
+**Benefits:**
+- Swap database, logging, configuration per environment
+- Integration tests use real wiring with test doubles
+- Dev/staging/prod share same composition logic
+
+Reference: [Clean Architecture - The Main Component](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch26.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/bound-partial-boundaries.md b/builtin-skills/software-engineer/clean-architecture/references/bound-partial-boundaries.md
new file mode 100644
index 00000000..c042b051
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/bound-partial-boundaries.md
@@ -0,0 +1,84 @@
+---
+title: Use Partial Boundaries When Full Separation is Premature
+impact: MEDIUM-HIGH
+impactDescription: prepares for future without over-engineering now
+tags: bound, partial-boundaries, pragmatism, yagni
+---
+
+## Use Partial Boundaries When Full Separation is Premature
+
+When you anticipate needing a boundary but the cost of full separation is too high, implement a partial boundary. This prepares for future separation without premature over-engineering.
+
+**Incorrect (no boundary when one might be needed):**
+
+```python
+# Tightly coupled - if we ever need to split, massive refactor
+class ReportService:
+    def generate_sales_report(self, start_date, end_date):
+        # Direct database access
+        conn = psycopg2.connect(DATABASE_URL)
+        cursor = conn.cursor()
+        cursor.execute("""
+            SELECT * FROM sales
+            WHERE date BETWEEN %s AND %s
+        """, (start_date, end_date))
+
+        # Direct PDF generation
+        pdf = FPDF()
+        for row in cursor.fetchall():
+            pdf.cell(200, 10, txt=str(row))
+        return pdf.output()
+
+# Cannot split report generation from data access without rewriting
+```
+
+**Correct (partial boundary - same component, prepared for split):**
+
+```python
+# Strategy 1: Facade pattern (simplest partial boundary)
+class ReportingFacade:
+    """Single entry point, internal implementation can be refactored later."""
+
+    def generate_sales_report(self, request: ReportRequest) -> Report:
+        data = self._fetch_data(request)
+        return self._format_report(data, request.format)
+
+    def _fetch_data(self, request):
+        # Could become a separate DataAccess component later
+        return self.repository.get_sales(request.start, request.end)
+
+    def _format_report(self, data, format):
+        # Could become a separate ReportRenderer component later
+        if format == 'pdf':
+            return PdfRenderer().render(data)
+        return CsvRenderer().render(data)
+
+
+# Strategy 2: Interface with single implementation
+class SalesDataProvider(Protocol):
+    def get_sales(self, start: date, end: date) -> list[Sale]: ...
+
+class PostgresSalesProvider:
+    def get_sales(self, start: date, end: date) -> list[Sale]:
+        # Implementation here
+
+# Both live in same component, but interface enables future split
+# When split needed: move interface to one component, impl to another
+
+
+# Strategy 3: One-dimensional boundary
+# Skip reciprocal interface - simpler but weaker protection
+class ReportGenerator:
+    def __init__(self, data_provider: SalesDataProvider):
+        self.data_provider = data_provider  # Depends on abstraction
+
+# SalesDataProvider implementation knows about ReportGenerator
+# Not fully decoupled, but good enough for now
+```
+
+**When to use partial boundaries:**
+- You suspect a boundary will be needed, but not yet
+- Team is small and deployment is unified
+- Cost of full boundary outweighs current benefits
+
+Reference: [Clean Architecture - Partial Boundaries](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch24.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/bound-service-internal-architecture.md b/builtin-skills/software-engineer/clean-architecture/references/bound-service-internal-architecture.md
new file mode 100644
index 00000000..a08b02aa
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/bound-service-internal-architecture.md
@@ -0,0 +1,94 @@
+---
+title: Services Must Have Internal Clean Architecture
+impact: MEDIUM-HIGH
+impactDescription: microservices don't replace architecture, they require it
+tags: bound, services, microservices, internal
+---
+
+## Services Must Have Internal Clean Architecture
+
+Breaking a monolith into microservices doesn't solve architectural problems. Each service still needs internal architecture. Services are a deployment option, not an architecture.
+
+**Incorrect (microservices as architecture replacement):**
+
+```text
+"We use microservices architecture"
+
+┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
+│  order-service  │  │  user-service   │  │ payment-service │
+│                 │  │                 │  │                 │
+│  routes.js      │  │  routes.js      │  │  routes.js      │
+│  database.js    │  │  database.js    │  │  database.js    │
+│  helpers.js     │  │  helpers.js     │  │  helpers.js     │
+│                 │  │                 │  │                 │
+│  (No layers,    │  │  (No layers,    │  │  (No layers,    │
+│   no boundaries,│  │   no boundaries,│  │   no boundaries,│
+│   just smaller  │  │   just smaller  │  │   just smaller  │
+│   messes)       │  │   messes)       │  │   messes)       │
+└─────────────────┘  └─────────────────┘  └─────────────────┘
+
+# Result: Distributed monolith
+# All the downsides of microservices (network, deployment, consistency)
+# None of the benefits (each service still a tangled mess)
+```
+
+**Correct (clean architecture within each service):**
+
+```text
+┌───────────────────────────────────────────────────────────┐
+│                      order-service                         │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │                      domain/                         │  │
+│  │   Order.ts  OrderLine.ts  OrderStatus.ts            │  │
+│  └─────────────────────────────────────────────────────┘  │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │                   application/                       │  │
+│  │   PlaceOrderUseCase.ts                               │  │
+│  │   ports/                                             │  │
+│  │     OrderRepository.ts                               │  │
+│  │     PaymentGateway.ts  ← calls payment-service       │  │
+│  └─────────────────────────────────────────────────────┘  │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │                  infrastructure/                     │  │
+│  │   PostgresOrderRepository.ts                         │  │
+│  │   HttpPaymentGateway.ts  → payment-service API       │  │
+│  │   KafkaEventPublisher.ts                             │  │
+│  └─────────────────────────────────────────────────────┘  │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │                   interface/                         │  │
+│  │   OrderController.ts                                 │  │
+│  │   OrderEventHandler.ts                               │  │
+│  └─────────────────────────────────────────────────────┘  │
+└───────────────────────────────────────────────────────────┘
+
+# Each service has:
+# - Domain layer with business rules
+# - Application layer with use cases and ports
+# - Infrastructure layer implementing ports
+# - Clean dependency direction within service
+```
+
+**Cross-service communication:**
+```typescript
+// application/ports/PaymentGateway.ts
+interface PaymentGateway {
+  charge(amount: Money, method: PaymentMethod): Promise<PaymentResult>
+}
+
+// infrastructure/HttpPaymentGateway.ts
+class HttpPaymentGateway implements PaymentGateway {
+  async charge(amount: Money, method: PaymentMethod): Promise<PaymentResult> {
+    // Calls payment-service over HTTP
+    // Service boundary is an infrastructure detail
+    const response = await fetch('http://payment-service/charge', { ... })
+    return this.mapResponse(response)
+  }
+}
+```
+
+**Benefits:**
+- Services testable without other services
+- Can extract or merge services without rewriting business logic
+- Network boundaries don't compromise internal architecture
+
+Reference: [Clean Architecture - Services: Great and Small](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch27.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/comp-common-closure.md b/builtin-skills/software-engineer/clean-architecture/references/comp-common-closure.md
new file mode 100644
index 00000000..3893f1c4
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/comp-common-closure.md
@@ -0,0 +1,62 @@
+---
+title: Group Classes That Change Together
+impact: HIGH
+impactDescription: localizes change impact, reduces deployment risk
+tags: comp, common-closure, cohesion, change
+---
+
+## Group Classes That Change Together
+
+Classes that change for the same reasons and at the same times should be in the same component. This is the Common Closure Principle (CCP) - the Single Responsibility Principle for components.
+
+**Incorrect (classes that change together are separated):**
+
+```text
+src/
+├── entities/
+│   └── Invoice.ts           # Changes when billing rules change
+├── repositories/
+│   └── InvoiceRepository.ts # Changes when billing rules change
+├── services/
+│   └── InvoiceService.ts    # Changes when billing rules change
+├── validators/
+│   └── InvoiceValidator.ts  # Changes when billing rules change
+└── mappers/
+    └── InvoiceMapper.ts     # Changes when billing rules change
+
+# A billing rule change touches 5 directories
+# Risk of forgetting one, inconsistent changes
+```
+
+**Correct (classes that change together are grouped):**
+
+```text
+src/
+├── billing/
+│   ├── domain/
+│   │   ├── Invoice.ts
+│   │   ├── InvoiceLine.ts
+│   │   ├── InvoiceRules.ts
+│   │   └── InvoiceValidator.ts
+│   ├── application/
+│   │   ├── CreateInvoiceUseCase.ts
+│   │   └── ports/
+│   │       └── InvoiceRepository.ts
+│   └── infrastructure/
+│       ├── PostgresInvoiceRepository.ts
+│       └── InvoiceMapper.ts
+├── payments/
+│   └── ...  # Changes for different reasons
+└── shipping/
+    └── ...  # Changes for different reasons
+
+# Billing rule change isolated to billing/
+# Single PR, single review, single deployment
+```
+
+**How to identify change reasons:**
+- "When X business rule changes, which classes change?"
+- "When the Y team requests a feature, which code changes?"
+- Group by actor/stakeholder, not by technical layer
+
+Reference: [Clean Architecture - Common Closure Principle](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch13.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/comp-common-reuse.md b/builtin-skills/software-engineer/clean-architecture/references/comp-common-reuse.md
new file mode 100644
index 00000000..b187264d
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/comp-common-reuse.md
@@ -0,0 +1,71 @@
+---
+title: Avoid Forcing Clients to Depend on Unused Code
+impact: HIGH
+impactDescription: reduces unnecessary recompilation and deployment
+tags: comp, common-reuse, dependencies, coupling
+---
+
+## Avoid Forcing Clients to Depend on Unused Code
+
+Classes used together should be in the same component. Classes not used together should be in separate components. Forcing a client to depend on things it doesn't use creates unnecessary coupling.
+
+**Incorrect (monolithic utility package):**
+
+```java
+// utils/src/main/java/com/app/utils/
+├── StringUtils.java
+├── DateUtils.java
+├── FileUtils.java
+├── HttpUtils.java
+├── CryptoUtils.java
+├── ImageUtils.java      // Depends on ImageMagick
+└── PdfUtils.java        // Depends on iText
+
+// pom.xml for utils module
+<dependencies>
+    <dependency>imagemagick</dependency>  <!-- 50MB -->
+    <dependency>itext-pdf</dependency>     <!-- 20MB -->
+    <dependency>bouncycastle</dependency>  <!-- 10MB -->
+</dependencies>
+
+// A service that only needs StringUtils
+// must now depend on all 80MB of transitive dependencies
+```
+
+**Correct (split by usage pattern):**
+
+```java
+// string-utils/
+├── StringUtils.java
+└── pom.xml  // No heavy dependencies
+
+// date-utils/
+├── DateUtils.java
+└── pom.xml
+
+// image-processing/
+├── ImageUtils.java
+├── ImageResizer.java
+└── pom.xml  // ImageMagick dependency only here
+
+// pdf-generation/
+├── PdfUtils.java
+├── PdfBuilder.java
+└── pom.xml  // iText dependency only here
+
+// crypto/
+├── CryptoUtils.java
+├── HashingService.java
+└── pom.xml  // BouncyCastle dependency only here
+
+// Services import only what they need
+// order-service depends on string-utils, date-utils (2MB)
+// report-service depends on string-utils, pdf-generation (22MB)
+```
+
+**Benefits:**
+- Clients only pull dependencies they actually use
+- Smaller deployment artifacts
+- Changes to image processing don't redeploy order service
+
+Reference: [Clean Architecture - Common Reuse Principle](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch13.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/comp-reuse-release-equivalence.md b/builtin-skills/software-engineer/clean-architecture/references/comp-reuse-release-equivalence.md
new file mode 100644
index 00000000..1df9ebc6
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/comp-reuse-release-equivalence.md
@@ -0,0 +1,70 @@
+---
+title: Release Components as Cohesive Units
+impact: HIGH
+impactDescription: enables version tracking, supports parallel team development
+tags: comp, release, versioning, cohesion
+---
+
+## Release Components as Cohesive Units
+
+Classes grouped into a component should be releasable together. A component should have a version number, release notes, and clear documentation. This is the Reuse/Release Equivalence Principle (REP).
+
+**Incorrect (arbitrary grouping):**
+
+```text
+shared-lib/
+├── src/
+│   ├── auth/
+│   │   ├── JwtValidator.ts
+│   │   └── PermissionChecker.ts
+│   ├── logging/
+│   │   └── Logger.ts
+│   ├── email/
+│   │   └── EmailSender.ts
+│   └── payment/
+│       └── StripeClient.ts
+└── package.json  // version 1.2.3
+
+# Version 1.2.4 fixes JWT bug
+# But users of EmailSender must also upgrade
+# Changelog unclear which features affect which users
+```
+
+**Correct (cohesive releasable components):**
+
+```text
+packages/
+├── auth/
+│   ├── src/
+│   │   ├── JwtValidator.ts
+│   │   ├── PermissionChecker.ts
+│   │   └── index.ts
+│   ├── CHANGELOG.md        # Auth-specific changes
+│   └── package.json        # @company/auth v2.1.0
+├── logging/
+│   ├── src/
+│   │   └── Logger.ts
+│   ├── CHANGELOG.md
+│   └── package.json        # @company/logging v1.0.3
+├── email/
+│   ├── src/
+│   │   └── EmailSender.ts
+│   ├── CHANGELOG.md
+│   └── package.json        # @company/email v1.5.0
+└── payments/
+    ├── src/
+    │   └── StripeClient.ts
+    ├── CHANGELOG.md
+    └── package.json        # @company/payments v3.0.0
+
+# Clear ownership: auth team owns @company/auth
+# Independent versioning: JWT fix only bumps auth
+# Semantic versioning: breaking change in payments doesn't affect others
+```
+
+**Benefits:**
+- Teams release independently on their own schedule
+- Version numbers communicate compatibility
+- Changelogs specific to what users of each component care about
+
+Reference: [Clean Architecture - Reuse/Release Equivalence Principle](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch13.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/comp-screaming-architecture.md b/builtin-skills/software-engineer/clean-architecture/references/comp-screaming-architecture.md
new file mode 100644
index 00000000..06edbc37
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/comp-screaming-architecture.md
@@ -0,0 +1,77 @@
+---
+title: Structure Should Scream the Domain Not the Framework
+impact: HIGH
+impactDescription: enables understanding at a glance, reveals intent
+tags: comp, screaming-architecture, structure, domain
+---
+
+## Structure Should Scream the Domain Not the Framework
+
+The folder structure should communicate what the system does, not what framework it uses. Looking at the top-level directories should reveal the business domain.
+
+**Incorrect (framework-oriented structure):**
+
+```text
+src/
+├── controllers/
+│   ├── UserController.ts
+│   ├── OrderController.ts
+│   └── ProductController.ts
+├── services/
+│   ├── UserService.ts
+│   ├── OrderService.ts
+│   └── ProductService.ts
+├── repositories/
+│   ├── UserRepository.ts
+│   ├── OrderRepository.ts
+│   └── ProductRepository.ts
+├── models/
+│   ├── User.ts
+│   ├── Order.ts
+│   └── Product.ts
+└── utils/
+    └── helpers.ts
+
+# This screams "MVC framework" not "e-commerce system"
+```
+
+**Correct (domain-oriented structure):**
+
+```text
+src/
+├── ordering/
+│   ├── domain/
+│   │   ├── Order.ts
+│   │   ├── OrderLine.ts
+│   │   └── OrderStatus.ts
+│   ├── application/
+│   │   ├── PlaceOrderUseCase.ts
+│   │   ├── CancelOrderUseCase.ts
+│   │   └── ports/
+│   │       ├── OrderRepository.ts
+│   │       └── PaymentGateway.ts
+│   └── infrastructure/
+│       ├── PostgresOrderRepository.ts
+│       └── StripePaymentGateway.ts
+├── inventory/
+│   ├── domain/
+│   ├── application/
+│   └── infrastructure/
+├── customers/
+│   ├── domain/
+│   ├── application/
+│   └── infrastructure/
+└── shared/
+    └── kernel/
+        ├── Money.ts
+        └── EntityId.ts
+
+# This screams "e-commerce with ordering, inventory, customers"
+```
+
+**Benefits:**
+- New developers understand the domain immediately
+- Related code lives together, enabling focused changes
+- Frameworks become implementation details, not organizing principles
+
+Reference: [Screaming Architecture](https://blog.cleancoder.com/uncle-bob/2011/09/30/Screaming-Architecture.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/comp-stable-dependencies.md b/builtin-skills/software-engineer/clean-architecture/references/comp-stable-dependencies.md
new file mode 100644
index 00000000..c5fb2f6b
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/comp-stable-dependencies.md
@@ -0,0 +1,69 @@
+---
+title: Depend in the Direction of Stability
+impact: HIGH
+impactDescription: prevents unstable components from destabilizing dependents
+tags: comp, stability, dependencies, direction
+---
+
+## Depend in the Direction of Stability
+
+Components should depend on components that are more stable than themselves. A stable component (many dependents, few dependencies) should not depend on an unstable component (few dependents, many dependencies).
+
+**Incorrect (stable component depends on unstable):**
+
+```text
+┌─────────────────────────────────────────────────────┐
+│                     core-domain                      │
+│  (Used by 50 services, should be very stable)       │
+│                                                      │
+│  import { formatDate } from 'ui-helpers'  // WRONG! │
+│  import { sendMetrics } from 'analytics'  // WRONG! │
+└──────────────────────┬──────────────────────────────┘
+                       │
+       ┌───────────────┼───────────────┐
+       ▼               ▼               ▼
+  ui-helpers      analytics      reporting
+  (Changes        (Changes       (Changes
+   weekly)         monthly)       often)
+
+# When ui-helpers changes, core-domain might break
+# When core-domain breaks, all 50 services break
+```
+
+**Correct (depend toward stability):**
+
+```text
+┌─────────────────────────────────────────────────────┐
+│                     core-domain                      │
+│  (Used by 50 services, zero external dependencies)  │
+│                                                      │
+│  - Only depends on language primitives              │
+│  - Defines interfaces, not implementations          │
+└─────────────────────────────────────────────────────┘
+                       ▲
+                       │
+       ┌───────────────┼───────────────┐
+       │               │               │
+  ui-helpers      analytics      reporting
+  │               │               │
+  │               │               │
+  ▼               ▼               ▼
+┌─────────────────────────────────────────────────────┐
+│              external-dependencies                   │
+│  (date-fns, axios, lodash - maintained externally)  │
+└─────────────────────────────────────────────────────┘
+
+# Unstable components depend on stable core
+# Core never breaks due to UI changes
+```
+
+**Stability Metric:**
+```text
+Instability = Outgoing Dependencies / (Incoming + Outgoing)
+```
+- I = 0: Maximally stable (many dependents, no dependencies)
+- I = 1: Maximally unstable (no dependents, many dependencies)
+
+Dependencies should flow from high I to low I.
+
+Reference: [Clean Architecture - Stable Dependencies Principle](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch14.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/dep-acyclic-dependencies.md b/builtin-skills/software-engineer/clean-architecture/references/dep-acyclic-dependencies.md
new file mode 100644
index 00000000..fd219d83
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/dep-acyclic-dependencies.md
@@ -0,0 +1,84 @@
+---
+title: Eliminate Cyclic Dependencies Between Components
+impact: CRITICAL
+impactDescription: prevents ripple effects, enables independent deployment
+tags: dep, cycles, acyclic, components
+---
+
+## Eliminate Cyclic Dependencies Between Components
+
+The dependency graph must be a Directed Acyclic Graph (DAG). Cycles create ripple effects where changes propagate unpredictably through the system.
+
+**Incorrect (cyclic dependency):**
+
+```typescript
+// modules/orders/OrderService.ts
+import { CustomerService } from '../customers/CustomerService'
+
+export class OrderService {
+  constructor(private customers: CustomerService) {}
+
+  async createOrder(customerId: string) {
+    const customer = await this.customers.findById(customerId)
+    // ...
+  }
+}
+
+// modules/customers/CustomerService.ts
+import { OrderService } from '../orders/OrderService'  // Cycle!
+
+export class CustomerService {
+  constructor(private orders: OrderService) {}
+
+  async getCustomerWithOrders(customerId: string) {
+    const orders = await this.orders.findByCustomer(customerId)
+    // ...
+  }
+}
+// Neither module can be deployed or tested independently
+```
+
+**Correct (break cycle with dependency inversion):**
+
+```typescript
+// modules/orders/ports/CustomerProvider.ts
+export interface CustomerProvider {
+  findById(id: string): Promise<Customer>
+}
+
+// modules/orders/OrderService.ts
+import { CustomerProvider } from './ports/CustomerProvider'
+
+export class OrderService {
+  constructor(private customers: CustomerProvider) {}
+
+  async createOrder(customerId: string) {
+    const customer = await this.customers.findById(customerId)
+    // ...
+  }
+}
+
+// modules/customers/CustomerService.ts
+// No import from orders module
+
+export class CustomerService implements CustomerProvider {
+  // Implements the interface defined in orders module
+}
+
+// modules/customers/adapters/OrderAdapter.ts
+import { OrderService } from '../../orders/OrderService'
+
+export class CustomerOrderAdapter {
+  constructor(private orders: OrderService) {}
+
+  async getOrdersForCustomer(customerId: string) {
+    return this.orders.findByCustomer(customerId)
+  }
+}
+```
+
+**Alternative (extract shared abstraction):**
+
+Create a new component that both depend on, breaking the cycle into a DAG.
+
+Reference: [Clean Architecture - Acyclic Dependencies Principle](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch14.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/dep-data-crossing-boundaries.md b/builtin-skills/software-engineer/clean-architecture/references/dep-data-crossing-boundaries.md
new file mode 100644
index 00000000..1187f273
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/dep-data-crossing-boundaries.md
@@ -0,0 +1,61 @@
+---
+title: Use Simple Data Structures Across Boundaries
+impact: CRITICAL
+impactDescription: prevents coupling between layers
+tags: dep, boundaries, dto, data-transfer
+---
+
+## Use Simple Data Structures Across Boundaries
+
+Data crossing architectural boundaries should be simple, isolated data structures. Never pass entities, database rows, or framework objects across boundaries.
+
+**Incorrect (entity crosses boundary):**
+
+```python
+# domain/entities/user.py
+class User:
+    def __init__(self, id, email, password_hash, created_at):
+        self.id = id
+        self.email = email
+        self.password_hash = password_hash  # Sensitive data
+        self.created_at = created_at
+
+# interface_adapters/controllers/user_controller.py
+class UserController:
+    def get_user(self, user_id):
+        user = self.use_case.get_user(user_id)
+        return jsonify(user.__dict__)  # Entity exposed to HTTP layer, leaks password_hash
+```
+
+**Correct (DTOs cross boundaries):**
+
+```python
+# application/dto/user_response.py
+@dataclass
+class UserResponse:
+    id: str
+    email: str
+    member_since: str  # Formatted for presentation
+
+# application/usecases/get_user.py
+class GetUserUseCase:
+    def execute(self, user_id: str) -> UserResponse:
+        user = self.repository.find_by_id(user_id)
+        return UserResponse(
+            id=user.id,
+            email=user.email,
+            member_since=user.created_at.strftime("%B %Y")
+        )
+
+# interface_adapters/controllers/user_controller.py
+class UserController:
+    def get_user(self, user_id):
+        response = self.use_case.execute(user_id)
+        return jsonify(asdict(response))  # Only safe, formatted data
+```
+
+**When NOT to use this pattern:**
+- Within the same architectural layer, entities can flow freely
+- Performance-critical paths may need optimized data transfer
+
+Reference: [Clean Architecture - Crossing Boundaries](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/dep-interface-ownership.md b/builtin-skills/software-engineer/clean-architecture/references/dep-interface-ownership.md
new file mode 100644
index 00000000..3138a571
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/dep-interface-ownership.md
@@ -0,0 +1,60 @@
+---
+title: Interfaces Belong to Clients Not Implementers
+impact: CRITICAL
+impactDescription: enables true dependency inversion
+tags: dep, interfaces, dependency-inversion, ownership
+---
+
+## Interfaces Belong to Clients Not Implementers
+
+Interfaces should be defined in the layer that uses them, not the layer that implements them. The client owns the abstraction; the implementation adapts to it.
+
+**Incorrect (interface defined next to implementation):**
+
+```java
+// infrastructure/persistence/UserRepository.java
+public interface UserRepository {
+    User findById(String id);
+    void save(User user);
+}
+
+// infrastructure/persistence/PostgresUserRepository.java
+public class PostgresUserRepository implements UserRepository {
+    // Implementation
+}
+
+// application/usecases/CreateUserUseCase.java
+import infrastructure.persistence.UserRepository;  // Use case imports from infrastructure!
+
+public class CreateUserUseCase {
+    private final UserRepository repository;
+}
+```
+
+**Correct (interface defined where it's used):**
+
+```java
+// application/ports/output/UserRepository.java
+public interface UserRepository {
+    User findById(String id);
+    void save(User user);
+}
+
+// application/usecases/CreateUserUseCase.java
+import application.ports.output.UserRepository;  // Same layer import
+
+public class CreateUserUseCase {
+    private final UserRepository repository;  // No infrastructure dependency
+}
+
+// infrastructure/persistence/PostgresUserRepository.java
+import application.ports.output.UserRepository;  // Infrastructure depends on application
+
+public class PostgresUserRepository implements UserRepository {
+    // Implementation adapts to the port
+}
+```
+
+**Note:** This is the essence of the Dependency Inversion Principle. The high-level module defines what it needs; low-level modules conform to that contract.
+
+Reference: [Clean Architecture - Chapter 11: DIP](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch11.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/dep-inward-only.md b/builtin-skills/software-engineer/clean-architecture/references/dep-inward-only.md
new file mode 100644
index 00000000..422e6673
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/dep-inward-only.md
@@ -0,0 +1,69 @@
+---
+title: Source Dependencies Point Inward Only
+impact: CRITICAL
+impactDescription: prevents cascade failures across all layers
+tags: dep, dependency-rule, layers, architecture
+---
+
+## Source Dependencies Point Inward Only
+
+The Dependency Rule states that source code dependencies can only point inward toward higher-level policies. Inner circles must never reference outer circles.
+
+**Incorrect (inner layer imports from outer layer):**
+
+```typescript
+// domain/entities/Order.ts - ENTITY LAYER
+import { OrderRepository } from '../../infrastructure/OrderRepository'
+import { EmailService } from '../../infrastructure/EmailService'
+
+export class Order {
+  constructor(
+    private repo: OrderRepository,  // Changes to repo implementation break Order
+    private email: EmailService
+  ) {}
+
+  async complete() {
+    await this.repo.save(this)
+    await this.email.notify(this.customerId)  // Cannot test without email server
+  }
+}
+```
+
+**Correct (inner layer defines interface, outer layer implements):**
+
+```typescript
+// domain/entities/Order.ts - ENTITY LAYER
+export interface OrderPersistence {
+  save(order: Order): Promise<void>
+}
+
+export interface NotificationPort {
+  notify(customerId: string): Promise<void>
+}
+
+export class Order {
+  constructor(
+    private repo: OrderPersistence,
+    private email: NotificationPort
+  ) {}
+
+  async complete() {
+    await this.repo.save(this)
+    await this.email.notify(this.customerId)
+  }
+}
+
+// infrastructure/OrderRepository.ts - INFRASTRUCTURE LAYER
+import { Order, OrderPersistence } from '../domain/entities/Order'
+
+export class OrderRepository implements OrderPersistence {
+  async save(order: Order): Promise<void> { /* DB implementation */ }
+}
+```
+
+**Benefits:**
+- Inner layers remain stable when outer layers change
+- Business rules can be tested without infrastructure
+- Infrastructure can be swapped without touching domain code
+
+Reference: [The Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/dep-no-framework-imports.md b/builtin-skills/software-engineer/clean-architecture/references/dep-no-framework-imports.md
new file mode 100644
index 00000000..df689cec
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/dep-no-framework-imports.md
@@ -0,0 +1,69 @@
+---
+title: Avoid Framework Imports in Inner Layers
+impact: CRITICAL
+impactDescription: prevents framework lock-in, enables 10× faster unit tests
+tags: dep, frameworks, imports, isolation
+---
+
+## Avoid Framework Imports in Inner Layers
+
+Entities and use cases must never import framework-specific types. Framework dependencies in inner layers create tight coupling that makes testing slow and migration impossible.
+
+**Incorrect (use case imports framework types):**
+
+```csharp
+// Application/UseCases/ProcessPaymentUseCase.cs
+using Microsoft.EntityFrameworkCore;
+using Microsoft.AspNetCore.Http;
+using Newtonsoft.Json;
+
+public class ProcessPaymentUseCase
+{
+    private readonly DbContext _context;  // EF Core dependency
+    private readonly IHttpContextAccessor _http;  // ASP.NET dependency
+
+    public async Task Execute(PaymentRequest request)
+    {
+        var userId = _http.HttpContext.User.Identity.Name;
+        var payment = JsonConvert.DeserializeObject<Payment>(request.Data);
+        _context.Payments.Add(payment);
+        await _context.SaveChangesAsync();
+    }
+}
+```
+
+**Correct (use case depends only on abstractions):**
+
+```csharp
+// Application/UseCases/ProcessPaymentUseCase.cs
+// No framework imports
+
+public class ProcessPaymentUseCase
+{
+    private readonly IPaymentRepository _payments;
+    private readonly ICurrentUserProvider _currentUser;
+
+    public async Task Execute(PaymentCommand command)
+    {
+        var userId = _currentUser.GetUserId();
+        var payment = new Payment(command.Amount, command.Currency, userId);
+        await _payments.Save(payment);
+    }
+}
+
+// Infrastructure/Persistence/EfPaymentRepository.cs
+using Microsoft.EntityFrameworkCore;
+
+public class EfPaymentRepository : IPaymentRepository
+{
+    private readonly DbContext _context;
+    // Framework usage isolated to infrastructure
+}
+```
+
+**Benefits:**
+- Use case tests run without framework bootstrapping
+- Framework can be upgraded or replaced independently
+- Business logic remains readable without framework noise
+
+Reference: [Clean Architecture - Frameworks are Details](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/dep-stable-abstractions.md b/builtin-skills/software-engineer/clean-architecture/references/dep-stable-abstractions.md
new file mode 100644
index 00000000..6a0e9466
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/dep-stable-abstractions.md
@@ -0,0 +1,76 @@
+---
+title: Depend on Stable Abstractions Not Volatile Concretions
+impact: CRITICAL
+impactDescription: reduces change frequency by 5-10×
+tags: dep, stability, abstractions, volatility
+---
+
+## Depend on Stable Abstractions Not Volatile Concretions
+
+The most flexible systems depend on abstractions, not concretions. Volatile concrete classes are under active development and change frequently; depending on them propagates instability.
+
+**Incorrect (depending on volatile concrete class):**
+
+```go
+// services/notification.go
+package services
+
+import (
+    "myapp/infrastructure/email/sendgrid"
+    "myapp/infrastructure/sms/twilio"
+)
+
+type NotificationService struct {
+    email  *sendgrid.Client  // Concrete SendGrid client
+    sms    *twilio.Client    // Concrete Twilio client
+}
+
+func (n *NotificationService) NotifyUser(userID string, message string) {
+    // When SendGrid API changes, this service must change
+    // When migrating to AWS SES, this service must change
+    n.email.SendWithTemplate("notify", message)
+}
+```
+
+**Correct (depending on stable interface):**
+
+```go
+// domain/ports/notification.go
+package ports
+
+type EmailSender interface {
+    Send(to string, subject string, body string) error
+}
+
+type SMSSender interface {
+    Send(to string, message string) error
+}
+
+// services/notification.go
+package services
+
+import "myapp/domain/ports"
+
+type NotificationService struct {
+    email ports.EmailSender  // Stable abstraction
+    sms   ports.SMSSender    // Stable abstraction
+}
+
+func (n *NotificationService) NotifyUser(userID string, message string) {
+    // Service is immune to email provider changes
+    n.email.Send(userID, "Notification", message)
+}
+
+// infrastructure/sendgrid/client.go
+package sendgrid
+
+type Client struct { /* ... */ }
+
+func (c *Client) Send(to, subject, body string) error {
+    // Concrete implementation can change freely
+}
+```
+
+**Note:** Depending on stable concretions (like standard library classes) is acceptable. Focus inversion on volatile, actively-developed modules.
+
+Reference: [Clean Architecture - Stable Abstractions Principle](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch11.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/entity-encapsulate-invariants.md b/builtin-skills/software-engineer/clean-architecture/references/entity-encapsulate-invariants.md
new file mode 100644
index 00000000..9ed2696c
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/entity-encapsulate-invariants.md
@@ -0,0 +1,83 @@
+---
+title: Encapsulate Business Invariants Within Entities
+impact: CRITICAL
+impactDescription: prevents invalid state, centralizes validation
+tags: entity, invariants, validation, encapsulation
+---
+
+## Encapsulate Business Invariants Within Entities
+
+Business rules that must always be true (invariants) should be enforced by the entity itself. External code should not be able to put an entity into an invalid state.
+
+**Incorrect (invariants scattered outside entity):**
+
+```python
+# application/usecases/transfer_money.py
+class TransferMoneyUseCase:
+    def execute(self, from_id, to_id, amount):
+        from_account = self.repo.find(from_id)
+        to_account = self.repo.find(to_id)
+
+        # Validation scattered in use case
+        if from_account.balance < amount:
+            raise InsufficientFundsError()
+        if amount <= 0:
+            raise InvalidAmountError()
+        if from_account.status != 'active':
+            raise AccountInactiveError()
+
+        from_account.balance -= amount  # Direct field mutation
+        to_account.balance += amount
+
+# Another use case might forget these checks!
+```
+
+**Correct (invariants enforced by entity):**
+
+```python
+# domain/entities/account.py
+class Account:
+    def __init__(self, id: AccountId, balance: Money, status: AccountStatus):
+        self._id = id
+        self._balance = balance
+        self._status = status
+
+    def withdraw(self, amount: Money) -> None:
+        self._ensure_active()
+        self._ensure_positive_amount(amount)
+        self._ensure_sufficient_funds(amount)
+        self._balance = self._balance.subtract(amount)
+
+    def deposit(self, amount: Money) -> None:
+        self._ensure_active()
+        self._ensure_positive_amount(amount)
+        self._balance = self._balance.add(amount)
+
+    def _ensure_active(self) -> None:
+        if self._status != AccountStatus.ACTIVE:
+            raise AccountInactiveError(self._id)
+
+    def _ensure_positive_amount(self, amount: Money) -> None:
+        if amount.is_zero_or_negative():
+            raise InvalidAmountError(amount)
+
+    def _ensure_sufficient_funds(self, amount: Money) -> None:
+        if self._balance.less_than(amount):
+            raise InsufficientFundsError(self._id, self._balance, amount)
+
+# application/usecases/transfer_money.py
+class TransferMoneyUseCase:
+    def execute(self, from_id, to_id, amount):
+        from_account = self.repo.find(from_id)
+        to_account = self.repo.find(to_id)
+
+        from_account.withdraw(amount)  # Invariants guaranteed
+        to_account.deposit(amount)
+```
+
+**Benefits:**
+- Impossible to create invalid account state
+- Validation rules documented in one place
+- Every use case gets consistent validation automatically
+
+Reference: [Domain-Driven Design - Aggregates](https://martinfowler.com/bliki/DDD_Aggregate.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/entity-no-persistence-awareness.md b/builtin-skills/software-engineer/clean-architecture/references/entity-no-persistence-awareness.md
new file mode 100644
index 00000000..879ecee8
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/entity-no-persistence-awareness.md
@@ -0,0 +1,90 @@
+---
+title: Entities Must Not Know How They Are Persisted
+impact: CRITICAL
+impactDescription: enables database migration without domain changes
+tags: entity, persistence, database, ignorance
+---
+
+## Entities Must Not Know How They Are Persisted
+
+Entities should have no awareness of databases, ORMs, or storage mechanisms. Persistence is an infrastructure detail that must not leak into the domain.
+
+**Incorrect (entity aware of persistence):**
+
+```java
+// domain/entities/Product.java
+@Entity
+@Table(name = "products")
+public class Product {
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(name = "product_name", nullable = false)
+    private String name;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "category_id")
+    private Category category;
+
+    @Version
+    private Long version;
+
+    // Entity is coupled to JPA, cannot exist without Hibernate
+}
+```
+
+**Correct (persistence-ignorant entity):**
+
+```java
+// domain/entities/Product.java
+public class Product {
+    private final ProductId id;
+    private String name;
+    private CategoryId categoryId;
+    private Money price;
+
+    public Product(ProductId id, String name, CategoryId categoryId, Money price) {
+        this.id = id;
+        this.name = validateName(name);
+        this.categoryId = categoryId;
+        this.price = price;
+    }
+
+    public void updatePrice(Money newPrice, PricingPolicy policy) {
+        if (!policy.allowsPrice(newPrice)) {
+            throw new InvalidPriceException(newPrice);
+        }
+        this.price = newPrice;
+    }
+
+    private String validateName(String name) {
+        if (name == null || name.isBlank()) {
+            throw new InvalidProductNameException();
+        }
+        return name.trim();
+    }
+}
+
+// infrastructure/persistence/jpa/JpaProductEntity.java
+@Entity
+@Table(name = "products")
+class JpaProductEntity {
+    @Id private Long id;
+    @Column private String name;
+    // ORM mapping isolated to infrastructure
+}
+
+// infrastructure/persistence/jpa/ProductMapper.java
+class ProductMapper {
+    Product toDomain(JpaProductEntity entity) { /* ... */ }
+    JpaProductEntity toJpa(Product product) { /* ... */ }
+}
+```
+
+**Benefits:**
+- Switch from SQL to NoSQL without touching domain
+- Entity tests don't require database setup
+- Domain model expresses business concepts, not database schema
+
+Reference: [Clean Architecture - Database is a Detail](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch30.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/entity-pure-business-rules.md b/builtin-skills/software-engineer/clean-architecture/references/entity-pure-business-rules.md
new file mode 100644
index 00000000..4efc0f19
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/entity-pure-business-rules.md
@@ -0,0 +1,68 @@
+---
+title: Entities Contain Only Enterprise Business Rules
+impact: CRITICAL
+impactDescription: enables reuse across applications, prevents coupling
+tags: entity, business-rules, domain, purity
+---
+
+## Entities Contain Only Enterprise Business Rules
+
+Entities encapsulate enterprise-wide business rules that would exist regardless of automation. They must not contain application-specific logic, persistence code, or UI concerns.
+
+**Incorrect (entity mixed with infrastructure concerns):**
+
+```typescript
+class Invoice {
+  id: string
+  items: LineItem[]
+  status: InvoiceStatus
+  dueDate: Date
+
+  calculateTotal(): Money {
+    return this.items.reduce((sum, item) => sum.add(item.amount), Money.zero())
+  }
+
+  isOverdue(): boolean {
+    return this.status === InvoiceStatus.Unpaid && new Date() > this.dueDate
+  }
+
+  markPaid(): void {
+    this.status = InvoiceStatus.Paid
+    database.invoices.update(this)  // Entity cannot be tested without database
+    emailService.send(this.customerEmail, 'Payment received')  // Coupled to email system
+  }
+}
+```
+
+**Correct (entity contains only business rules):**
+
+```typescript
+class Invoice {
+  id: string
+  items: LineItem[]
+  status: InvoiceStatus
+  dueDate: Date
+
+  calculateTotal(): Money {
+    return this.items.reduce((sum, item) => sum.add(item.amount), Money.zero())
+  }
+
+  isOverdue(): boolean {
+    return this.status === InvoiceStatus.Unpaid && new Date() > this.dueDate
+  }
+
+  markPaid(): void {
+    if (this.status !== InvoiceStatus.Unpaid) {
+      throw new InvalidOperationError('Invoice already processed')
+    }
+    this.status = InvoiceStatus.Paid
+  }
+}
+```
+
+**Benefits:**
+- Entity can be used in billing system, reporting system, mobile app
+- Business rules tested without database or email setup
+- Rules documented in one place, not scattered across application
+
+Reference: [Clean Architecture - Entities](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/entity-rich-not-anemic.md b/builtin-skills/software-engineer/clean-architecture/references/entity-rich-not-anemic.md
new file mode 100644
index 00000000..4ae6e0b3
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/entity-rich-not-anemic.md
@@ -0,0 +1,106 @@
+---
+title: Build Rich Domain Models Not Anemic Data Structures
+impact: HIGH
+impactDescription: centralizes business logic, prevents scattered rules
+tags: entity, domain-model, anemic, behavior
+---
+
+## Build Rich Domain Models Not Anemic Data Structures
+
+Entities should contain behavior, not just data. Anemic domain models push business logic into services, scattering rules and duplicating validation.
+
+**Incorrect (anemic domain model):**
+
+```java
+// domain/entities/Subscription.java
+public class Subscription {
+    private String id;
+    private String planId;
+    private LocalDate startDate;
+    private LocalDate endDate;
+    private String status;
+
+    // Only getters and setters - no behavior
+    public String getStatus() { return status; }
+    public void setStatus(String status) { this.status = status; }
+    public LocalDate getEndDate() { return endDate; }
+    public void setEndDate(LocalDate endDate) { this.endDate = endDate; }
+}
+
+// application/services/SubscriptionService.java
+public class SubscriptionService {
+    public void cancel(Subscription sub) {
+        if (!sub.getStatus().equals("active")) {
+            throw new IllegalStateException("Cannot cancel");
+        }
+        sub.setStatus("cancelled");
+        sub.setEndDate(LocalDate.now());
+    }
+
+    public void renew(Subscription sub, int months) {
+        if (!sub.getStatus().equals("active")) {
+            throw new IllegalStateException("Cannot renew");
+        }
+        sub.setEndDate(sub.getEndDate().plusMonths(months));
+    }
+    // Logic scattered across many services
+}
+```
+
+**Correct (rich domain model):**
+
+```java
+// domain/entities/Subscription.java
+public class Subscription {
+    private final SubscriptionId id;
+    private final PlanId planId;
+    private final LocalDate startDate;
+    private LocalDate endDate;
+    private SubscriptionStatus status;
+
+    public void cancel() {
+        ensureActive();
+        this.status = SubscriptionStatus.CANCELLED;
+        this.endDate = LocalDate.now();
+    }
+
+    public void renew(Period extension) {
+        ensureActive();
+        if (extension.getMonths() < 1) {
+            throw new InvalidExtensionPeriodException(extension);
+        }
+        this.endDate = this.endDate.plus(extension);
+    }
+
+    public boolean isExpired() {
+        return LocalDate.now().isAfter(this.endDate);
+    }
+
+    public boolean canUpgradeTo(Plan newPlan) {
+        return this.status == SubscriptionStatus.ACTIVE
+            && newPlan.isUpgradeFrom(this.planId);
+    }
+
+    private void ensureActive() {
+        if (this.status != SubscriptionStatus.ACTIVE) {
+            throw new InactiveSubscriptionException(this.id);
+        }
+    }
+}
+
+// application/usecases/CancelSubscriptionUseCase.java
+public class CancelSubscriptionUseCase {
+    public void execute(SubscriptionId id) {
+        Subscription sub = repository.findById(id);
+        sub.cancel();  // Business logic in entity
+        repository.save(sub);
+    }
+}
+```
+
+**Benefits:**
+- Business rules live with the data they operate on
+- Impossible to forget validation when manipulating data
+- Entity documents its own capabilities and constraints
+
+Reference: [Anemic Domain Model Anti-pattern](https://martinfowler.com/bliki/AnemicDomainModel.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/entity-value-objects.md b/builtin-skills/software-engineer/clean-architecture/references/entity-value-objects.md
new file mode 100644
index 00000000..7b8fe4f1
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/entity-value-objects.md
@@ -0,0 +1,100 @@
+---
+title: Use Value Objects for Domain Concepts
+impact: HIGH
+impactDescription: eliminates primitive obsession, enforces constraints
+tags: entity, value-objects, domain, types
+---
+
+## Use Value Objects for Domain Concepts
+
+Replace primitive types with value objects that encapsulate validation and behavior. Value objects are immutable, compared by value, and self-validating.
+
+**Incorrect (primitive obsession):**
+
+```typescript
+class Customer {
+  constructor(
+    public id: string,
+    public email: string,
+    public phone: string,
+    public postalCode: string
+  ) {}
+
+  changeEmail(newEmail: string): void {
+    // Validation scattered or missing
+    if (!newEmail.includes('@')) {
+      throw new Error('Invalid email')
+    }
+    this.email = newEmail
+  }
+}
+
+// Callers can pass any string
+const customer = new Customer('123', 'not-an-email', '123', 'invalid')
+```
+
+**Correct (value objects for domain concepts):**
+
+```typescript
+class Email {
+  private constructor(private readonly value: string) {}
+
+  static create(value: string): Email {
+    if (!Email.isValid(value)) {
+      throw new InvalidEmailError(value)
+    }
+    return new Email(value.toLowerCase())
+  }
+
+  private static isValid(value: string): boolean {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+  }
+
+  equals(other: Email): boolean {
+    return this.value === other.value
+  }
+
+  toString(): string {
+    return this.value
+  }
+}
+
+class PhoneNumber {
+  private constructor(
+    private readonly countryCode: string,
+    private readonly number: string
+  ) {}
+
+  static create(countryCode: string, number: string): PhoneNumber {
+    // Validation and normalization
+    return new PhoneNumber(countryCode, number.replace(/\D/g, ''))
+  }
+}
+
+class Customer {
+  constructor(
+    public readonly id: CustomerId,
+    private email: Email,
+    private phone: PhoneNumber
+  ) {}
+
+  changeEmail(newEmail: Email): void {
+    this.email = newEmail  // Already validated
+  }
+}
+
+// Compile-time type safety + runtime validation
+const customer = new Customer(
+  CustomerId.create('123'),
+  Email.create('user@example.com'),
+  PhoneNumber.create('+1', '555-1234')
+)
+```
+
+**Benefits:**
+- Invalid values cannot exist in the system
+- Domain concepts explicitly named in code
+- Validation logic centralized and reusable
+- Type system prevents mixing up string parameters
+
+Reference: [Value Object Pattern](https://martinfowler.com/bliki/ValueObject.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/frame-di-container-edge.md b/builtin-skills/software-engineer/clean-architecture/references/frame-di-container-edge.md
new file mode 100644
index 00000000..1e0c2b29
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/frame-di-container-edge.md
@@ -0,0 +1,116 @@
+---
+title: Dependency Injection Containers Live at the Edge
+impact: MEDIUM
+impactDescription: prevents DI container coupling throughout codebase
+tags: frame, dependency-injection, container, composition
+---
+
+## Dependency Injection Containers Live at the Edge
+
+DI containers are infrastructure. Use them at composition root (main/startup) to wire dependencies, but don't let them invade domain or application code.
+
+**Incorrect (DI container throughout codebase):**
+
+```csharp
+// Domain depends on DI container
+using Microsoft.Extensions.DependencyInjection;
+
+public class Order
+{
+    public void Process()
+    {
+        // Service locator anti-pattern
+        var emailService = ServiceLocator.Current.GetService<IEmailService>();
+        var logger = ServiceLocator.Current.GetService<ILogger>();
+
+        // ...
+    }
+}
+
+// Application layer decorated with DI attributes
+public class CreateOrderUseCase
+{
+    [Inject]
+    public IOrderRepository Orders { get; set; }
+
+    [Inject]
+    public IPaymentGateway Payments { get; set; }
+
+    // Properties injected by container - hidden dependencies
+}
+
+// Switching DI containers requires touching domain code
+```
+
+**Correct (DI container only at composition root):**
+
+```csharp
+// Domain - no DI container knowledge
+public class Order
+{
+    public void Process(IEmailService email, ILogger logger)
+    {
+        // Dependencies passed explicitly
+    }
+}
+
+// Application - constructor injection, no container knowledge
+public class CreateOrderUseCase
+{
+    private readonly IOrderRepository _orders;
+    private readonly IPaymentGateway _payments;
+
+    // Plain constructor - works with any DI container or manual wiring
+    public CreateOrderUseCase(
+        IOrderRepository orders,
+        IPaymentGateway payments)
+    {
+        _orders = orders;
+        _payments = payments;
+    }
+}
+
+// Composition root - only place that knows about DI container
+// Program.cs or Startup.cs
+public class CompositionRoot
+{
+    public static IServiceProvider ConfigureServices()
+    {
+        var services = new ServiceCollection();
+
+        // Infrastructure
+        services.AddScoped<IOrderRepository, PostgresOrderRepository>();
+        services.AddScoped<IPaymentGateway, StripePaymentGateway>();
+        services.AddScoped<IEmailService, SendGridEmailService>();
+
+        // Application
+        services.AddScoped<CreateOrderUseCase>();
+        services.AddScoped<GetOrdersUseCase>();
+
+        // Interface
+        services.AddScoped<OrderController>();
+
+        return services.BuildServiceProvider();
+    }
+}
+
+// For tests - manual wiring without container
+[Test]
+public void CreatesOrder()
+{
+    var orders = new InMemoryOrderRepository();
+    var payments = new FakePaymentGateway();
+    var useCase = new CreateOrderUseCase(orders, payments);
+
+    useCase.Execute(command);
+
+    Assert.That(orders.All(), Has.Count.EqualTo(1));
+}
+```
+
+**Benefits:**
+- Domain and application code portable across DI containers
+- Tests don't need DI container setup
+- Dependencies explicit in constructors
+
+Reference: [Composition Root Pattern](https://blog.ploeh.dk/2011/07/28/CompositionRoot/)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/frame-domain-purity.md b/builtin-skills/software-engineer/clean-architecture/references/frame-domain-purity.md
new file mode 100644
index 00000000..fc03df02
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/frame-domain-purity.md
@@ -0,0 +1,121 @@
+---
+title: Domain Layer Has Zero Framework Dependencies
+impact: MEDIUM
+impactDescription: enables framework migration, pure unit tests
+tags: frame, domain, purity, dependencies
+---
+
+## Domain Layer Has Zero Framework Dependencies
+
+The domain layer (entities and domain services) should have zero dependencies on frameworks, ORMs, or external libraries. Only language primitives and domain-specific code.
+
+**Incorrect (domain depends on framework):**
+
+```csharp
+// Domain entity with framework dependencies
+using Microsoft.EntityFrameworkCore;
+using System.ComponentModel.DataAnnotations;
+using Newtonsoft.Json;
+
+namespace Domain.Entities
+{
+    [Table("products")]
+    public class Product
+    {
+        [Key]
+        [DatabaseGenerated(DatabaseGeneratedOption.Identity)]
+        public int Id { get; set; }
+
+        [Required]
+        [MaxLength(100)]
+        [JsonProperty("product_name")]
+        public string Name { get; set; }
+
+        [Column(TypeName = "decimal(18,2)")]
+        public decimal Price { get; set; }
+
+        // EF Core navigation property
+        public virtual Category Category { get; set; }
+
+        // Framework-specific validation
+        public IEnumerable<ValidationResult> Validate(ValidationContext context)
+        {
+            if (Price < 0)
+                yield return new ValidationResult("Price cannot be negative");
+        }
+    }
+}
+// Domain now depends on: EF Core, DataAnnotations, Newtonsoft.Json
+// Cannot exist without these frameworks
+```
+
+**Correct (pure domain):**
+
+```csharp
+// Domain entity - zero framework dependencies
+namespace Domain.Entities
+{
+    public class Product
+    {
+        public ProductId Id { get; }
+        public string Name { get; private set; }
+        public Money Price { get; private set; }
+        public CategoryId CategoryId { get; private set; }
+
+        public Product(ProductId id, string name, Money price, CategoryId categoryId)
+        {
+            if (string.IsNullOrWhiteSpace(name))
+                throw new InvalidProductNameException();
+            if (name.Length > 100)
+                throw new ProductNameTooLongException(name.Length, 100);
+            if (price.IsNegative)
+                throw new NegativePriceException(price);
+
+            Id = id;
+            Name = name;
+            Price = price;
+            CategoryId = categoryId;
+        }
+
+        public void UpdatePrice(Money newPrice)
+        {
+            if (newPrice.IsNegative)
+                throw new NegativePriceException(newPrice);
+            Price = newPrice;
+        }
+    }
+}
+
+// Infrastructure - framework dependencies isolated here
+namespace Infrastructure.Persistence
+{
+    using Microsoft.EntityFrameworkCore;
+
+    [Table("products")]
+    internal class ProductEntity
+    {
+        [Key] public int Id { get; set; }
+        [MaxLength(100)] public string Name { get; set; }
+        [Column(TypeName = "decimal(18,2)")] public decimal Price { get; set; }
+        public int CategoryId { get; set; }
+    }
+
+    internal class ProductMapper
+    {
+        public Product ToDomain(ProductEntity entity) => /* ... */
+        public ProductEntity ToEntity(Product product) => /* ... */
+    }
+}
+```
+
+**How to check domain purity:**
+```bash
+# Domain project should have no package references
+dotnet list Domain.csproj package
+# Should return: No packages found
+
+# Or in package.json
+# "dependencies": {} should be empty or only contain domain libraries
+```
+
+Reference: [Clean Architecture - Frameworks are Details](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/frame-logging-abstraction.md b/builtin-skills/software-engineer/clean-architecture/references/frame-logging-abstraction.md
new file mode 100644
index 00000000..400f0a13
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/frame-logging-abstraction.md
@@ -0,0 +1,127 @@
+---
+title: Abstract Logging Behind Domain Interfaces
+impact: MEDIUM
+impactDescription: prevents logging framework coupling, enables structured logging
+tags: frame, logging, abstraction, cross-cutting
+---
+
+## Abstract Logging Behind Domain Interfaces
+
+Logging frameworks are infrastructure details. Define logging interfaces in the application layer; implement them in infrastructure. This enables switching loggers and keeps domain pure.
+
+**Incorrect (logging framework in domain/application):**
+
+```go
+package usecases
+
+import (
+    "github.com/sirupsen/logrus"  // Framework dependency
+)
+
+type CreateOrderUseCase struct {
+    repo   OrderRepository
+    logger *logrus.Logger  // Concrete logger
+}
+
+func (uc *CreateOrderUseCase) Execute(cmd CreateOrderCommand) (*Order, error) {
+    uc.logger.WithFields(logrus.Fields{
+        "customer_id": cmd.CustomerID,
+        "item_count":  len(cmd.Items),
+    }).Info("Creating order")
+
+    order, err := uc.repo.Create(cmd)
+    if err != nil {
+        uc.logger.WithError(err).Error("Failed to create order")
+        return nil, err
+    }
+
+    uc.logger.WithField("order_id", order.ID).Info("Order created")
+    return order, nil
+}
+
+// Switching from logrus to zap requires changing all use cases
+```
+
+**Correct (logging behind interface):**
+
+```go
+// application/ports/logger.go
+package ports
+
+type Logger interface {
+    Info(msg string, fields ...Field)
+    Error(msg string, err error, fields ...Field)
+    Debug(msg string, fields ...Field)
+}
+
+type Field struct {
+    Key   string
+    Value interface{}
+}
+
+func F(key string, value interface{}) Field {
+    return Field{Key: key, Value: value}
+}
+
+// application/usecases/create_order.go
+package usecases
+
+import "myapp/application/ports"
+
+type CreateOrderUseCase struct {
+    repo   OrderRepository
+    logger ports.Logger
+}
+
+func (uc *CreateOrderUseCase) Execute(cmd CreateOrderCommand) (*Order, error) {
+    uc.logger.Info("Creating order",
+        ports.F("customer_id", cmd.CustomerID),
+        ports.F("item_count", len(cmd.Items)),
+    )
+
+    order, err := uc.repo.Create(cmd)
+    if err != nil {
+        uc.logger.Error("Failed to create order", err,
+            ports.F("customer_id", cmd.CustomerID),
+        )
+        return nil, err
+    }
+
+    uc.logger.Info("Order created", ports.F("order_id", order.ID))
+    return order, nil
+}
+
+// infrastructure/logging/logrus_logger.go
+package logging
+
+import (
+    "github.com/sirupsen/logrus"
+    "myapp/application/ports"
+)
+
+type LogrusLogger struct {
+    logger *logrus.Logger
+}
+
+func (l *LogrusLogger) Info(msg string, fields ...ports.Field) {
+    l.logger.WithFields(toLogrusFields(fields)).Info(msg)
+}
+
+func toLogrusFields(fields []ports.Field) logrus.Fields {
+    result := logrus.Fields{}
+    for _, f := range fields {
+        result[f.Key] = f.Value
+    }
+    return result
+}
+
+// infrastructure/logging/zap_logger.go - Alternative implementation
+// Switch without touching use cases
+```
+
+**Benefits:**
+- Application code doesn't import logging frameworks
+- Easy to switch logging backends
+- Test logging by asserting on mock logger calls
+
+Reference: [Clean Architecture - Frameworks are Details](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/frame-orm-in-infrastructure.md b/builtin-skills/software-engineer/clean-architecture/references/frame-orm-in-infrastructure.md
new file mode 100644
index 00000000..ff71882a
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/frame-orm-in-infrastructure.md
@@ -0,0 +1,103 @@
+---
+title: Keep ORM Usage in Infrastructure Layer
+impact: MEDIUM
+impactDescription: isolates persistence complexity, enables ORM switching
+tags: frame, orm, infrastructure, persistence
+---
+
+## Keep ORM Usage in Infrastructure Layer
+
+ORM-specific code (entities, mappings, queries) belongs in the infrastructure layer. The domain and application layers should not know which ORM (or if any ORM) is being used.
+
+**Incorrect (ORM in application layer):**
+
+```python
+# application/usecases/get_orders.py
+from sqlalchemy.orm import Session, joinedload
+from sqlalchemy import and_, or_
+
+class GetOrdersUseCase:
+    def __init__(self, session: Session):  # SQLAlchemy session in use case
+        self.session = session
+
+    def execute(self, customer_id: str, filters: OrderFilters):
+        # SQLAlchemy query in use case
+        query = self.session.query(Order).options(
+            joinedload(Order.items),
+            joinedload(Order.customer)
+        )
+
+        if filters.status:
+            query = query.filter(Order.status == filters.status)
+
+        if filters.date_range:
+            query = query.filter(and_(
+                Order.created_at >= filters.date_range.start,
+                Order.created_at <= filters.date_range.end
+            ))
+
+        return query.order_by(Order.created_at.desc()).all()
+
+# Use case is now coupled to SQLAlchemy
+# Switching to Peewee or raw SQL requires rewriting use case
+```
+
+**Correct (ORM isolated in infrastructure):**
+
+```python
+# application/ports/order_repository.py
+from abc import ABC, abstractmethod
+
+class OrderRepository(ABC):
+    @abstractmethod
+    def find_by_customer(
+        self,
+        customer_id: CustomerId,
+        filters: OrderFilters
+    ) -> list[Order]:
+        pass
+
+# application/usecases/get_orders.py
+class GetOrdersUseCase:
+    def __init__(self, orders: OrderRepository):  # Interface, not Session
+        self.orders = orders
+
+    def execute(self, customer_id: str, filters: OrderFilters) -> list[Order]:
+        return self.orders.find_by_customer(
+            CustomerId(customer_id),
+            filters
+        )
+
+# infrastructure/persistence/sqlalchemy_order_repository.py
+from sqlalchemy.orm import Session, joinedload
+
+class SqlAlchemyOrderRepository(OrderRepository):
+    def __init__(self, session: Session):
+        self.session = session
+
+    def find_by_customer(
+        self,
+        customer_id: CustomerId,
+        filters: OrderFilters
+    ) -> list[Order]:
+        query = self.session.query(OrderEntity).options(
+            joinedload(OrderEntity.items)
+        ).filter(OrderEntity.customer_id == customer_id.value)
+
+        if filters.status:
+            query = query.filter(OrderEntity.status == filters.status.value)
+
+        entities = query.order_by(OrderEntity.created_at.desc()).all()
+        return [self._to_domain(e) for e in entities]
+
+    def _to_domain(self, entity: OrderEntity) -> Order:
+        # Map ORM entity to domain entity
+        pass
+```
+
+**Benefits:**
+- Use case tests don't need database or ORM setup
+- Can switch ORMs without touching business logic
+- Complex queries encapsulated in repository
+
+Reference: [Repository Pattern](https://martinfowler.com/eaaCatalog/repository.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/frame-web-in-infrastructure.md b/builtin-skills/software-engineer/clean-architecture/references/frame-web-in-infrastructure.md
new file mode 100644
index 00000000..c1cb8132
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/frame-web-in-infrastructure.md
@@ -0,0 +1,132 @@
+---
+title: Web Framework Concerns Stay in Interface Layer
+impact: MEDIUM
+impactDescription: enables delivery mechanism substitution
+tags: frame, web, http, interface
+---
+
+## Web Framework Concerns Stay in Interface Layer
+
+HTTP-specific code (requests, responses, headers, cookies, sessions) belongs in the interface adapters layer. Use cases should be callable from any delivery mechanism.
+
+**Incorrect (use case coupled to HTTP):**
+
+```typescript
+// application/usecases/LoginUseCase.ts
+import { Request, Response } from 'express'
+import { sign } from 'jsonwebtoken'
+
+export class LoginUseCase {
+  async execute(req: Request, res: Response) {
+    const { email, password } = req.body
+
+    const user = await this.users.findByEmail(email)
+    if (!user || !user.verifyPassword(password)) {
+      return res.status(401).json({ error: 'Invalid credentials' })
+    }
+
+    // Set HTTP-only cookie
+    const token = sign({ userId: user.id }, process.env.JWT_SECRET)
+    res.cookie('auth_token', token, {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === 'production',
+      sameSite: 'strict'
+    })
+
+    return res.json({ user: { id: user.id, email: user.email } })
+  }
+}
+
+// Cannot call from CLI, message queue, or test without Express
+```
+
+**Correct (use case independent of delivery):**
+
+```typescript
+// application/usecases/LoginUseCase.ts
+export interface LoginCommand {
+  email: string
+  password: string
+}
+
+export interface LoginResult {
+  userId: string
+  email: string
+  authToken: string
+}
+
+export class LoginUseCase {
+  constructor(
+    private users: UserRepository,
+    private tokenService: TokenService
+  ) {}
+
+  async execute(command: LoginCommand): Promise<LoginResult> {
+    const user = await this.users.findByEmail(command.email)
+
+    if (!user) {
+      throw new InvalidCredentialsError()
+    }
+
+    if (!user.verifyPassword(command.password)) {
+      throw new InvalidCredentialsError()
+    }
+
+    const token = this.tokenService.generate({ userId: user.id.value })
+
+    return {
+      userId: user.id.value,
+      email: user.email.value,
+      authToken: token
+    }
+  }
+}
+
+// interface/http/AuthController.ts
+import { Request, Response } from 'express'
+
+export class AuthController {
+  constructor(private loginUseCase: LoginUseCase) {}
+
+  async login(req: Request, res: Response) {
+    try {
+      const result = await this.loginUseCase.execute({
+        email: req.body.email,
+        password: req.body.password
+      })
+
+      // HTTP concerns in controller
+      res.cookie('auth_token', result.authToken, {
+        httpOnly: true,
+        secure: process.env.NODE_ENV === 'production',
+        sameSite: 'strict'
+      })
+
+      return res.json({
+        user: { id: result.userId, email: result.email }
+      })
+    } catch (error) {
+      if (error instanceof InvalidCredentialsError) {
+        return res.status(401).json({ error: 'Invalid credentials' })
+      }
+      throw error
+    }
+  }
+}
+
+// interface/cli/AuthCli.ts - Same use case, different delivery
+export class AuthCli {
+  async login(email: string, password: string) {
+    const result = await this.loginUseCase.execute({ email, password })
+    console.log(`Logged in as ${result.email}`)
+    fs.writeFileSync('.auth_token', result.authToken)
+  }
+}
+```
+
+**Benefits:**
+- Same use case for HTTP, CLI, WebSocket, queue consumers
+- Easy to test without HTTP mocking
+- Web framework upgrades isolated to interface layer
+
+Reference: [Clean Architecture - The Web is a Detail](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch31.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/test-boundary-verification.md b/builtin-skills/software-engineer/clean-architecture/references/test-boundary-verification.md
new file mode 100644
index 00000000..54ac7bb7
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/test-boundary-verification.md
@@ -0,0 +1,106 @@
+---
+title: Verify Architectural Boundaries with Tests
+impact: LOW-MEDIUM
+impactDescription: prevents boundary erosion, enforces dependency rules
+tags: test, boundaries, architecture, enforcement
+---
+
+## Verify Architectural Boundaries with Tests
+
+Use automated tests to enforce that dependency rules are followed. Architecture tests catch violations before they become entrenched patterns.
+
+**Incorrect (no boundary verification):**
+
+```java
+// Over time, developers add shortcuts
+// domain/Order.java
+import org.springframework.stereotype.Component;  // Framework in domain!
+import javax.persistence.Entity;                   // JPA in domain!
+
+// application/CreateOrderUseCase.java
+import com.stripe.Stripe;  // Direct payment vendor dependency!
+import infrastructure.email.SendGridClient;  // Infrastructure in application!
+
+// No tests catch these violations
+// They accumulate until refactoring becomes impossible
+```
+
+**Correct (architecture tests enforce boundaries):**
+
+```java
+// Using ArchUnit (Java) or similar tools
+@AnalyzeClasses(packages = "com.myapp")
+class ArchitectureTest {
+
+    @ArchTest
+    static final ArchRule domain_should_not_depend_on_infrastructure =
+        noClasses()
+            .that().resideInAPackage("..domain..")
+            .should().dependOnClassesThat()
+            .resideInAPackage("..infrastructure..");
+
+    @ArchTest
+    static final ArchRule domain_should_not_use_frameworks =
+        noClasses()
+            .that().resideInAPackage("..domain..")
+            .should().dependOnClassesThat()
+            .resideInAnyPackage(
+                "org.springframework..",
+                "javax.persistence..",
+                "jakarta.persistence.."
+            );
+
+    @ArchTest
+    static final ArchRule usecases_should_not_access_controllers =
+        noClasses()
+            .that().resideInAPackage("..application..")
+            .should().dependOnClassesThat()
+            .resideInAPackage("..interface..");
+
+    @ArchTest
+    static final ArchRule dependencies_point_inward =
+        layeredArchitecture()
+            .consideringAllDependencies()
+            .layer("Domain").definedBy("..domain..")
+            .layer("Application").definedBy("..application..")
+            .layer("Infrastructure").definedBy("..infrastructure..")
+            .layer("Interface").definedBy("..interface..")
+            .whereLayer("Domain").mayNotAccessAnyLayer()
+            .whereLayer("Application").mayOnlyAccessLayers("Domain")
+            .whereLayer("Infrastructure").mayOnlyAccessLayers("Domain", "Application")
+            .whereLayer("Interface").mayOnlyAccessLayers("Domain", "Application");
+}
+
+// TypeScript equivalent using dependency-cruiser
+// .dependency-cruiser.js
+module.exports = {
+  forbidden: [
+    {
+      name: 'domain-no-infra',
+      from: { path: '^src/domain' },
+      to: { path: '^src/infrastructure' }
+    },
+    {
+      name: 'domain-no-frameworks',
+      from: { path: '^src/domain' },
+      to: { path: 'node_modules/(express|prisma|typeorm)' }
+    }
+  ]
+};
+```
+
+**Run in CI:**
+```yaml
+# .github/workflows/ci.yml
+- name: Check architecture
+  run: |
+    ./gradlew archTest  # Java with ArchUnit
+    npx depcruise src   # TypeScript with dependency-cruiser
+```
+
+**Benefits:**
+- Violations caught immediately in CI
+- New developers can't accidentally break boundaries
+- Architecture documentation that stays accurate
+
+Reference: [ArchUnit](https://www.archunit.org/)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/test-layer-isolation.md b/builtin-skills/software-engineer/clean-architecture/references/test-layer-isolation.md
new file mode 100644
index 00000000..a22cf141
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/test-layer-isolation.md
@@ -0,0 +1,121 @@
+---
+title: Test Each Layer in Isolation
+impact: LOW-MEDIUM
+impactDescription: fast feedback, precise failure location
+tags: test, isolation, layers, unit
+---
+
+## Test Each Layer in Isolation
+
+Each architectural layer should be testable independently. Domain tests need no infrastructure. Use case tests need no web framework. This enables fast, focused testing.
+
+**Incorrect (everything tested through API):**
+
+```typescript
+// All tests go through HTTP - slow, imprecise failures
+describe('Order API', () => {
+  let app: Express
+  let db: Database
+
+  beforeEach(async () => {
+    db = await Database.connect()
+    await db.migrate()
+    await db.seed()
+    app = createApp(db)
+  })
+
+  afterEach(async () => {
+    await db.clean()
+    await db.close()
+  })
+
+  it('rejects order with insufficient inventory', async () => {
+    // 500ms+ per test
+    const response = await request(app)
+      .post('/orders')
+      .send({ items: [{ productId: 'p1', quantity: 1000 }] })
+
+    expect(response.status).toBe(400)
+    expect(response.body.error).toBe('Insufficient inventory')
+  })
+
+  // 50 more tests like this - test suite takes 5 minutes
+  // When one fails, unclear if it's domain, use case, or HTTP issue
+})
+```
+
+**Correct (layered testing):**
+
+```typescript
+// Domain layer tests - instant, no dependencies
+describe('Order', () => {
+  it('calculates total from items', () => {
+    const order = new Order()
+    order.addItem(new Product('p1', Money.dollars(10)), 2)
+    order.addItem(new Product('p2', Money.dollars(5)), 1)
+
+    expect(order.total).toEqual(Money.dollars(25))
+  })
+
+  it('prevents adding item with zero quantity', () => {
+    const order = new Order()
+
+    expect(() => order.addItem(product, 0)).toThrow(InvalidQuantityError)
+  })
+})
+
+// Use case tests - fast, test doubles for ports
+describe('PlaceOrderUseCase', () => {
+  it('rejects order when inventory insufficient', () => {
+    const orders = new InMemoryOrderRepository()
+    const inventory = new FakeInventory({ 'p1': 5 })  // Only 5 in stock
+    const useCase = new PlaceOrderUseCase(orders, inventory)
+
+    const result = useCase.execute({
+      items: [{ productId: 'p1', quantity: 10 }]  // Want 10
+    })
+
+    expect(result.isFailure).toBe(true)
+    expect(result.error).toBe('INSUFFICIENT_INVENTORY')
+  })
+})
+
+// Infrastructure tests - verify adapters work correctly
+describe('PostgresOrderRepository', () => {
+  it('persists and retrieves order', async () => {
+    const repo = new PostgresOrderRepository(testDb)
+    const order = createTestOrder()
+
+    await repo.save(order)
+    const retrieved = await repo.findById(order.id)
+
+    expect(retrieved).toEqual(order)
+  })
+})
+
+// API tests - few, verify wiring only
+describe('POST /orders', () => {
+  it('returns 201 when order placed successfully', async () => {
+    // Most logic tested above; this verifies HTTP wiring
+    const response = await request(app)
+      .post('/orders')
+      .send(validOrderPayload)
+
+    expect(response.status).toBe(201)
+    expect(response.body).toHaveProperty('orderId')
+  })
+})
+```
+
+**Test pyramid:**
+```text
+        /\
+       /  \     E2E: ~5 tests (slow, expensive)
+      /----\
+     /      \   Integration: ~20 tests (medium)
+    /--------\
+   /          \ Unit: ~200 tests (fast, cheap)
+  /____________\
+```
+
+Reference: [The Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/test-testable-design.md b/builtin-skills/software-engineer/clean-architecture/references/test-testable-design.md
new file mode 100644
index 00000000..9849e8d8
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/test-testable-design.md
@@ -0,0 +1,104 @@
+---
+title: Design for Testability From the Start
+impact: LOW-MEDIUM
+impactDescription: enables comprehensive testing without test-induced damage
+tags: test, testability, design, interfaces
+---
+
+## Design for Testability From the Start
+
+Clean architecture makes testing easy by design. If something is hard to test, it's a sign of architectural coupling. Don't compromise architecture for testability; fix the coupling.
+
+**Incorrect (hard to test, requiring workarounds):**
+
+```java
+public class OrderProcessor {
+    public void process(Order order) {
+        // Hard to test: direct instantiation
+        PaymentService payment = new PaymentService();
+
+        // Hard to test: static call
+        if (InventoryChecker.isAvailable(order.getItems())) {
+
+            // Hard to test: singleton
+            payment.charge(order.getTotal());
+            NotificationService.getInstance().sendConfirmation(order);
+
+            // Hard to test: current time
+            order.setProcessedAt(new Date());
+        }
+    }
+}
+
+// Test requires PowerMock, static mocking, singleton reset
+// Test is slow, brittle, and complicated
+@Test
+@PrepareForTest({InventoryChecker.class, NotificationService.class})
+public void testProcess() {
+    PowerMockito.mockStatic(InventoryChecker.class);
+    PowerMockito.when(InventoryChecker.isAvailable(any())).thenReturn(true);
+    // ... 20 more lines of mock setup
+}
+```
+
+**Correct (testable by design):**
+
+```java
+public class OrderProcessor {
+    private final InventoryChecker inventory;
+    private final PaymentGateway payment;
+    private final NotificationPort notification;
+    private final Clock clock;
+
+    // All dependencies injected - easy to substitute
+    public OrderProcessor(
+        InventoryChecker inventory,
+        PaymentGateway payment,
+        NotificationPort notification,
+        Clock clock
+    ) {
+        this.inventory = inventory;
+        this.payment = payment;
+        this.notification = notification;
+        this.clock = clock;
+    }
+
+    public ProcessResult process(Order order) {
+        if (!inventory.isAvailable(order.getItems())) {
+            return ProcessResult.unavailable();
+        }
+
+        PaymentResult paymentResult = payment.charge(order.getTotal());
+        if (!paymentResult.isSuccessful()) {
+            return ProcessResult.paymentFailed(paymentResult.getError());
+        }
+
+        order.markProcessed(clock.now());
+        notification.sendConfirmation(order);
+
+        return ProcessResult.success(order);
+    }
+}
+
+@Test
+void processesOrderWhenInventoryAvailable() {
+    var inventory = StubInventory.withAvailability(true);
+    var payment = FakePaymentGateway.alwaysSucceeds();
+    var notification = new SpyNotification();
+    var clock = Clock.fixed(Instant.parse("2024-01-15T10:00:00Z"), ZoneOffset.UTC);
+
+    var processor = new OrderProcessor(inventory, payment, notification, clock);
+    var result = processor.process(order);
+
+    assertThat(result.isSuccessful()).isTrue();
+}
+```
+
+**Testability checklist:**
+- [ ] No `new` for services (inject dependencies)
+- [ ] No static method calls for behavior (use interfaces)
+- [ ] No singletons (pass instances)
+- [ ] No direct time/random access (inject Clock, Random)
+- [ ] No hidden dependencies (everything in constructor)
+
+Reference: [Growing Object-Oriented Software, Guided by Tests](http://www.growing-object-oriented-software.com/)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/test-tests-are-architecture.md b/builtin-skills/software-engineer/clean-architecture/references/test-tests-are-architecture.md
new file mode 100644
index 00000000..ca15d7df
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/test-tests-are-architecture.md
@@ -0,0 +1,106 @@
+---
+title: Tests Are Part of the System Architecture
+impact: LOW-MEDIUM
+impactDescription: enables fast feedback, documents behavior
+tags: test, architecture, design, first-class
+---
+
+## Tests Are Part of the System Architecture
+
+Tests participate in the architecture like any other component. They follow the dependency rule, couple to stable APIs, and should be designed for maintainability.
+
+**Incorrect (tests as afterthought):**
+
+```python
+# tests/test_everything.py - Monolithic test file
+import pytest
+from unittest.mock import patch, MagicMock
+
+class TestOrders:
+    @patch('app.services.order_service.db')
+    @patch('app.services.order_service.stripe')
+    @patch('app.services.order_service.email_sender')
+    @patch('app.services.order_service.inventory')
+    def test_create_order(self, mock_inv, mock_email, mock_stripe, mock_db):
+        # Testing implementation details
+        mock_db.query.return_value.filter.return_value.first.return_value = Customer(id=1)
+        mock_inv.check.return_value = True
+        mock_stripe.PaymentIntent.create.return_value = MagicMock(id='pi_123')
+
+        from app.services.order_service import create_order
+        result = create_order({'customer_id': 1, 'items': [...]})
+
+        # Asserting on internal calls, not behavior
+        mock_db.query.assert_called()
+        mock_stripe.PaymentIntent.create.assert_called_once()
+
+# Tests coupled to implementation, break with refactoring
+# Tests slow because they patch everything
+```
+
+**Correct (tests designed as architecture component):**
+
+```python
+# tests/unit/domain/test_order.py - Fast, stable, test domain rules
+class TestOrder:
+    def test_calculates_total_from_line_items(self):
+        order = Order.create(customer_id="c1")
+        order.add_item(Product("p1", Money(100)))
+        order.add_item(Product("p2", Money(50)))
+
+        assert order.total == Money(150)
+
+    def test_rejects_negative_quantity(self):
+        order = Order.create(customer_id="c1")
+
+        with pytest.raises(InvalidQuantityError):
+            order.add_item(Product("p1", Money(100)), quantity=-1)
+
+# tests/integration/application/test_create_order.py - Test use case
+class TestCreateOrderUseCase:
+    def test_creates_order_and_reserves_inventory(self):
+        # Use test doubles, not mocks of internals
+        orders = InMemoryOrderRepository()
+        inventory = FakeInventoryService(available={"p1": 10})
+        use_case = CreateOrderUseCase(orders, inventory)
+
+        result = use_case.execute(CreateOrderCommand(
+            customer_id="c1",
+            items=[OrderItem("p1", quantity=2)]
+        ))
+
+        # Assert on observable behavior
+        assert orders.find_by_id(result.order_id) is not None
+        assert inventory.reserved["p1"] == 2
+
+# tests/e2e/test_order_flow.py - Full flow, few tests
+class TestOrderFlow:
+    def test_complete_order_journey(self, api_client, test_db):
+        # Create order via API
+        response = api_client.post('/orders', json={...})
+        order_id = response.json['order_id']
+
+        # Verify order persisted
+        order = test_db.query(Order).get(order_id)
+        assert order.status == 'pending'
+```
+
+**Test architecture mirrors system:**
+```text
+tests/
+├── unit/                    # Fast, isolated
+│   ├── domain/              # Entity business rules
+│   └── application/         # Use case logic
+├── integration/             # Component interaction
+│   ├── persistence/         # Repository implementations
+│   └── external/            # Gateway implementations
+└── e2e/                     # Full system
+    └── api/                 # HTTP endpoints
+```
+
+**Benefits:**
+- Unit tests run in milliseconds
+- Refactoring doesn't break tests
+- Tests document intended behavior
+
+Reference: [Clean Architecture - The Test Boundary](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch28.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/usecase-explicit-dependencies.md b/builtin-skills/software-engineer/clean-architecture/references/usecase-explicit-dependencies.md
new file mode 100644
index 00000000..76cd761a
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/usecase-explicit-dependencies.md
@@ -0,0 +1,104 @@
+---
+title: Declare All Dependencies Explicitly in Constructor
+impact: HIGH
+impactDescription: enables testing, documents requirements, prevents hidden coupling
+tags: usecase, dependencies, constructor, injection
+---
+
+## Declare All Dependencies Explicitly in Constructor
+
+Use cases should receive all dependencies through their constructor. Hidden dependencies (service locators, singletons, static calls) make testing difficult and hide coupling.
+
+**Incorrect (hidden dependencies):**
+
+```java
+public class PlaceOrderUseCase {
+    public OrderConfirmation execute(PlaceOrderCommand command) {
+        // Hidden dependencies - impossible to test or trace
+        var customer = CustomerRepository.getInstance().find(command.customerId());
+        var inventory = InventoryService.getInventory();
+
+        for (var item : command.items()) {
+            if (!inventory.isAvailable(item)) {
+                throw new OutOfStockException(item);
+            }
+        }
+
+        var order = new Order(customer, command.items());
+
+        // More hidden dependencies
+        Database.getConnection().save(order);
+        EmailService.send(customer.email(), "Order placed");
+        EventBus.publish(new OrderPlacedEvent(order));
+
+        return new OrderConfirmation(order.id());
+    }
+}
+
+// Testing requires mocking static methods - complex and brittle
+```
+
+**Correct (explicit constructor dependencies):**
+
+```java
+public class PlaceOrderUseCase {
+    private final CustomerRepository customers;
+    private final InventoryChecker inventory;
+    private final OrderRepository orders;
+    private final NotificationPort notifications;
+    private final EventPublisher events;
+
+    public PlaceOrderUseCase(
+        CustomerRepository customers,
+        InventoryChecker inventory,
+        OrderRepository orders,
+        NotificationPort notifications,
+        EventPublisher events
+    ) {
+        this.customers = customers;
+        this.inventory = inventory;
+        this.orders = orders;
+        this.notifications = notifications;
+        this.events = events;
+    }
+
+    public OrderConfirmation execute(PlaceOrderCommand command) {
+        var customer = customers.find(command.customerId());
+
+        for (var item : command.items()) {
+            if (!inventory.isAvailable(item)) {
+                throw new OutOfStockException(item);
+            }
+        }
+
+        var order = new Order(customer, command.items());
+        orders.save(order);
+
+        notifications.orderPlaced(customer, order);
+        events.publish(new OrderPlacedEvent(order));
+
+        return new OrderConfirmation(order.id());
+    }
+}
+
+// Testing is straightforward
+@Test
+void placesOrderWhenInventoryAvailable() {
+    var customers = mock(CustomerRepository.class);
+    var inventory = mock(InventoryChecker.class);
+    var orders = mock(OrderRepository.class);
+    // ... configure mocks
+
+    var useCase = new PlaceOrderUseCase(customers, inventory, orders, ...);
+    var result = useCase.execute(command);
+
+    verify(orders).save(any(Order.class));
+}
+```
+
+**Benefits:**
+- Dependencies visible in constructor signature
+- Tests substitute any dependency with test doubles
+- Coupling is explicit and measurable
+
+Reference: [Dependency Injection Principles](https://martinfowler.com/articles/injection.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/usecase-input-output-ports.md b/builtin-skills/software-engineer/clean-architecture/references/usecase-input-output-ports.md
new file mode 100644
index 00000000..7041ebf4
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/usecase-input-output-ports.md
@@ -0,0 +1,98 @@
+---
+title: Define Input and Output Ports for Use Cases
+impact: HIGH
+impactDescription: decouples use cases from delivery mechanism
+tags: usecase, ports, input, output, boundaries
+---
+
+## Define Input and Output Ports for Use Cases
+
+Use cases should define their own input (request) and output (response) data structures. These ports isolate the use case from the delivery mechanism (HTTP, CLI, queue).
+
+**Incorrect (use case coupled to HTTP):**
+
+```csharp
+public class RegisterUserUseCase
+{
+    public IActionResult Execute(HttpRequest request)  // Coupled to ASP.NET
+    {
+        var email = request.Form["email"];
+        var password = request.Form["password"];
+
+        if (string.IsNullOrEmpty(email))
+            return new BadRequestResult();  // HTTP-specific response
+
+        var user = new User(email, password);
+        _repository.Save(user);
+
+        return new OkObjectResult(new { id = user.Id });  // JSON response
+    }
+}
+```
+
+**Correct (use case with defined ports):**
+
+```csharp
+// application/ports/input/RegisterUserCommand.cs
+public record RegisterUserCommand(
+    string Email,
+    string Password,
+    string Name
+);
+
+// application/ports/output/RegisterUserResult.cs
+public record RegisterUserResult(
+    string UserId,
+    string Email,
+    DateTime CreatedAt
+);
+
+// application/usecases/RegisterUserUseCase.cs
+public class RegisterUserUseCase
+{
+    private readonly IUserRepository _repository;
+    private readonly IPasswordHasher _hasher;
+
+    public RegisterUserResult Execute(RegisterUserCommand command)
+    {
+        if (string.IsNullOrEmpty(command.Email))
+            throw new ValidationException("Email required");
+
+        var hashedPassword = _hasher.Hash(command.Password);
+        var user = new User(command.Email, hashedPassword, command.Name);
+        _repository.Save(user);
+
+        return new RegisterUserResult(
+            user.Id.Value,
+            user.Email.Value,
+            user.CreatedAt
+        );
+    }
+}
+
+// interface_adapters/controllers/UserController.cs
+[ApiController]
+public class UserController : ControllerBase
+{
+    [HttpPost]
+    public IActionResult Register([FromBody] RegisterRequest request)
+    {
+        var command = new RegisterUserCommand(
+            request.Email,
+            request.Password,
+            request.Name
+        );
+
+        var result = _useCase.Execute(command);
+
+        return Ok(new { userId = result.UserId });
+    }
+}
+```
+
+**Benefits:**
+- Same use case callable from HTTP, CLI, message queue, tests
+- Request/response format changes don't affect use case
+- Use case testable without HTTP infrastructure
+
+Reference: [Clean Architecture - Input/Output Ports](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/usecase-no-presentation-logic.md b/builtin-skills/software-engineer/clean-architecture/references/usecase-no-presentation-logic.md
new file mode 100644
index 00000000..f9ade1e2
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/usecase-no-presentation-logic.md
@@ -0,0 +1,101 @@
+---
+title: Use Cases Must Not Contain Presentation Logic
+impact: HIGH
+impactDescription: enables multiple UI implementations from same use case
+tags: usecase, presentation, formatting, separation
+---
+
+## Use Cases Must Not Contain Presentation Logic
+
+Use cases return domain data, not formatted strings, HTML, or UI-specific structures. Presentation logic belongs in the interface adapters layer.
+
+**Incorrect (presentation logic in use case):**
+
+```typescript
+class GetUserProfileUseCase {
+  execute(userId: string): UserProfileResponse {
+    const user = this.repo.findById(userId)
+    const orders = this.orderRepo.findByUser(userId)
+
+    return {
+      displayName: `${user.firstName} ${user.lastName}`,  // Formatting
+      memberSince: user.createdAt.toLocaleDateString('en-US', {
+        month: 'long',
+        year: 'numeric'
+      }),  // Locale-specific formatting
+      avatarHtml: `<img src="${user.avatarUrl}" alt="${user.firstName}"/>`,  // HTML!
+      orderSummary: orders.length > 0
+        ? `${orders.length} orders totaling $${this.sumOrders(orders).toFixed(2)}`
+        : 'No orders yet',  // UI text
+      recentOrders: orders.slice(0, 5).map(o => ({
+        ...o,
+        statusBadgeColor: this.getStatusColor(o.status)  // UI styling
+      }))
+    }
+  }
+
+  private getStatusColor(status: string): string {
+    const colors = { pending: 'yellow', shipped: 'blue', delivered: 'green' }
+    return colors[status] || 'gray'
+  }
+}
+```
+
+**Correct (use case returns domain data):**
+
+```typescript
+// application/usecases/GetUserProfileUseCase.ts
+class GetUserProfileUseCase {
+  execute(userId: string): UserProfileResult {
+    const user = this.repo.findById(userId)
+    const orders = this.orderRepo.findByUser(userId)
+
+    return {
+      user: {
+        id: user.id.value,
+        firstName: user.firstName,
+        lastName: user.lastName,
+        email: user.email.value,
+        avatarUrl: user.avatarUrl,
+        createdAt: user.createdAt
+      },
+      orders: orders.map(o => ({
+        id: o.id.value,
+        total: o.total.amount,
+        currency: o.total.currency,
+        status: o.status,
+        createdAt: o.createdAt
+      })),
+      orderCount: orders.length,
+      totalSpent: this.sumOrders(orders)
+    }
+  }
+}
+
+// interface_adapters/presenters/UserProfilePresenter.ts
+class UserProfilePresenter {
+  present(result: UserProfileResult, locale: string): UserProfileViewModel {
+    const formatter = new Intl.DateTimeFormat(locale, {
+      month: 'long',
+      year: 'numeric'
+    })
+
+    return {
+      displayName: `${result.user.firstName} ${result.user.lastName}`,
+      memberSince: formatter.format(result.user.createdAt),
+      avatarUrl: result.user.avatarUrl,
+      orderSummary: this.formatOrderSummary(result, locale),
+      recentOrders: result.orders.slice(0, 5).map(o =>
+        this.formatOrder(o, locale)
+      )
+    }
+  }
+}
+```
+
+**Benefits:**
+- Same use case serves web, mobile, API consumers
+- Locale/format changes don't touch business logic
+- UI redesigns don't affect use case tests
+
+Reference: [Clean Architecture - Presenters](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch23.xhtml)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/usecase-orchestrates-not-implements.md b/builtin-skills/software-engineer/clean-architecture/references/usecase-orchestrates-not-implements.md
new file mode 100644
index 00000000..448c047d
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/usecase-orchestrates-not-implements.md
@@ -0,0 +1,102 @@
+---
+title: Use Cases Orchestrate Entities Not Implement Business Rules
+impact: HIGH
+impactDescription: prevents rule duplication, maintains single source of truth
+tags: usecase, orchestration, entities, delegation
+---
+
+## Use Cases Orchestrate Entities Not Implement Business Rules
+
+Use cases coordinate the flow of data to and from entities. Business rules belong in entities; use cases should not duplicate or implement them.
+
+**Incorrect (business rules in use case):**
+
+```go
+func (uc *ApplyDiscountUseCase) Execute(orderId string, code string) error {
+    order := uc.repo.Find(orderId)
+    discount := uc.discounts.Find(code)
+
+    // Business rules implemented in use case
+    if order.Status != "pending" {
+        return errors.New("cannot apply discount to processed order")
+    }
+
+    if discount.ExpiresAt.Before(time.Now()) {
+        return errors.New("discount expired")
+    }
+
+    if order.Total.LessThan(discount.MinimumOrder) {
+        return errors.New("order total below minimum")
+    }
+
+    if discount.UsageCount >= discount.MaxUses {
+        return errors.New("discount fully redeemed")
+    }
+
+    // Calculate discount - more business rules
+    var discountAmount Money
+    if discount.Type == "percentage" {
+        discountAmount = order.Total.MultiplyBy(discount.Value / 100)
+    } else {
+        discountAmount = discount.Value
+    }
+
+    order.DiscountAmount = discountAmount
+    order.Total = order.Total.Subtract(discountAmount)
+    uc.repo.Save(order)
+    return nil
+}
+```
+
+**Correct (use case orchestrates, entities implement rules):**
+
+```go
+func (uc *ApplyDiscountUseCase) Execute(orderId string, code string) error {
+    order := uc.repo.Find(orderId)
+    discount := uc.discounts.Find(code)
+
+    // Use case orchestrates the interaction
+    if err := order.ApplyDiscount(discount); err != nil {
+        return err
+    }
+
+    uc.repo.Save(order)
+    return nil
+}
+
+// domain/entities/order.go
+func (o *Order) ApplyDiscount(discount *Discount) error {
+    if o.status != OrderStatusPending {
+        return ErrOrderNotPending
+    }
+
+    if !discount.IsValidFor(o.total) {
+        return discount.ValidationError(o.total)
+    }
+
+    o.discount = discount
+    o.discountAmount = discount.CalculateFor(o.total)
+    return nil
+}
+
+// domain/entities/discount.go
+func (d *Discount) IsValidFor(orderTotal Money) bool {
+    return !d.IsExpired() &&
+           !d.IsFullyRedeemed() &&
+           orderTotal.GreaterThanOrEqual(d.minimumOrder)
+}
+
+func (d *Discount) CalculateFor(total Money) Money {
+    if d.discountType == PercentageDiscount {
+        return total.MultiplyBy(d.value).DivideBy(100)
+    }
+    return d.value
+}
+```
+
+**Benefits:**
+- Business rules tested once in entity, not in every use case
+- Rules cannot diverge between use cases
+- Use case clearly shows workflow, not implementation details
+
+Reference: [Clean Architecture - Use Cases](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/usecase-single-responsibility.md b/builtin-skills/software-engineer/clean-architecture/references/usecase-single-responsibility.md
new file mode 100644
index 00000000..776903a4
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/usecase-single-responsibility.md
@@ -0,0 +1,96 @@
+---
+title: Each Use Case Has One Reason to Change
+impact: HIGH
+impactDescription: isolates change impact, enables parallel development
+tags: usecase, single-responsibility, cohesion, srp
+---
+
+## Each Use Case Has One Reason to Change
+
+Each use case class should orchestrate exactly one application-specific workflow. Combining multiple use cases creates coupling that forces unrelated changes together.
+
+**Incorrect (multiple use cases in one class):**
+
+```python
+class OrderService:
+    def __init__(self, repo, payment, shipping, notification):
+        self.repo = repo
+        self.payment = payment
+        self.shipping = shipping
+        self.notification = notification
+
+    def create_order(self, items, customer_id):
+        # Use case 1: Create order
+        order = Order.create(items, customer_id)
+        self.repo.save(order)
+        return order
+
+    def process_payment(self, order_id, payment_method):
+        # Use case 2: Process payment
+        order = self.repo.find(order_id)
+        self.payment.charge(order.total, payment_method)
+        order.mark_paid()
+        self.repo.save(order)
+
+    def ship_order(self, order_id, address):
+        # Use case 3: Ship order
+        order = self.repo.find(order_id)
+        tracking = self.shipping.create_shipment(order, address)
+        order.mark_shipped(tracking)
+        self.notification.send_shipped(order)
+        self.repo.save(order)
+
+    # Changes to shipping logic force retest of payment logic
+```
+
+**Correct (separate use case classes):**
+
+```python
+class CreateOrderUseCase:
+    def __init__(self, repo: OrderRepository):
+        self.repo = repo
+
+    def execute(self, command: CreateOrderCommand) -> OrderId:
+        order = Order.create(command.items, command.customer_id)
+        self.repo.save(order)
+        return order.id
+
+
+class ProcessPaymentUseCase:
+    def __init__(self, repo: OrderRepository, payment: PaymentGateway):
+        self.repo = repo
+        self.payment = payment
+
+    def execute(self, command: ProcessPaymentCommand) -> None:
+        order = self.repo.find(command.order_id)
+        self.payment.charge(order.total, command.payment_method)
+        order.mark_paid()
+        self.repo.save(order)
+
+
+class ShipOrderUseCase:
+    def __init__(
+        self,
+        repo: OrderRepository,
+        shipping: ShippingService,
+        notification: NotificationPort
+    ):
+        self.repo = repo
+        self.shipping = shipping
+        self.notification = notification
+
+    def execute(self, command: ShipOrderCommand) -> TrackingNumber:
+        order = self.repo.find(command.order_id)
+        tracking = self.shipping.create_shipment(order, command.address)
+        order.mark_shipped(tracking)
+        self.notification.send_shipped(order)
+        self.repo.save(order)
+        return tracking
+```
+
+**Benefits:**
+- Changes to shipping don't affect payment tests
+- Teams can work on different use cases in parallel
+- Each use case has minimal dependencies
+
+Reference: [Clean Architecture - Use Cases](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
diff --git a/builtin-skills/software-engineer/clean-architecture/references/usecase-transaction-boundary.md b/builtin-skills/software-engineer/clean-architecture/references/usecase-transaction-boundary.md
new file mode 100644
index 00000000..b37b67b7
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-architecture/references/usecase-transaction-boundary.md
@@ -0,0 +1,80 @@
+---
+title: Use Case Defines the Transaction Boundary
+impact: HIGH
+impactDescription: ensures data consistency, prevents partial updates
+tags: usecase, transactions, consistency, boundaries
+---
+
+## Use Case Defines the Transaction Boundary
+
+The use case is the natural transaction boundary. All operations within a use case should succeed or fail atomically. Infrastructure manages the transaction; use case defines the scope.
+
+**Incorrect (transaction managed inside repository):**
+
+```python
+class OrderRepository:
+    def save(self, order):
+        with self.db.transaction():  # Transaction per operation
+            self.db.insert('orders', order)
+
+class InventoryRepository:
+    def reserve(self, items):
+        with self.db.transaction():  # Separate transaction
+            for item in items:
+                self.db.update('inventory', item.sku, decrement=item.qty)
+
+class PlaceOrderUseCase:
+    def execute(self, command):
+        order = Order.create(command.items)
+        self.orders.save(order)  # Commits
+        self.inventory.reserve(command.items)  # If this fails, order is orphaned!
+        self.payments.charge(order.total)  # If this fails, inventory is reserved but unpaid
+```
+
+**Correct (use case defines transaction boundary):**
+
+```python
+# application/ports/UnitOfWork.py
+class UnitOfWork(Protocol):
+    def begin(self) -> None: ...
+    def commit(self) -> None: ...
+    def rollback(self) -> None: ...
+
+# application/usecases/PlaceOrderUseCase.py
+class PlaceOrderUseCase:
+    def __init__(self, uow: UnitOfWork, orders, inventory, payments):
+        self.uow = uow
+        self.orders = orders
+        self.inventory = inventory
+        self.payments = payments
+
+    def execute(self, command):
+        self.uow.begin()
+        try:
+            order = Order.create(command.items)
+
+            self.inventory.reserve(command.items)
+            self.payments.charge(order.total)
+            self.orders.save(order)
+
+            self.uow.commit()  # All or nothing
+            return order.id
+
+        except Exception as e:
+            self.uow.rollback()  # Clean rollback
+            raise
+
+# Alternative using context manager
+class PlaceOrderUseCase:
+    def execute(self, command):
+        with self.uow:  # Transaction spans entire use case
+            order = Order.create(command.items)
+            self.inventory.reserve(command.items)
+            self.payments.charge(order.total)
+            self.orders.save(order)
+            return order.id
+```
+
+**Note:** For distributed systems, consider saga patterns or eventual consistency rather than distributed transactions.
+
+Reference: [Unit of Work Pattern](https://martinfowler.com/eaaCatalog/unitOfWork.html)
diff --git a/builtin-skills/software-engineer/clean-code/SKILL.md b/builtin-skills/software-engineer/clean-code/SKILL.md
new file mode 100644
index 00000000..efa78f93
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/SKILL.md
@@ -0,0 +1,128 @@
+---
+name: clean-code
+description: Use when writing, reviewing, or refactoring code for maintainability and readability. Triggers on code reviews, naming discussions, function design, error handling, and test writing. Based on Robert C. Martin's Clean Code handbook with modern corrections.
+---
+
+# Robert C. Martin (Uncle Bob) Clean Code Best Practices
+
+Comprehensive software craftsmanship guide based on Robert C. Martin's "Clean Code: A Handbook of Agile Software Craftsmanship", updated with modern corrections where the original 2008 advice has been superseded. Contains 48 rules across 10 categories, prioritized by impact to guide code reviews, refactoring decisions, and new development. Examples are primarily in Java but principles are language-agnostic.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new functions, classes, or modules
+- Naming variables, functions, classes, or files
+- Reviewing code for maintainability issues
+- Refactoring existing code to improve clarity
+- Writing or improving unit tests
+- Wrapping third-party dependencies
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Meaningful Names | CRITICAL | `name-` |
+| 2 | Functions | CRITICAL | `func-` |
+| 3 | Comments | HIGH | `cmt-` |
+| 4 | Formatting | HIGH | `fmt-` |
+| 5 | Error Handling | HIGH | `err-` |
+| 6 | Objects and Data Structures | MEDIUM-HIGH | `obj-` |
+| 7 | Boundaries | MEDIUM-HIGH | `bound-` |
+| 8 | Classes and Systems | MEDIUM-HIGH | `class-` |
+| 9 | Unit Tests | MEDIUM | `test-` |
+| 10 | Emergence and Simple Design | MEDIUM | `emerge-` |
+
+## Quick Reference
+
+### 1. Meaningful Names (CRITICAL)
+
+- [`name-intention-revealing`](references/name-intention-revealing.md) - Use names that reveal intent
+- [`name-avoid-disinformation`](references/name-avoid-disinformation.md) - Avoid misleading names
+- [`name-meaningful-distinctions`](references/name-meaningful-distinctions.md) - Make meaningful distinctions
+- [`name-pronounceable`](references/name-pronounceable.md) - Use pronounceable names
+- [`name-searchable`](references/name-searchable.md) - Use searchable names
+- [`name-avoid-encodings`](references/name-avoid-encodings.md) - Avoid encodings in names
+- [`name-class-noun`](references/name-class-noun.md) - Use noun phrases for class names
+- [`name-method-verb`](references/name-method-verb.md) - Use verb phrases for method names
+
+### 2. Functions (CRITICAL)
+
+- [`func-small`](references/func-small.md) - Keep functions small
+- [`func-one-thing`](references/func-one-thing.md) - Functions should do one thing
+- [`func-abstraction-level`](references/func-abstraction-level.md) - Maintain one level of abstraction
+- [`func-minimize-arguments`](references/func-minimize-arguments.md) - Minimize function arguments
+- [`func-no-side-effects`](references/func-no-side-effects.md) - Avoid side effects
+- [`func-command-query-separation`](references/func-command-query-separation.md) - Separate commands from queries
+- [`func-dry`](references/func-dry.md) - Do not repeat yourself
+
+### 3. Comments (HIGH)
+
+- [`cmt-express-in-code`](references/cmt-express-in-code.md) - Express yourself in code, not comments
+- [`cmt-explain-intent`](references/cmt-explain-intent.md) - Use comments to explain intent
+- [`cmt-avoid-redundant`](references/cmt-avoid-redundant.md) - Avoid redundant comments
+- [`cmt-avoid-commented-out-code`](references/cmt-avoid-commented-out-code.md) - Delete commented-out code
+- [`cmt-warning-consequences`](references/cmt-warning-consequences.md) - Use warning comments for consequences
+
+### 4. Formatting (HIGH)
+
+- [`fmt-vertical-formatting`](references/fmt-vertical-formatting.md) - Use vertical formatting for readability
+- [`fmt-horizontal-alignment`](references/fmt-horizontal-alignment.md) - Avoid horizontal alignment
+- [`fmt-team-rules`](references/fmt-team-rules.md) - Follow team formatting rules
+- [`fmt-indentation`](references/fmt-indentation.md) - Respect indentation rules
+
+### 5. Error Handling (HIGH)
+
+- [`err-use-exceptions`](references/err-use-exceptions.md) - Separate error handling from happy path
+- [`err-write-try-catch-first`](references/err-write-try-catch-first.md) - Write try-catch-finally first
+- [`err-provide-context`](references/err-provide-context.md) - Provide context with exceptions
+- [`err-define-by-caller-needs`](references/err-define-by-caller-needs.md) - Define exceptions by caller needs
+- [`err-avoid-null`](references/err-avoid-null.md) - Avoid returning and passing null
+
+### 6. Objects and Data Structures (MEDIUM-HIGH)
+
+- [`obj-data-abstraction`](references/obj-data-abstraction.md) - Hide data behind abstractions
+- [`obj-data-object-asymmetry`](references/obj-data-object-asymmetry.md) - Understand data/object anti-symmetry
+- [`obj-law-of-demeter`](references/obj-law-of-demeter.md) - Follow the Law of Demeter
+- [`obj-avoid-hybrids`](references/obj-avoid-hybrids.md) - Avoid hybrid data-object structures
+- [`obj-dto`](references/obj-dto.md) - Use DTOs for data transfer
+
+### 7. Boundaries (MEDIUM-HIGH)
+
+- [`bound-wrap-third-party`](references/bound-wrap-third-party.md) - Wrap third-party APIs
+- [`bound-learning-tests`](references/bound-learning-tests.md) - Write learning tests for third-party code
+
+### 8. Classes and Systems (MEDIUM-HIGH)
+
+- [`class-small`](references/class-small.md) - Keep classes small
+- [`class-cohesion`](references/class-cohesion.md) - Maintain class cohesion
+- [`class-organize-for-change`](references/class-organize-for-change.md) - Organize classes for change
+- [`class-isolate-from-change`](references/class-isolate-from-change.md) - Isolate classes from change
+- [`class-separate-concerns`](references/class-separate-concerns.md) - Separate construction from use
+
+### 9. Unit Tests (MEDIUM)
+
+- [`test-first-law`](references/test-first-law.md) - Follow the three laws of TDD
+- [`test-keep-clean`](references/test-keep-clean.md) - Keep tests clean
+- [`test-one-assert`](references/test-one-assert.md) - One concept per test
+- [`test-first-principles`](references/test-first-principles.md) - Follow FIRST principles
+- [`test-build-operate-check`](references/test-build-operate-check.md) - Use Build-Operate-Check pattern
+
+### 10. Emergence and Simple Design (MEDIUM)
+
+- [`emerge-simple-design`](references/emerge-simple-design.md) - Follow the four rules of simple design
+- [`emerge-expressiveness`](references/emerge-expressiveness.md) - Maximize expressiveness
+
+## How to Use
+
+Read individual reference files for detailed explanations and code examples:
+
+- [Section definitions](references/_sections.md) - Category structure and impact levels
+- [Rule template](assets/templates/_template.md) - Template for adding new rules
+
+## Reference Files
+
+| File | Description |
+|------|-------------|
+| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
+| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
+| [metadata.json](metadata.json) | Version and reference information |
diff --git a/builtin-skills/software-engineer/clean-code/assets/templates/_template.md b/builtin-skills/software-engineer/clean-code/assets/templates/_template.md
new file mode 100644
index 00000000..f9207254
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/assets/templates/_template.md
@@ -0,0 +1,30 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: description of impact (e.g., "eliminates confusion")
+tags: category-prefix, keyword1, keyword2
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters. Focus on the principle and its impact on code maintainability and readability.
+
+**Incorrect (description of what's wrong):**
+
+```java
+// Bad code example here showing the anti-pattern
+// Comment explaining the problem
+```
+
+**Correct (description of what's right):**
+
+```java
+// Good code example here showing the solution
+// Comment explaining the benefit
+```
+
+**When NOT to use this pattern:**
+- Exception case 1
+- Exception case 2
+
+Reference: [Clean Code, Chapter N: Topic](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/_sections.md b/builtin-skills/software-engineer/clean-code/references/_sections.md
new file mode 100644
index 00000000..c91b7e0b
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/_sections.md
@@ -0,0 +1,56 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Meaningful Names (name)
+
+**Impact:** CRITICAL
+**Description:** Names are the primary documentation. Bad names cascade confusion throughout the codebase, forcing every reader to decipher intent.
+
+## 2. Functions (func)
+
+**Impact:** CRITICAL
+**Description:** Functions are the verbs of code. Small, focused functions enable understanding, testing, and reuse while reducing complexity.
+
+## 3. Comments (cmt)
+
+**Impact:** HIGH
+**Description:** Comments should explain intent, not obvious mechanics. Wrong or stale comments actively mislead readers and cost more than no comments.
+
+## 4. Formatting (fmt)
+
+**Impact:** HIGH
+**Description:** Consistent formatting reduces cognitive load. Code should read top-to-bottom like a newspaper article.
+
+## 5. Error Handling (err)
+
+**Impact:** HIGH
+**Description:** Clean error handling separates happy path from exceptional cases. Use the error mechanism idiomatic to your language (exceptions, Result types, or explicit error returns).
+
+## 6. Objects and Data Structures (obj)
+
+**Impact:** MEDIUM-HIGH
+**Description:** Objects hide data and expose behavior; data structures expose data and have no behavior. Mixing these creates hybrid messes.
+
+## 7. Boundaries (bound)
+
+**Impact:** MEDIUM-HIGH
+**Description:** Third-party code and external APIs are boundaries. Wrap them to isolate change, ease testing, and maintain control over your codebase's interfaces.
+
+## 8. Classes and Systems (class)
+
+**Impact:** MEDIUM-HIGH
+**Description:** Classes should be small and have a single responsibility. Systems should separate construction from use. SRP and DIP are among the highest-leverage design principles.
+
+## 9. Unit Tests (test)
+
+**Impact:** MEDIUM
+**Description:** Tests are first-class citizens that enable safe refactoring. Test code deserves the same care as production code.
+
+## 10. Emergence and Simple Design (emerge)
+
+**Impact:** MEDIUM
+**Description:** Good design emerges from following four rules in order: pass tests, reveal intent, eliminate duplication, minimize elements. Resist the urge to over-engineer.
diff --git a/builtin-skills/software-engineer/clean-code/references/bound-learning-tests.md b/builtin-skills/software-engineer/clean-code/references/bound-learning-tests.md
new file mode 100644
index 00000000..d6e520ce
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/bound-learning-tests.md
@@ -0,0 +1,59 @@
+---
+title: Write Learning Tests for Third-Party Code
+impact: MEDIUM
+impactDescription: catches 90%+ of breaking changes in dependency upgrades before production
+tags: bound, boundary, learning-tests, third-party, testing
+---
+
+## Write Learning Tests for Third-Party Code
+
+When integrating a third-party library, write small tests that verify your understanding of how the API works. These tests serve double duty: they help you learn the API, and they act as a safety net when upgrading the library.
+
+**Incorrect (learning by trial and error in production code):**
+
+```java
+// Experimenting directly in application code
+public void importCustomerRecord(String json) {
+    // Does Gson handle null fields? Let's find out...
+    Gson gson = new Gson();
+    CustomerRecord record = gson.fromJson(json, CustomerRecord.class);
+    // Does this throw or return null for missing fields?
+    // Who knows — we'll find out in production
+}
+```
+
+**Correct (learning tests verify assumptions):**
+
+```java
+@Test
+public void gsonShouldDeserializeNullFieldsAsNull() {
+    Gson gson = new Gson();
+    Data data = gson.fromJson("{}", Data.class);
+
+    assertNull(data.getName());
+}
+
+@Test
+public void gsonShouldHandleMalformedJson() {
+    Gson gson = new Gson();
+
+    assertThrows(JsonSyntaxException.class,
+        () -> gson.fromJson("{invalid", Data.class));
+}
+
+@Test
+public void gsonShouldIgnoreUnknownFields() {
+    Gson gson = new Gson();
+    Data data = gson.fromJson("{\"name\":\"test\",\"unknown\":true}", Data.class);
+
+    assertEquals("test", data.getName());
+}
+```
+
+**Benefits:**
+- Free education on the API's behavior
+- When you upgrade the library, these tests break first — before your production code does
+- Documents exactly which behaviors your code relies on
+- Takes minutes to write but saves hours of debugging
+
+Reference: [Clean Code, Chapter 8: Boundaries](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/bound-wrap-third-party.md b/builtin-skills/software-engineer/clean-code/references/bound-wrap-third-party.md
new file mode 100644
index 00000000..df86faba
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/bound-wrap-third-party.md
@@ -0,0 +1,77 @@
+---
+title: Wrap Third-Party APIs
+impact: HIGH
+impactDescription: reduces dependency change points from N call sites to 1 wrapper
+tags: bound, boundary, wrapper, third-party, dependency
+---
+
+## Wrap Third-Party APIs
+
+When you use a third-party API, wrap it in a class you control. This minimizes your dependency on the third party, makes testing easier, and gives you a single place to change when the API evolves.
+
+**Incorrect (direct dependency scattered across codebase):**
+
+```java
+// Every caller depends on ACMEPort directly
+public class SensorReader {
+    public void readSensors() {
+        try {
+            ACMEPort port = new ACMEPort(12);
+            port.open();
+            // ...
+        } catch (ACMEDeviceException e) {
+            logger.log("Device exception", e);
+        } catch (ACMEConfigException e) {
+            logger.log("Config exception", e);
+        } catch (ACMECommunicationException e) {
+            logger.log("Communication exception", e);
+        }
+    }
+}
+// If ACME changes their API, every file that uses it must change
+```
+
+**Correct (wrapped behind your own interface):**
+
+```java
+public class LocalPort {
+    private ACMEPort innerPort;
+
+    public LocalPort(int portNumber) {
+        innerPort = new ACMEPort(portNumber);
+    }
+
+    public void open() {
+        try {
+            innerPort.open();
+        } catch (ACMEDeviceException | ACMEConfigException | ACMECommunicationException e) {
+            throw new PortException(e);
+        }
+    }
+}
+
+// Callers depend only on your wrapper
+public class SensorReader {
+    public void readSensors() {
+        try {
+            LocalPort port = new LocalPort(12);
+            port.open();
+            // ...
+        } catch (PortException e) {
+            logger.log("Port error", e);
+        }
+    }
+}
+```
+
+**Benefits:**
+- One place to change when the third-party API changes
+- Easier to mock in tests (mock `LocalPort`, not the vendor library)
+- Freedom to switch vendors without rewriting the entire codebase
+- Consistent exception hierarchy under your control
+
+**When NOT to wrap:**
+- Stable, widely-used standard library APIs (e.g., `java.util.List`, `String`) do not need wrapping.
+- If the wrapper would be a 1:1 passthrough with no value added, it's premature. Wait until you have a concrete reason (testing, migration, or simplification).
+
+Reference: [Clean Code, Chapter 8: Boundaries](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/class-cohesion.md b/builtin-skills/software-engineer/clean-code/references/class-cohesion.md
new file mode 100644
index 00000000..715dce8f
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/class-cohesion.md
@@ -0,0 +1,66 @@
+---
+title: Maintain Class Cohesion
+impact: MEDIUM
+impactDescription: enables extracting focused subclasses
+tags: class, cohesion, variables, methods
+---
+
+## Maintain Class Cohesion
+
+Classes should have a small number of instance variables. Each method should manipulate one or more of those variables. The more variables a method manipulates, the more cohesive the method is to its class.
+
+**Incorrect (low cohesion - methods use different variables):**
+
+```java
+public class Utility {
+    private Database db;
+    private EmailService email;
+    private Logger logger;
+    private Cache cache;
+
+    public void saveUser(User user) {
+        db.save(user);  // Only uses db
+        logger.log("Saved user");  // Only uses logger
+    }
+
+    public void sendNotification(String message) {
+        email.send(message);  // Only uses email
+    }
+
+    public Object getCached(String key) {
+        return cache.get(key);  // Only uses cache
+    }
+}
+// Each method uses different instance variables - low cohesion
+```
+
+**Correct (high cohesion - methods use shared variables):**
+
+```java
+public class Stack {
+    private int topOfStack = 0;
+    private List<Integer> elements = new LinkedList<>();
+
+    public int size() {
+        return topOfStack;  // Uses topOfStack
+    }
+
+    public void push(int element) {
+        topOfStack++;  // Uses topOfStack
+        elements.add(element);  // Uses elements
+    }
+
+    public int pop() throws EmptyStackException {
+        if (topOfStack == 0)
+            throw new EmptyStackException();
+        int element = elements.get(--topOfStack);  // Uses both
+        elements.remove(topOfStack);  // Uses both
+        return element;
+    }
+}
+// Every method uses the same instance variables - high cohesion
+```
+
+**When cohesion breaks down:** If a subset of methods only uses a subset of variables, extract those methods and variables into a separate class.
+
+Reference: [Clean Code, Chapter 10: Classes](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/class-isolate-from-change.md b/builtin-skills/software-engineer/clean-code/references/class-isolate-from-change.md
new file mode 100644
index 00000000..8c527adb
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/class-isolate-from-change.md
@@ -0,0 +1,76 @@
+---
+title: Isolate Classes from Change
+impact: MEDIUM
+impactDescription: enables testing and reduces coupling
+tags: class, dip, interfaces, coupling
+---
+
+## Isolate Classes from Change
+
+Depend on abstractions, not concretions. Classes should depend on interfaces rather than concrete implementations. This enables testing and reduces the impact of change.
+
+**Incorrect (depends on concrete implementation):**
+
+```java
+public class Portfolio {
+    private NYSEStockExchange exchange;
+
+    public Portfolio(NYSEStockExchange exchange) {
+        this.exchange = exchange;
+    }
+
+    public Money value() {
+        Money total = Money.ZERO;
+        for (String symbol : holdings.keySet()) {
+            // Cannot test without real stock exchange connection
+            total = total.plus(exchange.currentPrice(symbol)
+                                .times(holdings.get(symbol)));
+        }
+        return total;
+    }
+}
+```
+
+**Correct (depends on abstraction):**
+
+```java
+public interface StockExchange {
+    Money currentPrice(String symbol);
+}
+
+public class Portfolio {
+    private StockExchange exchange;
+
+    public Portfolio(StockExchange exchange) {
+        this.exchange = exchange;
+    }
+
+    public Money value() {
+        Money total = Money.ZERO;
+        for (String symbol : holdings.keySet()) {
+            total = total.plus(exchange.currentPrice(symbol)
+                                .times(holdings.get(symbol)));
+        }
+        return total;
+    }
+}
+
+// Production
+Portfolio portfolio = new Portfolio(new NYSEStockExchange());
+
+// Testing
+@Test
+public void portfolioValueShouldSumAllHoldings() {
+    StockExchange mockExchange = mock(StockExchange.class);
+    when(mockExchange.currentPrice("AAPL")).thenReturn(Money.dollars(150));
+
+    Portfolio portfolio = new Portfolio(mockExchange);
+    portfolio.add("AAPL", 10);
+
+    assertEquals(Money.dollars(1500), portfolio.value());
+}
+```
+
+**Dependency Inversion Principle (DIP):** High-level modules should not depend on low-level modules. Both should depend on abstractions.
+
+Reference: [Clean Code, Chapter 10: Classes](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/class-organize-for-change.md b/builtin-skills/software-engineer/clean-code/references/class-organize-for-change.md
new file mode 100644
index 00000000..387f27f2
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/class-organize-for-change.md
@@ -0,0 +1,70 @@
+---
+title: Organize Classes for Change
+impact: MEDIUM
+impactDescription: minimizes modification risk when requirements change
+tags: class, ocp, change, design
+---
+
+## Organize Classes for Change
+
+Classes should be organized so that change is minimally invasive. Following the Open-Closed Principle (OCP): classes should be open for extension but closed for modification.
+
+**Incorrect (must modify class for each new SQL type):**
+
+```java
+public class Sql {
+    public Sql(String table, Column[] columns) { /* ... */ }
+
+    public String create() { /* ... */ }
+    public String insert(Object[] fields) { /* ... */ }
+    public String selectAll() { /* ... */ }
+    public String findByKey(String key) { /* ... */ }
+    // Must modify this class to add update, delete, etc.
+    // Each change risks breaking existing functionality
+}
+```
+
+**Correct (extend without modifying):**
+
+```java
+public abstract class Sql {
+    protected String table;
+    protected Column[] columns;
+
+    public Sql(String table, Column[] columns) {
+        this.table = table;
+        this.columns = columns;
+    }
+
+    public abstract String generate();
+}
+
+public class CreateSql extends Sql {
+    public CreateSql(String table, Column[] columns) {
+        super(table, columns);
+    }
+
+    public String generate() { /* CREATE TABLE ... */ }
+}
+
+public class InsertSql extends Sql {
+    private Object[] fields;
+
+    public InsertSql(String table, Column[] columns, Object[] fields) {
+        super(table, columns);
+        this.fields = fields;
+    }
+
+    public String generate() { /* INSERT INTO ... */ }
+}
+
+// Adding UpdateSql doesn't require modifying existing classes
+public class UpdateSql extends Sql { /* ... */ }
+```
+
+**Benefits:**
+- Adding new SQL types = adding new classes
+- Existing classes remain untouched
+- Each class does one thing
+
+Reference: [Clean Code, Chapter 10: Classes](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/class-separate-concerns.md b/builtin-skills/software-engineer/clean-code/references/class-separate-concerns.md
new file mode 100644
index 00000000..14b8d12e
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/class-separate-concerns.md
@@ -0,0 +1,74 @@
+---
+title: Separate Construction from Use
+impact: MEDIUM
+impactDescription: enables testing and reduces coupling
+tags: class, construction, factories, separation
+---
+
+## Separate Construction from Use
+
+The startup process of object construction is a separate concern from runtime logic. Applications should separate the main function (which builds objects) from the rest of the system (which uses them).
+
+**Incorrect (construction mixed with use):**
+
+```java
+public class OrderProcessor {
+    public void processOrder(Order order) {
+        // Construction buried in business logic
+        EmailService emailService = new SmtpEmailService(
+            "smtp.example.com", 587, "user", "password");
+        InventoryService inventory = new InventoryServiceImpl(
+            new PostgresConnection("localhost", 5432));
+        PaymentGateway gateway = new StripeGateway(API_KEY);
+
+        // Business logic
+        inventory.reserve(order.getItems());
+        gateway.charge(order.getPayment());
+        emailService.sendConfirmation(order);
+    }
+}
+```
+
+**Correct (construction separated from use):**
+
+```java
+// Main builds the object graph
+public class Application {
+    public static void main(String[] args) {
+        EmailService emailService = new SmtpEmailService(
+            Config.get("smtp.host"), Config.getInt("smtp.port"));
+        InventoryService inventory = new InventoryServiceImpl(
+            new PostgresConnection(Config.get("db.url")));
+        PaymentGateway gateway = new StripeGateway(Config.get("stripe.key"));
+
+        OrderProcessor processor = new OrderProcessor(
+            emailService, inventory, gateway);
+
+        processor.start();
+    }
+}
+
+// Business class receives dependencies
+public class OrderProcessor {
+    private final EmailService emailService;
+    private final InventoryService inventory;
+    private final PaymentGateway gateway;
+
+    public OrderProcessor(EmailService email, InventoryService inv,
+                          PaymentGateway pay) {
+        this.emailService = email;
+        this.inventory = inv;
+        this.gateway = pay;
+    }
+
+    public void processOrder(Order order) {
+        inventory.reserve(order.getItems());
+        gateway.charge(order.getPayment());
+        emailService.sendConfirmation(order);
+    }
+}
+```
+
+**Alternative:** Use Dependency Injection frameworks (Spring, Guice) to manage construction.
+
+Reference: [Clean Code, Chapter 11: Systems](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/class-small.md b/builtin-skills/software-engineer/clean-code/references/class-small.md
new file mode 100644
index 00000000..e8910e1d
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/class-small.md
@@ -0,0 +1,63 @@
+---
+title: Keep Classes Small
+impact: MEDIUM
+impactDescription: enables comprehension and focused testing
+tags: class, size, srp, cohesion
+---
+
+## Keep Classes Small
+
+Classes should be small. With functions, we measure size by counting lines. With classes, we count responsibilities. A class should have only one reason to change.
+
+**Incorrect (large class with multiple responsibilities):**
+
+```java
+public class SuperDashboard extends JFrame implements MetaDataUser {
+    public String getCustomizerLanguagePath() { /* ... */ }
+    public void setSystemConfigPath(String path) { /* ... */ }
+    public String getSystemConfigDocument() { /* ... */ }
+    public void setSystemConfigDocument(String doc) { /* ... */ }
+    public boolean getGuruState() { /* ... */ }
+    public boolean getNoviceState() { /* ... */ }
+    public boolean getOpenSourceState() { /* ... */ }
+    public void showObject(MetaObject object) { /* ... */ }
+    public void showProgress(String s) { /* ... */ }
+    public boolean isMetadataDirty() { /* ... */ }
+    public void setIsMetadataDirty(boolean dirty) { /* ... */ }
+    public Component getLastFocusedComponent() { /* ... */ }
+    // 70+ more methods...
+}
+```
+
+**Correct (small focused classes):**
+
+```java
+public class Version {
+    public int getMajorVersionNumber() { /* ... */ }
+    public int getMinorVersionNumber() { /* ... */ }
+    public int getBuildNumber() { /* ... */ }
+}
+
+public class Dashboard extends JFrame {
+    private final Version version;
+    private final UserPreferences preferences;
+    private final ProgressIndicator progress;
+
+    public void show() { /* ... */ }
+}
+
+public class UserPreferences {
+    public Language getLanguage() { /* ... */ }
+    public boolean isNovice() { /* ... */ }
+    public boolean isGuru() { /* ... */ }
+}
+
+public class ProgressIndicator {
+    public void showProgress(String message) { /* ... */ }
+    public void hideProgress() { /* ... */ }
+}
+```
+
+**Single Responsibility Principle (SRP):** A class should have one, and only one, reason to change.
+
+Reference: [Clean Code, Chapter 10: Classes](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/cmt-avoid-commented-out-code.md b/builtin-skills/software-engineer/clean-code/references/cmt-avoid-commented-out-code.md
new file mode 100644
index 00000000..c94b23b6
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/cmt-avoid-commented-out-code.md
@@ -0,0 +1,48 @@
+---
+title: Delete Commented-Out Code
+impact: HIGH
+impactDescription: prevents code archaeology confusion
+tags: cmt, dead-code, version-control, clutter
+---
+
+## Delete Commented-Out Code
+
+Commented-out code is an abomination. Others who see it will not have the courage to delete it. They think it must be there for a reason. It rots and becomes increasingly irrelevant.
+
+**Incorrect (commented-out code persisting):**
+
+```java
+public void processOrder(Order order) {
+    validateOrder(order);
+    // calculateLegacyDiscount(order);
+    // if (order.getCustomer().isPremium()) {
+    //     applyPremiumDiscount(order);
+    // }
+    calculateDiscount(order);
+    // sendNotification(order);
+    // logOrderDetails(order);
+    saveOrder(order);
+    notifyWarehouse(order);
+}
+```
+
+**Correct (clean code, trust version control):**
+
+```java
+public void processOrder(Order order) {
+    validateOrder(order);
+    calculateDiscount(order);
+    saveOrder(order);
+    notifyWarehouse(order);
+}
+```
+
+**Why delete it?**
+- Version control remembers everything
+- Commented code creates confusion: Is it needed? Why is it there?
+- It clutters the file and makes scanning harder
+- It becomes stale and misleading over time
+
+**If you really need it:** Create a git branch, or add a reference comment pointing to the commit where it was removed.
+
+Reference: [Clean Code, Chapter 4: Comments](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/cmt-avoid-redundant.md b/builtin-skills/software-engineer/clean-code/references/cmt-avoid-redundant.md
new file mode 100644
index 00000000..58aa846a
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/cmt-avoid-redundant.md
@@ -0,0 +1,68 @@
+---
+title: Avoid Redundant Comments
+impact: HIGH
+impactDescription: eliminates noise that obscures important information
+tags: cmt, redundant, noise, clutter
+---
+
+## Avoid Redundant Comments
+
+A comment that merely restates what the code does is worse than no comment. It adds clutter, becomes stale, and trains readers to ignore comments entirely.
+
+**Incorrect (redundant comments):**
+
+```java
+/**
+ * The name of the customer
+ */
+private String customerName;
+
+/**
+ * Returns the name
+ * @return the name
+ */
+public String getName() {
+    return name;
+}
+
+// Check if the account is closed
+if (account.isClosed()) {
+    // Throw an exception
+    throw new AccountClosedException();
+}
+
+/**
+ * Default constructor
+ */
+public Account() {
+}
+```
+
+**Correct (comment only when necessary):**
+
+```java
+private String customerName;
+
+public String getName() {
+    return name;
+}
+
+if (account.isClosed()) {
+    throw new AccountClosedException();
+}
+
+public Account() {
+}
+
+// Comments that add value:
+
+// RFC 2822 date format required by legacy email parser
+private static final String DATE_FORMAT = "EEE, dd MMM yyyy HH:mm:ss Z";
+
+// Thread-safe: ConcurrentHashMap handles synchronization
+private Map<String, Session> activeSessions = new ConcurrentHashMap<>();
+```
+
+**Rule of thumb:** If the comment just repeats the code in English, delete it.
+
+Reference: [Clean Code, Chapter 4: Comments](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/cmt-explain-intent.md b/builtin-skills/software-engineer/clean-code/references/cmt-explain-intent.md
new file mode 100644
index 00000000..8cfbd224
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/cmt-explain-intent.md
@@ -0,0 +1,54 @@
+---
+title: Use Comments to Explain Intent
+impact: HIGH
+impactDescription: preserves decision rationale for future readers
+tags: cmt, intent, why, rationale
+---
+
+## Use Comments to Explain Intent
+
+Good comments explain WHY, not WHAT. The code already tells you what it does. Comments should explain the reasoning behind a decision that cannot be expressed in code.
+
+**Incorrect (narrating the code):**
+
+```java
+// Increment counter by 1
+counter++;
+
+// Loop through all employees
+for (Employee employee : employees) {
+    // Check if employee is active
+    if (employee.isActive()) {
+        // Add employee to list
+        activeEmployees.add(employee);
+    }
+}
+
+// Set the name
+this.name = name;
+```
+
+**Correct (explaining intent):**
+
+```java
+// We use insertion sort here because the list is almost always nearly sorted,
+// and insertion sort is O(n) for nearly sorted data vs O(n log n) for quicksort
+insertionSort(nearlyOrderedList);
+
+// Format matches the external API's expected date format (ISO 8601 without timezone)
+// See: https://api.vendor.com/docs/date-format
+String formattedDate = date.format(DateTimeFormatter.ISO_LOCAL_DATE);
+
+// Bias toward newer sessions - users expect recent data first
+// Business requirement from Product (ticket PROD-1234)
+sessions.sort(Comparator.comparing(Session::getCreatedAt).reversed());
+```
+
+**Good comment situations:**
+- Legal comments (copyright, license)
+- Explanation of intent or rationale
+- Clarification of obscure API behavior
+- Warning of consequences
+- TODO comments (temporary)
+
+Reference: [Clean Code, Chapter 4: Comments](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/cmt-express-in-code.md b/builtin-skills/software-engineer/clean-code/references/cmt-express-in-code.md
new file mode 100644
index 00000000..3fbf16d5
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/cmt-express-in-code.md
@@ -0,0 +1,58 @@
+---
+title: Express Yourself in Code, Not Comments
+impact: CRITICAL
+impactDescription: eliminates stale comment risk
+tags: cmt, self-documenting, refactoring, clarity
+---
+
+## Express Yourself in Code, Not Comments
+
+In many cases, creating a function that says the same thing as the comment you wanted to write is better. Code can be refactored to be self-explanatory.
+
+**Incorrect (comment explains obscure code):**
+
+```java
+// Check to see if the employee is eligible for full benefits
+if ((employee.flags & HOURLY_FLAG) && (employee.age > 65)) {
+    // ...
+}
+
+// Add 30 days to the current date
+Date newDate = new Date(currentDate.getTime() + (30L * 24 * 60 * 60 * 1000));
+
+// Returns true if the string contains only digits
+boolean result = str.matches("[0-9]+");
+```
+
+**Correct (code expresses intent):**
+
+```java
+if (employee.isEligibleForFullBenefits()) {
+    // ...
+}
+
+// In Employee class:
+public boolean isEligibleForFullBenefits() {
+    return isHourlyWorker() && age > RETIREMENT_AGE;
+}
+
+Date newDate = currentDate.plusDays(30);
+
+boolean result = StringUtils.isNumeric(str);
+// Or define your own:
+boolean result = containsOnlyDigits(str);
+```
+
+**Benefits:**
+- Function names are searchable
+- Functions can be tested
+- Code documents itself
+- No risk of comment becoming stale
+
+**When comments are still valuable:**
+- **Why, not what:** Comments explaining *why* a decision was made (business rules, regulatory requirements, algorithm choices) cannot be replaced by code.
+- **Warnings:** Thread-safety, performance implications, or non-obvious side effects deserve explicit comments.
+- **Legal/license comments:** Required by policy and cannot be expressed as code.
+- **Public API documentation:** Javadoc/docstrings for public APIs are expected and useful.
+
+Reference: [Clean Code, Chapter 4: Comments](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/cmt-warning-consequences.md b/builtin-skills/software-engineer/clean-code/references/cmt-warning-consequences.md
new file mode 100644
index 00000000..5b302119
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/cmt-warning-consequences.md
@@ -0,0 +1,66 @@
+---
+title: Use Warning Comments for Consequences
+impact: MEDIUM
+impactDescription: prevents costly mistakes by future maintainers
+tags: cmt, warning, consequences, safety
+---
+
+## Use Warning Comments for Consequences
+
+Comments that warn other programmers about certain consequences are valuable. They prevent others from making mistakes that have non-obvious impacts.
+
+**Incorrect (no warning about hidden dangers):**
+
+```java
+public static SimpleDateFormat makeStandardDateFormat() {
+    return new SimpleDateFormat("yyyy-MM-dd");
+}
+
+public void runExpensiveOperation() {
+    // Process all historical data
+    processAllRecords();
+}
+
+@Test
+public void testWithRealDatabase() {
+    database.connect();
+    // ...
+}
+```
+
+**Correct (warnings prevent mistakes):**
+
+```java
+// WARNING: DateTimeFormatter is thread-safe, but this legacy method returns
+// SimpleDateFormat which is NOT thread-safe. Do not cache or share the result.
+// Consider migrating callers to use DateTimeFormatter.ISO_LOCAL_DATE directly.
+public static SimpleDateFormat makeStandardDateFormat() {
+    return new SimpleDateFormat("yyyy-MM-dd");
+}
+
+// Preferred (Java 8+): thread-safe, no warning needed
+private static final DateTimeFormatter DATE_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd");
+
+// WARNING: This operation takes ~30 minutes on production data
+// and consumes significant memory. Run only during maintenance windows.
+public void runExpensiveOperation() {
+    processAllRecords();
+}
+
+// Don't run this test unless you have several hours to kill.
+// Requires real database connection and processes 10M+ records.
+@Ignore("Long-running integration test")
+@Test
+public void testWithRealDatabase() {
+    database.connect();
+    // ...
+}
+```
+
+**Good warnings include:**
+- Thread-safety concerns
+- Performance implications
+- External dependencies or side effects
+- Security considerations
+
+Reference: [Clean Code, Chapter 4: Comments](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/emerge-expressiveness.md b/builtin-skills/software-engineer/clean-code/references/emerge-expressiveness.md
new file mode 100644
index 00000000..ef94b015
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/emerge-expressiveness.md
@@ -0,0 +1,52 @@
+---
+title: Maximize Expressiveness
+impact: MEDIUM-HIGH
+impactDescription: reduces time to understand unfamiliar code by 50%+
+tags: emerge, expressiveness, readability, maintenance
+---
+
+## Maximize Expressiveness
+
+The majority of the cost of a software project is in long-term maintenance. Write code for the reader, not the writer. The clearer the author can make the code, the less time others will spend understanding it.
+
+**Incorrect (clever but opaque):**
+
+```java
+// Bit manipulation for no reason
+public boolean isWeekend(int day) {
+    return ((day & 0x6) == day) && (day > 0);
+}
+
+// Terse variable names in complex logic
+public int calc(int[] a, int n) {
+    int r = 0;
+    for (int i = 0; i < n; i++)
+        r = Math.max(r, a[i] - (i > 0 ? a[i-1] : 0));
+    return r;
+}
+```
+
+**Correct (clear and expressive):**
+
+```java
+public boolean isWeekend(DayOfWeek day) {
+    return day == DayOfWeek.SATURDAY || day == DayOfWeek.SUNDAY;
+}
+
+public int findMaxDailyGain(int[] dailyPrices, int numberOfDays) {
+    int maxGain = 0;
+    for (int day = 1; day < numberOfDays; day++) {
+        int dailyChange = dailyPrices[day] - dailyPrices[day - 1];
+        maxGain = Math.max(maxGain, dailyChange);
+    }
+    return maxGain;
+}
+```
+
+**Techniques for expressiveness:**
+- Choose good names (the single most effective technique)
+- Keep functions and classes small and focused
+- Use standard patterns and nomenclature — when you use the Strategy pattern, name the class with "Strategy" so readers recognize the intent
+- Write well-crafted unit tests — tests are documentation by example
+
+Reference: [Clean Code, Chapter 12: Emergence](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/emerge-simple-design.md b/builtin-skills/software-engineer/clean-code/references/emerge-simple-design.md
new file mode 100644
index 00000000..94376aa8
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/emerge-simple-design.md
@@ -0,0 +1,59 @@
+---
+title: Follow the Four Rules of Simple Design
+impact: HIGH
+impactDescription: prevents over-engineering while maintaining quality
+tags: emerge, simple-design, kent-beck, refactoring
+---
+
+## Follow the Four Rules of Simple Design
+
+Kent Beck's four rules of Simple Design, in order of priority:
+
+1. **Passes all tests** — correctness is non-negotiable
+2. **Reveals intent** — code is clear and expressive
+3. **No duplication** — every concept has a single representation
+4. **Fewest elements** — remove anything that doesn't serve the first three
+
+**Incorrect (over-engineered for imaginary requirements):**
+
+```java
+// Single implementation with unnecessary abstraction layers
+public interface PaymentProcessor {}
+public interface PaymentProcessorFactory {}
+public abstract class AbstractPaymentProcessor implements PaymentProcessor {}
+public class PaymentProcessorFactoryImpl implements PaymentProcessorFactory {
+    public PaymentProcessor create() {
+        return new DefaultPaymentProcessor();
+    }
+}
+public class DefaultPaymentProcessor extends AbstractPaymentProcessor {
+    public void process(Payment payment) {
+        gateway.charge(payment.getAmount());
+    }
+}
+```
+
+**Correct (simplest design that works):**
+
+```java
+public class PaymentProcessor {
+    private final PaymentGateway gateway;
+
+    public PaymentProcessor(PaymentGateway gateway) {
+        this.gateway = gateway;
+    }
+
+    public void process(Payment payment) {
+        gateway.charge(payment.getAmount());
+    }
+}
+```
+
+**Rule 4 is the most overlooked:** After making code correct, expressive, and DRY, actively look for things to remove. Every class, method, and variable should justify its existence. If you have one implementation of an interface, question whether you need the interface. If a design pattern adds indirection without a current concrete benefit, remove it.
+
+**When more structure is justified:**
+- When you have 2+ implementations today (not hypothetically)
+- When a framework requires it (e.g., dependency injection interfaces)
+- When tests need seams for mocking external dependencies
+
+Reference: [Clean Code, Chapter 12: Emergence](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/err-avoid-null.md b/builtin-skills/software-engineer/clean-code/references/err-avoid-null.md
new file mode 100644
index 00000000..3890fcfa
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/err-avoid-null.md
@@ -0,0 +1,78 @@
+---
+title: Avoid Returning and Passing Null
+impact: HIGH
+impactDescription: eliminates NullPointerException risk
+tags: err, null, optional, null-object
+---
+
+## Avoid Returning and Passing Null
+
+Returning null creates work for callers and invites errors. One missing null check leads to NullPointerException. Throw exceptions, return empty collections, or use the Special Case / Null Object pattern.
+
+**Incorrect (returning null):**
+
+```java
+public List<Employee> getEmployees() {
+    if (thereAreNoEmployees) {
+        return null;  // Caller must check for null
+    }
+    return employees;
+}
+
+// Every caller must do this
+List<Employee> employees = getEmployees();
+if (employees != null) {  // Easy to forget
+    for (Employee e : employees) {
+        pay(e);
+    }
+}
+
+// Passing null
+public double calculatePay(Employee employee, Money bonus) {
+    // What if bonus is null?
+}
+calculatePay(employee, null);  // What does null mean?
+```
+
+**Correct (avoid null entirely):**
+
+```java
+// Return empty collection instead of null
+public List<Employee> getEmployees() {
+    if (thereAreNoEmployees) {
+        return Collections.emptyList();
+    }
+    return employees;
+}
+
+// Clean caller code
+for (Employee e : getEmployees()) {
+    pay(e);
+}
+
+// Use Optional for truly optional values
+public Optional<Employee> findById(Long id) {
+    return Optional.ofNullable(employeeMap.get(id));
+}
+
+// Use Special Case object
+public interface BillingPlan {
+    Money getRate();
+}
+
+public class NullBillingPlan implements BillingPlan {
+    public Money getRate() {
+        return Money.ZERO;
+    }
+}
+
+// Explicit parameters instead of null
+public double calculatePay(Employee employee, Money bonus) { /* ... */ }
+public double calculatePayWithoutBonus(Employee employee) { /* ... */ }
+```
+
+**When null/nullable is acceptable:**
+- Language-level nullable types with compiler enforcement (Kotlin `?`, TypeScript `strictNullChecks`, Rust `Option<T>`) make null safe because the compiler forces handling. The problem is untracked nullability, not the concept itself.
+- Interop with APIs or frameworks that require null (e.g., JDBC, some serialization libraries).
+
+Reference: [Clean Code, Chapter 7: Error Handling](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/err-define-by-caller-needs.md b/builtin-skills/software-engineer/clean-code/references/err-define-by-caller-needs.md
new file mode 100644
index 00000000..421155e9
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/err-define-by-caller-needs.md
@@ -0,0 +1,67 @@
+---
+title: Define Exceptions by Caller Needs
+impact: HIGH
+impactDescription: reduces catch blocks by 3-5× per call site
+tags: err, wrapper, classification, design
+---
+
+## Define Exceptions by Caller Needs
+
+Define exception classes based on how they are caught, not on their source or type. Often a single exception class is sufficient for a particular area of code. Wrap third-party API exceptions.
+
+**Incorrect (catching many exception types):**
+
+```java
+// Caller must handle many different exceptions
+try {
+    port.open();
+} catch (DeviceResponseException e) {
+    reportPortError(e);
+    logger.log("Device response problem", e);
+} catch (ATM1212UnlockedException e) {
+    reportPortError(e);
+    logger.log("Unlock exception", e);
+} catch (GMXError e) {
+    reportPortError(e);
+    logger.log("Device response exception", e);
+} finally {
+    // ...
+}
+```
+
+**Correct (unified exception handling):**
+
+```java
+// Wrapper class translates exceptions
+public class LocalPort {
+    private ACMEPort innerPort;
+
+    public void open() throws PortDeviceFailure {
+        try {
+            innerPort.open();
+        } catch (DeviceResponseException e) {
+            throw new PortDeviceFailure(e);
+        } catch (ATM1212UnlockedException e) {
+            throw new PortDeviceFailure(e);
+        } catch (GMXError e) {
+            throw new PortDeviceFailure(e);
+        }
+    }
+}
+
+// Clean caller code
+try {
+    port.open();
+} catch (PortDeviceFailure e) {
+    reportPortError(e);
+    logger.log(e.getMessage(), e);
+}
+```
+
+**Benefits of wrapping:**
+- Minimizes dependencies on third-party APIs
+- Easier to mock for testing
+- Easier to switch implementations later
+- Single exception type per area simplifies catching
+
+Reference: [Clean Code, Chapter 7: Error Handling](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/err-provide-context.md b/builtin-skills/software-engineer/clean-code/references/err-provide-context.md
new file mode 100644
index 00000000..951ae967
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/err-provide-context.md
@@ -0,0 +1,53 @@
+---
+title: Provide Context with Exceptions
+impact: HIGH
+impactDescription: enables rapid root cause identification
+tags: err, context, messages, debugging
+---
+
+## Provide Context with Exceptions
+
+Each exception should provide enough context to determine the source and location of an error. Create informative error messages that describe the operation that failed and the type of failure.
+
+**Incorrect (no context):**
+
+```java
+throw new Exception("Error occurred");
+
+throw new RuntimeException("Failed");
+
+throw new DataAccessException("Query failed");
+
+// Stack trace alone doesn't tell you which order, which customer
+catch (SQLException e) {
+    throw new RuntimeException(e);
+}
+```
+
+**Correct (rich context):**
+
+```java
+throw new OrderProcessingException(
+    String.format("Failed to process order %s for customer %s: %s",
+        orderId, customerId, "Insufficient inventory for item SKU-12345"));
+
+throw new ConfigurationException(
+    "Cannot load configuration from " + configPath +
+    ". Expected format: YAML. Check file permissions and syntax.");
+
+catch (SQLException e) {
+    throw new DataAccessException(
+        String.format("Failed to insert order %s into table %s. " +
+            "Constraint violated: %s",
+            order.getId(), "orders", e.getMessage()),
+        e);  // Preserve original exception
+}
+```
+
+**Include in exception messages:**
+- What operation was being attempted
+- What data was involved (IDs, names, quantities)
+- Why it failed (the specific error condition)
+- Preserve the original exception when wrapping
+
+Reference: [Clean Code, Chapter 7: Error Handling](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/err-use-exceptions.md b/builtin-skills/software-engineer/clean-code/references/err-use-exceptions.md
new file mode 100644
index 00000000..a38656cf
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/err-use-exceptions.md
@@ -0,0 +1,88 @@
+---
+title: Separate Error Handling from Happy Path
+impact: HIGH
+impactDescription: reduces nested conditionals by 50-80% in exception-based languages
+tags: err, exceptions, error-handling, separation, result-types
+---
+
+## Separate Error Handling from Happy Path
+
+Error handling is important, but when it obscures logic, it's wrong. The core insight is separation: keep the happy path visible and error handling consolidated, regardless of which mechanism your language uses.
+
+**Incorrect (error handling obscures business logic):**
+
+```java
+if (deletePage(page) == E_OK) {
+    if (registry.deleteReference(page.name) == E_OK) {
+        if (configKeys.deleteKey(page.name.makeKey()) == E_OK) {
+            logger.log("page deleted");
+        } else {
+            logger.log("configKey not deleted");
+        }
+    } else {
+        logger.log("deleteReference from registry failed");
+    }
+} else {
+    logger.log("delete failed");
+    return E_ERROR;
+}
+```
+
+**Correct (Java/C#/Python — exceptions separate concerns):**
+
+```java
+public void delete(Page page) {
+    try {
+        deletePageAndAllReferences(page);
+    } catch (PageDeletionException e) {
+        logger.log(e.getMessage());
+    }
+}
+
+private void deletePageAndAllReferences(Page page) throws PageDeletionException {
+    deletePage(page);
+    registry.deleteReference(page.name);
+    configKeys.deleteKey(page.name.makeKey());
+}
+```
+
+**Correct (Go — explicit error returns with early return):**
+
+```go
+func (s *Service) Delete(page Page) error {
+    if err := s.deletePage(page); err != nil {
+        return fmt.Errorf("deleting page: %w", err)
+    }
+    if err := s.registry.DeleteReference(page.Name); err != nil {
+        return fmt.Errorf("deleting reference: %w", err)
+    }
+    if err := s.configKeys.DeleteKey(page.Name); err != nil {
+        return fmt.Errorf("deleting config key: %w", err)
+    }
+    return nil
+}
+```
+
+**Correct (Rust — Result type with ? operator):**
+
+```rust
+fn delete(&self, page: &Page) -> Result<(), DeletionError> {
+    self.delete_page(page)?;
+    self.registry.delete_reference(&page.name)?;
+    self.config_keys.delete_key(&page.name)?;
+    Ok(())
+}
+```
+
+**The principle is language-agnostic:** separate error-handling logic from business logic. The mechanism differs:
+- **Java/C#/Python:** try-catch with specific exception types
+- **Go:** explicit error returns with early return pattern
+- **Rust:** `Result<T, E>` with `?` operator
+- **TypeScript/Kotlin:** `Result` types or exceptions depending on the domain
+
+**When NOT to use exceptions:**
+- In Go, Rust, or other languages designed around explicit error values — use their idiomatic patterns instead
+- For expected business outcomes (e.g., "user not found") — consider returning `Optional` or a domain-specific result type rather than throwing
+- In performance-critical hot paths where exception overhead matters
+
+Reference: [Clean Code, Chapter 3: Functions](https://www.oreilly.com/library/view/clean-code-a/9780136083238/) and [Chapter 7: Error Handling](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/err-write-try-catch-first.md b/builtin-skills/software-engineer/clean-code/references/err-write-try-catch-first.md
new file mode 100644
index 00000000..b7243bfd
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/err-write-try-catch-first.md
@@ -0,0 +1,53 @@
+---
+title: Write Try-Catch-Finally First
+impact: HIGH
+impactDescription: prevents missing error handling cases
+tags: err, try-catch, tdd, boundaries
+---
+
+## Write Try-Catch-Finally First
+
+When writing code that could throw exceptions, start with the try-catch-finally statement. This helps define what the user of the code should expect, regardless of what goes wrong in the try block.
+
+**Incorrect (error handling added as afterthought):**
+
+```java
+// Written without considering error cases
+public List<RecordedGrip> retrieveSection(String sectionName) {
+    FileInputStream stream = new FileInputStream(sectionName);
+    BufferedReader reader = new BufferedReader(new InputStreamReader(stream));
+    String line;
+    List<RecordedGrip> grips = new ArrayList<>();
+    while ((line = reader.readLine()) != null) {
+        grips.add(parseGrip(line));
+    }
+    return grips;
+    // What if file doesn't exist? What if parsing fails?
+}
+```
+
+**Correct (start with try-catch structure):**
+
+```java
+// TDD approach: start with test for exception case
+@Test(expected = StorageException.class)
+public void retrieveSectionShouldThrowOnInvalidFileName() {
+    sectionStore.retrieveSection("invalid-file");
+}
+
+// Then write code starting with try-catch
+public List<RecordedGrip> retrieveSection(String sectionName) throws StorageException {
+    try (var stream = new FileInputStream(sectionName)) {
+        return readGrips(stream);
+    } catch (IOException e) {
+        throw new StorageException("Error reading section: " + sectionName, e);
+    }
+}
+```
+
+**Benefits:**
+- Forces you to consider error cases first
+- Establishes clear transaction boundaries
+- The finally block ensures cleanup happens
+
+Reference: [Clean Code, Chapter 7: Error Handling](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/fmt-horizontal-alignment.md b/builtin-skills/software-engineer/clean-code/references/fmt-horizontal-alignment.md
new file mode 100644
index 00000000..cafeb4c5
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/fmt-horizontal-alignment.md
@@ -0,0 +1,59 @@
+---
+title: Avoid Horizontal Alignment
+impact: MEDIUM
+impactDescription: prevents alignment maintenance burden
+tags: fmt, horizontal, alignment, whitespace
+---
+
+## Avoid Horizontal Alignment
+
+Horizontal alignment of variable declarations or assignments looks nice but creates maintenance problems. When one line changes length, all aligned lines need reformatting.
+
+**Incorrect (horizontal alignment):**
+
+```java
+private   Socket          socket;
+private   InputStream     input;
+private   OutputStream    output;
+private   Request         request;
+private   Response        response;
+private   FitNesseContext context;
+private   long            requestParsingTimeLimit;
+private   long            requestProgress;
+
+public void setResponse(Response       response)  { this.response  = response;  }
+public void setSocket(Socket           socket)    { this.socket    = socket;    }
+public void setContext(FitNesseContext context)   { this.context   = context;   }
+```
+
+**Correct (natural formatting):**
+
+```java
+private Socket socket;
+private InputStream input;
+private OutputStream output;
+private Request request;
+private Response response;
+private FitNesseContext context;
+private long requestParsingTimeLimit;
+private long requestProgress;
+
+public void setResponse(Response response) {
+    this.response = response;
+}
+
+public void setSocket(Socket socket) {
+    this.socket = socket;
+}
+
+public void setContext(FitNesseContext context) {
+    this.context = context;
+}
+```
+
+**Why avoid alignment?**
+- Adding a longer variable name requires reformatting all lines
+- Eyes are drawn to the wrong thing (the alignment, not the names)
+- Most formatters don't preserve it anyway
+
+Reference: [Clean Code, Chapter 5: Formatting](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/fmt-indentation.md b/builtin-skills/software-engineer/clean-code/references/fmt-indentation.md
new file mode 100644
index 00000000..361e354a
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/fmt-indentation.md
@@ -0,0 +1,60 @@
+---
+title: Respect Indentation Rules
+impact: MEDIUM
+impactDescription: preserves visual hierarchy for quick scanning
+tags: fmt, indentation, hierarchy, structure
+---
+
+## Respect Indentation Rules
+
+Indentation makes the scope hierarchy visible. Each level of indentation represents a nested scope. Never collapse short statements onto one line to save space.
+
+**Incorrect (collapsed structure):**
+
+```java
+public class CommentWidget extends TextWidget {
+public CommentWidget(ParentWidget parent, String text) { super(parent, text); }
+public String render() throws Exception { return ""; }
+}
+
+public void process() { for (int i = 0; i < 10; i++) { if (valid(i)) { execute(i); } } }
+
+if (condition) return false; else return true;
+```
+
+**Correct (proper indentation):**
+
+```java
+public class CommentWidget extends TextWidget {
+
+    public CommentWidget(ParentWidget parent, String text) {
+        super(parent, text);
+    }
+
+    public String render() throws Exception {
+        return "";
+    }
+}
+
+public void process() {
+    for (int i = 0; i < 10; i++) {
+        if (valid(i)) {
+            execute(i);
+        }
+    }
+}
+
+if (condition) {
+    return false;
+} else {
+    return true;
+}
+```
+
+**Why maintain indentation?**
+- Visual scanning relies on indentation
+- Structure is immediately apparent
+- Debugging is easier when scope is visible
+- Merges are cleaner with consistent formatting
+
+Reference: [Clean Code, Chapter 5: Formatting](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/fmt-team-rules.md b/builtin-skills/software-engineer/clean-code/references/fmt-team-rules.md
new file mode 100644
index 00000000..45a05ded
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/fmt-team-rules.md
@@ -0,0 +1,67 @@
+---
+title: Follow Team Formatting Rules
+impact: HIGH
+impactDescription: eliminates style-related code review friction
+tags: fmt, team, consistency, standards
+---
+
+## Follow Team Formatting Rules
+
+A team of developers should agree upon a single formatting style. Every member should use that style. The goal is to make the software have a consistent style, as if written by one person.
+
+**Incorrect (inconsistent styles mixed):**
+
+```java
+// Developer A's style
+public void processOrder(Order order){
+    if(order.isValid()){
+        order.process();
+    }
+}
+
+// Developer B's style
+public void processPayment( Payment payment )
+{
+    if ( payment.isValid() )
+    {
+        payment.process();
+    }
+}
+
+// Developer C's style
+public void processShipment(Shipment shipment) {
+  if (shipment.isValid()) {
+    shipment.process(); }}
+```
+
+**Correct (consistent team style):**
+
+```java
+public void processOrder(Order order) {
+    if (order.isValid()) {
+        order.process();
+    }
+}
+
+public void processPayment(Payment payment) {
+    if (payment.isValid()) {
+        payment.process();
+    }
+}
+
+public void processShipment(Shipment shipment) {
+    if (shipment.isValid()) {
+        shipment.process();
+    }
+}
+```
+
+**Implementation:**
+- Document the team's coding standards
+- Use automated formatters (Prettier, Black, google-java-format)
+- Enforce in CI/CD pipelines
+- Configure IDE to format on save
+
+Your personal style preferences are less important than team consistency.
+
+Reference: [Clean Code, Chapter 5: Formatting](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/fmt-vertical-formatting.md b/builtin-skills/software-engineer/clean-code/references/fmt-vertical-formatting.md
new file mode 100644
index 00000000..43e3b2e5
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/fmt-vertical-formatting.md
@@ -0,0 +1,72 @@
+---
+title: Use Vertical Formatting for Readability
+impact: HIGH
+impactDescription: enables scanning code like a newspaper
+tags: fmt, vertical, whitespace, organization
+---
+
+## Use Vertical Formatting for Readability
+
+Code should read like a newspaper article: headline at the top, details as you go down. Use vertical whitespace to separate concepts. Keep related code close together.
+
+**Incorrect (no vertical organization):**
+
+```java
+public class WikiPageResponder implements SecureResponder {
+private static final String CONTENT_TYPE = "text/html";
+private WikiPage page;
+private PageData pageData;
+private String pageTitle;
+private Request request;
+private PageCrawler crawler;
+public Response makeResponse(FitNesseContext context, Request request) {
+this.request = request;
+this.page = loadPage();
+if (page == null)
+return notFoundResponse(context, request);
+return makePageResponse(context);
+}
+private WikiPage loadPage() {
+String resource = request.getResource();
+return PageCrawlerImpl.getPageCrawler(context.root).getPage(resource);
+}
+}
+```
+
+**Correct (vertical formatting applied):**
+
+```java
+public class WikiPageResponder implements SecureResponder {
+
+    private static final String CONTENT_TYPE = "text/html";
+
+    private WikiPage page;
+    private PageData pageData;
+    private String pageTitle;
+    private Request request;
+    private PageCrawler crawler;
+
+    public Response makeResponse(FitNesseContext context, Request request) {
+        this.request = request;
+        this.page = loadPage();
+
+        if (page == null)
+            return notFoundResponse(context, request);
+
+        return makePageResponse(context);
+    }
+
+    private WikiPage loadPage() {
+        String resource = request.getResource();
+        return PageCrawlerImpl.getPageCrawler(context.root).getPage(resource);
+    }
+}
+```
+
+**Guidelines:**
+- Blank lines between concepts (methods, logical sections)
+- Related code grouped together
+- Caller above callee (top-down reading)
+- Variable declarations close to their usage
+
+Reference: [Clean Code, Chapter 5: Formatting](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/func-abstraction-level.md b/builtin-skills/software-engineer/clean-code/references/func-abstraction-level.md
new file mode 100644
index 00000000..624327e1
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/func-abstraction-level.md
@@ -0,0 +1,68 @@
+---
+title: Maintain One Level of Abstraction
+impact: CRITICAL
+impactDescription: prevents jarring context switches
+tags: func, abstraction, stepdown, readability
+---
+
+## Maintain One Level of Abstraction
+
+Statements within a function should all be at the same level of abstraction. Mixing high-level concepts with low-level details is confusing. Code should read like a top-down narrative.
+
+**Incorrect (mixed abstraction levels):**
+
+```java
+public void analyzeDocument(String documentPath) {
+    // High level
+    Document document = loadDocument(documentPath);
+
+    // Low level - string manipulation details
+    String text = document.getText();
+    text = text.replaceAll("\\s+", " ");
+    text = text.toLowerCase();
+    String[] words = text.split(" ");
+
+    // High level again
+    WordFrequency frequency = analyzeFrequency(words);
+
+    // Low level - file I/O details
+    FileOutputStream fos = new FileOutputStream("output.txt");
+    BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(fos));
+    for (Map.Entry<String, Integer> entry : frequency.getEntries()) {
+        writer.write(entry.getKey() + ": " + entry.getValue());
+        writer.newLine();
+    }
+    writer.close();
+}
+```
+
+**Correct (consistent abstraction level):**
+
+```java
+public void analyzeDocument(String documentPath) {
+    Document document = loadDocument(documentPath);
+    String normalizedText = normalizeText(document);
+    WordFrequency frequency = analyzeFrequency(normalizedText);
+    saveResults(frequency);
+}
+
+private String normalizeText(Document document) {
+    String text = document.getText();
+    text = collapseWhitespace(text);
+    text = toLowerCase(text);
+    return text;
+}
+
+private void saveResults(WordFrequency frequency) {
+    ResultWriter writer = new ResultWriter("output.txt");
+    writer.write(frequency);
+}
+```
+
+Read the code from top to bottom. Each function introduces the next level of abstraction.
+
+**When mixing levels is acceptable:**
+- Short utility functions (under 10 lines) that perform one task can mix levels without confusion. The overhead of extracting one-line helpers often exceeds the readability benefit.
+- Test code frequently mixes setup (low-level) with assertions (high-level) — this is expected and follows the Arrange-Act-Assert pattern.
+
+Reference: [Clean Code, Chapter 3: Functions](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/func-command-query-separation.md b/builtin-skills/software-engineer/clean-code/references/func-command-query-separation.md
new file mode 100644
index 00000000..06355e99
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/func-command-query-separation.md
@@ -0,0 +1,57 @@
+---
+title: Separate Commands from Queries
+impact: MEDIUM
+impactDescription: eliminates ambiguous function behavior
+tags: func, cqs, command, query, separation
+---
+
+## Separate Commands from Queries
+
+Functions should either do something or answer something, but not both. Either your function changes the state of an object, or it returns information about that object.
+
+**Incorrect (command and query mixed):**
+
+```java
+// Does this set the attribute and return success?
+// Or check if attribute exists?
+public boolean set(String attribute, String value) {
+    // ... sets attribute and returns true if it was set
+}
+
+// Confusing usage
+if (set("username", "bob")) {
+    // Was username set, or did it already exist?
+}
+```
+
+**Correct (separated command and query):**
+
+```java
+// Query - returns information
+public boolean attributeExists(String attribute) {
+    return attributes.containsKey(attribute);
+}
+
+// Command - changes state
+public void setAttribute(String attribute, String value) {
+    attributes.put(attribute, value);
+}
+
+// Clear usage
+if (!attributeExists("username")) {
+    setAttribute("username", "bob");
+}
+```
+
+**Alternative (return new state for immutable design):**
+
+```java
+// For immutable patterns, returning new state is acceptable
+public Settings withAttribute(String attribute, String value) {
+    return new Settings(this.attributes.plus(attribute, value));
+}
+```
+
+The separation makes code easier to read and reason about.
+
+Reference: [Clean Code, Chapter 3: Functions](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/func-dry.md b/builtin-skills/software-engineer/clean-code/references/func-dry.md
new file mode 100644
index 00000000..b4b699da
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/func-dry.md
@@ -0,0 +1,70 @@
+---
+title: Do Not Repeat Yourself
+impact: CRITICAL
+impactDescription: prevents N× maintenance burden
+tags: func, dry, duplication, abstraction
+---
+
+## Do Not Repeat Yourself
+
+Duplication is the root of all evil in software. When an algorithm changes, you must change it in multiple places. When you fix a bug, you must remember to fix it everywhere.
+
+**Incorrect (duplicated logic):**
+
+```java
+public void processNewEmployee(Employee employee) {
+    if (employee.getName() == null || employee.getName().trim().isEmpty()) {
+        throw new ValidationException("Name is required");
+    }
+    if (employee.getEmail() == null || !employee.getEmail().contains("@")) {
+        throw new ValidationException("Valid email is required");
+    }
+    employeeRepository.save(employee);
+    emailService.sendWelcome(employee.getEmail());
+}
+
+public void updateEmployee(Employee employee) {
+    if (employee.getName() == null || employee.getName().trim().isEmpty()) {
+        throw new ValidationException("Name is required");  // Duplicated
+    }
+    if (employee.getEmail() == null || !employee.getEmail().contains("@")) {
+        throw new ValidationException("Valid email is required");  // Duplicated
+    }
+    employeeRepository.update(employee);
+}
+```
+
+**Correct (extracted common logic):**
+
+```java
+public void processNewEmployee(Employee employee) {
+    validateEmployee(employee);
+    employeeRepository.save(employee);
+    emailService.sendWelcome(employee.getEmail());
+}
+
+public void updateEmployee(Employee employee) {
+    validateEmployee(employee);
+    employeeRepository.update(employee);
+}
+
+private void validateEmployee(Employee employee) {
+    requireNonEmpty(employee.getName(), "Name is required");
+    requireValidEmail(employee.getEmail());
+}
+
+private void requireNonEmpty(String value, String message) {
+    if (value == null || value.trim().isEmpty()) {
+        throw new ValidationException(message);
+    }
+}
+```
+
+Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.
+
+**When NOT to apply DRY:**
+- **Coincidental duplication:** Two code blocks look similar but serve different purposes and will evolve independently. Extracting a shared function creates a false coupling that makes both harder to change later.
+- **Premature abstraction:** If the code has only been duplicated once, wait. The third occurrence reveals the true abstraction. Premature extraction often produces awkward, over-parameterized helpers.
+- **Cross-boundary duplication:** Sometimes duplication across microservices or bounded contexts is preferable to introducing a shared library that couples the services.
+
+Reference: [Clean Code, Chapter 3: Functions](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/func-minimize-arguments.md b/builtin-skills/software-engineer/clean-code/references/func-minimize-arguments.md
new file mode 100644
index 00000000..03e44422
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/func-minimize-arguments.md
@@ -0,0 +1,56 @@
+---
+title: Minimize Function Arguments
+impact: HIGH
+impactDescription: reduces cognitive load and testing complexity
+tags: func, arguments, parameters, simplicity
+---
+
+## Minimize Function Arguments
+
+The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible.
+
+**Incorrect (too many arguments):**
+
+```java
+// Flag arguments are bad - function does different things
+public void render(boolean isSuite) {}
+
+// Four arguments - hard to remember order
+public Circle makeCircle(double x, double y, double radius, String color) {}
+
+// Order matters and is easy to confuse
+public void assertExpectedEqualsActual(String expected, String actual) {}
+```
+
+**Correct (minimized arguments):**
+
+```java
+// Separate functions instead of flag
+public void renderForSingleTest() {}
+public void renderForSuite() {}
+
+// Encapsulate related arguments in objects
+public Circle makeCircle(Point center, double radius, Color color) {}
+
+// Even better - use a builder for many optional params
+Circle circle = Circle.builder()
+    .center(new Point(0, 0))
+    .radius(5.0)
+    .color(Color.RED)
+    .build();
+
+// Self-documenting method name
+assertThat(actual).isEqualTo(expected);
+```
+
+**Why fewer arguments?**
+- Easier to understand
+- Easier to test (fewer combinations)
+- Less chance of argument order errors
+
+**Acceptable monadic forms:**
+- Asking a question: `boolean fileExists(String path)`
+- Transforming input: `InputStream openFile(String path)`
+- Events: `void passwordAttemptFailed(int attempts)`
+
+Reference: [Clean Code, Chapter 3: Functions](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/func-no-side-effects.md b/builtin-skills/software-engineer/clean-code/references/func-no-side-effects.md
new file mode 100644
index 00000000..39d4a76c
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/func-no-side-effects.md
@@ -0,0 +1,67 @@
+---
+title: Avoid Side Effects
+impact: HIGH
+impactDescription: prevents hidden temporal couplings
+tags: func, side-effects, purity, predictability
+---
+
+## Avoid Side Effects
+
+Side effects are lies. Your function promises to do one thing, but it also does other hidden things. Avoid unexpected changes to class variables, globals, or passed arguments.
+
+**Incorrect (hidden side effect):**
+
+```java
+public class UserValidator {
+    private Cryptographer cryptographer;
+    private Session session;
+
+    public boolean checkPassword(String userName, String password) {
+        User user = UserGateway.findByName(userName);
+        if (user != null) {
+            String codedPhrase = user.getPhraseEncodedByPassword();
+            String phrase = cryptographer.decrypt(codedPhrase, password);
+            if ("Valid Password".equals(phrase)) {
+                session.initialize();  // Hidden side effect!
+                return true;
+            }
+        }
+        return false;
+    }
+}
+// Calling checkPassword twice destroys the session unexpectedly
+```
+
+**Correct (explicit behavior):**
+
+```java
+public class UserValidator {
+    private Cryptographer cryptographer;
+
+    public boolean checkPassword(String userName, String password) {
+        User user = UserGateway.findByName(userName);
+        if (user == null) return false;
+
+        String codedPhrase = user.getPhraseEncodedByPassword();
+        String phrase = cryptographer.decrypt(codedPhrase, password);
+        return "Valid Password".equals(phrase);
+    }
+}
+
+// Separate function with clear name
+public class SessionManager {
+    public void initializeSessionForUser(String userName, String password) {
+        if (userValidator.checkPassword(userName, password)) {
+            session.initialize();
+        }
+    }
+}
+```
+
+If you must have a temporal coupling, make it explicit in the function name: `checkPasswordAndInitializeSession`.
+
+**When side effects are expected:**
+- I/O operations (file writes, network calls, database mutations) inherently have side effects — the principle here is about *hidden* side effects, not avoiding all mutation. A function named `saveUser()` clearly signals side effects.
+- Event handlers, middleware, and lifecycle hooks are designed to produce side effects. Name them to make the effect obvious.
+
+Reference: [Clean Code, Chapter 3: Functions](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/func-one-thing.md b/builtin-skills/software-engineer/clean-code/references/func-one-thing.md
new file mode 100644
index 00000000..b25622ad
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/func-one-thing.md
@@ -0,0 +1,77 @@
+---
+title: Functions Should Do One Thing
+impact: CRITICAL
+impactDescription: enables understanding functions at a glance
+tags: func, single-responsibility, cohesion, focus
+---
+
+## Functions Should Do One Thing
+
+Functions should do one thing. They should do it well. They should do it only. If a function does multiple things, extract those things into separate functions.
+
+**Incorrect (function does multiple things):**
+
+```java
+public void processEmployee(Employee employee) {
+    // Validate employee
+    if (employee.getName() == null || employee.getName().isEmpty()) {
+        throw new IllegalArgumentException("Name required");
+    }
+    if (employee.getSalary() < 0) {
+        throw new IllegalArgumentException("Salary cannot be negative");
+    }
+
+    // Calculate tax
+    double tax = employee.getSalary() * 0.3;
+    employee.setTax(tax);
+
+    // Save to database
+    Connection conn = getConnection();
+    PreparedStatement stmt = conn.prepareStatement(
+        "INSERT INTO employees VALUES (?, ?, ?)");
+    stmt.setString(1, employee.getName());
+    stmt.setDouble(2, employee.getSalary());
+    stmt.setDouble(3, tax);
+    stmt.execute();
+
+    // Send email notification
+    EmailService.send(employee.getEmail(), "Welcome!");
+}
+```
+
+**Correct (each function does one thing):**
+
+```java
+public void processEmployee(Employee employee) {
+    validateEmployee(employee);
+    calculateTax(employee);
+    saveEmployee(employee);
+    sendWelcomeEmail(employee);
+}
+
+private void validateEmployee(Employee employee) {
+    validateName(employee);
+    validateSalary(employee);
+}
+
+private void calculateTax(Employee employee) {
+    double tax = employee.getSalary() * TAX_RATE;
+    employee.setTax(tax);
+}
+
+private void saveEmployee(Employee employee) {
+    employeeRepository.save(employee);
+}
+
+private void sendWelcomeEmail(Employee employee) {
+    emailService.sendWelcome(employee.getEmail());
+}
+```
+
+**Test:** If you can extract another function from it with a name that is not merely a restatement of its implementation, the function is doing more than one thing.
+
+**When NOT to split:**
+- If the extracted function's name would just restate its body (e.g., `calculateTax` containing only `salary * TAX_RATE`), the extraction adds indirection without clarity.
+- Orchestration functions that call a sequence of steps at the same abstraction level (like `processEmployee` above) are doing "one thing" — orchestrating. Don't try to extract the orchestration further.
+
+Reference: [Clean Code, Chapter 3: Functions](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/func-small.md b/builtin-skills/software-engineer/clean-code/references/func-small.md
new file mode 100644
index 00000000..3f21c3e1
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/func-small.md
@@ -0,0 +1,71 @@
+---
+title: Keep Functions Small
+impact: CRITICAL
+impactDescription: enables comprehension at a glance
+tags: func, size, readability, comprehension
+---
+
+## Keep Functions Small
+
+Functions should be small. They should be smaller than that. Functions should hardly ever be 20 lines long. Each function should do one thing, do it well, and do it only.
+
+**Incorrect (large function doing multiple things):**
+
+```java
+public void renderPageWithSetupsAndTeardowns(PageData pageData, boolean isSuite) {
+    if (isTestPage(pageData)) {
+        WikiPage testPage = pageData.getWikiPage();
+        StringBuffer newPageContent = new StringBuffer();
+        includeSetupPages(testPage, newPageContent, isSuite);
+        newPageContent.append(pageData.getContent());
+        includeTeardownPages(testPage, newPageContent, isSuite);
+        pageData.setContent(newPageContent.toString());
+    }
+}
+
+private void includeSetupPages(WikiPage testPage, StringBuffer buffer, boolean isSuite) {
+    if (isSuite) {
+        WikiPage suitePage = PageCrawlerImpl.getInheritedPage(
+            SuiteResponder.SUITE_SETUP_NAME, testPage);
+        if (suitePage != null) {
+            WikiPagePath pagePath = testPage.getPageCrawler()
+                .getFullPath(suitePage);
+            String pagePathName = PathParser.render(pagePath);
+            buffer.append("!include -setup .")
+                  .append(pagePathName)
+                  .append("\n");
+        }
+    }
+    // ... 20 more lines
+}
+```
+
+**Correct (small, focused functions):**
+
+```java
+public void renderPageWithSetupsAndTeardowns(PageData pageData, boolean isSuite) {
+    if (isTestPage(pageData))
+        includeSetupsAndTeardowns(pageData, isSuite);
+}
+
+private void includeSetupsAndTeardowns(PageData pageData, boolean isSuite) {
+    WikiPage testPage = pageData.getWikiPage();
+    String content = buildPageContent(testPage, isSuite);
+    pageData.setContent(content);
+}
+
+private String buildPageContent(WikiPage testPage, boolean isSuite) {
+    return getSetups(testPage, isSuite) +
+           testPage.getContent() +
+           getTeardowns(testPage, isSuite);
+}
+```
+
+Each function is 3-5 lines. Each does exactly one thing. Each is at one level of abstraction.
+
+**When NOT to apply this pattern:**
+- If a 15-20 line function does one thing at one level of abstraction, it does not need further decomposition. The goal is comprehensibility, not minimizing line count.
+- Do not extract functions that are only called from one place and whose names merely restate their implementation — this adds indirection without clarity.
+- Ousterhout's "deep modules" critique: extremely small functions can create "shallow modules" that spread logic across many files, forcing readers to jump between functions to understand a single behavior. Balance depth (functionality per interface) against size.
+
+Reference: [Clean Code, Chapter 3: Functions](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/name-avoid-disinformation.md b/builtin-skills/software-engineer/clean-code/references/name-avoid-disinformation.md
new file mode 100644
index 00000000..671dd2cc
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/name-avoid-disinformation.md
@@ -0,0 +1,44 @@
+---
+title: Avoid Disinformation in Names
+impact: CRITICAL
+impactDescription: prevents incorrect mental models
+tags: name, disinformation, misleading, types
+---
+
+## Avoid Disinformation in Names
+
+Avoid names that encode false information. Do not refer to a grouping as a "List" unless it is actually a List. Avoid names that vary in small ways that are hard to distinguish.
+
+**Incorrect (misleading type information):**
+
+```java
+// Not actually a List, it's a Map
+private Map<String, Account> accountList;
+
+// These look almost identical - easy to confuse
+private String XYZControllerForEfficientHandlingOfStrings;
+private String XYZControllerForEfficientStorageOfStrings;
+
+// Lowercase L looks like 1, uppercase O looks like 0
+int a = l;
+if (O == l)
+    a = O1;
+```
+
+**Correct (accurate and distinguishable):**
+
+```java
+// Accurately describes the data structure
+private Map<String, Account> accountsByName;
+
+// Clearly distinguishable names
+private String stringProcessingController;
+private String stringStorageController;
+
+// Clear variable names
+int result = leftValue;
+if (originalValue == leftValue)
+    result = outputValue;
+```
+
+Reference: [Clean Code, Chapter 2: Meaningful Names](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/name-avoid-encodings.md b/builtin-skills/software-engineer/clean-code/references/name-avoid-encodings.md
new file mode 100644
index 00000000..c57651b2
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/name-avoid-encodings.md
@@ -0,0 +1,66 @@
+---
+title: Avoid Encodings in Names
+impact: HIGH
+impactDescription: reduces mental translation burden
+tags: name, encoding, hungarian, prefixes
+---
+
+## Avoid Encodings in Names
+
+Encoding type or scope information into names adds an extra burden of deciphering. Modern IDEs make Hungarian Notation and member prefixes unnecessary.
+
+**Incorrect (encoded type and scope):**
+
+```java
+// Hungarian Notation - type encoded in name
+String strName;
+int iAge;
+boolean bIsActive;
+PhoneNumber phoneString;  // Type changed but name wasn't updated!
+
+// Member prefixes
+public class Part {
+    private String m_dsc;  // Member description
+
+    void setDescription(String dsc) {
+        m_dsc = dsc;
+    }
+}
+
+// Interface prefix
+public interface IShapeFactory {}
+```
+
+**Correct (no encodings):**
+
+```java
+// Let the type system handle types
+String name;
+int age;
+boolean isActive;
+PhoneNumber phone;
+
+// No member prefixes - IDE highlights members
+public class Part {
+    private String description;
+
+    void setDescription(String description) {
+        this.description = description;
+    }
+}
+
+// Drop the interface prefix — callers use ShapeFactory, not IShapeFactory
+public interface ShapeFactory {}
+
+// Name implementations by what distinguishes them
+public class JsonShapeFactory implements ShapeFactory {}
+public class SvgShapeFactory implements ShapeFactory {}
+
+// If only one implementation exists, consider whether you need the interface at all
+```
+
+Readers learn to ignore prefixes. You end up seeing only the meaningful part of the name.
+
+**Note:** `ShapeFactoryImpl` is a lesser evil than `IShapeFactory`, but `Impl` is still an encoding. When possible, name implementations by their distinguishing characteristic (protocol, storage mechanism, algorithm).
+
+Reference: [Clean Code, Chapter 2: Meaningful Names](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/name-class-noun.md b/builtin-skills/software-engineer/clean-code/references/name-class-noun.md
new file mode 100644
index 00000000..4b9ac99d
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/name-class-noun.md
@@ -0,0 +1,54 @@
+---
+title: Use Noun Phrases for Class Names
+impact: MEDIUM-HIGH
+impactDescription: eliminates 80%+ of "what does this class do" questions
+tags: name, class, noun, identity
+---
+
+## Use Noun Phrases for Class Names
+
+Class names should be nouns or noun phrases. A class represents a thing or concept. Avoid verbs, manager-style names, and vague words.
+
+**Incorrect (verbs, vague, or manager-style):**
+
+```java
+// Verb as class name
+class ProcessPayment {}
+
+// Vague manager names
+class Manager {}
+class Processor {}
+class Data {}
+class Info {}
+
+// Unnecessary suffixes
+class CustomerManager {}
+class AccountProcessor {}
+class PaymentHandler {}
+```
+
+**Correct (specific noun phrases):**
+
+```java
+// Clear nouns representing entities
+class Payment {}
+class PaymentGateway {}
+
+// Specific, descriptive nouns
+class Customer {}
+class WikiPage {}
+class Account {}
+class AddressParser {}
+
+// Role-specific names when needed
+class PaymentValidator {}    // Validates payments
+class AccountRepository {}   // Stores accounts
+```
+
+**When NOT to use this pattern:**
+
+Manager-style names are acceptable when the class genuinely manages a resource lifecycle:
+- `ConnectionPool` - manages connection lifecycle
+- `ThreadPoolExecutor` - manages thread lifecycle
+
+Reference: [Clean Code, Chapter 2: Meaningful Names](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/name-intention-revealing.md b/builtin-skills/software-engineer/clean-code/references/name-intention-revealing.md
new file mode 100644
index 00000000..487bac15
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/name-intention-revealing.md
@@ -0,0 +1,47 @@
+---
+title: Use Intention-Revealing Names
+impact: CRITICAL
+impactDescription: eliminates mental mapping overhead
+tags: name, intention, readability, clarity
+---
+
+## Use Intention-Revealing Names
+
+Names should reveal intent. A name should tell you why something exists, what it does, and how it is used. If a name requires a comment, it does not reveal its intent.
+
+**Incorrect (requires mental decoding):**
+
+```java
+int d; // elapsed time in days
+
+public List<int[]> getThem() {
+    List<int[]> list1 = new ArrayList<>();
+    for (int[] x : theList)
+        if (x[0] == 4)  // What is 4? What is x[0]?
+            list1.add(x);
+    return list1;
+}
+```
+
+**Correct (self-documenting):**
+
+```java
+int elapsedTimeInDays;
+
+public List<Cell> getFlaggedCells() {
+    List<Cell> flaggedCells = new ArrayList<>();
+    for (Cell cell : gameBoard)
+        if (cell.isFlagged())
+            flaggedCells.add(cell);
+    return flaggedCells;
+}
+```
+
+The code now explicitly communicates its purpose: finding flagged cells in a minesweeper game. No comment needed.
+
+**When short names are acceptable:**
+- Loop counters (`i`, `j`, `k`) in small, tightly-scoped loops where the index has no domain meaning.
+- Mathematical algorithms where `x`, `y`, `dx`, `dt` are conventional and understood by the target audience.
+- Lambda parameters in trivial callbacks: `items.filter(x -> x > 0)` is clearer than `items.filter(numberThatMustBePositive -> numberThatMustBePositive > 0)`.
+
+Reference: [Clean Code, Chapter 2: Meaningful Names](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/name-meaningful-distinctions.md b/builtin-skills/software-engineer/clean-code/references/name-meaningful-distinctions.md
new file mode 100644
index 00000000..204fbd84
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/name-meaningful-distinctions.md
@@ -0,0 +1,54 @@
+---
+title: Make Meaningful Distinctions
+impact: CRITICAL
+impactDescription: eliminates ambiguity between similar concepts
+tags: name, distinction, noise-words, clarity
+---
+
+## Make Meaningful Distinctions
+
+If names must be different, then they should also mean something different. Avoid number-series naming and noise words that add no information.
+
+**Incorrect (indistinguishable names):**
+
+```java
+// Number series - meaningless distinction
+public static void copyChars(char[] a1, char[] a2) {
+    for (int i = 0; i < a1.length; i++) {
+        a2[i] = a1[i];
+    }
+}
+
+// Noise words - what's the difference?
+class Product {}
+class ProductInfo {}
+class ProductData {}
+
+// Redundant prefixes
+String nameString;
+Customer customerObject;
+```
+
+**Correct (meaningful distinctions):**
+
+```java
+// Descriptive parameter names
+public static void copyChars(char[] source, char[] destination) {
+    for (int i = 0; i < source.length; i++) {
+        destination[i] = source[i];
+    }
+}
+
+// If distinctions exist, name them
+class Product {}
+class ProductDetails {}       // Shows additional information
+class ProductInventory {}     // Stock and availability
+
+// No redundant type encoding
+String name;
+Customer customer;
+```
+
+If you cannot distinguish what `ProductInfo` offers that `Product` does not, the names are noise.
+
+Reference: [Clean Code, Chapter 2: Meaningful Names](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/name-method-verb.md b/builtin-skills/software-engineer/clean-code/references/name-method-verb.md
new file mode 100644
index 00000000..7283e4f2
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/name-method-verb.md
@@ -0,0 +1,55 @@
+---
+title: Use Verb Phrases for Method Names
+impact: MEDIUM-HIGH
+impactDescription: reduces "what does this method do" lookups by 80%
+tags: name, method, verb, action
+---
+
+## Use Verb Phrases for Method Names
+
+Method names should be verbs or verb phrases. Methods do things, so their names should say what they do. Follow JavaBean conventions for accessors and mutators.
+
+**Incorrect (non-verb or unclear):**
+
+```java
+// Noun names for methods
+public String name() {}
+public int size() {}  // Acceptable for collections
+
+// Unclear action
+public void customer() {}  // Does what to customer?
+
+// Missing verb
+public boolean valid() {}
+```
+
+**Correct (verb phrases):**
+
+```java
+// Clear verb phrases
+public void postPayment() {}
+public void deletePage() {}
+public void saveCustomer() {}
+
+// Accessors, mutators, predicates follow conventions
+public String getName() {}
+public void setName(String name) {}
+public boolean isPosted() {}
+public boolean hasPermission() {}
+
+// Static factory methods describe what is created
+Complex fulcrumPoint = Complex.fromRealNumber(23.0);
+```
+
+Use `get`, `set`, `is`, and `has` prefixes consistently for accessors, mutators, and predicates.
+
+**Language-specific conventions:**
+- **Java/C#:** `getName()`, `setName()`, `isActive()` (JavaBean conventions)
+- **Python:** Use `@property` decorators — `user.name` not `user.get_name()`
+- **Kotlin/Swift:** Direct property access with `val`/`var` — `user.name` not `user.getName()`
+- **TypeScript:** Direct properties or getters — `get name(): string`
+- **Go:** `Name()` not `GetName()` (Go convention omits `Get` prefix)
+
+The underlying principle (methods describe actions, names describe things) is universal. The accessor/mutator conventions are language-specific.
+
+Reference: [Clean Code, Chapter 2: Meaningful Names](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/name-pronounceable.md b/builtin-skills/software-engineer/clean-code/references/name-pronounceable.md
new file mode 100644
index 00000000..9436bc76
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/name-pronounceable.md
@@ -0,0 +1,38 @@
+---
+title: Use Pronounceable Names
+impact: HIGH
+impactDescription: enables verbal communication about code
+tags: name, pronounceable, communication, readability
+---
+
+## Use Pronounceable Names
+
+Use pronounceable names. If you cannot pronounce a name, you cannot discuss it without sounding foolish. Programming is a social activity; names should facilitate discussion.
+
+**Incorrect (unpronounceable abbreviations):**
+
+```java
+class DtaRcrd102 {
+    private Date genymdhms;  // generation year, month, day, hour, minute, second
+    private Date modymdhms;
+    private final String pszqint = "102";
+}
+
+// In conversation: "Hey, look at this dee-tee-ay-arr-cee-arr-dee"
+```
+
+**Correct (pronounceable names):**
+
+```java
+class Customer {
+    private Date generationTimestamp;
+    private Date modificationTimestamp;
+    private final String recordId = "102";
+}
+
+// In conversation: "Hey, look at this Customer record"
+```
+
+The pronounceable version enables natural conversation: "Hey, when did we modify this customer's generation timestamp?"
+
+Reference: [Clean Code, Chapter 2: Meaningful Names](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/name-searchable.md b/builtin-skills/software-engineer/clean-code/references/name-searchable.md
new file mode 100644
index 00000000..5b840491
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/name-searchable.md
@@ -0,0 +1,39 @@
+---
+title: Use Searchable Names
+impact: HIGH
+impactDescription: enables effective code navigation
+tags: name, searchable, constants, refactoring
+---
+
+## Use Searchable Names
+
+Single-letter names and numeric constants are hard to locate across a body of text. Longer names trump shorter names, and searchable names trump convenient abbreviations.
+
+**Incorrect (unsearchable):**
+
+```java
+for (int j = 0; j < 34; j++) {
+    s += (t[j] * 4) / 5;  // What is 34? What is 4? What is 5?
+}
+```
+
+**Correct (searchable and meaningful):**
+
+```java
+int realDaysPerIdealDay = 4;
+final int WORK_DAYS_PER_WEEK = 5;
+final int NUMBER_OF_TASKS = 34;
+
+int sum = 0;
+for (int taskIndex = 0; taskIndex < NUMBER_OF_TASKS; taskIndex++) {
+    int realTaskDays = taskEstimate[taskIndex] * realDaysPerIdealDay;
+    int realTaskWeeks = realTaskDays / WORK_DAYS_PER_WEEK;
+    sum += realTaskWeeks;
+}
+```
+
+Now you can search for `WORK_DAYS_PER_WEEK` and find every place it is used. Try searching for `5` in a large codebase.
+
+**Exception:** Single-letter names are acceptable only as local variables in short methods. The length of a name should correspond to the size of its scope.
+
+Reference: [Clean Code, Chapter 2: Meaningful Names](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/obj-avoid-hybrids.md b/builtin-skills/software-engineer/clean-code/references/obj-avoid-hybrids.md
new file mode 100644
index 00000000..d599a34d
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/obj-avoid-hybrids.md
@@ -0,0 +1,69 @@
+---
+title: Avoid Hybrid Data-Object Structures
+impact: MEDIUM-HIGH
+impactDescription: prevents worst-of-both-worlds maintenance burden
+tags: obj, hybrid, structure, design
+---
+
+## Avoid Hybrid Data-Object Structures
+
+Hybrids are half object, half data structure. They have functions that do significant things, AND they have public variables or accessors that expose internal structure. Avoid creating these monstrosities.
+
+**Incorrect (hybrid structure):**
+
+```java
+// Half object, half data structure
+public class Employee {
+    // Public data like a data structure
+    public String name;
+    public double salary;
+    public List<String> skills;
+
+    // Behavior like an object
+    public void promote() {
+        this.salary *= 1.1;
+        notifyHR();
+    }
+
+    public void addSkill(String skill) {
+        this.skills.add(skill);
+        updateTrainingRecord();
+    }
+}
+
+// Client code can bypass behavior
+employee.salary = employee.salary * 1.5;  // Skips notifyHR()
+employee.skills.clear();  // Skips updateTrainingRecord()
+```
+
+**Correct (choose one approach):**
+
+```java
+// Pure object - hide data, expose behavior
+public class Employee {
+    private String name;
+    private Money salary;
+    private SkillSet skills;
+
+    public void promote(PromotionDetails details) {
+        this.salary = salary.increase(details.getRaisePercentage());
+        notifyHR(details);
+    }
+
+    public void addSkill(Skill skill) {
+        this.skills.add(skill);
+        updateTrainingRecord(skill);
+    }
+
+    public EmployeeReport getReport() {
+        return new EmployeeReport(name, salary.getAmount(), skills.list());
+    }
+}
+
+// OR pure data structure - no behavior, expose data
+public record EmployeeData(String name, double salary, List<String> skills) {}
+```
+
+Hybrids make it hard to add new functions AND hard to add new data structures.
+
+Reference: [Clean Code, Chapter 6: Objects and Data Structures](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/obj-data-abstraction.md b/builtin-skills/software-engineer/clean-code/references/obj-data-abstraction.md
new file mode 100644
index 00000000..93e5a998
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/obj-data-abstraction.md
@@ -0,0 +1,51 @@
+---
+title: Hide Data Behind Abstractions
+impact: MEDIUM-HIGH
+impactDescription: enables implementation changes without ripple effects
+tags: obj, abstraction, encapsulation, data-hiding
+---
+
+## Hide Data Behind Abstractions
+
+Objects hide their data behind abstractions and expose functions that operate on that data. Data structures expose their data and have no meaningful functions. Do not mix these concepts.
+
+**Incorrect (exposing implementation):**
+
+```java
+// Exposes internal representation - clients depend on Cartesian coordinates
+public class Point {
+    public double x;
+    public double y;
+}
+
+// Using it forces clients to know the implementation
+double distance = Math.sqrt(point.x * point.x + point.y * point.y);
+```
+
+**Correct (hiding behind abstraction — immutable):**
+
+```java
+// Hides representation - could be Cartesian, polar, or something else
+public interface Point {
+    double getX();
+    double getY();
+    double getR();
+    double getTheta();
+
+    static Point fromCartesian(double x, double y) {
+        return new CartesianPoint(x, y);
+    }
+
+    static Point fromPolar(double r, double theta) {
+        return new PolarPoint(r, theta);
+    }
+}
+
+// Clients work with the abstraction
+double distance = point.getR();  // Works regardless of internal representation
+Point moved = Point.fromCartesian(point.getX() + dx, point.getY() + dy);
+```
+
+**Key insight:** The abstraction is not just about using getters/setters. It is about hiding the form of the data and exposing operations that work with the abstract concept. Prefer immutable objects with factory methods over mutable objects with setters — immutable designs are easier to reason about, thread-safe by default, and less prone to bugs.
+
+Reference: [Clean Code, Chapter 6: Objects and Data Structures](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/obj-data-object-asymmetry.md b/builtin-skills/software-engineer/clean-code/references/obj-data-object-asymmetry.md
new file mode 100644
index 00000000..b335baf6
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/obj-data-object-asymmetry.md
@@ -0,0 +1,72 @@
+---
+title: Understand Data/Object Anti-Symmetry
+impact: MEDIUM-HIGH
+impactDescription: prevents 2× effort when requirements change
+tags: obj, asymmetry, procedural, polymorphism
+---
+
+## Understand Data/Object Anti-Symmetry
+
+Objects and data structures are opposites. Objects hide data and expose behavior; data structures expose data and have no behavior. Choose based on what kind of changes you anticipate.
+
+**Incorrect (wrong approach for frequent type additions):**
+
+```java
+// Procedural approach - adding Triangle requires modifying EVERY function
+public class Square { public double side; }
+public class Circle { public double radius; }
+
+public class Geometry {
+    public double area(Object shape) {
+        if (shape instanceof Square) {
+            Square s = (Square) shape;
+            return s.side * s.side;
+        } else if (shape instanceof Circle) {
+            Circle c = (Circle) shape;
+            return Math.PI * c.radius * c.radius;
+        }
+        // Must add Triangle case here AND in perimeter() AND in draw()...
+        throw new NoSuchShapeException();
+    }
+}
+```
+
+**Correct (polymorphic approach for frequent type additions):**
+
+```java
+// Object approach - adding Triangle only requires one new class
+public interface Shape {
+    double area();
+}
+
+public class Square implements Shape {
+    private double side;
+
+    public double area() {
+        return side * side;
+    }
+}
+
+public class Circle implements Shape {
+    private double radius;
+
+    public double area() {
+        return Math.PI * radius * radius;
+    }
+}
+
+// Adding Triangle is easy - just add one class
+public class Triangle implements Shape {
+    private double base, height;
+
+    public double area() {
+        return 0.5 * base * height;
+    }
+}
+```
+
+**Choose based on anticipated changes:**
+- Adding new functions often? Use data structures (procedural)
+- Adding new types often? Use objects (polymorphic)
+
+Reference: [Clean Code, Chapter 6: Objects and Data Structures](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/obj-dto.md b/builtin-skills/software-engineer/clean-code/references/obj-dto.md
new file mode 100644
index 00000000..2fa6c2f4
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/obj-dto.md
@@ -0,0 +1,63 @@
+---
+title: Use DTOs for Data Transfer
+impact: MEDIUM
+impactDescription: prevents sensitive data exposure at boundaries
+tags: obj, dto, transfer, boundary
+---
+
+## Use DTOs for Data Transfer
+
+Data Transfer Objects (DTOs) are pure data structures for transferring data between layers or systems. They should have no behavior beyond accessors. Use them at system boundaries.
+
+**Incorrect (domain object used for transfer):**
+
+```java
+// Domain object with behavior used for API response
+public class User {
+    private String name;
+    private String hashedPassword;
+    private CreditCard creditCard;
+
+    public void authenticate(String password) { /* ... */ }
+    public void chargeCard(Money amount) { /* ... */ }
+
+    // Serialized directly - exposes sensitive data and internal structure
+}
+```
+
+**Correct (separate DTO for transfer):**
+
+```java
+// Domain object with behavior (internal)
+public class User {
+    private String name;
+    private HashedPassword password;
+    private CreditCard creditCard;
+
+    public void authenticate(String password) { /* ... */ }
+    public void chargeCard(Money amount) { /* ... */ }
+
+    public UserDTO toDTO() {
+        return new UserDTO(name, creditCard.getMaskedNumber());
+    }
+}
+
+// DTO for API response (external)
+public record UserDTO(String name, String maskedCardNumber) {}
+
+// Active Record variant - DTO with persistence methods only
+public class UserRecord {
+    public String name;
+    public String email;
+
+    public void save() { /* SQL insert/update */ }
+    public static UserRecord findById(Long id) { /* SQL select */ }
+}
+```
+
+**Use DTOs when:**
+- Transferring data across system boundaries (API, database, message queue)
+- Hiding internal structure from external consumers
+- Transforming data format between layers
+
+Reference: [Clean Code, Chapter 6: Objects and Data Structures](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/obj-law-of-demeter.md b/builtin-skills/software-engineer/clean-code/references/obj-law-of-demeter.md
new file mode 100644
index 00000000..9b4c7ae6
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/obj-law-of-demeter.md
@@ -0,0 +1,45 @@
+---
+title: Follow the Law of Demeter
+impact: MEDIUM-HIGH
+impactDescription: prevents hidden dependencies between modules
+tags: obj, demeter, coupling, encapsulation
+---
+
+## Follow the Law of Demeter
+
+A method should only call methods on: its own object, objects passed as parameters, objects it creates, or its direct component objects. Avoid chained method calls on returned objects.
+
+**Incorrect (train wreck - violates Law of Demeter):**
+
+```java
+// Reaches through multiple objects
+String outputDir = ctxt.getOptions().getScratchDir().getAbsolutePath();
+
+// Forces knowledge of internal structure
+customer.getAddress().getCity().getName();
+
+// Chains expose implementation details
+report.getFormatter().getConfiguration().getPageSize();
+```
+
+**Correct (respects object boundaries):**
+
+```java
+// Option 1: Create a direct method
+String outputDir = ctxt.getOutputDirectory();
+
+// Option 2: Tell, don't ask
+customer.sendBillingNotice();  // Let customer handle its own address
+
+// Option 3: If data structure, use it directly (no behavior expected)
+BufferedOutputStream bos = ctxt.createScratchFileStream(classFileName);
+```
+
+**Exception:** The Law of Demeter does not apply to data structures. If `Options`, `ScratchDir`, etc. are just data containers without behavior, the chaining is acceptable:
+
+```java
+// Data transfer objects can be chained
+final String outputDir = ctxt.options.scratchDir.absolutePath;
+```
+
+Reference: [Clean Code, Chapter 6: Objects and Data Structures](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/test-build-operate-check.md b/builtin-skills/software-engineer/clean-code/references/test-build-operate-check.md
new file mode 100644
index 00000000..647297e3
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/test-build-operate-check.md
@@ -0,0 +1,78 @@
+---
+title: Use Build-Operate-Check Pattern
+impact: MEDIUM
+impactDescription: reduces test comprehension time by 50%
+tags: test, boc, arrange-act-assert, structure
+---
+
+## Use Build-Operate-Check Pattern
+
+Structure tests in three distinct phases: Build (arrange), Operate (act), Check (assert). This pattern makes tests easy to read and understand at a glance.
+
+**Incorrect (mixed phases, unclear structure):**
+
+```java
+@Test
+public void testOrder() {
+    Order order = new Order();
+    assertTrue(order.isEmpty());
+    Product product = new Product("Widget", 9.99);
+    order.add(product);
+    assertEquals(1, order.getItemCount());
+    assertEquals(9.99, order.getTotal(), 0.01);
+    order.add(product);
+    assertEquals(2, order.getItemCount());
+    assertEquals(19.98, order.getTotal(), 0.01);
+}
+```
+
+**Correct (clear Build-Operate-Check):**
+
+```java
+@Test
+public void addingProductShouldIncreaseItemCount() {
+    // Build
+    Order order = new Order();
+    Product widget = new Product("Widget", 9.99);
+
+    // Operate
+    order.add(widget);
+
+    // Check
+    assertEquals(1, order.getItemCount());
+}
+
+@Test
+public void addingProductShouldUpdateTotal() {
+    // Build
+    Order order = new Order();
+    Product widget = new Product("Widget", 9.99);
+
+    // Operate
+    order.add(widget);
+
+    // Check
+    assertEquals(9.99, order.getTotal(), 0.01);
+}
+
+@Test
+public void addingSameProductTwiceShouldDoubleTotal() {
+    // Build
+    Order order = new Order();
+    Product widget = new Product("Widget", 9.99);
+
+    // Operate
+    order.add(widget);
+    order.add(widget);
+
+    // Check
+    assertEquals(19.98, order.getTotal(), 0.01);
+}
+```
+
+**Alias patterns:**
+- Build-Operate-Check (BOC)
+- Arrange-Act-Assert (AAA)
+- Given-When-Then (BDD)
+
+Reference: [Clean Code, Chapter 9: Unit Tests](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/test-first-law.md b/builtin-skills/software-engineer/clean-code/references/test-first-law.md
new file mode 100644
index 00000000..ff0de141
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/test-first-law.md
@@ -0,0 +1,68 @@
+---
+title: Follow the Three Laws of TDD
+impact: MEDIUM
+impactDescription: achieves 90%+ test coverage naturally
+tags: test, tdd, first, laws
+---
+
+## Follow the Three Laws of TDD
+
+Test-Driven Development follows three rules: (1) Write a failing test before production code, (2) Write only enough test to fail, (3) Write only enough production code to pass. This cycle repeats.
+
+**Incorrect (writing tests after code):**
+
+```java
+// Production code written first, then tests added later (or never)
+public class Calculator {
+    public int add(int a, int b) {
+        return a + b;
+    }
+
+    public int divide(int a, int b) {
+        return a / b;  // Edge cases not considered
+    }
+}
+
+// Test written after - may not cover edge cases
+@Test
+public void testAdd() {
+    assertEquals(4, calculator.add(2, 2));
+}
+// No test for divide by zero because code was written first
+```
+
+**Correct (TDD cycle):**
+
+```java
+// 1. Write failing test first
+@Test
+public void divideShouldReturnQuotient() {
+    assertEquals(2, calculator.divide(6, 3));
+}
+
+// 2. Write minimal code to pass
+public int divide(int a, int b) {
+    return a / b;
+}
+
+// 3. Write next failing test
+@Test(expected = IllegalArgumentException.class)
+public void divideShouldThrowOnDivideByZero() {
+    calculator.divide(6, 0);
+}
+
+// 4. Update code to pass
+public int divide(int a, int b) {
+    if (b == 0) {
+        throw new IllegalArgumentException("Cannot divide by zero");
+    }
+    return a / b;
+}
+```
+
+**Benefits:**
+- Tests cover requirements, not implementation
+- Edge cases discovered through test-first thinking
+- High coverage achieved naturally
+
+Reference: [Clean Code, Chapter 9: Unit Tests](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/test-first-principles.md b/builtin-skills/software-engineer/clean-code/references/test-first-principles.md
new file mode 100644
index 00000000..d75996a4
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/test-first-principles.md
@@ -0,0 +1,80 @@
+---
+title: Follow FIRST Principles
+impact: MEDIUM
+impactDescription: prevents test suite from becoming 10× slower over time
+tags: test, first, fast, independent, repeatable
+---
+
+## Follow FIRST Principles
+
+Clean tests follow FIRST: Fast, Independent, Repeatable, Self-Validating, and Timely. These properties ensure tests remain useful and maintainable.
+
+**Incorrect (violating FIRST):**
+
+```java
+// Slow - depends on real database
+@Test
+public void testUserQuery() {
+    Connection conn = DriverManager.getConnection(PROD_DB_URL);  // Slow!
+    // ...
+}
+
+// Not Independent - tests depend on each other
+private static User sharedUser;
+
+@Test
+public void test1CreateUser() {
+    sharedUser = userService.create("bob");
+}
+
+@Test
+public void test2UpdateUser() {
+    sharedUser.setName("alice");  // Depends on test1 running first
+}
+
+// Not Repeatable - depends on external state
+@Test
+public void testPayment() {
+    assertTrue(paymentGateway.charge(card, 100));  // Different result each time
+}
+```
+
+**Correct (following FIRST):**
+
+```java
+// Fast - uses mocks, runs in milliseconds
+@Test
+public void queryShouldReturnMatchingUsers() {
+    UserRepository repo = mock(UserRepository.class);
+    when(repo.findByName("bob")).thenReturn(List.of(testUser));
+
+    List<User> result = userService.query("bob");
+
+    assertEquals(1, result.size());
+}
+
+// Independent - each test sets up its own state
+@Test
+public void createShouldReturnNewUser() {
+    User user = userService.create("bob");
+    assertEquals("bob", user.getName());
+}
+
+@Test
+public void updateShouldModifyUserName() {
+    User user = userService.create("bob");
+    user.setName("alice");
+    assertEquals("alice", user.getName());
+}
+
+// Repeatable - uses test doubles
+@Test
+public void chargeShouldReturnTrueOnSuccess() {
+    PaymentGateway gateway = mock(PaymentGateway.class);
+    when(gateway.charge(any(), eq(100))).thenReturn(true);
+
+    assertTrue(paymentService.processPayment(100));
+}
+```
+
+Reference: [Clean Code, Chapter 9: Unit Tests](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/test-keep-clean.md b/builtin-skills/software-engineer/clean-code/references/test-keep-clean.md
new file mode 100644
index 00000000..332f92e2
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/test-keep-clean.md
@@ -0,0 +1,75 @@
+---
+title: Keep Tests Clean
+impact: MEDIUM
+impactDescription: maintains test maintainability over time
+tags: test, clean, maintainability, quality
+---
+
+## Keep Tests Clean
+
+Test code is just as important as production code. It requires thought, design, and care. If you let tests rot, they become a liability instead of an asset.
+
+**Incorrect (dirty tests):**
+
+```java
+@Test
+public void test1() {
+    // Cryptic, no clear purpose
+    S s = new S();
+    s.a("x");
+    s.b("y");
+    assertTrue(s.c());
+    s.d();
+    assertEquals("xy", s.e());
+}
+
+@Test
+public void testEverything() {
+    // Multiple assertions testing different concepts
+    assertNotNull(user);
+    assertEquals("Bob", user.getName());
+    assertTrue(user.isActive());
+    assertEquals(3, user.getOrders().size());
+    assertTrue(user.getOrders().get(0).isPaid());
+}
+```
+
+**Correct (clean, readable tests):**
+
+```java
+@Test
+public void concatenatingTwoStringsShouldReturnCombinedResult() {
+    StringBuffer buffer = new StringBuffer();
+
+    buffer.append("first");
+    buffer.append("second");
+
+    assertEquals("firstsecond", buffer.toString());
+}
+
+@Test
+public void userShouldBeActiveAfterActivation() {
+    User user = new User("Bob");
+
+    user.activate();
+
+    assertTrue(user.isActive());
+}
+
+@Test
+public void activatingUserShouldSendWelcomeEmail() {
+    User user = new User("Bob");
+    EmailService emailService = mock(EmailService.class);
+
+    user.activate(emailService);
+
+    verify(emailService).sendWelcome(user.getEmail());
+}
+```
+
+**Qualities of clean tests:**
+- Readable: Clear setup, action, assertion
+- One concept per test
+- Descriptive names explaining what is being tested
+
+Reference: [Clean Code, Chapter 9: Unit Tests](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-code/references/test-one-assert.md b/builtin-skills/software-engineer/clean-code/references/test-one-assert.md
new file mode 100644
index 00000000..84e9ad45
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-code/references/test-one-assert.md
@@ -0,0 +1,65 @@
+---
+title: One Concept Per Test
+impact: MEDIUM
+impactDescription: enables precise failure diagnosis
+tags: test, assert, concept, focus
+---
+
+## One Concept Per Test
+
+Each test should verify a single concept or behavior. Multiple assertions are fine when they all verify different aspects of that one concept. What you want to avoid is testing unrelated concerns in a single test.
+
+**Incorrect (multiple unrelated concepts in one test):**
+
+```java
+@Test
+public void testUserRegistration() {
+    User user = userService.register("bob@example.com", "password123");
+
+    // Concept 1: user creation
+    assertNotNull(user);
+    assertNotNull(user.getId());
+
+    // Concept 2: email notification (unrelated to creation details)
+    verify(emailService).sendWelcome("bob@example.com");
+
+    // Concept 3: repository state (separate concern)
+    assertEquals(1, userRepository.count());
+}
+// If this fails, which concept is broken? Creation? Email? Persistence?
+```
+
+**Correct (one concept per test, multiple assertions are fine):**
+
+```java
+@Test
+public void registerShouldCreateActiveUserWithGeneratedId() {
+    User user = userService.register("bob@example.com", "password123");
+
+    assertNotNull(user.getId());
+    assertEquals("bob@example.com", user.getEmail());
+    assertTrue(user.isActive());
+}
+
+@Test
+public void registerShouldSendWelcomeEmail() {
+    userService.register("bob@example.com", "password123");
+
+    verify(emailService).sendWelcome("bob@example.com");
+}
+
+@Test
+public void registerShouldPersistUser() {
+    userService.register("bob@example.com", "password123");
+
+    assertEquals(1, userRepository.count());
+}
+```
+
+The first test has three assertions — that's fine because they all verify a single concept: "the returned user object is correctly constructed." Each test can be understood from its name alone.
+
+**When NOT to split tests:**
+- When multiple assertions verify the same behavior from different angles (like checking all fields of a returned object), keep them together — splitting creates duplicate setup and slower test suites.
+- When the operation under test has side effects (API calls, DB writes), avoid calling it multiple times just to isolate assertions.
+
+Reference: [Clean Code, Chapter 9: Unit Tests](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
diff --git a/builtin-skills/software-engineer/clean-comments/SKILL.md b/builtin-skills/software-engineer/clean-comments/SKILL.md
new file mode 100644
index 00000000..e7375f78
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-comments/SKILL.md
@@ -0,0 +1,52 @@
+---
+name: clean-comments
+description: Use when writing, fixing, editing, or reviewing Python comments and docstrings. Enforces Clean Code principles—no metadata, no redundancy, no commented-out code.
+---
+
+# Clean Comments
+
+## C1: No Inappropriate Information
+
+Comments shouldn't hold metadata. Use Git for author names, change history, 
+ticket numbers, and dates. Comments are for technical notes about code only.
+
+## C2: Delete Obsolete Comments
+
+If a comment describes code that no longer exists or works differently, 
+delete it immediately. Stale comments become "floating islands of 
+irrelevance and misdirection."
+
+## C3: No Redundant Comments
+
+```python
+# Bad - the code already says this
+i += 1  # increment i
+user.save()  # save the user
+
+# Good - explains WHY, not WHAT
+i += 1  # compensate for zero-indexing in display
+```
+
+## C4: Write Comments Well
+
+If a comment is worth writing, write it well:
+- Choose words carefully
+- Use correct grammar
+- Don't ramble or state the obvious
+- Be brief
+
+## C5: Never Commit Commented-Out Code
+
+```python
+# DELETE THIS - it's an abomination
+# def old_calculate_tax(income):
+#     return income * 0.15
+```
+
+Who knows how old it is? Who knows if it's meaningful? Delete it. 
+Git remembers everything.
+
+## The Goal
+
+The best comment is the code itself. If you need a comment to explain 
+what code does, refactor first, comment last.
diff --git a/builtin-skills/software-engineer/clean-functions/SKILL.md b/builtin-skills/software-engineer/clean-functions/SKILL.md
new file mode 100644
index 00000000..b3f1a32c
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-functions/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: clean-functions
+description: Use when writing, fixing, editing, or refactoring Python functions. Enforces Clean Code principles—maximum 3 arguments, single responsibility, no flag parameters.
+---
+
+# Clean Functions
+
+## F1: Too Many Arguments (Maximum 3)
+
+```python
+# Bad - too many parameters
+def create_user(name, email, age, country, timezone, language, newsletter):
+    ...
+
+# Good - use a dataclass or dict
+@dataclass
+class UserData:
+    name: str
+    email: str
+    age: int
+    country: str
+    timezone: str
+    language: str
+    newsletter: bool
+
+def create_user(data: UserData):
+    ...
+```
+
+More than 3 arguments means your function is doing too much or needs 
+a data structure.
+
+## F2: No Output Arguments
+
+Don't modify arguments as side effects. Return values instead.
+
+```python
+# Bad - modifies argument
+def append_footer(report: Report) -> None:
+    report.append("\n---\nGenerated by System")
+
+# Good - returns new value
+def with_footer(report: Report) -> Report:
+    return report + "\n---\nGenerated by System"
+```
+
+## F3: No Flag Arguments
+
+Boolean flags mean your function does at least two things.
+
+```python
+# Bad - function does two different things
+def render(is_test: bool):
+    if is_test:
+        render_test_page()
+    else:
+        render_production_page()
+
+# Good - split into two functions
+def render_test_page(): ...
+def render_production_page(): ...
+```
+
+## F4: Delete Dead Functions
+
+If it's not called, delete it. No "just in case" code. Git preserves history.
diff --git a/builtin-skills/software-engineer/clean-general/SKILL.md b/builtin-skills/software-engineer/clean-general/SKILL.md
new file mode 100644
index 00000000..099a3e68
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-general/SKILL.md
@@ -0,0 +1,97 @@
+---
+name: clean-general
+description: Use when writing, fixing, editing, or reviewing Python code quality. Enforces Clean Code's core principles—DRY, single responsibility, clear intent, no magic numbers, proper abstractions.
+---
+
+# General Clean Code Principles
+
+## Critical Rules
+
+**G5: DRY (Don't Repeat Yourself)**
+
+Every piece of knowledge has one authoritative representation.
+
+```python
+# Bad - duplication
+tax_rate = 0.0825
+ca_total = subtotal * 1.0825
+ny_total = subtotal * 1.07
+
+# Good - single source of truth
+TAX_RATES = {"CA": 0.0825, "NY": 0.07}
+def calculate_total(subtotal: float, state: str) -> float:
+    return subtotal * (1 + TAX_RATES[state])
+```
+
+**G16: No Obscured Intent**
+
+Don't be clever. Be clear.
+
+```python
+# Bad - what does this do?
+return (x & 0x0F) << 4 | (y & 0x0F)
+
+# Good - obvious intent
+return pack_coordinates(x, y)
+```
+
+**G23: Prefer Polymorphism to If/Else**
+
+```python
+# Bad - will grow forever
+def calculate_pay(employee):
+    if employee.type == "SALARIED":
+        return employee.salary
+    elif employee.type == "HOURLY":
+        return employee.hours * employee.rate
+    elif employee.type == "COMMISSIONED":
+        return employee.base + employee.commission
+
+# Good - open/closed principle
+class SalariedEmployee:
+    def calculate_pay(self): return self.salary
+
+class HourlyEmployee:
+    def calculate_pay(self): return self.hours * self.rate
+
+class CommissionedEmployee:
+    def calculate_pay(self): return self.base + self.commission
+```
+
+**G25: Replace Magic Numbers with Named Constants**
+
+```python
+# Bad
+if elapsed_time > 86400:
+    ...
+
+# Good
+SECONDS_PER_DAY = 86400
+if elapsed_time > SECONDS_PER_DAY:
+    ...
+```
+
+**G30: Functions Should Do One Thing**
+
+If you can extract another function, your function does more than one thing.
+
+**G36: Law of Demeter (Avoid Train Wrecks)**
+
+```python
+# Bad - reaching through multiple objects
+output_dir = context.options.scratch_dir.absolute_path
+
+# Good - one dot
+output_dir = context.get_scratch_dir()
+```
+
+## Enforcement Checklist
+
+When reviewing AI-generated code, verify:
+- [ ] No duplication (G5)
+- [ ] Clear intent, no magic numbers (G16, G25)
+- [ ] Polymorphism over conditionals (G23)
+- [ ] Functions do one thing (G30)
+- [ ] No Law of Demeter violations (G36)
+- [ ] Boundary conditions handled (G3)
+- [ ] Dead code removed (G9)
diff --git a/builtin-skills/software-engineer/clean-names/SKILL.md b/builtin-skills/software-engineer/clean-names/SKILL.md
new file mode 100644
index 00000000..970d8e40
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-names/SKILL.md
@@ -0,0 +1,136 @@
+---
+name: clean-names
+description: Use when naming, renaming, or fixing names of variables, functions, classes, or modules in Python. Enforces Clean Code principles—descriptive names, appropriate length, no encodings.
+---
+
+# Clean Names
+
+## N1: Choose Descriptive Names
+
+Names should reveal intent. If a name requires a comment, it doesn't reveal its intent.
+
+```python
+# Bad - what is d?
+d = 86400
+
+# Good - obvious meaning
+SECONDS_PER_DAY = 86400
+
+# Bad - what does this function do?
+def proc(lst):
+    return [x for x in lst if x > 0]
+
+# Good - intent is clear
+def filter_positive_numbers(numbers):
+    return [n for n in numbers if n > 0]
+```
+
+## N2: Choose Names at the Appropriate Level of Abstraction
+
+Don't pick names that communicate implementation; choose names that reflect the level of abstraction of the class or function.
+
+```python
+# Bad - too implementation-specific
+def get_dict_of_user_ids_to_names():
+    ...
+
+# Good - abstracts the data structure
+def get_user_directory():
+    ...
+```
+
+## N3: Use Standard Nomenclature Where Possible
+
+Use terms from the domain, design patterns, or well-known conventions.
+
+```python
+# Good - uses pattern name
+class UserFactory:
+    def create(self, data): ...
+
+# Good - uses domain term
+def calculate_amortization(principal, rate, term): ...
+```
+
+## N4: Unambiguous Names
+
+Choose names that make the workings of a function or variable unambiguous.
+
+```python
+# Bad - ambiguous
+def rename(old, new):
+    ...
+
+# Good - clear what's being renamed
+def rename_file(old_path: Path, new_path: Path):
+    ...
+```
+
+## N5: Use Longer Names for Longer Scopes
+
+Short names are fine for tiny scopes. Longer scopes need longer, more descriptive names.
+
+```python
+# Good - short name for tiny scope
+total = sum(x for x in numbers)
+
+# Good - longer name for module-level constant
+MAX_RETRY_ATTEMPTS_BEFORE_FAILURE = 5
+
+# Bad - short name at module level
+MAX = 5
+```
+
+## N6: Avoid Encodings
+
+Don't encode type or scope information into names. Modern editors make this unnecessary.
+
+```python
+# Bad - Hungarian notation
+str_name = "Alice"
+lst_users = []
+i_count = 0
+
+# Good - clean names
+name = "Alice"
+users = []
+count = 0
+
+# Bad - interface prefix
+class IUserRepository:
+    ...
+
+# Good - just name it
+class UserRepository:
+    ...
+```
+
+## N7: Names Should Describe Side Effects
+
+If a function does something beyond what its name suggests, the name is misleading.
+
+```python
+# Bad - name doesn't mention file creation
+def get_config():
+    if not config_path.exists():
+        config_path.write_text("{}")  # Hidden side effect!
+    return json.loads(config_path.read_text())
+
+# Good - name reveals behavior
+def get_or_create_config():
+    if not config_path.exists():
+        config_path.write_text("{}")
+    return json.loads(config_path.read_text())
+```
+
+## Quick Reference
+
+| Rule | Principle | Example |
+|------|-----------|---------|
+| N1 | Descriptive names | `SECONDS_PER_DAY` not `d` |
+| N2 | Right abstraction level | `get_user_directory()` not `get_dict_of_...` |
+| N3 | Standard nomenclature | `UserFactory`, `calculate_amortization` |
+| N4 | Unambiguous | `rename_file(old_path, new_path)` |
+| N5 | Length matches scope | Short for loops, long for globals |
+| N6 | No encodings | `users` not `lst_users` |
+| N7 | Describe side effects | `get_or_create_config()` |
diff --git a/builtin-skills/software-engineer/clean-tests/SKILL.md b/builtin-skills/software-engineer/clean-tests/SKILL.md
new file mode 100644
index 00000000..b06d8671
--- /dev/null
+++ b/builtin-skills/software-engineer/clean-tests/SKILL.md
@@ -0,0 +1,196 @@
+---
+name: clean-tests
+description: Use when writing, fixing, editing, or refactoring Python tests. Enforces Clean Code principles—fast tests, boundary coverage, one assert per test.
+---
+
+# Clean Tests
+
+## T1: Insufficient Tests
+
+Test everything that could possibly break. Use coverage tools as a guide, not a goal.
+
+```python
+# Bad - only tests happy path
+def test_divide():
+    assert divide(10, 2) == 5
+
+# Good - tests edge cases too
+def test_divide_normal():
+    assert divide(10, 2) == 5
+
+def test_divide_by_zero():
+    with pytest.raises(ZeroDivisionError):
+        divide(10, 0)
+
+def test_divide_negative():
+    assert divide(-10, 2) == -5
+```
+
+## T2: Use a Coverage Tool
+
+Coverage tools report gaps in your testing strategy. Don't ignore them.
+
+```bash
+# Run with coverage
+pytest --cov=myproject --cov-report=term-missing
+
+# Aim for meaningful coverage, not 100%
+```
+
+## T3: Don't Skip Trivial Tests
+
+Trivial tests document behavior and catch regressions. They're worth more than their cost.
+
+```python
+# Worth having - documents expected behavior
+def test_user_default_role():
+    user = User(name="Alice")
+    assert user.role == "member"
+```
+
+## T4: An Ignored Test Is a Question About an Ambiguity
+
+Don't use `@pytest.mark.skip` to hide problems. Either fix the test or delete it.
+
+```python
+# Bad - hiding a problem
+@pytest.mark.skip(reason="flaky, fix later")
+def test_async_operation():
+    ...
+
+# Good - either fix it or document why it's skipped
+@pytest.mark.skip(reason="Requires Redis, see CONTRIBUTING.md for setup")
+def test_cache_invalidation():
+    ...
+```
+
+## T5: Test Boundary Conditions
+
+Bugs congregate at boundaries. Test them explicitly.
+
+```python
+def test_pagination_boundaries():
+    items = list(range(100))
+    
+    # First page
+    assert paginate(items, page=1, size=10) == items[0:10]
+    
+    # Last page
+    assert paginate(items, page=10, size=10) == items[90:100]
+    
+    # Beyond last page
+    assert paginate(items, page=11, size=10) == []
+    
+    # Page zero (invalid)
+    with pytest.raises(ValueError):
+        paginate(items, page=0, size=10)
+    
+    # Empty list
+    assert paginate([], page=1, size=10) == []
+```
+
+## T6: Exhaustively Test Near Bugs
+
+When you find a bug, write tests for all similar cases. Bugs cluster.
+
+```python
+# Found bug: off-by-one in date calculation
+# Now test ALL date boundaries
+def test_month_boundaries():
+    assert last_day_of_month(2024, 1) == 31  # January
+    assert last_day_of_month(2024, 2) == 29  # Leap year February
+    assert last_day_of_month(2023, 2) == 28  # Non-leap February
+    assert last_day_of_month(2024, 4) == 30  # 30-day month
+    assert last_day_of_month(2024, 12) == 31 # December
+```
+
+## T7: Patterns of Failure Are Revealing
+
+When tests fail, look for patterns. They often point to deeper issues.
+
+```python
+# If all async tests fail intermittently,
+# the problem isn't the tests—it's the async handling
+```
+
+## T8: Test Coverage Patterns Can Be Revealing
+
+Look at which code paths are untested. Often they reveal design problems.
+
+```python
+# If you can't easily test a function, it probably does too much
+# Refactor for testability
+```
+
+## T9: Tests Should Be Fast
+
+Slow tests don't get run. Keep unit tests under 100ms each.
+
+```python
+# Bad - hits real database
+def test_user_creation():
+    db = connect_to_database()  # Slow!
+    user = db.create_user("Alice")
+    assert user.name == "Alice"
+
+# Good - uses mock or in-memory
+def test_user_creation():
+    db = InMemoryDatabase()
+    user = db.create_user("Alice")
+    assert user.name == "Alice"
+```
+
+## Test Organization
+
+### F.I.R.S.T. Principles
+
+- **Fast**: Tests should run quickly
+- **Independent**: Tests shouldn't depend on each other
+- **Repeatable**: Same result every time, any environment
+- **Self-Validating**: Pass or fail, no manual inspection
+- **Timely**: Written before or with the code, not after
+
+### One Concept Per Test
+
+```python
+# Bad - testing multiple things
+def test_user():
+    user = User("Alice", "alice@example.com")
+    assert user.name == "Alice"
+    assert user.email == "alice@example.com"
+    assert user.is_valid()
+    user.activate()
+    assert user.is_active
+
+# Good - one concept each
+def test_user_stores_name():
+    user = User("Alice", "alice@example.com")
+    assert user.name == "Alice"
+
+def test_user_stores_email():
+    user = User("Alice", "alice@example.com")
+    assert user.email == "alice@example.com"
+
+def test_new_user_is_valid():
+    user = User("Alice", "alice@example.com")
+    assert user.is_valid()
+
+def test_user_can_be_activated():
+    user = User("Alice", "alice@example.com")
+    user.activate()
+    assert user.is_active
+```
+
+## Quick Reference
+
+| Rule | Principle |
+|------|-----------|
+| T1 | Test everything that could break |
+| T2 | Use coverage tools |
+| T3 | Don't skip trivial tests |
+| T4 | Ignored test = ambiguity question |
+| T5 | Test boundary conditions |
+| T6 | Exhaustively test near bugs |
+| T7 | Look for patterns in failures |
+| T8 | Check coverage when debugging |
+| T9 | Tests must be fast (<100ms) |
diff --git a/builtin-skills/software-engineer/coding-guidelines/SKILL.md b/builtin-skills/software-engineer/coding-guidelines/SKILL.md
new file mode 100644
index 00000000..4a505f48
--- /dev/null
+++ b/builtin-skills/software-engineer/coding-guidelines/SKILL.md
@@ -0,0 +1,95 @@
+---
+name: coding-guidelines
+description: "Use when asking about Rust code style or best practices. Keywords: naming, formatting, comment, clippy, rustfmt, lint, code style, best practice, P.NAM, G.FMT, code review, naming convention, variable naming, function naming, type naming, 命名规范, 代码风格, 格式化, 最佳实践, 代码审查, 怎么命名"
+source: https://rust-coding-guidelines.github.io/rust-coding-guidelines-zh/
+user-invocable: false
+---
+
+# Rust Coding Guidelines (50 Core Rules)
+
+## Naming (Rust-Specific)
+
+| Rule | Guideline |
+|------|-----------|
+| No `get_` prefix | `fn name()` not `fn get_name()` |
+| Iterator convention | `iter()` / `iter_mut()` / `into_iter()` |
+| Conversion naming | `as_` (cheap &), `to_` (expensive), `into_` (ownership) |
+| Static var prefix | `G_CONFIG` for `static`, no prefix for `const` |
+
+## Data Types
+
+| Rule | Guideline |
+|------|-----------|
+| Use newtypes | `struct Email(String)` for domain semantics |
+| Prefer slice patterns | `if let [first, .., last] = slice` |
+| Pre-allocate | `Vec::with_capacity()`, `String::with_capacity()` |
+| Avoid Vec abuse | Use arrays for fixed sizes |
+
+## Strings
+
+| Rule | Guideline |
+|------|-----------|
+| Prefer bytes | `s.bytes()` over `s.chars()` when ASCII |
+| Use `Cow<str>` | When might modify borrowed data |
+| Use `format!` | Over string concatenation with `+` |
+| Avoid nested iteration | `contains()` on string is O(n*m) |
+
+## Error Handling
+
+| Rule | Guideline |
+|------|-----------|
+| Use `?` propagation | Not `try!()` macro |
+| `expect()` over `unwrap()` | When value guaranteed |
+| Assertions for invariants | `assert!` at function entry |
+
+## Memory
+
+| Rule | Guideline |
+|------|-----------|
+| Meaningful lifetimes | `'src`, `'ctx` not just `'a` |
+| `try_borrow()` for RefCell | Avoid panic |
+| Shadowing for transformation | `let x = x.parse()?` |
+
+## Concurrency
+
+| Rule | Guideline |
+|------|-----------|
+| Identify lock ordering | Prevent deadlocks |
+| Atomics for primitives | Not Mutex for bool/usize |
+| Choose memory order carefully | Relaxed/Acquire/Release/SeqCst |
+
+## Async
+
+| Rule | Guideline |
+|------|-----------|
+| Sync for CPU-bound | Async is for I/O |
+| Don't hold locks across await | Use scoped guards |
+
+## Macros
+
+| Rule | Guideline |
+|------|-----------|
+| Avoid unless necessary | Prefer functions/generics |
+| Follow Rust syntax | Macro input should look like Rust |
+
+## Deprecated → Better
+
+| Deprecated | Better | Since |
+|------------|--------|-------|
+| `lazy_static!` | `std::sync::OnceLock` | 1.70 |
+| `once_cell::Lazy` | `std::sync::LazyLock` | 1.80 |
+| `std::sync::mpsc` | `crossbeam::channel` | - |
+| `std::sync::Mutex` | `parking_lot::Mutex` | - |
+| `failure`/`error-chain` | `thiserror`/`anyhow` | - |
+| `try!()` | `?` operator | 2018 |
+
+## Quick Reference
+
+```
+Naming: snake_case (fn/var), CamelCase (type), SCREAMING_CASE (const)
+Format: rustfmt (just use it)
+Docs: /// for public items, //! for module docs
+Lint: #![warn(clippy::all)]
+```
+
+Claude knows Rust conventions well. These are the non-obvious Rust-specific rules.
diff --git a/builtin-skills/software-engineer/coding-guidelines/clippy-lints/_index.md b/builtin-skills/software-engineer/coding-guidelines/clippy-lints/_index.md
new file mode 100644
index 00000000..74816071
--- /dev/null
+++ b/builtin-skills/software-engineer/coding-guidelines/clippy-lints/_index.md
@@ -0,0 +1,16 @@
+# Clippy Lint → Rule Mapping
+
+| Clippy Lint | Category | Fix |
+|-------------|----------|-----|
+| `unwrap_used` | Error | Use `?` or `expect()` |
+| `needless_clone` | Perf | Use reference |
+| `await_holding_lock` | Async | Scope guard before await |
+| `linkedlist` | Perf | Use Vec/VecDeque |
+| `wildcard_imports` | Style | Explicit imports |
+| `missing_safety_doc` | Safety | Add `# Safety` doc |
+| `undocumented_unsafe_blocks` | Safety | Add `// SAFETY:` |
+| `transmute_ptr_to_ptr` | Safety | Use `pointer::cast()` |
+| `large_stack_arrays` | Mem | Use Vec or Box |
+| `too_many_arguments` | Design | Use struct params |
+
+For unsafe-related lints → see `unsafe-checker` skill.
diff --git a/builtin-skills/software-engineer/coding-guidelines/index/rules-index.md b/builtin-skills/software-engineer/coding-guidelines/index/rules-index.md
new file mode 100644
index 00000000..14242727
--- /dev/null
+++ b/builtin-skills/software-engineer/coding-guidelines/index/rules-index.md
@@ -0,0 +1,6 @@
+# Complete Rules Reference
+
+For the full 500+ rules, see:
+- Source: https://rust-coding-guidelines.github.io/rust-coding-guidelines-zh/
+
+Core rules are in `../SKILL.md`.
diff --git a/builtin-skills/software-engineer/ddia-principles/SKILL.md b/builtin-skills/software-engineer/ddia-principles/SKILL.md
new file mode 100644
index 00000000..67e6bf11
--- /dev/null
+++ b/builtin-skills/software-engineer/ddia-principles/SKILL.md
@@ -0,0 +1,421 @@
+---
+name: ddia-principles
+description: >
+  Designing Data-Intensive Applications (DDIA) distilled reference guide by Martin Kleppmann.
+  MUST be loaded when: designing database schemas, choosing storage engines, implementing replication
+  or partitioning, handling distributed transactions, building batch/stream processing pipelines,
+  choosing consistency models, implementing consensus, designing data flow architectures,
+  evaluating trade-offs between availability and consistency, encoding/serialization decisions,
+  data modeling (relational vs document vs graph), building fault-tolerant systems, or any
+  system design and architecture discussion involving data-intensive applications.
+  Trigger on: database design, replication, partitioning, sharding, transactions, isolation levels,
+  consistency, consensus, CAP theorem, batch processing, stream processing, MapReduce, Kafka,
+  event sourcing, CDC, OLTP, OLAP, B-tree, LSM-tree, data warehouse, schema evolution,
+  encoding formats, distributed systems, fault tolerance, leader election, quorum.
+---
+
+# Designing Data-Intensive Applications — Distilled Guide
+
+> Source: Martin Kleppmann, *Designing Data-Intensive Applications*
+> Central thesis: **Data is the core challenge of modern applications — not compute.**
+
+---
+
+## Part I: Foundations of Data Systems
+
+### Chapter 1: Reliability, Scalability, Maintainability
+
+#### Three Pillars
+
+| Pillar | Definition | Key Metric |
+|--------|-----------|------------|
+| **Reliability** | System works correctly even when faults occur | Fault ≠ Failure; tolerate faults, prevent failures |
+| **Scalability** | System handles load growth gracefully | Measure with percentiles: p50, p95, p99, p999 |
+| **Maintainability** | System is easy to operate, understand, evolve | Operability + Simplicity + Evolvability |
+
+#### Fault Categories
+- **Hardware**: Random, independent (disk, RAM, power). Mitigate with redundancy (RAID, dual power).
+- **Software**: Systematic bugs affecting all nodes simultaneously (leap-second bug). Mitigate with process isolation, monitoring, chaos engineering.
+- **Human**: #1 cause of outages (config errors). Mitigate with good abstractions, sandboxes, canary deployments, fast rollback.
+
+#### Scalability Patterns
+- **Vertical (scale-up)**: Bigger machine. Simple but has ceiling.
+- **Horizontal (scale-out)**: More machines (shared-nothing). Complex but unlimited.
+- **Elastic**: Auto-scale on load detection. Good for unpredictable workloads.
+
+**Twitter fan-out case study**: 4.6k writes/s but 300k reads/s. Solution: pre-compute timelines (write fan-out) for most users; read-time merge for celebrities.
+
+#### Performance: Use Percentiles, Not Averages
+- p50 = median. p99 = tail latency matters for user experience.
+- Amazon: 100ms delay = 1% revenue loss.
+- **Tail latency amplification**: One slow backend call slows entire parallel request.
+
+---
+
+### Chapter 2: Data Models & Query Languages
+
+#### Model Selection Guide
+
+| Model | Best For | Weakness |
+|-------|----------|----------|
+| **Relational** | Structured data, complex joins, ACID transactions | Rigid schema, impedance mismatch with OOP |
+| **Document** | Hierarchical data, flexible schema, data locality | Poor joins, many-to-many relationships |
+| **Graph** | Highly connected data, variable-depth traversals | Less mature tooling, harder to partition |
+
+#### Schema Strategy
+- **Schema-on-write** (relational): Enforce structure at write time. Early error detection, migration cost.
+- **Schema-on-read** (document): Interpret structure at read time. Flexible but validation burden on app.
+
+#### Normalization vs Denormalization
+- **Normalize**: Single source of truth, consistent updates, requires joins.
+- **Denormalize**: Faster reads, risks inconsistency, update anomalies.
+
+**Trend**: Models converge — PostgreSQL supports JSON, MongoDB added joins. Choose based on access patterns, not ideology.
+
+---
+
+### Chapter 3: Storage & Retrieval
+
+#### Storage Engine Comparison
+
+| Feature | B-Tree | LSM-Tree |
+|---------|--------|----------|
+| Write throughput | Lower (in-place update + WAL) | Higher (sequential append) |
+| Read latency | More predictable | May check multiple SSTables |
+| Write amplification | Higher | Lower |
+| Space efficiency | Fragmentation possible | Better compression |
+| Transaction support | Simpler (lock on tree node) | More complex |
+| Used by | PostgreSQL, MySQL, Oracle | LevelDB, RocksDB, Cassandra |
+
+#### OLTP vs OLAP
+
+| Aspect | OLTP | OLAP |
+|--------|------|------|
+| Access | Random, few records | Sequential scan, millions of rows |
+| Users | End users | Analysts |
+| Data | Current state | Historical events |
+| Scale | GB–TB | TB–PB |
+| Optimize for | Low latency | Throughput |
+
+#### Data Warehousing
+- **ETL**: Extract from OLTP → Transform → Load into warehouse.
+- **Star schema**: Central fact table (events) + dimension tables (attributes). Fact tables can have 100+ columns and petabyte scale.
+- **Column-oriented storage**: Store each column separately. Huge I/O savings when queries touch few columns. Enables bitmap encoding, run-length compression, vectorized processing.
+
+---
+
+### Chapter 4: Encoding & Evolution
+
+#### Format Comparison
+
+| Format | Size (example) | Schema | Evolution | Cross-language |
+|--------|---------------|--------|-----------|----------------|
+| JSON | 81 bytes | Implicit | Manual | Excellent |
+| Thrift | 59 bytes | Required | Field tags | Good |
+| Protobuf | 33 bytes | Required | Field tags | Excellent |
+| Avro | 32 bytes | Required | Name matching | Good |
+
+#### Compatibility Rules
+- **Backward compatible**: New code reads old data. *(Always required)*
+- **Forward compatible**: Old code reads new data. *(Required for rolling upgrades)*
+- Rule: Only add/remove fields with default values. Never reuse deleted field tags.
+
+#### Data Flow Patterns
+1. **Via databases**: Multiple code versions coexist during rolling deploys. Data outlives code.
+2. **Via services (REST/RPC)**: Servers update before clients. Backward compat on requests, forward compat on responses.
+3. **Via async messaging**: Decouples producers/consumers. Supports independent version evolution.
+
+**Avoid**: Language-specific serialization (Java Serializable, Python pickle) — vendor lock-in + security risk.
+
+---
+
+## Part II: Distributed Data
+
+### Chapter 5: Replication
+
+#### Replication Models
+
+| Model | Writes | Conflict | Use Case |
+|-------|--------|----------|----------|
+| **Single-leader** | One node | None | Most common (PostgreSQL, MySQL) |
+| **Multi-leader** | Multiple nodes | Must resolve | Multi-datacenter, offline clients |
+| **Leaderless** | Any node | Must resolve | Cassandra, Riak, Voldemort |
+
+#### Sync vs Async Replication
+- **Sync**: Durable, blocks on replica failure.
+- **Async**: Fast, risks data loss on leader failure.
+- **Semi-sync**: One replica sync, rest async. Practical compromise.
+
+#### Replication Lag Problems & Solutions
+
+| Problem | Symptom | Solution |
+|---------|---------|----------|
+| **Read-after-write** | User doesn't see own write | Read from leader for user's own data |
+| **Monotonic reads** | Data goes backward in time | Stick user to one replica |
+| **Consistent prefix reads** | Causal order violated | Write causally related data to same partition |
+
+#### Conflict Resolution
+- **Last-Write-Wins (LWW)**: Simple but loses data. Only safe if keys are immutable.
+- **Merge**: Union values, concatenate, CRDT data structures.
+- **Application-level**: Return all versions ("siblings"), let app decide.
+- **Version vectors**: Track causal dependencies per replica.
+
+#### Quorum: `w + r > n`
+- w = write acknowledgments, r = read queries, n = total replicas.
+- **Sloppy quorum**: Accept writes on non-home nodes during partitions (hinted handoff). Improves availability, weakens consistency.
+
+---
+
+### Chapter 6: Partitioning (Sharding)
+
+#### Partitioning Strategies
+
+| Strategy | Pros | Cons |
+|----------|------|------|
+| **Key-range** | Efficient range queries | Hotspot risk on sequential keys |
+| **Hash** | Even distribution | No range queries |
+| **Compound** | First part hashed, rest sorted | More complex, best of both |
+
+#### Secondary Index Partitioning
+- **Local (document-based)**: Each partition indexes its own data. Writes simple, reads scatter-gather.
+- **Global (term-based)**: Index partitioned by term. Reads efficient, writes update multiple partitions.
+
+#### Rebalancing
+- **Fixed partition count**: More partitions than nodes. Redistribute on node changes. (Riak, Elasticsearch)
+- **Dynamic**: Split/merge based on size. (HBase, RethinkDB)
+- **Proportional to nodes**: Fixed partitions per node. (Cassandra)
+
+#### Request Routing
+- Round-robin to any node (node forwards if needed)
+- Routing layer (partition-aware proxy)
+- Client-aware (client knows partition map)
+- **ZooKeeper**: Authoritative partition → node mapping. Used by HBase, Kafka.
+
+---
+
+### Chapter 7: Transactions
+
+#### Isolation Levels (Weakest → Strongest)
+
+| Level | Prevents | Allows | Implementation |
+|-------|----------|--------|----------------|
+| **Read Committed** | Dirty reads, dirty writes | Non-repeatable reads, lost updates | Row locks + old value copy |
+| **Snapshot Isolation** | + Non-repeatable reads | Write skew, phantoms | MVCC (multi-version) |
+| **Serializable** | Everything | Nothing | 2PL, serial execution, or SSI |
+
+#### Concurrency Anomalies
+
+| Anomaly | Description | Example |
+|---------|-------------|---------|
+| **Dirty read** | See uncommitted data | Reading half-written transfer |
+| **Dirty write** | Overwrite uncommitted data | Two buyers "winning" same item |
+| **Lost update** | Read-modify-write race | Two concurrent counter increments |
+| **Write skew** | Decision based on stale read | Two doctors both going off-call |
+| **Phantom** | New rows change query result | Meeting room double-booking |
+
+#### Serializable Implementations
+1. **Serial execution**: Single thread, in-memory. Fast but limited throughput. (VoltDB, Redis)
+2. **Two-Phase Locking (2PL)**: Shared/exclusive locks held until commit. Strong but slow, deadlock-prone.
+3. **SSI (Serializable Snapshot Isolation)**: Optimistic — execute freely, detect conflicts at commit. Best performance for read-heavy workloads. (PostgreSQL 9.1+)
+
+---
+
+### Chapter 8: Troubles with Distributed Systems
+
+#### The Three Unreliabilities
+
+**Networks**: Async packet networks — no delivery guarantee, no timing guarantee. Cannot distinguish crash from network delay. Timeouts are the only failure detector, but no correct timeout value exists.
+
+**Clocks**:
+- Wall clocks: Can jump backward (NTP correction). Never use for ordering events.
+- Monotonic clocks: Safe for elapsed time, not cross-node comparison.
+- Quartz drift: ~200ppm → 6ms error every 30 seconds.
+
+**Processes**: GC pauses, VM suspension, page faults — threads stop without warning. A paused node doesn't know time passed.
+
+#### Key Principles
+- **Fault ≠ failure**: Design for partial failures. Some nodes work while others don't.
+- **Truth is defined by majority**: Individual nodes cannot determine system state alone. Quorum votes decide.
+- **Fencing tokens**: Monotonically increasing tokens prevent zombie processes from corrupting state.
+- **Safety vs liveness**: Safety (bad things never happen) must hold always. Liveness (good things eventually happen) may have conditions.
+
+---
+
+### Chapter 9: Consistency & Consensus
+
+#### Consistency Models (Strongest → Weakest)
+
+| Model | Guarantee | Cost |
+|-------|-----------|------|
+| **Linearizability** | Behaves as if one copy, all ops atomic | High latency, reduced availability during partition |
+| **Causal consistency** | Respects cause-effect ordering | Better performance, partition-tolerant |
+| **Eventual consistency** | Replicas converge eventually | Best performance, weakest guarantee |
+
+#### Linearizability Use Cases
+- Leader election / distributed locks
+- Uniqueness constraints (usernames, filenames)
+- Cross-channel coordination (message queue + storage)
+
+#### Consensus Algorithms
+- **2PC**: Coordinator-based, blocking on coordinator failure. Practical but fragile.
+- **Paxos/Raft/Zab**: Epoch-based leader election + quorum voting. Non-blocking. Used by etcd, ZooKeeper, Consul.
+- **FLP impossibility**: Consensus impossible in pure async systems with crashes. Practical algorithms use timeouts.
+
+#### Total Order Broadcast ≡ Consensus ≡ Linearizable CAS
+These three problems are mathematically equivalent. Solving one solves all.
+
+#### ZooKeeper / etcd Pattern
+- Small consensus cluster (3–5 nodes) for coordination.
+- Linearizable atomic CAS operations.
+- Failure detection via session heartbeats.
+- Applications: leader election, partition assignment, distributed locks, service discovery.
+
+---
+
+## Part III: Derived Data
+
+### Chapter 10: Batch Processing
+
+#### Unix Philosophy → MapReduce
+- Each program does one thing well.
+- Output of one program = input of another.
+- Immutable inputs, deterministic processing.
+
+#### MapReduce Pipeline
+`Input → Mapper (extract key-value) → Sort/Partition → Reducer (aggregate by key) → Output`
+
+#### Distributed Join Strategies
+
+| Join Type | When | How |
+|-----------|------|-----|
+| **Sort-merge** | Both inputs large | Sort by join key, merge in reducer |
+| **Broadcast hash** | One input small (fits in RAM) | Load small side as hash table |
+| **Partitioned hash** | Both inputs partitioned identically | Per-partition hash join |
+
+#### Beyond MapReduce: Dataflow Engines (Spark, Flink, Tez)
+- Treat entire workflow as single job.
+- Pipeline intermediate results (avoid full materialization to HDFS).
+- Keep data in memory where possible.
+- Track computation lineage for fault recovery (RDDs).
+- Support iterative algorithms (graph processing via Pregel/BSP model).
+
+---
+
+### Chapter 11: Stream Processing
+
+#### Message Broker Models
+
+| Model | Delivery | Ordering | Replay | Use Case |
+|-------|----------|----------|--------|----------|
+| **AMQP/JMS** | Per-message ack, delete after | No ordering guarantee | No | Task queues, async RPC |
+| **Log-based (Kafka)** | Offset-based, retained | Per-partition ordering | Yes | Event streaming, CDC |
+
+#### Change Data Capture (CDC)
+Extract database changes as event stream → keep derived systems (search indexes, caches, warehouses) in sync. **Source of truth stays in database; derived views are consumers.**
+
+#### Event Sourcing
+Model state as append-only sequence of business events (not DB operations). Events are immutable facts. Current state = fold over event history.
+
+#### Stream Joins
+
+| Join | Input A | Input B | State |
+|------|---------|---------|-------|
+| **Stream-Stream** | Events | Events | Time-windowed buffer |
+| **Stream-Table** | Events | DB snapshot (via CDC) | Local materialized table |
+| **Table-Table** | CDC stream | CDC stream | Derived materialized view |
+
+#### Time & Windowing
+
+| Window | Description |
+|--------|-------------|
+| **Tumbling** | Fixed-size, non-overlapping (e.g., every 1 min) |
+| **Hopping** | Fixed-size, overlapping (e.g., 1 min window every 30s) |
+| **Sliding** | All events within time threshold of each other |
+| **Session** | Grouped by activity gap (e.g., 30 min inactivity) |
+
+**Event time ≠ processing time.** Always use event time for correctness. Handle late events with watermarks or correction publishes.
+
+#### Processing Guarantees
+- **Microbatching** (Spark Streaming): ~1s latency, atomic small batches.
+- **Checkpointing** (Flink): Periodic snapshots with message barriers.
+- **Idempotency**: Deduplicate using message offsets or unique IDs.
+- End-to-end exactly-once requires idempotent output + deduplication.
+
+---
+
+### Chapter 12: The Future of Data Systems
+
+#### Data Integration Pattern
+No single database does everything. Use **event log as integration backbone**:
+1. All writes go through authoritative event log.
+2. Derived systems (indexes, caches, ML models) consume the log.
+3. Deterministic, idempotent functions transform between layers.
+
+#### Unbundling Databases
+Separate concerns:
+- **Record system**: Captures authoritative writes.
+- **Derived systems**: Indexes, caches, materialized views consume change streams.
+- Enables gradual migration — run old and new systems in parallel.
+
+#### End-to-End Exactly-Once
+Low-level guarantees (TCP, DB transactions) don't ensure application correctness. Require:
+- **Operation identifiers**: UUID-based deduplication at application level.
+- **Idempotent operations**: Same effect whether executed once or many times.
+- **Unique constraint enforcement**: Via partitioned stream processing.
+
+#### Async Constraint Enforcement
+Instead of distributed transactions:
+1. Route requests by constraint field to partitioned log.
+2. Stream processor sequences competing requests.
+3. Reject violations, notify clients via output stream.
+4. Some applications tolerate temporary violations with compensating transactions.
+
+#### Auditability
+- Treat data like immutable event log — enables reconstruction and verification.
+- Implement cryptographic audit trails (Merkle trees).
+- Periodically test backup restoration and data reconstruction.
+
+---
+
+## Decision Framework: Quick Reference
+
+### Choosing a Data Model
+```
+Many-to-many relationships?     → Relational or Graph
+Hierarchical / nested data?     → Document
+Highly connected data?          → Graph
+Flexible / evolving schema?     → Document (schema-on-read)
+Strong consistency required?    → Relational (ACID)
+```
+
+### Choosing a Storage Engine
+```
+Write-heavy workload?           → LSM-tree (RocksDB, Cassandra)
+Read-heavy, predictable?        → B-tree (PostgreSQL, MySQL)
+Analytical queries?             → Column store (ClickHouse, Redshift)
+Full-text search?               → Inverted index (Elasticsearch)
+```
+
+### Choosing a Replication Strategy
+```
+Single datacenter?              → Single-leader
+Multi-datacenter?               → Multi-leader
+Offline-first clients?          → Multi-leader or Leaderless
+Maximum availability?           → Leaderless with sloppy quorum
+Strong consistency?             → Single-leader with sync replication
+```
+
+### Choosing an Isolation Level
+```
+Read-only analytics?            → Snapshot isolation
+General OLTP?                   → Read committed (default in most DBs)
+Financial / critical?           → Serializable (prefer SSI over 2PL)
+High write contention?          → Serial execution (if data fits in RAM)
+```
+
+### Choosing Batch vs Stream
+```
+Historical data reprocessing?   → Batch (Spark, Flink batch mode)
+Real-time derived views?        → Stream (Kafka + Flink/Spark Streaming)
+Both needed?                    → Unified engine (Flink) over Lambda architecture
+```
diff --git a/builtin-skills/software-engineer/devops-engineer/SKILL.md b/builtin-skills/software-engineer/devops-engineer/SKILL.md
new file mode 100644
index 00000000..d5dd170d
--- /dev/null
+++ b/builtin-skills/software-engineer/devops-engineer/SKILL.md
@@ -0,0 +1,144 @@
+---
+name: devops-engineer
+description: Creates Dockerfiles, configures CI/CD pipelines, writes Kubernetes manifests, and generates Terraform/Pulumi infrastructure templates. Handles deployment automation, GitOps configuration, incident response runbooks, and internal developer platform tooling. Use when setting up CI/CD pipelines, containerizing applications, managing infrastructure as code, deploying to Kubernetes clusters, configuring cloud platforms, automating releases, or responding to production incidents. Invoke for pipelines, Docker, Kubernetes, GitOps, Terraform, GitHub Actions, on-call, or platform engineering.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.1"
+  domain: devops
+  triggers: DevOps, CI/CD, deployment, Docker, Kubernetes, Terraform, GitHub Actions, infrastructure, platform engineering, incident response, on-call, self-service
+  role: engineer
+  scope: implementation
+  output-format: code
+  related-skills: terraform-engineer, kubernetes-specialist, sre-engineer, monitoring-expert, security-reviewer
+---
+
+# DevOps Engineer
+
+Senior DevOps engineer specializing in CI/CD pipelines, infrastructure as code, and deployment automation.
+
+## Role Definition
+
+You are a senior DevOps engineer with 10+ years of experience. You operate with three perspectives:
+- **Build Hat**: Automating build, test, and packaging
+- **Deploy Hat**: Orchestrating deployments across environments
+- **Ops Hat**: Ensuring reliability, monitoring, and incident response
+
+## When to Use This Skill
+
+- Setting up CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins)
+- Containerizing applications (Docker, Docker Compose)
+- Kubernetes deployments and configurations
+- Infrastructure as code (Terraform, Pulumi)
+- Cloud platform configuration (AWS, GCP, Azure)
+- Deployment strategies (blue-green, canary, rolling)
+- Building internal developer platforms and self-service tools
+- Incident response, on-call, and production troubleshooting
+- Release automation and artifact management
+
+## Core Workflow
+
+1. **Assess** - Understand application, environments, requirements
+2. **Design** - Pipeline structure, deployment strategy
+3. **Implement** - IaC, Dockerfiles, CI/CD configs
+4. **Validate** - Run `terraform plan`, lint configs, execute unit/integration tests; confirm no destructive changes before proceeding
+5. **Deploy** - Roll out with verification; run smoke tests post-deployment
+6. **Monitor** - Set up observability, alerts; confirm rollback procedure is ready before going live
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| GitHub Actions | `references/github-actions.md` | Setting up CI/CD pipelines, GitHub workflows |
+| Docker | `references/docker-patterns.md` | Containerizing applications, writing Dockerfiles |
+| Kubernetes | `references/kubernetes.md` | K8s deployments, services, ingress, pods |
+| Terraform | `references/terraform-iac.md` | Infrastructure as code, AWS/GCP provisioning |
+| Deployment | `references/deployment-strategies.md` | Blue-green, canary, rolling updates, rollback |
+| Platform | `references/platform-engineering.md` | Self-service infra, developer portals, golden paths, Backstage |
+| Release | `references/release-automation.md` | Artifact management, feature flags, multi-platform CI/CD |
+| Incidents | `references/incident-response.md` | Production outages, on-call, MTTR, postmortems, runbooks |
+
+## Constraints
+
+### MUST DO
+- Use infrastructure as code (never manual changes)
+- Implement health checks and readiness probes
+- Store secrets in secret managers (not env files)
+- Enable container scanning in CI/CD
+- Document rollback procedures
+- Use GitOps for Kubernetes (ArgoCD, Flux)
+
+### MUST NOT DO
+- Deploy to production without explicit approval
+- Store secrets in code or CI/CD variables
+- Skip staging environment testing
+- Ignore resource limits in containers
+- Use `latest` tag in production
+- Deploy on Fridays without monitoring
+
+## Output Templates
+
+Provide: CI/CD pipeline config, Dockerfile, K8s/Terraform files, deployment verification, rollback procedure
+
+### Minimal GitHub Actions Example
+
+```yaml
+name: CI
+on:
+  push:
+    branches: [main]
+jobs:
+  build-test-push:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build image
+        run: docker build -t myapp:${{ github.sha }} .
+      - name: Run tests
+        run: docker run --rm myapp:${{ github.sha }} pytest
+      - name: Scan image
+        uses: aquasecurity/trivy-action@master
+        with:
+          image-ref: myapp:${{ github.sha }}
+      - name: Push to registry
+        run: |
+          docker tag myapp:${{ github.sha }} ghcr.io/org/myapp:${{ github.sha }}
+          docker push ghcr.io/org/myapp:${{ github.sha }}
+```
+
+### Minimal Dockerfile Example
+
+```dockerfile
+FROM python:3.12-slim AS builder
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+FROM python:3.12-slim
+WORKDIR /app
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY . .
+USER nonroot
+HEALTHCHECK --interval=30s --timeout=5s CMD curl -f http://localhost:8080/health || exit 1
+CMD ["python", "main.py"]
+```
+
+### Rollback Procedure Example
+
+```bash
+# Kubernetes: roll back to previous deployment revision
+kubectl rollout undo deployment/myapp -n production
+kubectl rollout status deployment/myapp -n production
+
+# Verify rollback succeeded
+kubectl get pods -n production -l app=myapp
+curl -f https://myapp.example.com/health
+```
+
+Always document the rollback command and verification step in the PR or change ticket before deploying.
+
+## Knowledge Reference
+
+GitHub Actions, GitLab CI, Jenkins, CircleCI, Docker, Kubernetes, Helm, ArgoCD, Flux, Terraform, Pulumi, Crossplane, AWS/GCP/Azure, Prometheus, Grafana, PagerDuty, Backstage, LaunchDarkly, Flagger
diff --git a/builtin-skills/software-engineer/devops-engineer/references/deployment-strategies.md b/builtin-skills/software-engineer/devops-engineer/references/deployment-strategies.md
new file mode 100644
index 00000000..795bdd94
--- /dev/null
+++ b/builtin-skills/software-engineer/devops-engineer/references/deployment-strategies.md
@@ -0,0 +1,241 @@
+# Deployment Strategies
+
+## Strategy Comparison
+
+| Strategy | Use When | Rollback | Risk |
+|----------|----------|----------|------|
+| **Rolling** | Standard updates, can tolerate mixed versions | Automatic via health checks | Low |
+| **Blue-Green** | Zero downtime, instant rollback needed | Switch traffic to old env | Medium |
+| **Canary** | Risk mitigation, gradual rollout | Scale down canary | Low |
+| **Recreate** | Stateful apps, breaking changes | Redeploy previous version | High |
+
+## Rolling Deployment (Kubernetes)
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+spec:
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 25%        # Max pods above desired
+      maxUnavailable: 25%  # Max pods unavailable
+```
+
+## Blue-Green with Ingress
+
+```yaml
+# Blue deployment (current)
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: app-blue
+  labels:
+    version: blue
+---
+# Green deployment (new)
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: app-green
+  labels:
+    version: green
+---
+# Service pointing to active version
+apiVersion: v1
+kind: Service
+metadata:
+  name: app
+spec:
+  selector:
+    version: blue  # Switch to 'green' for cutover
+```
+
+## Canary with Istio
+
+```yaml
+apiVersion: networking.istio.io/v1beta1
+kind: VirtualService
+metadata:
+  name: app
+spec:
+  hosts:
+    - app
+  http:
+    - match:
+        - headers:
+            canary:
+              exact: "true"
+      route:
+        - destination:
+            host: app-canary
+    - route:
+        - destination:
+            host: app-stable
+          weight: 90
+        - destination:
+            host: app-canary
+          weight: 10
+```
+
+## Rollback Procedures
+
+### Kubernetes Rollback
+```bash
+# View rollout history
+kubectl rollout history deployment/app
+
+# Rollback to previous
+kubectl rollout undo deployment/app
+
+# Rollback to specific revision
+kubectl rollout undo deployment/app --to-revision=2
+
+# Check status
+kubectl rollout status deployment/app
+```
+
+### ArgoCD Rollback
+```bash
+argocd app rollback app-prod --revision=123
+```
+
+### Terraform Rollback
+```bash
+# Identify previous state
+terraform state list
+
+# Import previous configuration
+git checkout HEAD~1 -- main.tf
+terraform apply
+```
+
+## Pre-deployment Checklist
+
+- [ ] Database migrations are backward compatible
+- [ ] Feature flags for new functionality
+- [ ] Monitoring dashboards updated
+- [ ] Alert thresholds reviewed
+- [ ] Rollback procedure documented
+- [ ] Staging tested and approved
+- [ ] Team notified of deployment window
+
+## Post-deployment Verification
+
+```bash
+# Check pod status
+kubectl get pods -l app=app
+
+# Check logs for errors
+kubectl logs -l app=app --tail=100 | grep -i error
+
+# Verify endpoints
+curl -f https://app.example.com/health
+
+# Check metrics
+# - Error rate < 1%
+# - Latency p99 < 500ms
+# - No memory/CPU spikes
+```
+
+## Deployment Metrics (DORA)
+
+Track four key metrics:
+- **Deployment Frequency**: Target 10+/day
+- **Lead Time for Changes**: Target <1 hour
+- **Change Failure Rate**: Target <5%
+- **MTTR**: Target <30 minutes
+
+```yaml
+# Prometheus metrics for DORA tracking
+- record: deployment:frequency:1d
+  expr: count_over_time(deployment_completed[1d])
+
+- record: deployment:lead_time:p95
+  expr: histogram_quantile(0.95,
+    rate(commit_to_deploy_seconds_bucket[1h]))
+
+- record: deployment:failure_rate
+  expr: |
+    sum(rate(deployment_failed[1h]))
+    / sum(rate(deployment_total[1h]))
+```
+
+## Advanced Canary with Automated Analysis
+
+```yaml
+# Flagger: Automated canary with rollback
+apiVersion: flagger.app/v1beta1
+kind: Canary
+metadata:
+  name: api
+spec:
+  provider: istio
+  targetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: api
+  progressDeadlineSeconds: 60
+  service:
+    port: 8080
+    trafficPolicy:
+      tls:
+        mode: ISTIO_MUTUAL
+  analysis:
+    interval: 30s
+    threshold: 5
+    maxWeight: 50
+    stepWeight: 10
+    metrics:
+      - name: error-rate
+        templateRef:
+          name: error-rate
+        thresholdRange:
+          max: 1
+      - name: latency
+        templateRef:
+          name: latency
+        thresholdRange:
+          max: 500
+    webhooks:
+      - name: acceptance-test
+        type: pre-rollout
+        url: http://test-runner/
+      - name: load-test
+        url: http://loadtester/
+        timeout: 5s
+        metadata:
+          type: bash
+          cmd: "hey -z 1m -q 10 http://api-canary:8080/"
+```
+
+## Shadow Deployment
+
+```yaml
+# Mirror traffic to shadow deployment
+apiVersion: networking.istio.io/v1beta1
+kind: VirtualService
+metadata:
+  name: api
+spec:
+  hosts:
+    - api
+  http:
+    - match:
+        - headers:
+            x-test-version:
+              exact: "v2"
+      route:
+        - destination:
+            host: api
+            subset: v2
+      mirror:
+        host: api
+        subset: v2-shadow
+      mirrorPercentage:
+        value: 100
+    - route:
+        - destination:
+            host: api
+            subset: v1
+```
diff --git a/builtin-skills/software-engineer/devops-engineer/references/docker-patterns.md b/builtin-skills/software-engineer/devops-engineer/references/docker-patterns.md
new file mode 100644
index 00000000..f5523e7f
--- /dev/null
+++ b/builtin-skills/software-engineer/devops-engineer/references/docker-patterns.md
@@ -0,0 +1,113 @@
+# Docker Patterns
+
+## Multi-stage Dockerfile (Node.js)
+
+```dockerfile
+# Build stage
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production && npm cache clean --force
+COPY . .
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
+COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
+COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
+USER nodejs
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s \
+  CMD wget -qO- http://localhost:3000/health || exit 1
+CMD ["node", "dist/main.js"]
+```
+
+## Multi-stage Dockerfile (Python)
+
+```dockerfile
+FROM python:3.12-slim AS builder
+WORKDIR /app
+RUN pip install --no-cache-dir poetry
+COPY pyproject.toml poetry.lock ./
+RUN poetry export -f requirements.txt --output requirements.txt
+RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt
+
+FROM python:3.12-slim AS runner
+WORKDIR /app
+RUN useradd -m -u 1001 appuser
+COPY --from=builder /wheels /wheels
+RUN pip install --no-cache-dir /wheels/*
+COPY --chown=appuser:appuser . .
+USER appuser
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=3s \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+## Docker Compose (Development)
+
+```yaml
+version: '3.8'
+services:
+  app:
+    build:
+      context: .
+      target: builder  # Use dev stage
+    volumes:
+      - .:/app
+      - /app/node_modules
+    ports:
+      - "3000:3000"
+    environment:
+      - DATABASE_URL=postgres://user:pass@db:5432/app
+    depends_on:
+      db:
+        condition: service_healthy
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: pass
+      POSTGRES_DB: app
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U user -d app"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data:
+```
+
+## Security Best Practices
+
+| Practice | Implementation |
+|----------|----------------|
+| Non-root user | `USER nodejs` or `USER 1001` |
+| Minimal base image | Use `-alpine` or `-slim` variants |
+| No secrets in image | Use runtime env vars or secrets |
+| Pin versions | `FROM node:20.10.0-alpine` not `latest` |
+| Scan images | `docker scout`, `trivy`, `snyk` |
+| Health checks | `HEALTHCHECK` instruction |
+| .dockerignore | Exclude `node_modules`, `.git`, `.env` |
+
+## .dockerignore Template
+
+```
+node_modules
+.git
+.env*
+*.md
+Dockerfile*
+docker-compose*
+.dockerignore
+coverage
+.nyc_output
+```
diff --git a/builtin-skills/software-engineer/devops-engineer/references/github-actions.md b/builtin-skills/software-engineer/devops-engineer/references/github-actions.md
new file mode 100644
index 00000000..367c273d
--- /dev/null
+++ b/builtin-skills/software-engineer/devops-engineer/references/github-actions.md
@@ -0,0 +1,139 @@
+# GitHub Actions Pipelines
+
+## Complete CI/CD Pipeline
+
+```yaml
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test
+      - run: npm run lint
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      image-tag: ${{ steps.meta.outputs.tags }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=sha,prefix=
+            type=ref,event=branch
+      - uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  deploy-staging:
+    needs: build
+    if: github.ref == 'refs/heads/develop'
+    runs-on: ubuntu-latest
+    environment: staging
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          kubectl set image deployment/app app=${{ needs.build.outputs.image-tag }}
+
+  deploy-production:
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          kubectl set image deployment/app app=${{ needs.build.outputs.image-tag }}
+```
+
+## Common Workflow Patterns
+
+### Matrix Builds (Multi-version testing)
+```yaml
+jobs:
+  test:
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+```
+
+### Reusable Workflows
+```yaml
+# .github/workflows/deploy.yml
+on:
+  workflow_call:
+    inputs:
+      environment:
+        required: true
+        type: string
+    secrets:
+      DEPLOY_KEY:
+        required: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment }}
+    steps:
+      - run: echo "Deploying to ${{ inputs.environment }}"
+```
+
+### Caching Dependencies
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: ~/.npm
+    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+    restore-keys: |
+      ${{ runner.os }}-node-
+```
+
+## Quick Reference
+
+| Action | Purpose |
+|--------|---------|
+| `actions/checkout@v4` | Clone repository |
+| `actions/setup-node@v4` | Install Node.js |
+| `docker/build-push-action@v5` | Build and push Docker image |
+| `docker/metadata-action@v5` | Generate Docker tags |
+| `actions/cache@v4` | Cache dependencies |
diff --git a/builtin-skills/software-engineer/devops-engineer/references/incident-response.md b/builtin-skills/software-engineer/devops-engineer/references/incident-response.md
new file mode 100644
index 00000000..1ff77317
--- /dev/null
+++ b/builtin-skills/software-engineer/devops-engineer/references/incident-response.md
@@ -0,0 +1,331 @@
+# Incident Response
+
+## Response Metrics
+
+- **MTTD** (Mean Time to Detect): Target < 5 minutes
+- **MTTA** (Mean Time to Acknowledge): Target < 5 minutes
+- **MTTR** (Mean Time to Resolve): Target < 30 minutes
+- **MTBF** (Mean Time Between Failures): Maximize
+
+### Severity Levels
+
+| Level | Impact | Response | Example |
+|-------|--------|----------|---------|
+| SEV1 | Complete outage | Immediate | Database down, payment failed |
+| SEV2 | Major degradation | 15 min | API latency >5s, 50% errors |
+| SEV3 | Minor degradation | 1 hour | Non-critical feature broken |
+| SEV4 | Low impact | Business hours | UI glitch, logging issues |
+
+## Runbook Template
+
+```markdown
+# Runbook: High API Error Rate
+
+## Symptoms
+- Alert: `api_error_rate > 0.05`
+- Dashboard: https://grafana.example.com/d/api-errors
+
+## Impact
+Users cannot complete purchases (~$X per minute)
+
+## Triage
+1. Check dashboard for affected endpoints
+2. Check recent deployments: `kubectl rollout history deployment/api`
+3. Check dependencies: database, redis, external APIs
+
+## Resolution
+
+### Option 1: Rollback
+kubectl rollout undo deployment/api -n production
+
+### Option 2: Scale Up
+kubectl scale deployment/api --replicas=10 -n production
+
+### Option 3: Fix Config
+kubectl set env deployment/api DB_POOL_SIZE=50 -n production
+
+## Verification
+- [ ] Error rate <1%
+- [ ] P95 latency <500ms
+- [ ] Health checks passing
+
+## Communication
+- Update status page
+- Notify #incidents
+- Post if user-facing
+```
+
+## Auto-Remediation Script
+
+```python
+#!/usr/bin/env python3
+import kubernetes, prometheus_api_client
+
+class IncidentRemediator:
+    def check_high_error_rate(self):
+        query = 'rate(http_requests_total{status=~"5.."}[5m]) > 0.05'
+        result = self.prometheus.custom_query(query)
+        return len(result) > 0
+
+    def rollback_deployment(self, namespace, deployment):
+        body = {'spec': {'rollbackTo': {'revision': 0}}}
+        self.k8s.patch_namespaced_deployment(deployment, namespace, body)
+
+    def remediate(self):
+        if self.check_high_error_rate():
+            if self.rollback_deployment('production', 'api'):
+                time.sleep(120)
+                if not self.check_high_error_rate():
+                    return  # Success
+            # Escalate if remediation fails
+            self.create_incident("Auto-remediation failed")
+```
+
+## Postmortem Template
+
+```markdown
+# Postmortem: API Outage - 2024-01-15
+
+**Date**: January 15, 2024
+**Duration**: 45 minutes (14:23 - 15:08 UTC)
+**Severity**: SEV1
+**Impact**: Complete API outage, ~$25K revenue loss
+
+## Summary
+API became unresponsive due to database connection pool exhaustion
+from slow query in v2.3.1.
+
+## Timeline (UTC)
+- 14:23 - Alert fired
+- 14:27 - Incident declared SEV1
+- 14:30 - Rollback initiated
+- 14:45 - Identified slow query
+- 14:50 - Killed queries
+- 15:08 - Resolved
+
+## Root Cause
+New query missing index on `user_id`, causing full table scans that
+exhausted connection pool under load.
+
+## Impact
+- 100% API failure for 45 minutes
+- 15,000 users affected
+- $25K revenue loss
+- 200+ support tickets
+
+## Action Items
+| Action | Owner | Deadline |
+|--------|-------|----------|
+| Add index on user_id | DB team | 2024-01-16 |
+| Add query perf testing | Platform | 2024-01-22 |
+| Increase staging DB size | Infra | 2024-01-30 |
+
+## Lessons Learned
+- Performance testing must use production-scale data
+- Connection pool exhaustion needs active intervention
+- Consider circuit breakers for DB operations
+```
+
+## PagerDuty Configuration
+
+```yaml
+schedules:
+  - name: Primary On-Call
+    time_zone: America/New_York
+    layers:
+      - rotation_turn_length_seconds: 604800  # 1 week
+        users: [PXXXXXX, PXXXXXX, PXXXXXX]
+
+escalation_policies:
+  - name: Production
+    rules:
+      - escalation_delay_in_minutes: 0
+        targets: [{type: schedule, id: primary}]
+      - escalation_delay_in_minutes: 15
+        targets: [{type: schedule, id: secondary}]
+      - escalation_delay_in_minutes: 30
+        targets: [{type: user, id: manager}]
+```
+
+## Chaos Engineering
+
+```yaml
+# chaos-mesh: Pod failure test
+apiVersion: chaos-mesh.org/v1alpha1
+kind: PodChaos
+metadata:
+  name: pod-failure-test
+spec:
+  action: pod-failure
+  mode: one
+  duration: "30s"
+  selector:
+    namespaces: [production]
+    labelSelectors:
+      app: api
+  scheduler:
+    cron: "@every 2h"
+```
+
+```bash
+#!/bin/bash
+# Game Day: Database failover drill
+
+echo "🎮 Game Day: Database failover"
+slack-cli -d incidents "Starting failover drill"
+
+# Simulate failure
+kubectl delete pod postgres-0 -n production
+
+# Monitor recovery
+start=$(date +%s)
+while ! kubectl get pod postgres-1 | grep Running; do
+  sleep 5
+done
+duration=$(($(date +%s) - start))
+
+echo "Failover: ${duration}s" >> results.md
+curl -f https://api.example.com/health || echo "FAIL"
+```
+
+## Evidence Collection & Forensics
+
+```bash
+#!/bin/bash
+# collect-evidence.sh - Preserve incident evidence
+
+INCIDENT_ID=$1
+EVIDENCE_DIR="incidents/${INCIDENT_ID}/evidence"
+mkdir -p $EVIDENCE_DIR
+
+# Preserve logs
+kubectl logs -l app=api --all-containers --timestamps \
+  --since=2h > $EVIDENCE_DIR/pod-logs.txt
+
+# Capture current state
+kubectl get all -n production -o yaml > $EVIDENCE_DIR/k8s-state.yaml
+kubectl describe pods -n production > $EVIDENCE_DIR/pod-details.txt
+
+# Network traces
+kubectl exec -n production deploy/api -- \
+  tcpdump -i any -w /tmp/capture.pcap -G 60 -W 5 &
+
+# Memory/CPU snapshot
+kubectl top pods -n production > $EVIDENCE_DIR/resource-usage.txt
+
+# Git commit at time of incident
+git log --since="2 hours ago" --oneline > $EVIDENCE_DIR/recent-commits.txt
+
+# Database queries
+psql -c "SELECT * FROM pg_stat_activity" > $EVIDENCE_DIR/db-activity.txt
+
+# Create timeline
+echo "$(date): Evidence collection completed" >> $EVIDENCE_DIR/timeline.txt
+```
+
+## Communication Templates
+
+```markdown
+## SEV1 Initial Notification
+
+**INCIDENT ALERT - SEV1**
+
+**Status**: Investigating
+**Impact**: Payment API unavailable (100% error rate)
+**Started**: 2024-01-15 14:23 UTC
+**Affected**: All users (~15K active sessions)
+**Lead**: @oncall-engineer
+**War Room**: https://zoom.us/incident-123
+
+Updates every 15 minutes or on major change.
+
+---
+
+## SEV1 Resolution Notification
+
+**INCIDENT RESOLVED**
+
+**Summary**: Payment API restored after database connection pool exhaustion
+**Duration**: 45 minutes (14:23 - 15:08 UTC)
+**Resolution**: Rollback to v2.3.0 + query optimization
+**Impact**: 15K users, ~$25K revenue loss
+**Next Steps**: Postmortem scheduled for Jan 16 10am
+
+Thanks to @oncall-team for rapid response.
+```
+
+## Incident Classification
+
+| Type | Examples | Response Team | Escalation |
+|------|----------|---------------|------------|
+| **Security** | Breach, data leak, unauthorized access | Security + DevOps | CISO, Legal |
+| **Service** | Outage, degradation, errors | DevOps + SRE | Engineering VP |
+| **Data** | Corruption, loss, sync issues | DBA + DevOps | CTO |
+| **Compliance** | GDPR, SOC2, audit violations | Compliance + Legal | CEO |
+| **Third-party** | Provider outage, API failures | DevOps + Product | Account manager |
+
+## Security Incident Specifics
+
+```bash
+# Compromise investigation checklist
+□ Isolate affected systems
+□ Preserve logs and memory dumps
+□ Identify attack vector
+□ Check for lateral movement
+□ Scan for malware/backdoors
+□ Review access logs for 30 days
+□ Identify data accessed
+□ Assess exfiltration risk
+□ Check for persistence mechanisms
+□ Coordinate with security team
+□ Notify legal if PII involved
+□ Document chain of custody
+```
+
+## Compliance Requirements
+
+```yaml
+# Incident notification requirements
+gdpr:
+  notification_deadline: 72h
+  authority: Data Protection Officer
+  required_info:
+    - Nature of breach
+    - Data categories affected
+    - Number of individuals
+    - Consequences
+    - Remediation measures
+
+sox:
+  notification_deadline: immediate
+  authority: Audit Committee
+  documentation:
+    - Financial impact
+    - Control failures
+    - Remediation plan
+
+pci_dss:
+  notification_deadline: 24h
+  authority: Card brands + acquirer
+  required_info:
+    - Cardholder data affected
+    - Incident timeline
+    - Forensic investigation
+```
+
+## Best Practices
+
+- Maintain runbooks for critical services
+- Practice with game days monthly
+- Automate common remediation
+- Keep postmortems blameless
+- Track incident metrics
+- Test recovery procedures
+- Document all incidents
+- Improve detection continuously
+- Preserve evidence chain properly
+- Coordinate communication clearly
+- Escalate security incidents immediately
+- Understand compliance obligations
+- Train team on response procedures
+- Review and update playbooks quarterly
diff --git a/builtin-skills/software-engineer/devops-engineer/references/kubernetes.md b/builtin-skills/software-engineer/devops-engineer/references/kubernetes.md
new file mode 100644
index 00000000..1bb44f7c
--- /dev/null
+++ b/builtin-skills/software-engineer/devops-engineer/references/kubernetes.md
@@ -0,0 +1,154 @@
+# Kubernetes Manifests
+
+## Complete Deployment Stack
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: app
+  labels:
+    app: app
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: app
+  template:
+    metadata:
+      labels:
+        app: app
+    spec:
+      containers:
+        - name: app
+          image: ghcr.io/org/app:latest
+          ports:
+            - containerPort: 3000
+          resources:
+            requests:
+              memory: "128Mi"
+              cpu: "100m"
+            limits:
+              memory: "256Mi"
+              cpu: "500m"
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: 3000
+            initialDelaySeconds: 10
+            periodSeconds: 10
+          readinessProbe:
+            httpGet:
+              path: /ready
+              port: 3000
+            initialDelaySeconds: 5
+            periodSeconds: 5
+          env:
+            - name: DATABASE_URL
+              valueFrom:
+                secretKeyRef:
+                  name: app-secrets
+                  key: database-url
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: app
+spec:
+  selector:
+    app: app
+  ports:
+    - port: 80
+      targetPort: 3000
+  type: ClusterIP
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: app
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+spec:
+  ingressClassName: nginx
+  tls:
+    - hosts: [app.example.com]
+      secretName: app-tls
+  rules:
+    - host: app.example.com
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: app
+                port:
+                  number: 80
+```
+
+## ConfigMap and Secrets
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: app-config
+data:
+  LOG_LEVEL: "info"
+  API_TIMEOUT: "30s"
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: app-secrets
+type: Opaque
+stringData:
+  database-url: "postgres://user:pass@host:5432/db"
+```
+
+## Horizontal Pod Autoscaler
+
+```yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: app-hpa
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: app
+  minReplicas: 2
+  maxReplicas: 10
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+```
+
+## Quick Reference
+
+| Resource | Purpose |
+|----------|---------|
+| Deployment | Manages ReplicaSets, rolling updates |
+| Service | Internal load balancing, DNS |
+| Ingress | External HTTP/HTTPS routing |
+| ConfigMap | Non-sensitive configuration |
+| Secret | Sensitive data (base64 encoded) |
+| HPA | Auto-scaling based on metrics |
+| PVC | Persistent storage claims |
+
+## Common kubectl Commands
+
+```bash
+kubectl apply -f deployment.yaml
+kubectl get pods -l app=app
+kubectl describe pod <pod-name>
+kubectl logs -f <pod-name>
+kubectl exec -it <pod-name> -- /bin/sh
+kubectl rollout status deployment/app
+kubectl rollout undo deployment/app
+```
diff --git a/builtin-skills/software-engineer/devops-engineer/references/platform-engineering.md b/builtin-skills/software-engineer/devops-engineer/references/platform-engineering.md
new file mode 100644
index 00000000..cf9f081b
--- /dev/null
+++ b/builtin-skills/software-engineer/devops-engineer/references/platform-engineering.md
@@ -0,0 +1,417 @@
+# Platform Engineering
+
+## Platform Principles
+
+- **Self-service first**: Reduce manual work to <10%
+- **Golden paths**: Pre-approved, opinionated templates
+- **Developer experience**: Measure and optimize productivity
+- **Platform as product**: Treat with product mindset
+
+## Self-Service with Crossplane
+
+```yaml
+# Composition for self-service database
+apiVersion: apiextensions.crossplane.io/v1
+kind: Composition
+metadata:
+  name: postgres-database
+spec:
+  compositeTypeRef:
+    apiVersion: platform.example.com/v1alpha1
+    kind: Database
+  resources:
+    - name: rds-instance
+      base:
+        apiVersion: rds.aws.crossplane.io/v1alpha1
+        kind: DBInstance
+        spec:
+          forProvider:
+            dbInstanceClass: db.t3.micro
+            engine: postgres
+            engineVersion: "15"
+            masterUsername: admin
+            allocatedStorage: 20
+```
+
+## Terraform Self-Service Module
+
+```hcl
+# modules/service/main.tf
+variable "service_name" {}
+variable "environment" {}
+
+module "k8s_service" {
+  source   = "./k8s-deployment"
+  name     = var.service_name
+  env      = var.environment
+}
+
+module "database" {
+  source = "./postgres"
+  name   = "${var.service_name}-db"
+}
+
+module "monitoring" {
+  source  = "./monitoring-stack"
+  service = var.service_name
+}
+
+output "service_url" {
+  value = module.k8s_service.url
+}
+```
+
+## Backstage Service Template
+
+```yaml
+# templates/microservice/template.yaml
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+  name: microservice-template
+  title: Microservice Golden Path
+spec:
+  owner: platform-team
+  type: service
+  parameters:
+    - title: Service Info
+      properties:
+        name:
+          type: string
+        owner:
+          type: string
+          ui:field: OwnerPicker
+        language:
+          type: string
+          enum: [go, python, nodejs, java]
+  steps:
+    - id: fetch
+      action: fetch:template
+      input:
+        url: ./skeleton
+        values:
+          name: ${{ parameters.name }}
+    - id: publish
+      action: publish:github
+      input:
+        repoUrl: github.com?owner=org&repo=${{ parameters.name }}
+    - id: register
+      action: catalog:register
+```
+
+## Service Catalog Info
+
+```yaml
+# catalog-info.yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: payment-service
+  annotations:
+    github.com/project-slug: org/payment-service
+    pagerduty.com/integration-key: abc123
+    grafana/dashboard-selector: service=payment
+spec:
+  type: service
+  lifecycle: production
+  owner: payments-team
+  system: checkout
+  dependsOn:
+    - resource:default/payment-db
+    - component:default/auth-service
+  providesApis:
+    - payment-api
+```
+
+## Golden Path Scaffolding
+
+```bash
+#!/bin/bash
+# create-service.sh - Golden path for new services
+
+SERVICE=$1
+LANG=$2
+
+# Create from template
+gh repo create "org/$SERVICE" --template "org/template-$LANG"
+git clone "git@github.com:org/$SERVICE.git"
+cd "$SERVICE"
+
+# Setup CI/CD
+cat > .github/workflows/ci.yml <<EOF
+name: CI/CD
+on: [push]
+jobs:
+  pipeline:
+    uses: org/workflows/.github/workflows/standard.yml@v1
+    with:
+      service_name: $SERVICE
+EOF
+
+# Create infrastructure
+cat > terraform/main.tf <<EOF
+module "service" {
+  source = "git::https://github.com/org/terraform//service"
+  name   = "$SERVICE"
+}
+EOF
+
+git add . && git commit -m "Golden path init" && git push
+
+echo "✓ Service created! Merge to main to deploy."
+```
+
+## GitOps Repository Structure
+
+```
+gitops/
+├── apps/
+│   ├── production/
+│   │   ├── payment-service/
+│   │   └── auth-service/
+│   └── staging/
+│       └── payment-service/
+├── infrastructure/
+│   ├── clusters/
+│   │   ├── prod-us-east/
+│   │   └── prod-eu-west/
+│   └── base/
+│       ├── ingress/
+│       └── monitoring/
+└── platform/
+    ├── backstage/
+    ├── argocd/
+    └── vault/
+```
+
+## ArgoCD Application
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: payment-service
+spec:
+  project: default
+  source:
+    repoURL: https://github.com/org/gitops
+    path: apps/production/payment-service
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: production
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    retry:
+      limit: 5
+      backoff:
+        duration: 5s
+        maxDuration: 3m
+```
+
+## Platform Metrics
+
+```yaml
+# prometheus/platform-metrics.yaml
+groups:
+  - name: platform
+    rules:
+      # Self-service adoption rate
+      - record: platform:self_service:rate
+        expr: |
+          sum(rate(platform_provision_automated[1h]))
+          /
+          sum(rate(platform_provision_total[1h]))
+
+      # Provisioning time P95
+      - record: platform:provision:p95
+        expr: |
+          histogram_quantile(0.95,
+            rate(platform_provision_duration_bucket[5m]))
+
+      # Golden path adoption
+      - record: platform:golden_path:adoption
+        expr: |
+          count(service{template="golden-path"})
+          / count(service)
+```
+
+## Custom Backstage Plugin
+
+```typescript
+// plugins/platform-stats/PlatformMetrics.tsx
+import React from 'react';
+import { InfoCard, Progress } from '@backstage/core-components';
+
+export const PlatformMetrics = () => {
+  const metrics = {
+    selfServiceRate: 92,
+    avgProvisionTime: '3.5min',
+    uptime: '99.95%',
+    satisfaction: 4.6
+  };
+
+  return (
+    <InfoCard title="Platform Health">
+      <Progress value={metrics.selfServiceRate} label="Self-Service" />
+      <p>Provision Time: {metrics.avgProvisionTime}</p>
+      <p>Uptime: {metrics.uptime}</p>
+      <p>Satisfaction: {metrics.satisfaction}/5</p>
+    </InfoCard>
+  );
+};
+```
+
+## Cost Allocation
+
+```yaml
+# kubecost/allocation.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cost-allocation
+data:
+  allocation.json: |
+    {
+      "defaultLabels": {
+        "team": "team",
+        "service": "app",
+        "environment": "env"
+      },
+      "shareNamespaces": ["kube-system"],
+      "shareCost": "weighted"
+    }
+```
+
+## Platform APIs
+
+```python
+# Platform API for self-service provisioning
+from fastapi import FastAPI, Depends
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class ServiceRequest(BaseModel):
+    name: str
+    environment: str
+    language: str
+    database: bool = False
+
+@app.post("/api/v1/services")
+async def create_service(request: ServiceRequest):
+    # Validate and enqueue
+    task = platform.provision_service(
+        name=request.name,
+        env=request.environment,
+        template=f"golden-path-{request.language}"
+    )
+    return {"task_id": task.id, "status": "provisioning"}
+
+@app.get("/api/v1/services/{name}/status")
+async def service_status(name: str):
+    return {
+        "status": "running",
+        "url": f"https://{name}.example.com",
+        "health": "healthy",
+        "cost_mtd": "$142.50"
+    }
+```
+
+## Multi-Tenant Architecture
+
+```yaml
+# Policy: Resource quotas per tenant
+apiVersion: v1
+kind: ResourceQuota
+metadata:
+  name: team-quota
+  namespace: team-payments
+spec:
+  hard:
+    requests.cpu: "20"
+    requests.memory: 40Gi
+    persistentvolumeclaims: "10"
+    services.loadbalancers: "2"
+---
+# RBAC: Namespace admin
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: team-admin
+  namespace: team-payments
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: namespace-admin
+subjects:
+  - kind: Group
+    name: team-payments
+```
+
+## Adoption Strategy
+
+```yaml
+# Platform metrics tracking
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: platform-goals
+data:
+  goals.yaml: |
+    q1_2024:
+      self_service_rate: 90%
+      avg_provision_time: 5min
+      developer_satisfaction: 4.5/5
+      golden_path_adoption: 80%
+
+    tracking:
+      weekly_provisioning: true
+      team_feedback: true
+      support_tickets: true
+      training_completion: true
+```
+
+## CLI Tool Example
+
+```bash
+#!/bin/bash
+# platform-cli - Self-service CLI
+
+platform() {
+  case $1 in
+    create)
+      curl -X POST $PLATFORM_API/services \
+        -d "{\"name\":\"$2\",\"env\":\"$3\",\"language\":\"$4\"}"
+      ;;
+    status)
+      curl $PLATFORM_API/services/$2/status | jq
+      ;;
+    logs)
+      kubectl logs -l app=$2 -n ${3:-staging} --tail=100
+      ;;
+    cost)
+      curl $PLATFORM_API/services/$2/cost?period=mtd
+      ;;
+  esac
+}
+```
+
+## Best Practices
+
+- Design for self-service from day one
+- Make golden paths the easiest option
+- Measure developer satisfaction continuously
+- Automate platform operations
+- Provide excellent documentation
+- Build APIs, not just tools
+- Enable safe experimentation
+- Maintain backward compatibility
+- Treat platform as a product
+- Gather and act on feedback
+- Track adoption metrics weekly
+- Run platform as a product team
+- Invest in developer evangelism
+- Maintain SLOs for platform uptime
+- Provide fast, helpful support
diff --git a/builtin-skills/software-engineer/devops-engineer/references/release-automation.md b/builtin-skills/software-engineer/devops-engineer/references/release-automation.md
new file mode 100644
index 00000000..ca425192
--- /dev/null
+++ b/builtin-skills/software-engineer/devops-engineer/references/release-automation.md
@@ -0,0 +1,527 @@
+# Release Automation
+
+## Artifact Management
+
+### Container Registry Lifecycle
+
+```json
+{
+  "rules": [
+    {
+      "rulePriority": 1,
+      "description": "Keep last 10 prod images",
+      "selection": {
+        "tagStatus": "tagged",
+        "tagPrefixList": ["prod-"],
+        "countType": "imageCountMoreThan",
+        "countNumber": 10
+      },
+      "action": {"type": "expire"}
+    },
+    {
+      "rulePriority": 2,
+      "description": "Remove untagged after 7 days",
+      "selection": {
+        "tagStatus": "untagged",
+        "countType": "sinceImagePushed",
+        "countUnit": "days",
+        "countNumber": 7
+      },
+      "action": {"type": "expire"}
+    }
+  ]
+}
+```
+
+### Artifact Promotion
+
+```yaml
+# .github/workflows/promote.yml
+name: Artifact Promotion
+
+on:
+  workflow_dispatch:
+    inputs:
+      image_tag:
+        required: true
+      target_env:
+        type: choice
+        options: [staging, production]
+
+jobs:
+  promote:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Re-tag for environment
+        run: |
+          docker pull $REGISTRY/$IMAGE:${{ inputs.image_tag }}
+          docker tag $REGISTRY/$IMAGE:${{ inputs.image_tag }} \
+            $REGISTRY/$IMAGE:${{ inputs.target_env }}-latest
+          docker push $REGISTRY/$IMAGE:${{ inputs.target_env }}-latest
+
+      - name: Sign artifact
+        uses: sigstore/cosign-installer@v3
+      - run: cosign sign $REGISTRY/$IMAGE:${{ inputs.target_env }}-latest
+
+      - name: Update GitOps
+        run: |
+          cd gitops/apps/${{ inputs.target_env }}
+          yq e '.image.tag = "${{ inputs.image_tag }}"' -i values.yaml
+          git commit -am "Promote to ${{ inputs.target_env }}"
+          git push
+```
+
+## Feature Flags
+
+### LaunchDarkly Integration
+
+```python
+import launchdarkly
+
+ld = launchdarkly.get()
+
+def should_enable(user_id, feature_key):
+    user = {"key": user_id, "custom": {"groups": get_groups(user_id)}}
+    return ld.variation(feature_key, user, False)
+
+# Usage
+if should_enable(user.id, "new-payment-flow"):
+    return new_payment_service.process(payment)
+else:
+    return legacy_payment_service.process(payment)
+```
+
+### Flagger Progressive Delivery
+
+```yaml
+apiVersion: flagger.app/v1beta1
+kind: Canary
+metadata:
+  name: payment-service
+spec:
+  targetRef:
+    kind: Deployment
+    name: payment-service
+  service:
+    port: 8080
+  analysis:
+    interval: 1m
+    threshold: 5
+    maxWeight: 50
+    stepWeight: 10
+    metrics:
+      - name: request-success-rate
+        thresholdRange:
+          min: 99
+      - name: request-duration
+        thresholdRange:
+          max: 500
+    webhooks:
+      - name: load-test
+        url: http://flagger-loadtester/
+        metadata:
+          cmd: "hey -z 1m -q 10 http://payment-canary/"
+```
+
+## Multi-Platform CI/CD
+
+### GitLab CI
+
+```yaml
+stages: [test, build, deploy]
+
+test:
+  stage: test
+  image: node:20
+  script:
+    - npm ci && npm test
+
+build:
+  stage: build
+  image: docker:latest
+  services: [docker:dind]
+  script:
+    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
+    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
+
+deploy:production:
+  stage: deploy
+  script:
+    - kubectl set image deployment/app app=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
+  environment: production
+  when: manual
+  only: [main]
+```
+
+### Jenkins Pipeline
+
+```groovy
+pipeline {
+    agent any
+
+    environment {
+        IMAGE = "registry.example.com/app"
+    }
+
+    stages {
+        stage('Test') {
+            steps {
+                sh 'npm ci && npm test'
+                junit 'reports/junit.xml'
+            }
+        }
+
+        stage('Build') {
+            steps {
+                script {
+                    docker.build("${IMAGE}:${BUILD_NUMBER}")
+                }
+            }
+        }
+
+        stage('Security Scan') {
+            steps {
+                sh "trivy image ${IMAGE}:${BUILD_NUMBER}"
+            }
+        }
+
+        stage('Deploy Staging') {
+            when { branch 'main' }
+            steps {
+                sh "kubectl set image deployment/app app=${IMAGE}:${BUILD_NUMBER} -n staging"
+            }
+        }
+
+        stage('Deploy Production') {
+            when { branch 'main' }
+            steps {
+                input 'Deploy to production?'
+                sh "kubectl set image deployment/app app=${IMAGE}:${BUILD_NUMBER} -n production"
+            }
+        }
+    }
+
+    post {
+        failure {
+            slackSend color: 'danger', message: "Build failed: ${JOB_NAME}"
+        }
+    }
+}
+```
+
+## Build Optimization
+
+### Multi-stage Docker Build
+
+```dockerfile
+FROM node:20 AS deps
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+FROM node:20 AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-slim AS runner
+WORKDIR /app
+ENV NODE_ENV production
+COPY --from=deps /app/node_modules ./node_modules
+COPY --from=builder /app/dist ./dist
+USER node
+CMD ["node", "dist/main.js"]
+```
+
+### Parallel Testing
+
+```yaml
+# CircleCI
+version: 2.1
+jobs:
+  test:
+    parallelism: 4
+    docker:
+      - image: cimg/node:20
+    steps:
+      - checkout
+      - run: npm ci
+      - run: |
+          TESTS=$(circleci tests glob "test/**/*.js" | circleci tests split)
+          npm test $TESTS
+```
+
+## Release Orchestration
+
+```bash
+#!/bin/bash
+# release.sh - Multi-service coordinated release
+
+VERSION=$1
+SERVICES=(auth api worker frontend)
+
+echo "Release: $VERSION"
+
+# Create release branches
+for svc in "${SERVICES[@]}"; do
+    gh api repos/org/$svc/git/refs -f ref=refs/heads/release/$VERSION -f sha=$(git rev-parse main)
+done
+
+# Trigger builds
+for svc in "${SERVICES[@]}"; do
+    gh workflow run ci.yml --repo org/$svc --ref release/$VERSION
+done
+
+# Wait for completion
+for svc in "${SERVICES[@]}"; do
+    gh run watch --repo org/$svc $(gh run list --repo org/$svc -L1 -q '.[0].databaseId')
+done
+
+# Deploy to staging
+kubectl apply -f staging/release-$VERSION.yaml
+
+# Smoke tests
+./scripts/smoke-test.sh staging
+
+echo "✓ Release $VERSION ready for production"
+```
+
+## Dependency Management
+
+### Renovate Auto-Update
+
+```json
+{
+  "extends": ["config:base"],
+  "packageRules": [
+    {
+      "matchUpdateTypes": ["minor", "patch"],
+      "automerge": true
+    },
+    {
+      "matchDepTypes": ["devDependencies"],
+      "automerge": true
+    }
+  ],
+  "schedule": ["before 6am on Monday"],
+  "prConcurrentLimit": 5
+}
+```
+
+## Build Optimization
+
+### Build Caching Strategy
+
+```yaml
+# GitHub Actions: Multi-layer caching
+- name: Cache dependencies
+  uses: actions/cache@v3
+  with:
+    path: |
+      ~/.npm
+      ~/.cache
+      node_modules
+    key: ${{ runner.os }}-deps-${{ hashFiles('**/package-lock.json') }}
+    restore-keys: |
+      ${{ runner.os }}-deps-
+
+- name: Cache Docker layers
+  uses: docker/build-push-action@v4
+  with:
+    context: .
+    cache-from: type=gha
+    cache-to: type=gha,mode=max
+```
+
+### Parallel CI Pipeline
+
+```yaml
+# Multi-platform builds in parallel
+name: Build
+
+on: [push]
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        node: [18, 20, 22]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node }}
+      - run: npm ci && npm test
+
+  build-images:
+    needs: test
+    strategy:
+      matrix:
+        platform: [linux/amd64, linux/arm64]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: docker/build-push-action@v4
+        with:
+          platforms: ${{ matrix.platform }}
+          tags: app:${{ github.sha }}
+```
+
+## Multi-Service Release Orchestration
+
+```yaml
+# release-coordinator.yaml
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: release-v2.5.0
+spec:
+  template:
+    spec:
+      containers:
+        - name: coordinator
+          image: release-bot:latest
+          env:
+            - name: RELEASE_VERSION
+              value: "v2.5.0"
+            - name: SERVICES
+              value: "auth,api,worker,frontend"
+          command:
+            - /bin/bash
+            - -c
+            - |
+              # Deploy in dependency order
+              for svc in auth api worker frontend; do
+                echo "Deploying $svc..."
+                kubectl set image deploy/$svc \
+                  $svc=registry.io/$svc:$RELEASE_VERSION
+
+                kubectl rollout status deploy/$svc --timeout=5m
+
+                # Health check
+                kubectl run test-$svc --rm -i --restart=Never \
+                  --image=curlimages/curl -- \
+                  curl -f http://$svc/health
+
+                echo "$svc deployed successfully"
+              done
+```
+
+## Advanced Artifact Management
+
+```bash
+#!/bin/bash
+# artifact-scanner.sh - Scan before promotion
+
+IMAGE=$1
+SEVERITY=${2:-HIGH}
+
+# Vulnerability scan
+trivy image --severity $SEVERITY --exit-code 1 $IMAGE
+
+# License compliance
+syft $IMAGE -o json | \
+  jq '.artifacts[].licenses[] | select(.value |
+    contains("GPL") or contains("AGPL"))' && \
+  echo "License violation detected" && exit 1
+
+# SBOM generation
+syft $IMAGE -o spdx-json > sbom-$(basename $IMAGE).spdx.json
+
+# Sign artifact
+cosign sign --key cosign.key $IMAGE
+
+# Promote
+docker tag $IMAGE $IMAGE-approved
+docker push $IMAGE-approved
+
+echo "Artifact $IMAGE approved and promoted"
+```
+
+## Zero-Downtime Database Migrations
+
+```python
+# migrations/release_v2.5.py
+from alembic import op
+import sqlalchemy as sa
+
+def upgrade():
+    # Step 1: Add new column (nullable)
+    op.add_column('users',
+      sa.Column('email_verified', sa.Boolean(), nullable=True))
+
+    # Step 2: Backfill data (in batches)
+    connection = op.get_bind()
+    connection.execute("""
+      UPDATE users SET email_verified = true
+      WHERE email IS NOT NULL
+      LIMIT 1000
+    """)
+    # Repeat until complete (or use background job)
+
+    # Step 3: Make non-nullable (in next release)
+    # op.alter_column('users', 'email_verified', nullable=False)
+
+def downgrade():
+    op.drop_column('users', 'email_verified')
+```
+
+## Release Metrics Dashboard
+
+```yaml
+# Grafana dashboard for release metrics
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: release-dashboard
+data:
+  dashboard.json: |
+    {
+      "panels": [
+        {
+          "title": "Deployment Frequency",
+          "targets": [{
+            "expr": "count_over_time(deployment_completed[1d])"
+          }]
+        },
+        {
+          "title": "Lead Time",
+          "targets": [{
+            "expr": "histogram_quantile(0.95, commit_to_deploy_seconds_bucket)"
+          }]
+        },
+        {
+          "title": "Change Failure Rate",
+          "targets": [{
+            "expr": "sum(rate(deployment_failed[1h])) / sum(rate(deployment_total[1h]))"
+          }]
+        },
+        {
+          "title": "Active Releases",
+          "targets": [{
+            "expr": "count(release_in_progress == 1)"
+          }]
+        }
+      ]
+    }
+```
+
+## Best Practices
+
+- Version artifacts with immutable tags
+- Implement retention policies
+- Use progressive delivery for high-risk changes
+- Automate security scanning
+- Maintain deployment audit trails
+- Enable easy rollbacks
+- Monitor deployment metrics
+- Use feature flags for flexibility
+- Cache aggressively for fast builds
+- Parallelize test and build jobs
+- Coordinate multi-service releases
+- Generate and track SBOMs
+- Sign artifacts for supply chain security
+- Automate dependency updates
+- Track DORA metrics continuously
diff --git a/builtin-skills/software-engineer/devops-engineer/references/terraform-iac.md b/builtin-skills/software-engineer/devops-engineer/references/terraform-iac.md
new file mode 100644
index 00000000..62f52890
--- /dev/null
+++ b/builtin-skills/software-engineer/devops-engineer/references/terraform-iac.md
@@ -0,0 +1,141 @@
+# Terraform Infrastructure as Code
+
+## AWS ECS Fargate Setup
+
+```hcl
+terraform {
+  required_providers {
+    aws = { source = "hashicorp/aws", version = "~> 5.0" }
+  }
+  backend "s3" {
+    bucket = "terraform-state"
+    key    = "app/terraform.tfstate"
+    region = "us-east-1"
+  }
+}
+
+resource "aws_ecs_cluster" "main" {
+  name = "app-cluster"
+  setting {
+    name  = "containerInsights"
+    value = "enabled"
+  }
+}
+
+resource "aws_ecs_task_definition" "app" {
+  family                   = "app"
+  network_mode             = "awsvpc"
+  requires_compatibilities = ["FARGATE"]
+  cpu                      = "256"
+  memory                   = "512"
+  execution_role_arn       = aws_iam_role.ecs_execution.arn
+
+  container_definitions = jsonencode([{
+    name  = "app"
+    image = "${var.ecr_repository}:${var.image_tag}"
+    portMappings = [{ containerPort = 3000 }]
+    logConfiguration = {
+      logDriver = "awslogs"
+      options = {
+        awslogs-group         = aws_cloudwatch_log_group.app.name
+        awslogs-region        = var.region
+        awslogs-stream-prefix = "app"
+      }
+    }
+    secrets = [
+      { name = "DATABASE_URL", valueFrom = aws_ssm_parameter.db_url.arn }
+    ]
+  }])
+}
+
+resource "aws_ecs_service" "app" {
+  name            = "app"
+  cluster         = aws_ecs_cluster.main.id
+  task_definition = aws_ecs_task_definition.app.arn
+  desired_count   = 2
+  launch_type     = "FARGATE"
+
+  network_configuration {
+    subnets         = var.private_subnets
+    security_groups = [aws_security_group.app.id]
+  }
+
+  load_balancer {
+    target_group_arn = aws_lb_target_group.app.arn
+    container_name   = "app"
+    container_port   = 3000
+  }
+}
+```
+
+## AWS RDS PostgreSQL
+
+```hcl
+resource "aws_db_instance" "postgres" {
+  identifier           = "app-db"
+  engine               = "postgres"
+  engine_version       = "16.1"
+  instance_class       = "db.t3.micro"
+  allocated_storage    = 20
+  storage_encrypted    = true
+
+  db_name              = "app"
+  username             = "admin"
+  password             = var.db_password
+
+  vpc_security_group_ids = [aws_security_group.db.id]
+  db_subnet_group_name   = aws_db_subnet_group.main.name
+
+  backup_retention_period = 7
+  skip_final_snapshot     = false
+  final_snapshot_identifier = "app-db-final"
+
+  tags = { Environment = var.environment }
+}
+```
+
+## Variables and Outputs
+
+```hcl
+# variables.tf
+variable "environment" {
+  type        = string
+  description = "Environment name"
+}
+
+variable "region" {
+  type    = string
+  default = "us-east-1"
+}
+
+# outputs.tf
+output "ecs_cluster_arn" {
+  value = aws_ecs_cluster.main.arn
+}
+
+output "alb_dns_name" {
+  value = aws_lb.main.dns_name
+}
+```
+
+## Best Practices
+
+| Practice | Implementation |
+|----------|----------------|
+| State locking | S3 backend with DynamoDB |
+| Secrets | Use AWS Secrets Manager / SSM |
+| Modules | Reusable components |
+| Workspaces | Environment separation |
+| Tagging | Consistent resource tags |
+| Validation | `terraform validate`, `tflint` |
+
+## Common Commands
+
+```bash
+terraform init
+terraform plan -out=tfplan
+terraform apply tfplan
+terraform destroy
+terraform state list
+terraform import aws_instance.app i-1234567890
+```
diff --git a/builtin-skills/software-engineer/e2e-testing-patterns/SKILL.md b/builtin-skills/software-engineer/e2e-testing-patterns/SKILL.md
new file mode 100644
index 00000000..49d477e2
--- /dev/null
+++ b/builtin-skills/software-engineer/e2e-testing-patterns/SKILL.md
@@ -0,0 +1,535 @@
+---
+name: e2e-testing-patterns
+description: Master end-to-end testing with Playwright and Cypress to build reliable test suites that catch bugs, improve confidence, and enable fast deployment. Use when implementing E2E tests, debugging flaky tests, or establishing testing standards.
+---
+
+# E2E Testing Patterns
+
+Build reliable, fast, and maintainable end-to-end test suites that provide confidence to ship code quickly and catch regressions before users do.
+
+## When to Use This Skill
+
+- Implementing end-to-end test automation
+- Debugging flaky or unreliable tests
+- Testing critical user workflows
+- Setting up CI/CD test pipelines
+- Testing across multiple browsers
+- Validating accessibility requirements
+- Testing responsive designs
+- Establishing E2E testing standards
+
+## Core Concepts
+
+### 1. E2E Testing Fundamentals
+
+**What to Test with E2E:**
+
+- Critical user journeys (login, checkout, signup)
+- Complex interactions (drag-and-drop, multi-step forms)
+- Cross-browser compatibility
+- Real API integration
+- Authentication flows
+
+**What NOT to Test with E2E:**
+
+- Unit-level logic (use unit tests)
+- API contracts (use integration tests)
+- Edge cases (too slow)
+- Internal implementation details
+
+### 2. Test Philosophy
+
+**The Testing Pyramid:**
+
+```
+        /\
+       /E2E\         ← Few, focused on critical paths
+      /─────\
+     /Integr\        ← More, test component interactions
+    /────────\
+   /Unit Tests\      ← Many, fast, isolated
+  /────────────\
+```
+
+**Best Practices:**
+
+- Test user behavior, not implementation
+- Keep tests independent
+- Make tests deterministic
+- Optimize for speed
+- Use data-testid, not CSS selectors
+
+## Playwright Patterns
+
+### Setup and Configuration
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./e2e",
+  timeout: 30000,
+  expect: {
+    timeout: 5000,
+  },
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [["html"], ["junit", { outputFile: "results.xml" }]],
+  use: {
+    baseURL: "http://localhost:3000",
+    trace: "on-first-retry",
+    screenshot: "only-on-failure",
+    video: "retain-on-failure",
+  },
+  projects: [
+    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
+    { name: "webkit", use: { ...devices["Desktop Safari"] } },
+    { name: "mobile", use: { ...devices["iPhone 13"] } },
+  ],
+});
+```
+
+### Pattern 1: Page Object Model
+
+```typescript
+// pages/LoginPage.ts
+import { Page, Locator } from "@playwright/test";
+
+export class LoginPage {
+  readonly page: Page;
+  readonly emailInput: Locator;
+  readonly passwordInput: Locator;
+  readonly loginButton: Locator;
+  readonly errorMessage: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.emailInput = page.getByLabel("Email");
+    this.passwordInput = page.getByLabel("Password");
+    this.loginButton = page.getByRole("button", { name: "Login" });
+    this.errorMessage = page.getByRole("alert");
+  }
+
+  async goto() {
+    await this.page.goto("/login");
+  }
+
+  async login(email: string, password: string) {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.loginButton.click();
+  }
+
+  async getErrorMessage(): Promise<string> {
+    return (await this.errorMessage.textContent()) ?? "";
+  }
+}
+
+// Test using Page Object
+import { test, expect } from "@playwright/test";
+import { LoginPage } from "./pages/LoginPage";
+
+test("successful login", async ({ page }) => {
+  const loginPage = new LoginPage(page);
+  await loginPage.goto();
+  await loginPage.login("user@example.com", "password123");
+
+  await expect(page).toHaveURL("/dashboard");
+  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
+});
+
+test("failed login shows error", async ({ page }) => {
+  const loginPage = new LoginPage(page);
+  await loginPage.goto();
+  await loginPage.login("invalid@example.com", "wrong");
+
+  const error = await loginPage.getErrorMessage();
+  expect(error).toContain("Invalid credentials");
+});
+```
+
+### Pattern 2: Fixtures for Test Data
+
+```typescript
+// fixtures/test-data.ts
+import { test as base } from "@playwright/test";
+
+type TestData = {
+  testUser: {
+    email: string;
+    password: string;
+    name: string;
+  };
+  adminUser: {
+    email: string;
+    password: string;
+  };
+};
+
+export const test = base.extend<TestData>({
+  testUser: async ({}, use) => {
+    const user = {
+      email: `test-${Date.now()}@example.com`,
+      password: "Test123!@#",
+      name: "Test User",
+    };
+    // Setup: Create user in database
+    await createTestUser(user);
+    await use(user);
+    // Teardown: Clean up user
+    await deleteTestUser(user.email);
+  },
+
+  adminUser: async ({}, use) => {
+    await use({
+      email: "admin@example.com",
+      password: process.env.ADMIN_PASSWORD!,
+    });
+  },
+});
+
+// Usage in tests
+import { test } from "./fixtures/test-data";
+
+test("user can update profile", async ({ page, testUser }) => {
+  await page.goto("/login");
+  await page.getByLabel("Email").fill(testUser.email);
+  await page.getByLabel("Password").fill(testUser.password);
+  await page.getByRole("button", { name: "Login" }).click();
+
+  await page.goto("/profile");
+  await page.getByLabel("Name").fill("Updated Name");
+  await page.getByRole("button", { name: "Save" }).click();
+
+  await expect(page.getByText("Profile updated")).toBeVisible();
+});
+```
+
+### Pattern 3: Waiting Strategies
+
+```typescript
+// ❌ Bad: Fixed timeouts
+await page.waitForTimeout(3000); // Flaky!
+
+// ✅ Good: Wait for specific conditions
+await page.waitForLoadState("networkidle");
+await page.waitForURL("/dashboard");
+await page.waitForSelector('[data-testid="user-profile"]');
+
+// ✅ Better: Auto-waiting with assertions
+await expect(page.getByText("Welcome")).toBeVisible();
+await expect(page.getByRole("button", { name: "Submit" })).toBeEnabled();
+
+// Wait for API response
+const responsePromise = page.waitForResponse(
+  (response) =>
+    response.url().includes("/api/users") && response.status() === 200,
+);
+await page.getByRole("button", { name: "Load Users" }).click();
+const response = await responsePromise;
+const data = await response.json();
+expect(data.users).toHaveLength(10);
+
+// Wait for multiple conditions
+await Promise.all([
+  page.waitForURL("/success"),
+  page.waitForLoadState("networkidle"),
+  expect(page.getByText("Payment successful")).toBeVisible(),
+]);
+```
+
+### Pattern 4: Network Mocking and Interception
+
+```typescript
+// Mock API responses
+test("displays error when API fails", async ({ page }) => {
+  await page.route("**/api/users", (route) => {
+    route.fulfill({
+      status: 500,
+      contentType: "application/json",
+      body: JSON.stringify({ error: "Internal Server Error" }),
+    });
+  });
+
+  await page.goto("/users");
+  await expect(page.getByText("Failed to load users")).toBeVisible();
+});
+
+// Intercept and modify requests
+test("can modify API request", async ({ page }) => {
+  await page.route("**/api/users", async (route) => {
+    const request = route.request();
+    const postData = JSON.parse(request.postData() || "{}");
+
+    // Modify request
+    postData.role = "admin";
+
+    await route.continue({
+      postData: JSON.stringify(postData),
+    });
+  });
+
+  // Test continues...
+});
+
+// Mock third-party services
+test("payment flow with mocked Stripe", async ({ page }) => {
+  await page.route("**/api/stripe/**", (route) => {
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify({
+        id: "mock_payment_id",
+        status: "succeeded",
+      }),
+    });
+  });
+
+  // Test payment flow with mocked response
+});
+```
+
+## Cypress Patterns
+
+### Setup and Configuration
+
+```typescript
+// cypress.config.ts
+import { defineConfig } from "cypress";
+
+export default defineConfig({
+  e2e: {
+    baseUrl: "http://localhost:3000",
+    viewportWidth: 1280,
+    viewportHeight: 720,
+    video: false,
+    screenshotOnRunFailure: true,
+    defaultCommandTimeout: 10000,
+    requestTimeout: 10000,
+    setupNodeEvents(on, config) {
+      // Implement node event listeners
+    },
+  },
+});
+```
+
+### Pattern 1: Custom Commands
+
+```typescript
+// cypress/support/commands.ts
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      login(email: string, password: string): Chainable<void>;
+      createUser(userData: UserData): Chainable<User>;
+      dataCy(value: string): Chainable<JQuery<HTMLElement>>;
+    }
+  }
+}
+
+Cypress.Commands.add("login", (email: string, password: string) => {
+  cy.visit("/login");
+  cy.get('[data-testid="email"]').type(email);
+  cy.get('[data-testid="password"]').type(password);
+  cy.get('[data-testid="login-button"]').click();
+  cy.url().should("include", "/dashboard");
+});
+
+Cypress.Commands.add("createUser", (userData: UserData) => {
+  return cy.request("POST", "/api/users", userData).its("body");
+});
+
+Cypress.Commands.add("dataCy", (value: string) => {
+  return cy.get(`[data-cy="${value}"]`);
+});
+
+// Usage
+cy.login("user@example.com", "password");
+cy.dataCy("submit-button").click();
+```
+
+### Pattern 2: Cypress Intercept
+
+```typescript
+// Mock API calls
+cy.intercept("GET", "/api/users", {
+  statusCode: 200,
+  body: [
+    { id: 1, name: "John" },
+    { id: 2, name: "Jane" },
+  ],
+}).as("getUsers");
+
+cy.visit("/users");
+cy.wait("@getUsers");
+cy.get('[data-testid="user-list"]').children().should("have.length", 2);
+
+// Modify responses
+cy.intercept("GET", "/api/users", (req) => {
+  req.reply((res) => {
+    // Modify response
+    res.body.users = res.body.users.slice(0, 5);
+    res.send();
+  });
+});
+
+// Simulate slow network
+cy.intercept("GET", "/api/data", (req) => {
+  req.reply((res) => {
+    res.delay(3000); // 3 second delay
+    res.send();
+  });
+});
+```
+
+## Advanced Patterns
+
+### Pattern 1: Visual Regression Testing
+
+```typescript
+// With Playwright
+import { test, expect } from "@playwright/test";
+
+test("homepage looks correct", async ({ page }) => {
+  await page.goto("/");
+  await expect(page).toHaveScreenshot("homepage.png", {
+    fullPage: true,
+    maxDiffPixels: 100,
+  });
+});
+
+test("button in all states", async ({ page }) => {
+  await page.goto("/components");
+
+  const button = page.getByRole("button", { name: "Submit" });
+
+  // Default state
+  await expect(button).toHaveScreenshot("button-default.png");
+
+  // Hover state
+  await button.hover();
+  await expect(button).toHaveScreenshot("button-hover.png");
+
+  // Disabled state
+  await button.evaluate((el) => el.setAttribute("disabled", "true"));
+  await expect(button).toHaveScreenshot("button-disabled.png");
+});
+```
+
+### Pattern 2: Parallel Testing with Sharding
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  projects: [
+    {
+      name: "shard-1",
+      use: { ...devices["Desktop Chrome"] },
+      grepInvert: /@slow/,
+      shard: { current: 1, total: 4 },
+    },
+    {
+      name: "shard-2",
+      use: { ...devices["Desktop Chrome"] },
+      shard: { current: 2, total: 4 },
+    },
+    // ... more shards
+  ],
+});
+
+// Run in CI
+// npx playwright test --shard=1/4
+// npx playwright test --shard=2/4
+```
+
+### Pattern 3: Accessibility Testing
+
+```typescript
+// Install: npm install @axe-core/playwright
+import { test, expect } from "@playwright/test";
+import AxeBuilder from "@axe-core/playwright";
+
+test("page should not have accessibility violations", async ({ page }) => {
+  await page.goto("/");
+
+  const accessibilityScanResults = await new AxeBuilder({ page })
+    .exclude("#third-party-widget")
+    .analyze();
+
+  expect(accessibilityScanResults.violations).toEqual([]);
+});
+
+test("form is accessible", async ({ page }) => {
+  await page.goto("/signup");
+
+  const results = await new AxeBuilder({ page }).include("form").analyze();
+
+  expect(results.violations).toEqual([]);
+});
+```
+
+## Best Practices
+
+1. **Use Data Attributes**: `data-testid` or `data-cy` for stable selectors
+2. **Avoid Brittle Selectors**: Don't rely on CSS classes or DOM structure
+3. **Test User Behavior**: Click, type, see - not implementation details
+4. **Keep Tests Independent**: Each test should run in isolation
+5. **Clean Up Test Data**: Create and destroy test data in each test
+6. **Use Page Objects**: Encapsulate page logic
+7. **Meaningful Assertions**: Check actual user-visible behavior
+8. **Optimize for Speed**: Mock when possible, parallel execution
+
+```typescript
+// ❌ Bad selectors
+cy.get(".btn.btn-primary.submit-button").click();
+cy.get("div > form > div:nth-child(2) > input").type("text");
+
+// ✅ Good selectors
+cy.getByRole("button", { name: "Submit" }).click();
+cy.getByLabel("Email address").type("user@example.com");
+cy.get('[data-testid="email-input"]').type("user@example.com");
+```
+
+## Common Pitfalls
+
+- **Flaky Tests**: Use proper waits, not fixed timeouts
+- **Slow Tests**: Mock external APIs, use parallel execution
+- **Over-Testing**: Don't test every edge case with E2E
+- **Coupled Tests**: Tests should not depend on each other
+- **Poor Selectors**: Avoid CSS classes and nth-child
+- **No Cleanup**: Clean up test data after each test
+- **Testing Implementation**: Test user behavior, not internals
+
+## Debugging Failing Tests
+
+```typescript
+// Playwright debugging
+// 1. Run in headed mode
+npx playwright test --headed
+
+// 2. Run in debug mode
+npx playwright test --debug
+
+// 3. Use trace viewer
+await page.screenshot({ path: 'screenshot.png' });
+await page.video()?.saveAs('video.webm');
+
+// 4. Add test.step for better reporting
+test('checkout flow', async ({ page }) => {
+    await test.step('Add item to cart', async () => {
+        await page.goto('/products');
+        await page.getByRole('button', { name: 'Add to Cart' }).click();
+    });
+
+    await test.step('Proceed to checkout', async () => {
+        await page.goto('/cart');
+        await page.getByRole('button', { name: 'Checkout' }).click();
+    });
+});
+
+// 5. Inspect page state
+await page.pause();  // Pauses execution, opens inspector
+```
diff --git a/builtin-skills/software-engineer/mobile-development/SKILL.md b/builtin-skills/software-engineer/mobile-development/SKILL.md
new file mode 100644
index 00000000..dad1e839
--- /dev/null
+++ b/builtin-skills/software-engineer/mobile-development/SKILL.md
@@ -0,0 +1,261 @@
+---
+# ═══════════════════════════════════════════════════════════════════════════
+# SKILL: Mobile Development
+# Version: 2.0.0 | Updated: 2025-01
+# ═══════════════════════════════════════════════════════════════════════════
+name: mobile-development
+description: iOS (Swift, SwiftUI), Android (Kotlin, Compose), cross-platform (Flutter, React Native), and game development (Unity, Unreal).
+
+# ACTIVATION TRIGGERS
+triggers:
+  - ios
+  - android
+  - flutter
+  - react native
+  - mobile
+  - swift
+  - kotlin
+  - unity
+  - game development
+
+# SKILL PARAMETERS
+parameters:
+  platform:
+    type: string
+    enum: [ios, android, cross-platform, games]
+    required: true
+  project_type:
+    type: string
+    required: false
+    description: Type of app (social, productivity, game, etc.)
+
+# OUTPUT SPECIFICATION
+outputs:
+  recommended_stack:
+    type: object
+  learning_path:
+    type: array
+  portfolio_projects:
+    type: array
+
+# RELIABILITY
+retry:
+  max_attempts: 3
+  backoff: exponential
+
+# OBSERVABILITY
+observability:
+  log_level: info
+
+level: advanced
+prerequisites:
+  - core-development
+
+sasmp_version: "1.3.0"
+bonded_agent: 01-core-paths
+bond_type: PRIMARY_BOND
+---
+
+# Mobile Development Skill
+
+## Quick Reference
+
+| Platform | Language | Framework | Timeline | Job Market |
+|----------|----------|-----------|----------|------------|
+| **iOS** | Swift | SwiftUI | 6-9 mo | High |
+| **Android** | Kotlin | Compose | 6-9 mo | High |
+| **Cross-Platform** | Dart | Flutter | 4-6 mo | Growing |
+| **Games** | C# | Unity | 12-24 mo | Moderate |
+
+---
+
+## Learning Paths
+
+### iOS Development
+```
+[1] Swift Fundamentals (4-6 wk)
+ │  └─ Types, optionals, closures, protocols
+ │
+ ▼
+[2] SwiftUI (4-6 wk)
+ │  └─ Views, modifiers, state, binding
+ │
+ ▼
+[3] Navigation + Data (3-4 wk)
+ │  └─ NavigationStack, SwiftData/Core Data
+ │
+ ▼
+[4] Networking + Async (2-3 wk)
+ │  └─ URLSession, async/await, Combine
+ │
+ ▼
+[5] Testing + App Store (2 wk)
+    └─ XCTest, TestFlight, submission
+```
+
+**2025 Stack:** Swift 5.10 + SwiftUI + SwiftData + Xcode 16
+
+---
+
+### Android Development
+```
+[1] Kotlin Fundamentals (4-6 wk)
+ │  └─ Null safety, coroutines, data classes
+ │
+ ▼
+[2] Jetpack Compose (4-6 wk)
+ │  └─ Composables, state, effects
+ │
+ ▼
+[3] Architecture (3-4 wk)
+ │  └─ MVVM, Room, Navigation
+ │
+ ▼
+[4] Networking + DI (2-3 wk)
+ │  └─ Retrofit, Hilt, Flow
+ │
+ ▼
+[5] Testing + Play Store (2 wk)
+    └─ JUnit, Espresso, release
+```
+
+**2025 Stack:** Kotlin 2.0 + Jetpack Compose + Room + Hilt
+
+---
+
+### Flutter (Cross-Platform)
+```
+[1] Dart Fundamentals (2-3 wk)
+ │
+ ▼
+[2] Flutter Widgets (3-4 wk)
+ │
+ ▼
+[3] State Management (2-3 wk)
+ │  └─ Riverpod or Bloc
+ │
+ ▼
+[4] Backend Integration (2 wk)
+ │  └─ Firebase, REST APIs
+ │
+ ▼
+[5] Deploy to Both Stores (1 wk)
+```
+
+**2025 Stack:** Flutter 3.x + Dart 3.x + Riverpod + Firebase
+
+---
+
+### Game Development
+```
+[1] Game Basics (4-6 wk)
+ │  └─ Game loop, input handling
+ │
+ ▼
+[2] Unity/C# Fundamentals (6-8 wk)
+ │  └─ GameObjects, Components, Scripts
+ │
+ ▼
+[3] Physics + Graphics (4-6 wk)
+ │  └─ Rigidbody, colliders, shaders
+ │
+ ▼
+[4] Audio + Polish (2-4 wk)
+ │
+ ▼
+[5] Publish (ongoing)
+    └─ Steam, App Store, Play Store
+```
+
+**2025 Stack:** Unity 6 LTS + C# OR Unreal 5.4 + C++
+
+---
+
+## Platform Decision Tree
+
+```
+Which platform?
+│
+├─► Apple ecosystem only?
+│   └─► iOS (Swift + SwiftUI)
+│
+├─► Android ecosystem only?
+│   └─► Android (Kotlin + Compose)
+│
+├─► Both platforms?
+│   ├─► Performance-critical? → Native for both
+│   ├─► Budget/time limited? → Flutter
+│   └─► Web developer background? → React Native
+│
+└─► Making games?
+    ├─► 2D/3D indie → Unity
+    ├─► AAA quality → Unreal
+    └─► Simple 2D → Godot
+```
+
+---
+
+## Game Engine Comparison
+
+| Engine | Market | Language | Learning | Best For |
+|--------|--------|----------|----------|----------|
+| **Unity** | 51% | C# | Medium | Indie, mobile, VR |
+| **Unreal** | 31% | C++/BP | Hard | AAA, high-fidelity |
+| **Godot** | 10% | GDScript | Easy | Indie, 2D |
+
+---
+
+## Troubleshooting
+
+```
+Native vs Cross-platform?
+├─► Need platform-specific APIs (HealthKit, ARCore)? → Native
+├─► Performance-critical (AR/VR, complex animations)? → Native
+├─► Budget or time limited? → Flutter
+├─► Team knows JavaScript? → React Native
+└─► Starting from scratch? → Flutter (best DX)
+
+Simulator works, device doesn't?
+├─► Missing entitlements/capabilities?
+├─► Different iOS/Android version?
+├─► Network connectivity issues?
+└─► Always test on real devices from day 1
+
+App rejected by store?
+├─► Read rejection reason carefully
+├─► Check App Store Review Guidelines
+├─► Most common: metadata issues, crashes, spam
+└─► Appeal if unjustified
+```
+
+---
+
+## Common Failure Modes
+
+| Symptom | Root Cause | Recovery |
+|---------|------------|----------|
+| Slow UI | Too many recompositions | Profile, optimize state |
+| Memory leaks | Not cleaning up resources | Use lifecycle-aware components |
+| App rejected | Guidelines violation | Read guidelines BEFORE building |
+| Game stutters | Draw call overhead | Object pooling, LOD, batching |
+
+---
+
+## Portfolio Projects
+
+### Mobile (Progressive)
+1. **Todo App** - CRUD basics
+2. **Weather App** - API integration
+3. **Chat App** - Real-time, auth
+4. **Payment App** - Stripe, security
+
+### Games
+1. **2D Platformer** - Physics basics
+2. **3D Runner** - 3D graphics, particles
+3. **Multiplayer Game** - Networking
+
+---
+
+## Next Actions
+
+Specify your target platform for a detailed learning plan.
diff --git a/builtin-skills/software-engineer/mobile-development/references/MOBILE_GUIDE.md b/builtin-skills/software-engineer/mobile-development/references/MOBILE_GUIDE.md
new file mode 100644
index 00000000..c1b17dca
--- /dev/null
+++ b/builtin-skills/software-engineer/mobile-development/references/MOBILE_GUIDE.md
@@ -0,0 +1,73 @@
+# Mobile Development Guide for Cloudflare
+
+## PWA on Cloudflare Pages
+
+```json
+// manifest.json
+{
+  "name": "My PWA",
+  "short_name": "PWA",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#f38020",
+  "icons": [
+    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
+  ]
+}
+```
+
+## Service Worker with Cloudflare
+
+```typescript
+// sw.ts - Offline-first strategy
+const CACHE_NAME = 'v1';
+const OFFLINE_URL = '/offline.html';
+
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => {
+      return cache.addAll([OFFLINE_URL, '/', '/styles.css']);
+    })
+  );
+});
+
+self.addEventListener('fetch', (event) => {
+  event.respondWith(
+    fetch(event.request).catch(() => caches.match(OFFLINE_URL))
+  );
+});
+```
+
+## Mobile API with Workers
+
+```typescript
+// Optimized for mobile clients
+export default {
+  async fetch(request: Request, env: Env) {
+    const userAgent = request.headers.get('User-Agent') || '';
+    const isMobile = /Mobile|Android|iPhone/i.test(userAgent);
+
+    return Response.json({
+      data: await getData(env),
+      optimized: isMobile ? 'mobile' : 'desktop'
+    }, {
+      headers: {
+        'Cache-Control': isMobile ? 'max-age=300' : 'max-age=3600'
+      }
+    });
+  }
+};
+```
+
+## Deployment
+
+```bash
+# Deploy to Cloudflare Pages
+npx wrangler pages deploy dist --project-name=my-pwa
+```
+
+---
+
+*Cloudflare Plugin - Mobile Development Skill*
diff --git a/builtin-skills/software-engineer/openapi-spec-generation/SKILL.md b/builtin-skills/software-engineer/openapi-spec-generation/SKILL.md
new file mode 100644
index 00000000..e9531331
--- /dev/null
+++ b/builtin-skills/software-engineer/openapi-spec-generation/SKILL.md
@@ -0,0 +1,1017 @@
+---
+name: openapi-spec-generation
+description: Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns. Use when creating API documentation, generating SDKs, or ensuring API contract compliance.
+---
+
+# OpenAPI Spec Generation
+
+Comprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.
+
+## When to Use This Skill
+
+- Creating API documentation from scratch
+- Generating OpenAPI specs from existing code
+- Designing API contracts (design-first approach)
+- Validating API implementations against specs
+- Generating client SDKs from specs
+- Setting up API documentation portals
+
+## Core Concepts
+
+### 1. OpenAPI 3.1 Structure
+
+```yaml
+openapi: 3.1.0
+info:
+  title: API Title
+  version: 1.0.0
+servers:
+  - url: https://api.example.com/v1
+paths:
+  /resources:
+    get: ...
+components:
+  schemas: ...
+  securitySchemes: ...
+```
+
+### 2. Design Approaches
+
+| Approach         | Description                  | Best For            |
+| ---------------- | ---------------------------- | ------------------- |
+| **Design-First** | Write spec before code       | New APIs, contracts |
+| **Code-First**   | Generate spec from code      | Existing APIs       |
+| **Hybrid**       | Annotate code, generate spec | Evolving APIs       |
+
+## Templates
+
+### Template 1: Complete API Specification
+
+```yaml
+openapi: 3.1.0
+info:
+  title: User Management API
+  description: |
+    API for managing users and their profiles.
+
+    ## Authentication
+    All endpoints require Bearer token authentication.
+
+    ## Rate Limiting
+    - 1000 requests per minute for standard tier
+    - 10000 requests per minute for enterprise tier
+  version: 2.0.0
+  contact:
+    name: API Support
+    email: api-support@example.com
+    url: https://docs.example.com
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+
+servers:
+  - url: https://api.example.com/v2
+    description: Production
+  - url: https://staging-api.example.com/v2
+    description: Staging
+  - url: http://localhost:3000/v2
+    description: Local development
+
+tags:
+  - name: Users
+    description: User management operations
+  - name: Profiles
+    description: User profile operations
+  - name: Admin
+    description: Administrative operations
+
+paths:
+  /users:
+    get:
+      operationId: listUsers
+      summary: List all users
+      description: Returns a paginated list of users with optional filtering.
+      tags:
+        - Users
+      parameters:
+        - $ref: "#/components/parameters/PageParam"
+        - $ref: "#/components/parameters/LimitParam"
+        - name: status
+          in: query
+          description: Filter by user status
+          schema:
+            $ref: "#/components/schemas/UserStatus"
+        - name: search
+          in: query
+          description: Search by name or email
+          schema:
+            type: string
+            minLength: 2
+            maxLength: 100
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UserListResponse"
+              examples:
+                default:
+                  $ref: "#/components/examples/UserListExample"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+      security:
+        - bearerAuth: []
+
+    post:
+      operationId: createUser
+      summary: Create a new user
+      description: Creates a new user account and sends welcome email.
+      tags:
+        - Users
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateUserRequest"
+            examples:
+              standard:
+                summary: Standard user
+                value:
+                  email: user@example.com
+                  name: John Doe
+                  role: user
+              admin:
+                summary: Admin user
+                value:
+                  email: admin@example.com
+                  name: Admin User
+                  role: admin
+      responses:
+        "201":
+          description: User created successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/User"
+          headers:
+            Location:
+              description: URL of created user
+              schema:
+                type: string
+                format: uri
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "409":
+          description: Email already exists
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+      security:
+        - bearerAuth: []
+
+  /users/{userId}:
+    parameters:
+      - $ref: "#/components/parameters/UserIdParam"
+
+    get:
+      operationId: getUser
+      summary: Get user by ID
+      tags:
+        - Users
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/User"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      security:
+        - bearerAuth: []
+
+    patch:
+      operationId: updateUser
+      summary: Update user
+      tags:
+        - Users
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateUserRequest"
+      responses:
+        "200":
+          description: User updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/User"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      security:
+        - bearerAuth: []
+
+    delete:
+      operationId: deleteUser
+      summary: Delete user
+      tags:
+        - Users
+        - Admin
+      responses:
+        "204":
+          description: User deleted
+        "404":
+          $ref: "#/components/responses/NotFound"
+      security:
+        - bearerAuth: []
+        - apiKey: []
+
+components:
+  schemas:
+    User:
+      type: object
+      required:
+        - id
+        - email
+        - name
+        - status
+        - createdAt
+      properties:
+        id:
+          type: string
+          format: uuid
+          readOnly: true
+          description: Unique user identifier
+        email:
+          type: string
+          format: email
+          description: User email address
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+          description: User display name
+        status:
+          $ref: "#/components/schemas/UserStatus"
+        role:
+          type: string
+          enum: [user, moderator, admin]
+          default: user
+        avatar:
+          type: string
+          format: uri
+          nullable: true
+        metadata:
+          type: object
+          additionalProperties: true
+          description: Custom metadata
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+        updatedAt:
+          type: string
+          format: date-time
+          readOnly: true
+
+    UserStatus:
+      type: string
+      enum: [active, inactive, suspended, pending]
+      description: User account status
+
+    CreateUserRequest:
+      type: object
+      required:
+        - email
+        - name
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+        role:
+          type: string
+          enum: [user, moderator, admin]
+          default: user
+        metadata:
+          type: object
+          additionalProperties: true
+
+    UpdateUserRequest:
+      type: object
+      minProperties: 1
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+        status:
+          $ref: "#/components/schemas/UserStatus"
+        role:
+          type: string
+          enum: [user, moderator, admin]
+        metadata:
+          type: object
+          additionalProperties: true
+
+    UserListResponse:
+      type: object
+      required:
+        - data
+        - pagination
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/User"
+        pagination:
+          $ref: "#/components/schemas/Pagination"
+
+    Pagination:
+      type: object
+      required:
+        - page
+        - limit
+        - total
+        - totalPages
+      properties:
+        page:
+          type: integer
+          minimum: 1
+        limit:
+          type: integer
+          minimum: 1
+          maximum: 100
+        total:
+          type: integer
+          minimum: 0
+        totalPages:
+          type: integer
+          minimum: 0
+        hasNext:
+          type: boolean
+        hasPrev:
+          type: boolean
+
+    Error:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: string
+          description: Error code for programmatic handling
+        message:
+          type: string
+          description: Human-readable error message
+        details:
+          type: array
+          items:
+            type: object
+            properties:
+              field:
+                type: string
+              message:
+                type: string
+        requestId:
+          type: string
+          description: Request ID for support
+
+  parameters:
+    UserIdParam:
+      name: userId
+      in: path
+      required: true
+      description: User ID
+      schema:
+        type: string
+        format: uuid
+
+    PageParam:
+      name: page
+      in: query
+      description: Page number (1-based)
+      schema:
+        type: integer
+        minimum: 1
+        default: 1
+
+    LimitParam:
+      name: limit
+      in: query
+      description: Items per page
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 20
+
+  responses:
+    BadRequest:
+      description: Invalid request
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+          example:
+            code: VALIDATION_ERROR
+            message: Invalid request parameters
+            details:
+              - field: email
+                message: Must be a valid email address
+
+    Unauthorized:
+      description: Authentication required
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+          example:
+            code: UNAUTHORIZED
+            message: Authentication required
+
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+          example:
+            code: NOT_FOUND
+            message: User not found
+
+    RateLimited:
+      description: Too many requests
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+      headers:
+        Retry-After:
+          description: Seconds until rate limit resets
+          schema:
+            type: integer
+        X-RateLimit-Limit:
+          description: Request limit per window
+          schema:
+            type: integer
+        X-RateLimit-Remaining:
+          description: Remaining requests in window
+          schema:
+            type: integer
+
+  examples:
+    UserListExample:
+      value:
+        data:
+          - id: "550e8400-e29b-41d4-a716-446655440000"
+            email: "john@example.com"
+            name: "John Doe"
+            status: "active"
+            role: "user"
+            createdAt: "2024-01-15T10:30:00Z"
+        pagination:
+          page: 1
+          limit: 20
+          total: 1
+          totalPages: 1
+          hasNext: false
+          hasPrev: false
+
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: JWT token from /auth/login
+
+    apiKey:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: API key for service-to-service calls
+
+security:
+  - bearerAuth: []
+```
+
+### Template 2: Code-First Generation (Python/FastAPI)
+
+```python
+# FastAPI with automatic OpenAPI generation
+from fastapi import FastAPI, HTTPException, Query, Path, Depends
+from pydantic import BaseModel, Field, EmailStr
+from typing import Optional, List
+from datetime import datetime
+from uuid import UUID
+from enum import Enum
+
+app = FastAPI(
+    title="User Management API",
+    description="API for managing users and profiles",
+    version="2.0.0",
+    openapi_tags=[
+        {"name": "Users", "description": "User operations"},
+        {"name": "Profiles", "description": "Profile operations"},
+    ],
+    servers=[
+        {"url": "https://api.example.com/v2", "description": "Production"},
+        {"url": "http://localhost:8000", "description": "Development"},
+    ],
+)
+
+# Enums
+class UserStatus(str, Enum):
+    active = "active"
+    inactive = "inactive"
+    suspended = "suspended"
+    pending = "pending"
+
+class UserRole(str, Enum):
+    user = "user"
+    moderator = "moderator"
+    admin = "admin"
+
+# Models
+class UserBase(BaseModel):
+    email: EmailStr = Field(..., description="User email address")
+    name: str = Field(..., min_length=1, max_length=100, description="Display name")
+
+class UserCreate(UserBase):
+    role: UserRole = Field(default=UserRole.user)
+    metadata: Optional[dict] = Field(default=None, description="Custom metadata")
+
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "email": "user@example.com",
+                    "name": "John Doe",
+                    "role": "user"
+                }
+            ]
+        }
+    }
+
+class UserUpdate(BaseModel):
+    name: Optional[str] = Field(None, min_length=1, max_length=100)
+    status: Optional[UserStatus] = None
+    role: Optional[UserRole] = None
+    metadata: Optional[dict] = None
+
+class User(UserBase):
+    id: UUID = Field(..., description="Unique identifier")
+    status: UserStatus
+    role: UserRole
+    avatar: Optional[str] = Field(None, description="Avatar URL")
+    metadata: Optional[dict] = None
+    created_at: datetime = Field(..., alias="createdAt")
+    updated_at: Optional[datetime] = Field(None, alias="updatedAt")
+
+    model_config = {"populate_by_name": True}
+
+class Pagination(BaseModel):
+    page: int = Field(..., ge=1)
+    limit: int = Field(..., ge=1, le=100)
+    total: int = Field(..., ge=0)
+    total_pages: int = Field(..., ge=0, alias="totalPages")
+    has_next: bool = Field(..., alias="hasNext")
+    has_prev: bool = Field(..., alias="hasPrev")
+
+class UserListResponse(BaseModel):
+    data: List[User]
+    pagination: Pagination
+
+class ErrorDetail(BaseModel):
+    field: str
+    message: str
+
+class ErrorResponse(BaseModel):
+    code: str = Field(..., description="Error code")
+    message: str = Field(..., description="Error message")
+    details: Optional[List[ErrorDetail]] = None
+    request_id: Optional[str] = Field(None, alias="requestId")
+
+# Endpoints
+@app.get(
+    "/users",
+    response_model=UserListResponse,
+    tags=["Users"],
+    summary="List all users",
+    description="Returns a paginated list of users with optional filtering.",
+    responses={
+        400: {"model": ErrorResponse, "description": "Invalid request"},
+        401: {"model": ErrorResponse, "description": "Unauthorized"},
+    },
+)
+async def list_users(
+    page: int = Query(1, ge=1, description="Page number"),
+    limit: int = Query(20, ge=1, le=100, description="Items per page"),
+    status: Optional[UserStatus] = Query(None, description="Filter by status"),
+    search: Optional[str] = Query(None, min_length=2, max_length=100),
+):
+    """
+    List users with pagination and filtering.
+
+    - **page**: Page number (1-based)
+    - **limit**: Number of items per page (max 100)
+    - **status**: Filter by user status
+    - **search**: Search by name or email
+    """
+    # Implementation
+    pass
+
+@app.post(
+    "/users",
+    response_model=User,
+    status_code=201,
+    tags=["Users"],
+    summary="Create a new user",
+    responses={
+        400: {"model": ErrorResponse},
+        409: {"model": ErrorResponse, "description": "Email already exists"},
+    },
+)
+async def create_user(user: UserCreate):
+    """Create a new user and send welcome email."""
+    pass
+
+@app.get(
+    "/users/{user_id}",
+    response_model=User,
+    tags=["Users"],
+    summary="Get user by ID",
+    responses={404: {"model": ErrorResponse}},
+)
+async def get_user(
+    user_id: UUID = Path(..., description="User ID"),
+):
+    """Retrieve a specific user by their ID."""
+    pass
+
+@app.patch(
+    "/users/{user_id}",
+    response_model=User,
+    tags=["Users"],
+    summary="Update user",
+    responses={
+        400: {"model": ErrorResponse},
+        404: {"model": ErrorResponse},
+    },
+)
+async def update_user(
+    user_id: UUID = Path(..., description="User ID"),
+    user: UserUpdate = ...,
+):
+    """Update user attributes."""
+    pass
+
+@app.delete(
+    "/users/{user_id}",
+    status_code=204,
+    tags=["Users", "Admin"],
+    summary="Delete user",
+    responses={404: {"model": ErrorResponse}},
+)
+async def delete_user(
+    user_id: UUID = Path(..., description="User ID"),
+):
+    """Permanently delete a user."""
+    pass
+
+# Export OpenAPI spec
+if __name__ == "__main__":
+    import json
+    print(json.dumps(app.openapi(), indent=2))
+```
+
+### Template 3: Code-First (TypeScript/Express with tsoa)
+
+```typescript
+// tsoa generates OpenAPI from TypeScript decorators
+
+import {
+  Controller,
+  Get,
+  Post,
+  Patch,
+  Delete,
+  Route,
+  Path,
+  Query,
+  Body,
+  Response,
+  SuccessResponse,
+  Tags,
+  Security,
+  Example,
+} from "tsoa";
+
+// Models
+interface User {
+  /** Unique identifier */
+  id: string;
+  /** User email address */
+  email: string;
+  /** Display name */
+  name: string;
+  status: UserStatus;
+  role: UserRole;
+  /** Avatar URL */
+  avatar?: string;
+  /** Custom metadata */
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt?: Date;
+}
+
+enum UserStatus {
+  Active = "active",
+  Inactive = "inactive",
+  Suspended = "suspended",
+  Pending = "pending",
+}
+
+enum UserRole {
+  User = "user",
+  Moderator = "moderator",
+  Admin = "admin",
+}
+
+interface CreateUserRequest {
+  email: string;
+  name: string;
+  role?: UserRole;
+  metadata?: Record<string, unknown>;
+}
+
+interface UpdateUserRequest {
+  name?: string;
+  status?: UserStatus;
+  role?: UserRole;
+  metadata?: Record<string, unknown>;
+}
+
+interface Pagination {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+
+interface UserListResponse {
+  data: User[];
+  pagination: Pagination;
+}
+
+interface ErrorResponse {
+  code: string;
+  message: string;
+  details?: { field: string; message: string }[];
+  requestId?: string;
+}
+
+@Route("users")
+@Tags("Users")
+export class UsersController extends Controller {
+  /**
+   * List all users with pagination and filtering
+   * @param page Page number (1-based)
+   * @param limit Items per page (max 100)
+   * @param status Filter by user status
+   * @param search Search by name or email
+   */
+  @Get()
+  @Security("bearerAuth")
+  @Response<ErrorResponse>(400, "Invalid request")
+  @Response<ErrorResponse>(401, "Unauthorized")
+  @Example<UserListResponse>({
+    data: [
+      {
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        email: "john@example.com",
+        name: "John Doe",
+        status: UserStatus.Active,
+        role: UserRole.User,
+        createdAt: new Date("2024-01-15T10:30:00Z"),
+      },
+    ],
+    pagination: {
+      page: 1,
+      limit: 20,
+      total: 1,
+      totalPages: 1,
+      hasNext: false,
+      hasPrev: false,
+    },
+  })
+  public async listUsers(
+    @Query() page: number = 1,
+    @Query() limit: number = 20,
+    @Query() status?: UserStatus,
+    @Query() search?: string,
+  ): Promise<UserListResponse> {
+    // Implementation
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Create a new user
+   */
+  @Post()
+  @Security("bearerAuth")
+  @SuccessResponse(201, "Created")
+  @Response<ErrorResponse>(400, "Invalid request")
+  @Response<ErrorResponse>(409, "Email already exists")
+  public async createUser(@Body() body: CreateUserRequest): Promise<User> {
+    this.setStatus(201);
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Get user by ID
+   * @param userId User ID
+   */
+  @Get("{userId}")
+  @Security("bearerAuth")
+  @Response<ErrorResponse>(404, "User not found")
+  public async getUser(@Path() userId: string): Promise<User> {
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Update user attributes
+   * @param userId User ID
+   */
+  @Patch("{userId}")
+  @Security("bearerAuth")
+  @Response<ErrorResponse>(400, "Invalid request")
+  @Response<ErrorResponse>(404, "User not found")
+  public async updateUser(
+    @Path() userId: string,
+    @Body() body: UpdateUserRequest,
+  ): Promise<User> {
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Delete user
+   * @param userId User ID
+   */
+  @Delete("{userId}")
+  @Tags("Users", "Admin")
+  @Security("bearerAuth")
+  @SuccessResponse(204, "Deleted")
+  @Response<ErrorResponse>(404, "User not found")
+  public async deleteUser(@Path() userId: string): Promise<void> {
+    this.setStatus(204);
+  }
+}
+```
+
+### Template 4: Validation & Linting
+
+```bash
+# Install validation tools
+npm install -g @stoplight/spectral-cli
+npm install -g @redocly/cli
+
+# Spectral ruleset (.spectral.yaml)
+cat > .spectral.yaml << 'EOF'
+extends: ["spectral:oas", "spectral:asyncapi"]
+
+rules:
+  # Enforce operation IDs
+  operation-operationId: error
+
+  # Require descriptions
+  operation-description: warn
+  info-description: error
+
+  # Naming conventions
+  operation-operationId-valid-in-url: true
+
+  # Security
+  operation-security-defined: error
+
+  # Response codes
+  operation-success-response: error
+
+  # Custom rules
+  path-params-snake-case:
+    description: Path parameters should be snake_case
+    severity: warn
+    given: "$.paths[*].parameters[?(@.in == 'path')].name"
+    then:
+      function: pattern
+      functionOptions:
+        match: "^[a-z][a-z0-9_]*$"
+
+  schema-properties-camelCase:
+    description: Schema properties should be camelCase
+    severity: warn
+    given: "$.components.schemas[*].properties[*]~"
+    then:
+      function: casing
+      functionOptions:
+        type: camel
+EOF
+
+# Run Spectral
+spectral lint openapi.yaml
+
+# Redocly config (redocly.yaml)
+cat > redocly.yaml << 'EOF'
+extends:
+  - recommended
+
+rules:
+  no-invalid-media-type-examples: error
+  no-invalid-schema-examples: error
+  operation-4xx-response: warn
+  request-mime-type:
+    severity: error
+    allowedValues:
+      - application/json
+  response-mime-type:
+    severity: error
+    allowedValues:
+      - application/json
+      - application/problem+json
+
+theme:
+  openapi:
+    generateCodeSamples:
+      languages:
+        - lang: curl
+        - lang: python
+        - lang: javascript
+EOF
+
+# Run Redocly
+redocly lint openapi.yaml
+redocly bundle openapi.yaml -o bundled.yaml
+redocly preview-docs openapi.yaml
+```
+
+## SDK Generation
+
+```bash
+# OpenAPI Generator
+npm install -g @openapitools/openapi-generator-cli
+
+# Generate TypeScript client
+openapi-generator-cli generate \
+  -i openapi.yaml \
+  -g typescript-fetch \
+  -o ./generated/typescript-client \
+  --additional-properties=supportsES6=true,npmName=@myorg/api-client
+
+# Generate Python client
+openapi-generator-cli generate \
+  -i openapi.yaml \
+  -g python \
+  -o ./generated/python-client \
+  --additional-properties=packageName=api_client
+
+# Generate Go client
+openapi-generator-cli generate \
+  -i openapi.yaml \
+  -g go \
+  -o ./generated/go-client
+```
+
+## Best Practices
+
+### Do's
+
+- **Use $ref** - Reuse schemas, parameters, responses
+- **Add examples** - Real-world values help consumers
+- **Document errors** - All possible error codes
+- **Version your API** - In URL or header
+- **Use semantic versioning** - For spec changes
+
+### Don'ts
+
+- **Don't use generic descriptions** - Be specific
+- **Don't skip security** - Define all schemes
+- **Don't forget nullable** - Be explicit about null
+- **Don't mix styles** - Consistent naming throughout
+- **Don't hardcode URLs** - Use server variables
diff --git a/builtin-skills/software-engineer/optimize-cicd-pipeline/SKILL.md b/builtin-skills/software-engineer/optimize-cicd-pipeline/SKILL.md
new file mode 100644
index 00000000..3f2d00ec
--- /dev/null
+++ b/builtin-skills/software-engineer/optimize-cicd-pipeline/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: optimize-cicd-pipeline
+description: Analyzes CI/CD pipelines to identify common antipatterns (like slow feedback loops or sequential steps) and recommends best practice patterns (like build images, parallelization, and build-once-deploy-anywhere). Use when designing, auditing, or troubleshooting CI/CD workflows to improve speed and reliability.
+---
+
+# Optimize CI/CD Pipeline
+
+This skill provides a framework for auditing and improving CI/CD pipelines. The primary goal of any pipeline optimization is to **shorten the feedback loop**. The faster a developer knows something is wrong, the cheaper it is to fix.
+
+## Usage Instructions
+
+When analyzing a pipeline configuration or advising on DevOps practices, compare the user's current setup against the Antipatterns below. If an antipattern is detected, recommend the corresponding Pattern.
+
+### 1. Core Philosophy Checklist
+- [ ] **Feedback Loop**: Is the time from "commit" to "failure notification" under 10 minutes?
+- [ ] **Reproducibility**: Can a developer run the exact same build command locally?
+- [ ] **Maintenance**: Is the pipeline treated as a software product (versioned, refactored, maintained)?
+
+### 2. Pattern Analysis
+
+Use this table to diagnose issues and prescribe solutions:
+
+| Detection (Antipattern) | Solution (Pattern) | Implementation Advice |
+| :--- | :--- | :--- |
+| **Installing tools on every run**<br>Build logs show repeated `npm install`, `apt-get install`, or downloading CLI tools. | **Use Build Images** | Pre-bake all dependencies into a Docker image. Use this image as the build agent/runner so the environment is instant. |
+| **Sequential Steps**<br>Test, Lint, and Build run one after another. Total time = Sum of all steps. | **Parallelization (Fan-out)** | Run independent tasks simultaneously. Total time = Length of the slowest task. |
+| **Rebuilding per Environment**<br>Code is compiled separately for "Test", "Staging", and "Prod". | **Build Once, Deploy Anywhere** | Build a single binary/artifact at the start. Promote that exact artifact through all environments to ensure consistency. |
+| **Publishing on every run**<br>Artifact repository is flooded with broken or untested builds. | **Publish on Success** | Only push artifacts to the registry after all quality gates (linting, testing) have passed. |
+| **Slow Feedback / Late Failures**<br>Syntax errors or linting issues are caught at the end of a long build. | **Fail Fast** | Reorder steps: Run the fastest checks (linting, unit tests) first. Do not run expensive integration tests if basic checks fail. |
+| **"Works on My Machine"**<br>Pipeline fails but local build succeeds (or vice versa). | **Pipeline as Code** | Define infrastructure in code (Dockerfiles, YAML). Ensure local scripts match pipeline commands exactly. |
+
+## Common Recommendations
+
+1. **Target Time**: If a pipeline takes >15 minutes, productivity drops due to context switching. Aggressively optimize parallelization.
+2. **Environment Consistency**: Never allow the CI server environment to drift from the developer's local environment.
+3. **Drafting Pipelines**: Always start by defining the "Happy Path" (success state), then add the necessary gates to protect it.
diff --git a/builtin-skills/software-engineer/senior-architect/SKILL.md b/builtin-skills/software-engineer/senior-architect/SKILL.md
new file mode 100644
index 00000000..e57e6bb0
--- /dev/null
+++ b/builtin-skills/software-engineer/senior-architect/SKILL.md
@@ -0,0 +1,343 @@
+---
+name: "senior-architect"
+description: This skill should be used when the user asks to "design system architecture", "evaluate microservices vs monolith", "create architecture diagrams", "analyze dependencies", "choose a database", "plan for scalability", "make technical decisions", or "review system design". Use for architecture decision records (ADRs), tech stack evaluation, system design reviews, dependency analysis, and generating architecture diagrams in Mermaid, PlantUML, or ASCII format.
+---
+
+# Senior Architect
+
+Architecture design and analysis tools for making informed technical decisions.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Tools Overview](#tools-overview)
+  - [Architecture Diagram Generator](#1-architecture-diagram-generator)
+  - [Dependency Analyzer](#2-dependency-analyzer)
+  - [Project Architect](#3-project-architect)
+- [Decision Workflows](#decision-workflows)
+  - [Database Selection](#database-selection-workflow)
+  - [Architecture Pattern Selection](#architecture-pattern-selection-workflow)
+  - [Monolith vs Microservices](#monolith-vs-microservices-decision)
+- [Reference Documentation](#reference-documentation)
+- [Tech Stack Coverage](#tech-stack-coverage)
+- [Common Commands](#common-commands)
+
+---
+
+## Quick Start
+
+```bash
+# Generate architecture diagram from project
+python scripts/architecture_diagram_generator.py ./my-project --format mermaid
+
+# Analyze dependencies for issues
+python scripts/dependency_analyzer.py ./my-project --output json
+
+# Get architecture assessment
+python scripts/project_architect.py ./my-project --verbose
+```
+
+---
+
+## Tools Overview
+
+### 1. Architecture Diagram Generator
+
+Generates architecture diagrams from project structure in multiple formats.
+
+**Solves:** "I need to visualize my system architecture for documentation or team discussion"
+
+**Input:** Project directory path
+**Output:** Diagram code (Mermaid, PlantUML, or ASCII)
+
+**Supported diagram types:**
+- `component` - Shows modules and their relationships
+- `layer` - Shows architectural layers (presentation, business, data)
+- `deployment` - Shows deployment topology
+
+**Usage:**
+```bash
+# Mermaid format (default)
+python scripts/architecture_diagram_generator.py ./project --format mermaid --type component
+
+# PlantUML format
+python scripts/architecture_diagram_generator.py ./project --format plantuml --type layer
+
+# ASCII format (terminal-friendly)
+python scripts/architecture_diagram_generator.py ./project --format ascii
+
+# Save to file
+python scripts/architecture_diagram_generator.py ./project -o architecture.md
+```
+
+**Example output (Mermaid):**
+```mermaid
+graph TD
+    A[API Gateway] --> B[Auth Service]
+    A --> C[User Service]
+    B --> D[(PostgreSQL)]
+    C --> D
+```
+
+---
+
+### 2. Dependency Analyzer
+
+Analyzes project dependencies for coupling, circular dependencies, and outdated packages.
+
+**Solves:** "I need to understand my dependency tree and identify potential issues"
+
+**Input:** Project directory path
+**Output:** Analysis report (JSON or human-readable)
+
+**Analyzes:**
+- Dependency tree (direct and transitive)
+- Circular dependencies between modules
+- Coupling score (0-100)
+- Outdated packages
+
+**Supported package managers:**
+- npm/yarn (`package.json`)
+- Python (`requirements.txt`, `pyproject.toml`)
+- Go (`go.mod`)
+- Rust (`Cargo.toml`)
+
+**Usage:**
+```bash
+# Human-readable report
+python scripts/dependency_analyzer.py ./project
+
+# JSON output for CI/CD integration
+python scripts/dependency_analyzer.py ./project --output json
+
+# Check only for circular dependencies
+python scripts/dependency_analyzer.py ./project --check circular
+
+# Verbose mode with recommendations
+python scripts/dependency_analyzer.py ./project --verbose
+```
+
+**Example output:**
+```
+Dependency Analysis Report
+==========================
+Total dependencies: 47 (32 direct, 15 transitive)
+Coupling score: 72/100 (moderate)
+
+Issues found:
+- CIRCULAR: auth → user → permissions → auth
+- OUTDATED: lodash 4.17.15 → 4.17.21 (security)
+
+Recommendations:
+1. Extract shared interface to break circular dependency
+2. Update lodash to fix CVE-2020-8203
+```
+
+---
+
+### 3. Project Architect
+
+Analyzes project structure and detects architectural patterns, code smells, and improvement opportunities.
+
+**Solves:** "I want to understand the current architecture and identify areas for improvement"
+
+**Input:** Project directory path
+**Output:** Architecture assessment report
+
+**Detects:**
+- Architectural patterns (MVC, layered, hexagonal, microservices indicators)
+- Code organization issues (god classes, mixed concerns)
+- Layer violations
+- Missing architectural components
+
+**Usage:**
+```bash
+# Full assessment
+python scripts/project_architect.py ./project
+
+# Verbose with detailed recommendations
+python scripts/project_architect.py ./project --verbose
+
+# JSON output
+python scripts/project_architect.py ./project --output json
+
+# Check specific aspect
+python scripts/project_architect.py ./project --check layers
+```
+
+**Example output:**
+```
+Architecture Assessment
+=======================
+Detected pattern: Layered Architecture (confidence: 85%)
+
+Structure analysis:
+  ✓ controllers/  - Presentation layer detected
+  ✓ services/     - Business logic layer detected
+  ✓ repositories/ - Data access layer detected
+  ⚠ models/       - Mixed domain and DTOs
+
+Issues:
+- LARGE FILE: UserService.ts (1,847 lines) - consider splitting
+- MIXED CONCERNS: PaymentController contains business logic
+
+Recommendations:
+1. Split UserService into focused services
+2. Move business logic from controllers to services
+3. Separate domain models from DTOs
+```
+
+---
+
+## Decision Workflows
+
+### Database Selection Workflow
+
+Use when choosing a database for a new project or migrating existing data.
+
+**Step 1: Identify data characteristics**
+| Characteristic | Points to SQL | Points to NoSQL |
+|----------------|---------------|-----------------|
+| Structured with relationships | ✓ | |
+| ACID transactions required | ✓ | |
+| Flexible/evolving schema | | ✓ |
+| Document-oriented data | | ✓ |
+| Time-series data | | ✓ (specialized) |
+
+**Step 2: Evaluate scale requirements**
+- <1M records, single region → PostgreSQL or MySQL
+- 1M-100M records, read-heavy → PostgreSQL with read replicas
+- >100M records, global distribution → CockroachDB, Spanner, or DynamoDB
+- High write throughput (>10K/sec) → Cassandra or ScyllaDB
+
+**Step 3: Check consistency requirements**
+- Strong consistency required → SQL or CockroachDB
+- Eventual consistency acceptable → DynamoDB, Cassandra, MongoDB
+
+**Step 4: Document decision**
+Create an ADR (Architecture Decision Record) with:
+- Context and requirements
+- Options considered
+- Decision and rationale
+- Trade-offs accepted
+
+**Quick reference:**
+```
+PostgreSQL → Default choice for most applications
+MongoDB    → Document store, flexible schema
+Redis      → Caching, sessions, real-time features
+DynamoDB   → Serverless, auto-scaling, AWS-native
+TimescaleDB → Time-series data with SQL interface
+```
+
+---
+
+### Architecture Pattern Selection Workflow
+
+Use when designing a new system or refactoring existing architecture.
+
+**Step 1: Assess team and project size**
+| Team Size | Recommended Starting Point |
+|-----------|---------------------------|
+| 1-3 developers | Modular monolith |
+| 4-10 developers | Modular monolith or service-oriented |
+| 10+ developers | Consider microservices |
+
+**Step 2: Evaluate deployment requirements**
+- Single deployment unit acceptable → Monolith
+- Independent scaling needed → Microservices
+- Mixed (some services scale differently) → Hybrid
+
+**Step 3: Consider data boundaries**
+- Shared database acceptable → Monolith or modular monolith
+- Strict data isolation required → Microservices with separate DBs
+- Event-driven communication fits → Event-sourcing/CQRS
+
+**Step 4: Match pattern to requirements**
+
+| Requirement | Recommended Pattern |
+|-------------|-------------------|
+| Rapid MVP development | Modular Monolith |
+| Independent team deployment | Microservices |
+| Complex domain logic | Domain-Driven Design |
+| High read/write ratio difference | CQRS |
+| Audit trail required | Event Sourcing |
+| Third-party integrations | Hexagonal/Ports & Adapters |
+
+See `references/architecture_patterns.md` for detailed pattern descriptions.
+
+---
+
+### Monolith vs Microservices Decision
+
+**Choose Monolith when:**
+- [ ] Team is small (<10 developers)
+- [ ] Domain boundaries are unclear
+- [ ] Rapid iteration is priority
+- [ ] Operational complexity must be minimized
+- [ ] Shared database is acceptable
+
+**Choose Microservices when:**
+- [ ] Teams can own services end-to-end
+- [ ] Independent deployment is critical
+- [ ] Different scaling requirements per component
+- [ ] Technology diversity is needed
+- [ ] Domain boundaries are well understood
+
+**Hybrid approach:**
+Start with a modular monolith. Extract services only when:
+1. A module has significantly different scaling needs
+2. A team needs independent deployment
+3. Technology constraints require separation
+
+---
+
+## Reference Documentation
+
+Load these files for detailed information:
+
+| File | Contains | Load when user asks about |
+|------|----------|--------------------------|
+| `references/architecture_patterns.md` | 9 architecture patterns with trade-offs, code examples, and when to use | "which pattern?", "microservices vs monolith", "event-driven", "CQRS" |
+| `references/system_design_workflows.md` | 6 step-by-step workflows for system design tasks | "how to design?", "capacity planning", "API design", "migration" |
+| `references/tech_decision_guide.md` | Decision matrices for technology choices | "which database?", "which framework?", "which cloud?", "which cache?" |
+
+---
+
+## Tech Stack Coverage
+
+**Languages:** TypeScript, JavaScript, Python, Go, Swift, Kotlin, Rust
+**Frontend:** React, Next.js, Vue, Angular, React Native, Flutter
+**Backend:** Node.js, Express, FastAPI, Go, GraphQL, REST
+**Databases:** PostgreSQL, MySQL, MongoDB, Redis, DynamoDB, Cassandra
+**Infrastructure:** Docker, Kubernetes, Terraform, AWS, GCP, Azure
+**CI/CD:** GitHub Actions, GitLab CI, CircleCI, Jenkins
+
+---
+
+## Common Commands
+
+```bash
+# Architecture visualization
+python scripts/architecture_diagram_generator.py . --format mermaid
+python scripts/architecture_diagram_generator.py . --format plantuml
+python scripts/architecture_diagram_generator.py . --format ascii
+
+# Dependency analysis
+python scripts/dependency_analyzer.py . --verbose
+python scripts/dependency_analyzer.py . --check circular
+python scripts/dependency_analyzer.py . --output json
+
+# Architecture assessment
+python scripts/project_architect.py . --verbose
+python scripts/project_architect.py . --check layers
+python scripts/project_architect.py . --output json
+```
+
+---
+
+## Getting Help
+
+1. Run any script with `--help` for usage information
+2. Check reference documentation for detailed patterns and workflows
+3. Use `--verbose` flag for detailed explanations and recommendations
diff --git a/builtin-skills/software-engineer/senior-architect/references/architecture_patterns.md b/builtin-skills/software-engineer/senior-architect/references/architecture_patterns.md
new file mode 100644
index 00000000..e806e972
--- /dev/null
+++ b/builtin-skills/software-engineer/senior-architect/references/architecture_patterns.md
@@ -0,0 +1,470 @@
+# Architecture Patterns Reference
+
+Detailed guide to software architecture patterns with trade-offs and implementation guidance.
+
+## Patterns Index
+
+1. [Monolithic Architecture](#1-monolithic-architecture)
+2. [Modular Monolith](#2-modular-monolith)
+3. [Microservices Architecture](#3-microservices-architecture)
+4. [Event-Driven Architecture](#4-event-driven-architecture)
+5. [CQRS (Command Query Responsibility Segregation)](#5-cqrs)
+6. [Event Sourcing](#6-event-sourcing)
+7. [Hexagonal Architecture (Ports & Adapters)](#7-hexagonal-architecture)
+8. [Clean Architecture](#8-clean-architecture)
+9. [API Gateway Pattern](#9-api-gateway-pattern)
+
+---
+
+## 1. Monolithic Architecture
+
+**Problem it solves:** Need to build and deploy a complete application as a single unit with minimal operational complexity.
+
+**When to use:**
+- Small team (1-5 developers)
+- MVP or early-stage product
+- Simple domain with clear boundaries
+- Deployment simplicity is priority
+
+**When NOT to use:**
+- Multiple teams need independent deployment
+- Parts of system have vastly different scaling needs
+- Technology diversity is required
+
+**Trade-offs:**
+| Pros | Cons |
+|------|------|
+| Simple deployment | Scaling is all-or-nothing |
+| Easy debugging | Large codebase becomes unwieldy |
+| No network latency between components | Single point of failure |
+| Simple testing | Technology lock-in |
+
+**Structure example:**
+```
+monolith/
+├── src/
+│   ├── controllers/    # HTTP handlers
+│   ├── services/       # Business logic
+│   ├── repositories/   # Data access
+│   ├── models/         # Domain entities
+│   └── utils/          # Shared utilities
+├── tests/
+└── package.json
+```
+
+---
+
+## 2. Modular Monolith
+
+**Problem it solves:** Need monolith simplicity but with clear boundaries that enable future extraction to services.
+
+**When to use:**
+- Medium team (5-15 developers)
+- Domain boundaries are becoming clearer
+- Want option to extract services later
+- Need better code organization than traditional monolith
+
+**When NOT to use:**
+- Already need independent deployment
+- Teams can't coordinate releases
+
+**Trade-offs:**
+| Pros | Cons |
+|------|------|
+| Clear module boundaries | Still single deployment |
+| Easier to extract services later | Requires discipline to maintain boundaries |
+| Single database simplifies transactions | Can drift back to coupled monolith |
+| Team ownership of modules | |
+
+**Structure example:**
+```
+modular-monolith/
+├── modules/
+│   ├── users/
+│   │   ├── api/           # Public interface
+│   │   ├── internal/      # Implementation
+│   │   └── index.ts       # Module exports
+│   ├── orders/
+│   │   ├── api/
+│   │   ├── internal/
+│   │   └── index.ts
+│   └── payments/
+├── shared/                # Cross-cutting concerns
+└── main.ts
+```
+
+**Key rule:** Modules communicate only through their public API, never by importing internal files.
+
+---
+
+## 3. Microservices Architecture
+
+**Problem it solves:** Need independent deployment, scaling, and technology choices for different parts of the system.
+
+**When to use:**
+- Large team (15+ developers) organized around business capabilities
+- Different parts need different scaling
+- Independent deployment is critical
+- Technology diversity is beneficial
+
+**When NOT to use:**
+- Small team that can't handle operational complexity
+- Domain boundaries are unclear
+- Distributed transactions are common requirement
+- Network latency is unacceptable
+
+**Trade-offs:**
+| Pros | Cons |
+|------|------|
+| Independent deployment | Network complexity |
+| Independent scaling | Distributed system challenges |
+| Technology flexibility | Operational overhead |
+| Team autonomy | Data consistency challenges |
+| Fault isolation | Testing complexity |
+
+**Structure example:**
+```
+microservices/
+├── services/
+│   ├── user-service/
+│   │   ├── src/
+│   │   ├── Dockerfile
+│   │   └── package.json
+│   ├── order-service/
+│   └── payment-service/
+├── api-gateway/
+├── infrastructure/
+│   ├── kubernetes/
+│   └── terraform/
+└── docker-compose.yml
+```
+
+**Communication patterns:**
+- Synchronous: REST, gRPC
+- Asynchronous: Message queues (RabbitMQ, Kafka)
+
+---
+
+## 4. Event-Driven Architecture
+
+**Problem it solves:** Need loose coupling between components that react to business events asynchronously.
+
+**When to use:**
+- Components need loose coupling
+- Audit trail of all changes is valuable
+- Real-time reactions to events
+- Multiple consumers for same events
+
+**When NOT to use:**
+- Simple CRUD operations
+- Synchronous responses required
+- Team unfamiliar with async patterns
+- Debugging simplicity is priority
+
+**Trade-offs:**
+| Pros | Cons |
+|------|------|
+| Loose coupling | Eventual consistency |
+| Scalability | Debugging complexity |
+| Audit trail built-in | Message ordering challenges |
+| Easy to add new consumers | Infrastructure complexity |
+
+**Event structure example:**
+```typescript
+interface DomainEvent {
+  eventId: string;
+  eventType: string;
+  aggregateId: string;
+  timestamp: Date;
+  payload: Record<string, unknown>;
+  metadata: {
+    correlationId: string;
+    causationId: string;
+  };
+}
+
+// Example event
+const orderCreated: DomainEvent = {
+  eventId: "evt-123",
+  eventType: "OrderCreated",
+  aggregateId: "order-456",
+  timestamp: new Date(),
+  payload: {
+    customerId: "cust-789",
+    items: [...],
+    total: 99.99
+  },
+  metadata: {
+    correlationId: "req-001",
+    causationId: "cmd-create-order"
+  }
+};
+```
+
+---
+
+## 5. CQRS
+
+**Problem it solves:** Read and write workloads have different requirements and need to be optimized separately.
+
+**When to use:**
+- Read/write ratio is heavily skewed (10:1 or more)
+- Read and write models differ significantly
+- Complex queries that don't map to write model
+- Different scaling needs for reads vs writes
+
+**When NOT to use:**
+- Simple CRUD with balanced reads/writes
+- Read and write models are nearly identical
+- Team unfamiliar with pattern
+- Added complexity isn't justified
+
+**Trade-offs:**
+| Pros | Cons |
+|------|------|
+| Optimized read models | Eventual consistency between models |
+| Independent scaling | Complexity |
+| Simplified queries | Synchronization logic |
+| Better performance | More code to maintain |
+
+**Structure example:**
+```typescript
+// Write side (Commands)
+interface CreateOrderCommand {
+  customerId: string;
+  items: OrderItem[];
+}
+
+class OrderCommandHandler {
+  async handle(cmd: CreateOrderCommand): Promise<void> {
+    const order = Order.create(cmd);
+    await this.repository.save(order);
+    await this.eventBus.publish(order.events);
+  }
+}
+
+// Read side (Queries)
+interface OrderSummaryQuery {
+  customerId: string;
+  dateRange: DateRange;
+}
+
+class OrderQueryHandler {
+  async handle(query: OrderSummaryQuery): Promise<OrderSummary[]> {
+    // Query optimized read model (denormalized)
+    return this.readDb.query(`
+      SELECT * FROM order_summaries
+      WHERE customer_id = ? AND created_at BETWEEN ? AND ?
+    `, [query.customerId, query.dateRange.start, query.dateRange.end]);
+  }
+}
+```
+
+---
+
+## 6. Event Sourcing
+
+**Problem it solves:** Need complete audit trail and ability to reconstruct state at any point in time.
+
+**When to use:**
+- Audit trail is regulatory requirement
+- Need to answer "how did we get here?"
+- Complex domain with undo/redo requirements
+- Debugging production issues requires history
+
+**When NOT to use:**
+- Simple CRUD applications
+- No audit requirements
+- Team unfamiliar with pattern
+- Reporting on current state is primary need
+
+**Trade-offs:**
+| Pros | Cons |
+|------|------|
+| Complete audit trail | Storage grows indefinitely |
+| Time-travel debugging | Query complexity |
+| Natural fit for event-driven | Learning curve |
+| Enables CQRS | Eventual consistency |
+
+**Implementation example:**
+```typescript
+// Events
+type OrderEvent =
+  | { type: 'OrderCreated'; customerId: string; items: Item[] }
+  | { type: 'ItemAdded'; itemId: string; quantity: number }
+  | { type: 'OrderShipped'; trackingNumber: string };
+
+// Aggregate rebuilt from events
+class Order {
+  private state: OrderState;
+
+  static fromEvents(events: OrderEvent[]): Order {
+    const order = new Order();
+    events.forEach(event => order.apply(event));
+    return order;
+  }
+
+  private apply(event: OrderEvent): void {
+    switch (event.type) {
+      case 'OrderCreated':
+        this.state = { status: 'created', items: event.items };
+        break;
+      case 'ItemAdded':
+        this.state.items.push({ id: event.itemId, qty: event.quantity });
+        break;
+      case 'OrderShipped':
+        this.state.status = 'shipped';
+        this.state.trackingNumber = event.trackingNumber;
+        break;
+    }
+  }
+}
+```
+
+---
+
+## 7. Hexagonal Architecture
+
+**Problem it solves:** Need to isolate business logic from external concerns (databases, APIs, UI) for testability and flexibility.
+
+**When to use:**
+- Business logic is complex and valuable
+- Multiple interfaces to same domain (API, CLI, events)
+- Testability is priority
+- External systems may change
+
+**When NOT to use:**
+- Simple CRUD with no business logic
+- Single interface to domain
+- Overhead isn't justified
+
+**Trade-offs:**
+| Pros | Cons |
+|------|------|
+| Business logic isolation | More abstractions |
+| Highly testable | Initial setup overhead |
+| External systems are swappable | Can be over-engineered |
+| Clear boundaries | Learning curve |
+
+**Structure example:**
+```
+hexagonal/
+├── domain/              # Business logic (no external deps)
+│   ├── entities/
+│   ├── services/
+│   └── ports/           # Interfaces (what domain needs)
+│       ├── OrderRepository.ts
+│       └── PaymentGateway.ts
+├── adapters/            # Implementations
+│   ├── persistence/     # Database adapters
+│   │   └── PostgresOrderRepository.ts
+│   ├── payment/         # External service adapters
+│   │   └── StripePaymentGateway.ts
+│   └── api/             # HTTP adapters
+│       └── OrderController.ts
+└── config/              # Wiring it all together
+```
+
+---
+
+## 8. Clean Architecture
+
+**Problem it solves:** Need clear dependency rules where business logic doesn't depend on frameworks or external systems.
+
+**When to use:**
+- Long-lived applications that will outlive frameworks
+- Business logic is the core value
+- Team discipline to maintain boundaries
+- Multiple delivery mechanisms (web, mobile, CLI)
+
+**When NOT to use:**
+- Short-lived projects
+- Framework-centric applications
+- Simple CRUD operations
+
+**Trade-offs:**
+| Pros | Cons |
+|------|------|
+| Framework independence | More code |
+| Testable business logic | Can feel over-engineered |
+| Clear dependency direction | Learning curve |
+| Flexible delivery mechanisms | Initial setup cost |
+
+**Dependency rule:** Dependencies point inward. Inner circles know nothing about outer circles.
+
+```
+┌─────────────────────────────────────────┐
+│           Frameworks & Drivers          │
+│  ┌─────────────────────────────────┐    │
+│  │     Interface Adapters          │    │
+│  │  ┌─────────────────────────┐    │    │
+│  │  │    Application Layer    │    │    │
+│  │  │  ┌─────────────────┐    │    │    │
+│  │  │  │    Entities     │    │    │    │
+│  │  │  │ (Domain Logic)  │    │    │    │
+│  │  │  └─────────────────┘    │    │    │
+│  │  └─────────────────────────┘    │    │
+│  └─────────────────────────────────┘    │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## 9. API Gateway Pattern
+
+**Problem it solves:** Need single entry point for clients that routes to multiple backend services.
+
+**When to use:**
+- Multiple backend services
+- Cross-cutting concerns (auth, rate limiting, logging)
+- Different clients need different APIs
+- Service aggregation needed
+
+**When NOT to use:**
+- Single backend service
+- Simplicity is priority
+- Team can't maintain gateway
+
+**Trade-offs:**
+| Pros | Cons |
+|------|------|
+| Single entry point | Single point of failure |
+| Cross-cutting concerns centralized | Additional latency |
+| Backend service abstraction | Complexity |
+| Client-specific APIs | Can become bottleneck |
+
+**Responsibilities:**
+```
+┌─────────────────────────────────────┐
+│            API Gateway              │
+├─────────────────────────────────────┤
+│ • Authentication/Authorization      │
+│ • Rate limiting                     │
+│ • Request/Response transformation   │
+│ • Load balancing                    │
+│ • Circuit breaking                  │
+│ • Caching                          │
+│ • Logging/Monitoring               │
+└─────────────────────────────────────┘
+         │         │         │
+         ▼         ▼         ▼
+    ┌─────┐   ┌─────┐   ┌─────┐
+    │Svc A│   │Svc B│   │Svc C│
+    └─────┘   └─────┘   └─────┘
+```
+
+---
+
+## Pattern Selection Quick Reference
+
+| If you need... | Consider... |
+|----------------|-------------|
+| Simplicity, small team | Monolith |
+| Clear boundaries, future flexibility | Modular Monolith |
+| Independent deployment/scaling | Microservices |
+| Loose coupling, async processing | Event-Driven |
+| Separate read/write optimization | CQRS |
+| Complete audit trail | Event Sourcing |
+| Testable, swappable externals | Hexagonal |
+| Framework independence | Clean Architecture |
+| Single entry point, multiple services | API Gateway |
diff --git a/builtin-skills/software-engineer/senior-architect/references/system_design_workflows.md b/builtin-skills/software-engineer/senior-architect/references/system_design_workflows.md
new file mode 100644
index 00000000..c005ba66
--- /dev/null
+++ b/builtin-skills/software-engineer/senior-architect/references/system_design_workflows.md
@@ -0,0 +1,536 @@
+# System Design Workflows
+
+Step-by-step workflows for common system design tasks.
+
+## Workflows Index
+
+1. [System Design Interview Approach](#1-system-design-interview-approach)
+2. [Capacity Planning Workflow](#2-capacity-planning-workflow)
+3. [API Design Workflow](#3-api-design-workflow)
+4. [Database Schema Design](#4-database-schema-design-workflow)
+5. [Scalability Assessment](#5-scalability-assessment-workflow)
+6. [Migration Planning](#6-migration-planning-workflow)
+
+---
+
+## 1. System Design Interview Approach
+
+Use when designing a system from scratch or explaining architecture decisions.
+
+### Step 1: Clarify Requirements (3-5 minutes)
+
+**Functional requirements:**
+- What are the core features?
+- Who are the users?
+- What actions can users take?
+
+**Non-functional requirements:**
+- Expected scale (users, requests/sec, data size)
+- Latency requirements
+- Availability requirements (99.9%? 99.99%?)
+- Consistency requirements (strong? eventual?)
+
+**Example questions to ask:**
+```
+- How many users? Daily active users?
+- Read/write ratio?
+- Data retention period?
+- Geographic distribution?
+- Peak vs average load?
+```
+
+### Step 2: Estimate Scale (2-3 minutes)
+
+**Calculate key metrics:**
+```
+Users:        10M monthly active users
+DAU:          1M daily active users
+Requests:     100 req/user/day = 100M req/day
+              = 1,200 req/sec (avg)
+              = 3,600 req/sec (peak, 3x)
+
+Storage:      1KB/request × 100M = 100GB/day
+              = 36TB/year
+
+Bandwidth:    100GB/day = 1.2 MB/sec (avg)
+```
+
+### Step 3: Design High-Level Architecture (5-10 minutes)
+
+**Start with basic components:**
+```
+┌──────────┐     ┌──────────┐     ┌──────────┐
+│  Client  │────▶│   API    │────▶│ Database │
+└──────────┘     └──────────┘     └──────────┘
+```
+
+**Add components as needed:**
+- Load balancer for traffic distribution
+- Cache for read-heavy workloads
+- CDN for static content
+- Message queue for async processing
+- Search index for complex queries
+
+### Step 4: Deep Dive into Components (10-15 minutes)
+
+**For each major component, discuss:**
+- Why this technology choice?
+- How does it handle failures?
+- How does it scale?
+- What are the trade-offs?
+
+### Step 5: Address Bottlenecks (5 minutes)
+
+**Common bottlenecks:**
+- Database read/write capacity
+- Network bandwidth
+- Single points of failure
+- Hot spots in data distribution
+
+**Solutions:**
+- Caching (Redis, Memcached)
+- Database sharding
+- Read replicas
+- CDN for static content
+- Async processing for non-critical paths
+
+---
+
+## 2. Capacity Planning Workflow
+
+Use when estimating infrastructure requirements for a new system or feature.
+
+### Step 1: Gather Requirements
+
+| Metric | Current | 6 months | 1 year |
+|--------|---------|----------|--------|
+| Monthly active users | | | |
+| Peak concurrent users | | | |
+| Requests per second | | | |
+| Data storage (GB) | | | |
+| Bandwidth (Mbps) | | | |
+
+### Step 2: Calculate Compute Requirements
+
+**Web/API servers:**
+```
+Peak RPS:           3,600
+Requests per server: 500 (conservative)
+Servers needed:     3,600 / 500 = 8 servers
+
+With redundancy (N+2): 10 servers
+```
+
+**CPU estimation:**
+```
+Per request: 50ms CPU time
+Peak RPS:    3,600
+CPU cores:   3,600 × 0.05 = 180 cores
+
+With headroom (70% target utilization):
+             180 / 0.7 = 257 cores
+             = 32 servers × 8 cores
+```
+
+### Step 3: Calculate Storage Requirements
+
+**Database storage:**
+```
+Records per day:    100,000
+Record size:        2KB
+Daily growth:       200MB
+
+With indexes (2x):  400MB/day
+Retention (1 year): 146GB
+
+With replication (3x): 438GB
+```
+
+**File storage:**
+```
+Files per day:      10,000
+Average file size:  500KB
+Daily growth:       5GB
+
+Retention (1 year): 1.8TB
+```
+
+### Step 4: Calculate Network Requirements
+
+**Bandwidth:**
+```
+Response size:      10KB average
+Peak RPS:           3,600
+Outbound:           3,600 × 10KB = 36MB/s = 288 Mbps
+
+With headroom (50%): 432 Mbps ≈ 500 Mbps connection
+```
+
+### Step 5: Document and Review
+
+**Create capacity plan document:**
+- Current requirements
+- Growth projections
+- Infrastructure recommendations
+- Cost estimates
+- Review triggers (when to re-evaluate)
+
+---
+
+## 3. API Design Workflow
+
+Use when designing new APIs or refactoring existing ones.
+
+### Step 1: Identify Resources
+
+**List the nouns in your domain:**
+```
+E-commerce example:
+- Users
+- Products
+- Orders
+- Payments
+- Reviews
+```
+
+### Step 2: Define Operations
+
+**Map CRUD to HTTP methods:**
+| Operation | HTTP Method | URL Pattern |
+|-----------|-------------|-------------|
+| List | GET | /resources |
+| Get one | GET | /resources/{id} |
+| Create | POST | /resources |
+| Update | PUT/PATCH | /resources/{id} |
+| Delete | DELETE | /resources/{id} |
+
+### Step 3: Design Request/Response Formats
+
+**Request example:**
+```json
+POST /api/v1/orders
+Content-Type: application/json
+
+{
+  "customer_id": "cust-123",
+  "items": [
+    {"product_id": "prod-456", "quantity": 2}
+  ],
+  "shipping_address": {
+    "street": "123 Main St",
+    "city": "San Francisco",
+    "state": "CA",
+    "zip": "94102"
+  }
+}
+```
+
+**Response example:**
+```json
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+  "id": "ord-789",
+  "status": "pending",
+  "customer_id": "cust-123",
+  "items": [...],
+  "total": 99.99,
+  "created_at": "2024-01-15T10:30:00Z",
+  "_links": {
+    "self": "/api/v1/orders/ord-789",
+    "customer": "/api/v1/customers/cust-123"
+  }
+}
+```
+
+### Step 4: Handle Errors Consistently
+
+**Error response format:**
+```json
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid request parameters",
+    "details": [
+      {
+        "field": "quantity",
+        "message": "must be greater than 0"
+      }
+    ]
+  },
+  "request_id": "req-abc123"
+}
+```
+
+**Standard error codes:**
+| HTTP Status | Use Case |
+|-------------|----------|
+| 400 | Validation errors |
+| 401 | Authentication required |
+| 403 | Permission denied |
+| 404 | Resource not found |
+| 409 | Conflict (duplicate, etc.) |
+| 429 | Rate limit exceeded |
+| 500 | Internal server error |
+
+### Step 5: Document the API
+
+**Include:**
+- Authentication method
+- Base URL and versioning
+- Endpoints with examples
+- Error codes and meanings
+- Rate limits
+- Pagination format
+
+---
+
+## 4. Database Schema Design Workflow
+
+Use when designing a new database or major schema changes.
+
+### Step 1: Identify Entities
+
+**List the things you need to store:**
+```
+E-commerce:
+- User (id, email, name, created_at)
+- Product (id, name, price, stock)
+- Order (id, user_id, status, total)
+- OrderItem (id, order_id, product_id, quantity, price)
+```
+
+### Step 2: Define Relationships
+
+**Relationship types:**
+```
+User ──1:N──▶ Order       (one user, many orders)
+Order ──1:N──▶ OrderItem  (one order, many items)
+Product ──1:N──▶ OrderItem (one product, many order items)
+```
+
+### Step 3: Choose Primary Keys
+
+**Options:**
+| Type | Pros | Cons |
+|------|------|------|
+| Auto-increment | Simple, ordered | Not distributed-friendly |
+| UUID | Globally unique | Larger, random |
+| ULID | Globally unique, sortable | Larger |
+
+### Step 4: Add Indexes
+
+**Index selection rules:**
+```sql
+-- Index columns used in WHERE clauses
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+
+-- Index columns used in JOINs
+CREATE INDEX idx_order_items_order_id ON order_items(order_id);
+
+-- Index columns used in ORDER BY with WHERE
+CREATE INDEX idx_orders_user_status ON orders(user_id, status);
+
+-- Consider composite indexes for common queries
+-- Query: SELECT * FROM orders WHERE user_id = ? AND status = 'active'
+CREATE INDEX idx_orders_user_status ON orders(user_id, status);
+```
+
+### Step 5: Plan for Scale
+
+**Partitioning strategies:**
+```sql
+-- Partition by date (time-series data)
+CREATE TABLE events (
+  id BIGINT,
+  created_at TIMESTAMP,
+  data JSONB
+) PARTITION BY RANGE (created_at);
+
+-- Partition by hash (distribute evenly)
+CREATE TABLE users (
+  id BIGINT,
+  email VARCHAR(255)
+) PARTITION BY HASH (id);
+```
+
+**Sharding considerations:**
+- Shard key selection (user_id, tenant_id, etc.)
+- Cross-shard query limitations
+- Rebalancing strategy
+
+---
+
+## 5. Scalability Assessment Workflow
+
+Use when evaluating if current architecture can handle growth.
+
+### Step 1: Profile Current System
+
+**Metrics to collect:**
+```
+Current load:
+- Average requests/sec: ___
+- Peak requests/sec: ___
+- Average latency: ___ ms
+- P99 latency: ___ ms
+- Error rate: ___%
+
+Resource utilization:
+- CPU: ___%
+- Memory: ___%
+- Disk I/O: ___%
+- Network: ___%
+```
+
+### Step 2: Identify Bottlenecks
+
+**Check each layer:**
+| Layer | Bottleneck Signs |
+|-------|------------------|
+| Web servers | High CPU, connection limits |
+| Application | Slow requests, thread pool exhaustion |
+| Database | Slow queries, lock contention |
+| Cache | High miss rate, memory pressure |
+| Network | Bandwidth saturation, latency |
+
+### Step 3: Load Test
+
+**Test scenarios:**
+```
+1. Baseline: Current production load
+2. 2x load: Expected growth in 6 months
+3. 5x load: Stress test
+4. Spike: Sudden 10x for 5 minutes
+```
+
+**Tools:**
+- k6, Locust, JMeter for HTTP
+- pgbench for PostgreSQL
+- redis-benchmark for Redis
+
+### Step 4: Identify Scaling Strategy
+
+**Vertical scaling (scale up):**
+- Add more CPU, memory, disk
+- Simpler but has limits
+- Use when: Single server can handle more
+
+**Horizontal scaling (scale out):**
+- Add more servers
+- Requires stateless design
+- Use when: Need linear scaling
+
+### Step 5: Create Scaling Plan
+
+**Document:**
+```
+Trigger: When average CPU > 70% for 15 minutes
+
+Action:
+1. Add 2 more web servers
+2. Update load balancer
+3. Verify health checks pass
+
+Rollback:
+1. Remove added servers
+2. Update load balancer
+3. Investigate issue
+```
+
+---
+
+## 6. Migration Planning Workflow
+
+Use when migrating to new infrastructure, database, or architecture.
+
+### Step 1: Assess Current State
+
+**Document:**
+- Current architecture diagram
+- Data volumes
+- Dependencies
+- Integration points
+- Performance baselines
+
+### Step 2: Define Target State
+
+**Document:**
+- New architecture diagram
+- Technology changes
+- Expected improvements
+- Success criteria
+
+### Step 3: Plan Migration Strategy
+
+**Strategies:**
+
+| Strategy | Risk | Downtime | Complexity |
+|----------|------|----------|------------|
+| Big bang | High | Yes | Low |
+| Blue-green | Medium | Minimal | Medium |
+| Canary | Low | None | High |
+| Strangler fig | Low | None | High |
+
+**Strangler fig pattern (recommended for large systems):**
+```
+1. Add facade in front of old system
+2. Route small percentage of traffic to new system
+3. Gradually increase traffic to new system
+4. Retire old system when 100% migrated
+```
+
+### Step 4: Create Rollback Plan
+
+**For each step, define:**
+```
+Step: Migrate user service to new database
+
+Rollback trigger:
+- Error rate > 1%
+- Latency > 500ms P99
+- Data inconsistency detected
+
+Rollback steps:
+1. Route traffic back to old database
+2. Sync any new data back
+3. Investigate root cause
+
+Rollback time estimate: 15 minutes
+```
+
+### Step 5: Execute with Checkpoints
+
+**Migration checklist:**
+```
+□ Backup current system
+□ Verify backup restoration works
+□ Deploy new infrastructure
+□ Run smoke tests on new system
+□ Migrate small percentage (1%)
+□ Monitor for 24 hours
+□ Increase to 10%
+□ Monitor for 24 hours
+□ Increase to 50%
+□ Monitor for 24 hours
+□ Complete migration (100%)
+□ Decommission old system
+□ Document lessons learned
+```
+
+---
+
+## Quick Reference
+
+| Task | Start Here |
+|------|------------|
+| New system design | [System Design Interview Approach](#1-system-design-interview-approach) |
+| Infrastructure sizing | [Capacity Planning](#2-capacity-planning-workflow) |
+| New API | [API Design](#3-api-design-workflow) |
+| Database design | [Database Schema Design](#4-database-schema-design-workflow) |
+| Handle growth | [Scalability Assessment](#5-scalability-assessment-workflow) |
+| System migration | [Migration Planning](#6-migration-planning-workflow) |
diff --git a/builtin-skills/software-engineer/senior-architect/references/tech_decision_guide.md b/builtin-skills/software-engineer/senior-architect/references/tech_decision_guide.md
new file mode 100644
index 00000000..94dae860
--- /dev/null
+++ b/builtin-skills/software-engineer/senior-architect/references/tech_decision_guide.md
@@ -0,0 +1,412 @@
+# Technology Decision Guide
+
+Decision frameworks and comparison matrices for common technology choices.
+
+## Decision Frameworks Index
+
+1. [Database Selection](#1-database-selection)
+2. [Caching Strategy](#2-caching-strategy)
+3. [Message Queue Selection](#3-message-queue-selection)
+4. [Authentication Strategy](#4-authentication-strategy)
+5. [Frontend Framework Selection](#5-frontend-framework-selection)
+6. [Cloud Provider Selection](#6-cloud-provider-selection)
+7. [API Style Selection](#7-api-style-selection)
+
+---
+
+## 1. Database Selection
+
+### SQL vs NoSQL Decision Matrix
+
+| Factor | Choose SQL | Choose NoSQL |
+|--------|-----------|--------------|
+| Data relationships | Complex, many-to-many | Simple, denormalized OK |
+| Schema | Well-defined, stable | Evolving, flexible |
+| Transactions | ACID required | Eventual consistency OK |
+| Query patterns | Complex joins, aggregations | Key-value, document lookups |
+| Scale | Vertical (some horizontal) | Horizontal first |
+| Team expertise | Strong SQL skills | Document/KV experience |
+
+### Database Type Selection
+
+**Relational (SQL):**
+| Database | Best For | Avoid When |
+|----------|----------|------------|
+| PostgreSQL | General purpose, JSON support, extensions | Simple key-value only |
+| MySQL | Web applications, read-heavy | Complex queries, JSON-heavy |
+| SQLite | Embedded, development, small apps | Concurrent writes, scale |
+
+**Document (NoSQL):**
+| Database | Best For | Avoid When |
+|----------|----------|------------|
+| MongoDB | Flexible schema, rapid iteration | Complex transactions |
+| CouchDB | Offline-first, sync required | High throughput |
+
+**Key-Value:**
+| Database | Best For | Avoid When |
+|----------|----------|------------|
+| Redis | Caching, sessions, real-time | Persistence critical |
+| DynamoDB | Serverless, auto-scaling | Complex queries |
+
+**Wide-Column:**
+| Database | Best For | Avoid When |
+|----------|----------|------------|
+| Cassandra | Write-heavy, time-series | Complex queries, small scale |
+| ScyllaDB | Cassandra alternative, performance | Small datasets |
+
+**Time-Series:**
+| Database | Best For | Avoid When |
+|----------|----------|------------|
+| TimescaleDB | Time-series with SQL | Non-time-series data |
+| InfluxDB | Metrics, monitoring | Relational queries |
+
+**Search:**
+| Database | Best For | Avoid When |
+|----------|----------|------------|
+| Elasticsearch | Full-text search, logs | Primary data store |
+| Meilisearch | Simple search, fast setup | Complex analytics |
+
+### Quick Decision Flow
+
+```
+Start
+  │
+  ├─ Need ACID transactions? ──Yes──► PostgreSQL/MySQL
+  │
+  ├─ Flexible schema needed? ──Yes──► MongoDB
+  │
+  ├─ Write-heavy (>50K/sec)? ──Yes──► Cassandra/ScyllaDB
+  │
+  ├─ Key-value access only? ──Yes──► Redis/DynamoDB
+  │
+  ├─ Time-series data? ──Yes──► TimescaleDB/InfluxDB
+  │
+  ├─ Full-text search? ──Yes──► Elasticsearch
+  │
+  └─ Default ──────────────────────► PostgreSQL
+```
+
+---
+
+## 2. Caching Strategy
+
+### Cache Type Selection
+
+| Type | Use Case | Invalidation | Complexity |
+|------|----------|--------------|------------|
+| Read-through | Frequent reads, tolerance for stale | On write/TTL | Low |
+| Write-through | Data consistency critical | Automatic | Medium |
+| Write-behind | High write throughput | Async | High |
+| Cache-aside | Fine-grained control | Application | Medium |
+
+### Cache Technology Selection
+
+| Technology | Best For | Limitations |
+|------------|----------|-------------|
+| Redis | General purpose, data structures | Memory cost |
+| Memcached | Simple key-value, high throughput | No persistence |
+| CDN (CloudFront, Fastly) | Static assets, edge caching | Dynamic content |
+| Application cache | Per-instance, small data | Not distributed |
+
+### Cache Patterns
+
+**Cache-Aside (Lazy Loading):**
+```
+Read:
+1. Check cache
+2. If miss, read from DB
+3. Store in cache
+4. Return data
+
+Write:
+1. Write to DB
+2. Invalidate cache
+```
+
+**Write-Through:**
+```
+Write:
+1. Write to cache
+2. Cache writes to DB
+3. Return success
+
+Read:
+1. Read from cache (always hit)
+```
+
+**TTL Guidelines:**
+
+| Data Type | Suggested TTL |
+|-----------|---------------|
+| User sessions | 24-48 hours |
+| API responses | 1-5 minutes |
+| Static content | 24 hours - 1 week |
+| Database queries | 5-60 minutes |
+| Feature flags | 1-5 minutes |
+
+---
+
+## 3. Message Queue Selection
+
+### Queue Technology Comparison
+
+| Feature | RabbitMQ | Kafka | SQS | Redis Streams |
+|---------|----------|-------|-----|---------------|
+| Throughput | Medium (10K/s) | Very High (100K+/s) | Medium | High |
+| Ordering | Per-queue | Per-partition | FIFO optional | Per-stream |
+| Durability | Configurable | Strong | Strong | Configurable |
+| Replay | No | Yes | No | Yes |
+| Complexity | Medium | High | Low | Low |
+| Cost | Self-hosted | Self-hosted | Pay-per-use | Self-hosted |
+
+### Decision Matrix
+
+| Requirement | Recommendation |
+|-------------|----------------|
+| Simple task queue | SQS or Redis |
+| Event streaming | Kafka |
+| Complex routing | RabbitMQ |
+| Log aggregation | Kafka |
+| Serverless integration | SQS |
+| Real-time analytics | Kafka |
+| Request/reply pattern | RabbitMQ |
+
+### When to Use Each
+
+**RabbitMQ:**
+- Complex routing logic (topic, fanout, headers)
+- Request/reply patterns
+- Priority queues
+- Message acknowledgment critical
+
+**Kafka:**
+- Event sourcing
+- High throughput requirements (>50K messages/sec)
+- Message replay needed
+- Stream processing
+- Log aggregation
+
+**SQS:**
+- AWS-native applications
+- Simple queue semantics
+- Serverless architectures
+- Don't want to manage infrastructure
+
+**Redis Streams:**
+- Already using Redis
+- Moderate throughput
+- Simple streaming needs
+- Real-time features
+
+---
+
+## 4. Authentication Strategy
+
+### Method Selection
+
+| Method | Best For | Avoid When |
+|--------|----------|------------|
+| Session-based | Traditional web apps, server-rendered | Mobile apps, microservices |
+| JWT | SPAs, mobile apps, microservices | Need immediate revocation |
+| OAuth 2.0 | Third-party access, social login | Internal-only apps |
+| API Keys | Server-to-server, simple auth | User authentication |
+| mTLS | Service mesh, high security | Public APIs |
+
+### JWT vs Sessions
+
+| Factor | JWT | Sessions |
+|--------|-----|----------|
+| Scalability | Stateless, easy to scale | Requires session store |
+| Revocation | Difficult (need blocklist) | Immediate |
+| Payload | Can contain claims | Server-side only |
+| Security | Token in client | Server-controlled |
+| Mobile friendly | Yes | Requires cookies |
+
+### OAuth 2.0 Flow Selection
+
+| Flow | Use Case |
+|------|----------|
+| Authorization Code | Web apps with backend |
+| Authorization Code + PKCE | SPAs, mobile apps |
+| Client Credentials | Machine-to-machine |
+| Device Code | Smart TVs, CLI tools |
+
+**Avoid:** Implicit flow (deprecated), Resource Owner Password (legacy only)
+
+### Token Lifetimes
+
+| Token Type | Suggested Lifetime |
+|------------|-------------------|
+| Access token | 15-60 minutes |
+| Refresh token | 7-30 days |
+| API key | No expiry (rotate quarterly) |
+| Session | 24 hours - 7 days |
+
+---
+
+## 5. Frontend Framework Selection
+
+### Framework Comparison
+
+| Factor | React | Vue | Angular | Svelte |
+|--------|-------|-----|---------|--------|
+| Learning curve | Medium | Low | High | Low |
+| Ecosystem | Largest | Large | Complete | Growing |
+| Performance | Good | Good | Good | Excellent |
+| Bundle size | Medium | Small | Large | Smallest |
+| TypeScript | Good | Good | Native | Good |
+| Job market | Largest | Growing | Enterprise | Niche |
+
+### Decision Matrix
+
+| Requirement | Recommendation |
+|-------------|----------------|
+| Large team, enterprise | Angular |
+| Startup, rapid iteration | React or Vue |
+| Performance critical | Svelte or Solid |
+| Existing React team | React |
+| Progressive enhancement | Vue or Svelte |
+| Component library needed | React (most options) |
+
+### Meta-Framework Selection
+
+| Framework | Best For |
+|-----------|----------|
+| Next.js (React) | Full-stack React, SSR/SSG |
+| Nuxt (Vue) | Full-stack Vue, SSR/SSG |
+| SvelteKit | Full-stack Svelte |
+| Remix | Data-heavy React apps |
+| Astro | Content sites, multi-framework |
+
+### When to Use SSR vs SPA vs SSG
+
+| Rendering | Use When |
+|-----------|----------|
+| SSR | SEO critical, dynamic content, auth-gated |
+| SPA | Internal tools, highly interactive, no SEO |
+| SSG | Content sites, blogs, documentation |
+| ISR | Mix of static and dynamic |
+
+---
+
+## 6. Cloud Provider Selection
+
+### Provider Comparison
+
+| Factor | AWS | GCP | Azure |
+|--------|-----|-----|-------|
+| Market share | Largest | Growing | Enterprise strong |
+| Service breadth | Most comprehensive | Strong ML/data | Best Microsoft integration |
+| Pricing | Complex, volume discounts | Simpler, sustained use | EA discounts |
+| Kubernetes | EKS | GKE (best managed) | AKS |
+| Serverless | Lambda (mature) | Cloud Functions | Azure Functions |
+| Database | RDS, DynamoDB | Cloud SQL, Spanner | SQL, Cosmos |
+
+### Decision Factors
+
+| If You Need | Consider |
+|-------------|----------|
+| Microsoft ecosystem | Azure |
+| Best Kubernetes experience | GCP |
+| Widest service selection | AWS |
+| Machine learning focus | GCP or AWS |
+| Government compliance | AWS GovCloud or Azure Gov |
+| Startup credits | All offer programs |
+
+### Multi-Cloud Considerations
+
+**Go multi-cloud when:**
+- Regulatory requirements mandate it
+- Specific service (e.g., GCP BigQuery) is best-in-class
+- Negotiating leverage with vendors
+
+**Stay single-cloud when:**
+- Team is small
+- Want to minimize complexity
+- Deep integration needed
+
+### Service Mapping
+
+| Need | AWS | GCP | Azure |
+|------|-----|-----|-------|
+| Compute | EC2 | Compute Engine | Virtual Machines |
+| Containers | ECS, EKS | GKE, Cloud Run | AKS, Container Apps |
+| Serverless | Lambda | Cloud Functions | Azure Functions |
+| Object Storage | S3 | Cloud Storage | Blob Storage |
+| SQL Database | RDS | Cloud SQL | Azure SQL |
+| NoSQL | DynamoDB | Firestore | Cosmos DB |
+| CDN | CloudFront | Cloud CDN | Azure CDN |
+| DNS | Route 53 | Cloud DNS | Azure DNS |
+
+---
+
+## 7. API Style Selection
+
+### REST vs GraphQL vs gRPC
+
+| Factor | REST | GraphQL | gRPC |
+|--------|------|---------|------|
+| Use case | General purpose | Flexible queries | Microservices |
+| Learning curve | Low | Medium | High |
+| Over-fetching | Common | Solved | N/A |
+| Caching | HTTP native | Complex | Custom |
+| Browser support | Native | Native | Limited |
+| Tooling | Mature | Growing | Strong |
+| Performance | Good | Good | Excellent |
+
+### Decision Matrix
+
+| Requirement | Recommendation |
+|-------------|----------------|
+| Public API | REST |
+| Mobile apps with varied needs | GraphQL |
+| Microservices communication | gRPC |
+| Real-time updates | GraphQL subscriptions or WebSocket |
+| File uploads | REST |
+| Internal services only | gRPC |
+| Third-party developers | REST + OpenAPI |
+
+### When to Choose Each
+
+**Choose REST when:**
+- Building public APIs
+- Need HTTP caching
+- Simple CRUD operations
+- Team experienced with REST
+
+**Choose GraphQL when:**
+- Multiple clients with different data needs
+- Rapid frontend iteration
+- Complex, nested data relationships
+- Want to reduce API calls
+
+**Choose gRPC when:**
+- Service-to-service communication
+- Performance critical
+- Streaming required
+- Strong typing important
+
+### API Versioning Strategies
+
+| Strategy | Pros | Cons |
+|----------|------|------|
+| URL path (`/v1/`) | Clear, easy to implement | URL pollution |
+| Query param (`?version=1`) | Flexible | Easy to miss |
+| Header (`Accept-Version: 1`) | Clean URLs | Less discoverable |
+| No versioning (evolve) | Simple | Breaking changes risky |
+
+**Recommendation:** URL path versioning for public APIs, header versioning for internal.
+
+---
+
+## Quick Reference
+
+| Decision | Default Choice | Alternative When |
+|----------|----------------|------------------|
+| Database | PostgreSQL | Scale/flexibility → MongoDB, DynamoDB |
+| Cache | Redis | Simple needs → Memcached |
+| Queue | SQS (AWS) / RabbitMQ | Event streaming → Kafka |
+| Auth | JWT + Refresh | Traditional web → Sessions |
+| Frontend | React + Next.js | Simplicity → Vue, Performance → Svelte |
+| Cloud | AWS | Microsoft shop → Azure, ML-first → GCP |
+| API | REST | Mobile flexibility → GraphQL, Internal → gRPC |
diff --git a/src/main/index.ts b/src/main/index.ts
index 63fb37fd..bcd2a1da 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -1,3 +1,4 @@
+import "./suppress-warnings";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { app } from "electron";
diff --git a/src/main/ipc-support.ts b/src/main/ipc-support.ts
index c9e496df..cc0026ab 100644
--- a/src/main/ipc-support.ts
+++ b/src/main/ipc-support.ts
@@ -96,8 +96,19 @@ export function createIpcSupport({
   function emitEvent(event: DesktopEvent) {
     const mainWindow = getMainWindow();
     if (!mainWindow || mainWindow.isDestroyed()) return;
+    const webContents = mainWindow.webContents;
+    if (webContents.isDestroyed() || webContents.isCrashed()) return;
+    // `mainFrame.detached` flips true while the frame is being torn down
+    // or swapped during a navigation. Sending into a detached frame is
+    // what makes Electron's native layer throw "Render frame was
+    // disposed" and also what makes its own WebFrameMain.prototype.send
+    // spam `console.error('Error sending from webFrameMain: ', …)` to
+    // stderr on every call. Short-circuiting here closes the window
+    // between our `isDestroyed` check and the native send.
+    const mainFrame = webContents.mainFrame;
+    if (!mainFrame || mainFrame.detached) return;
     try {
-      mainWindow.webContents.send("agent-company:event", event);
+      webContents.send("agent-company:event", event);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       if (message.includes(renderFrameDisposedMessage)) {
diff --git a/src/main/message-dispatch.ts b/src/main/message-dispatch.ts
index 5dcdfbb4..cad1929e 100644
--- a/src/main/message-dispatch.ts
+++ b/src/main/message-dispatch.ts
@@ -260,6 +260,13 @@ export function resolveMessageWakeTargets(
     }
   }
 
+  // The human participant (`__board__`) is a reader, not a wake-able
+  // agent: it has no runtime, no heartbeat, no DB row. Leaving it in the
+  // set makes `wakeAgentIfPossible` call `db.getAgent("__board__")`,
+  // which throws "Agent not found" and spams the log. Filter once, at
+  // the point of resolution, so every downstream consumer is clean.
+  wakeTargets.delete(HUMAN_SENDER_ID);
+
   return Array.from(wakeTargets);
 }
 
diff --git a/src/main/orchestration/heartbeat.ts b/src/main/orchestration/heartbeat.ts
index 3abb4224..91b3f1bc 100644
--- a/src/main/orchestration/heartbeat.ts
+++ b/src/main/orchestration/heartbeat.ts
@@ -4,6 +4,7 @@ import type { AgentRecord, ConnectorRecord } from "@shared/types";
 import type { OrchestrationDependencies } from "./types";
 import type { RunDispatchParams } from "./turn-context";
 import { pickModelForAgent } from "../model-dispatch";
+import { HUMAN_SENDER_ID } from "../message-dispatch";
 
 /**
  * Every reason a heartbeat attempt can be rejected before a run is
@@ -258,6 +259,12 @@ export function createHeartbeat(
 
   function wakeAgentIfPossible(agentId: string | null | undefined, companyId: string, trigger: string, context?: Record<string, unknown>) {
     if (!agentId || isQuitting()) return null;
+    // `__board__` is the human participant sentinel, not an agent row.
+    // Upstream filters should strip it before we get here, but keeping
+    // this guard as defense-in-depth prevents a single stray call site
+    // (e.g. a future automation action that forwards the `toAgentId`
+    // raw) from spamming the log with "Agent not found: __board__".
+    if (agentId === HUMAN_SENDER_ID) return null;
     try {
       const agent = db.getAgent(agentId);
       if (agent.companyId !== companyId) {
diff --git a/src/main/suppress-warnings.ts b/src/main/suppress-warnings.ts
index 0fb1700e..89250e22 100644
--- a/src/main/suppress-warnings.ts
+++ b/src/main/suppress-warnings.ts
@@ -1,10 +1,23 @@
 /**
- * Silences the `node:sqlite` ExperimentalWarning emitted on first import.
- * Must be imported before any module that touches `node:sqlite`, otherwise
- * the warning has already fired.
+ * Silences two Electron/Node sources of stderr spam that are pure
+ * lifecycle noise, not logic bugs:
  *
- * Targeted: only the SQLite experimental warning. All other warnings pass
- * through unchanged.
+ * 1. `node:sqlite` ExperimentalWarning on first import — emitted by the
+ *    Node runtime itself. Must be installed before any module touches
+ *    `node:sqlite`, or the warning has already fired.
+ *
+ * 2. `Error sending from webFrameMain:` — emitted by Electron's own
+ *    `WebFrameMain.prototype.send` when the renderer frame was disposed
+ *    mid-send (window close, dev HMR, reload). Electron catches the
+ *    native exception internally and `console.error`s it; the send is
+ *    already a no-op by the time our `webContents.send` returns, and
+ *    nothing downstream reads the message. With every agent-event fan
+ *    out producing two sends, a single dead renderer floods the log
+ *    with thousands of copies and can stall the main event loop on
+ *    synchronous stderr I/O. We filter only this specific prefix so
+ *    real console errors still surface.
+ *
+ * Targeted: everything else passes through unchanged.
  */
 
 const originalEmitWarning = process.emitWarning.bind(process);
@@ -23,3 +36,23 @@ process.emitWarning = ((warning: unknown, ...rest: unknown[]) => {
   if (isSqliteExperimentalWarning(warning)) return;
   return (originalEmitWarning as (...args: unknown[]) => void)(warning, ...rest);
 }) as typeof process.emitWarning;
+
+const originalConsoleError = console.error.bind(console);
+
+function isDisposedWebFrameNoise(args: unknown[]): boolean {
+  if (args.length === 0) return false;
+  const first = args[0];
+  if (typeof first !== "string") return false;
+  if (!first.startsWith("Error sending from webFrameMain")) return false;
+  // Only swallow when the accompanying error is the disposal signal;
+  // any other payload surfaces normally so genuine IPC failures still
+  // show up in logs.
+  const payload = args[1];
+  const message = payload instanceof Error ? payload.message : String(payload ?? "");
+  return message.includes("Render frame was disposed");
+}
+
+console.error = ((...args: unknown[]) => {
+  if (isDisposedWebFrameNoise(args)) return;
+  return originalConsoleError(...args);
+}) as typeof console.error;