feat(marketing): add visual examples to portable Skill guide

docs/editorial/portable-skills/BRIEF.md

@@ -9,6 +9,7 @@ Keep its run command first. Link package-specific work to the existing authoring
 This page owns cross-Agent mechanics. The project guide links here instead of gaining a duplicate compatibility section.
 It does not create an agent-by-agent article series or a general guides expansion.
 Exclude: every-agent guarantees, hosted-chat uploads, new renderers and unrelated rewrites.
+Native figures and source-linked Skill cards use the existing article renderer.
 
 Foundations: [sources](SOURCES.md), [claims](VERIFIED-CLAIMS.md), [voice](../../../COPY.md), [figures](SCREENSHOTS.md).
 Claims: P01 through P08. Primary sources opened 2026-10-05.
@@ -86,3 +87,28 @@ The final article and its accepted digest are unchanged.
 Independent linking review: article_review accepted the placements and donor eligibility.
 Resolved findings: qualify donor compatibility claims, correct Claude's loaded-context claim,
 and require dated equal-length Search Console windows without causal attribution.
+
+## Visual enhancement brief, 2026-10-05
+
+User: the article feels weak and needs visuals, diagrams or Skill embeds.
+Keep the same route, primary command, complete example and existing review fragment.
+Add project discovery and four-stage check diagrams at their relevant steps.
+Add a worked expected-result figure beside the exact supplied diff and notes.
+Replace the final plain authoring links with source-linked project and package Skill cards.
+Reuse the existing native MDC renderer and copyable code blocks. Add no dependency or remote data request.
+The [figure plan](SCREENSHOTS.md) owns evidence boundaries and captions.
+No screenshot or chart is needed to imply stronger execution evidence than REPLAY.md supports.
+Review: an independent brief reviewer checks scope before drafting; an independent article reviewer checks the final rendered revision.
+Brief reviewer: brief_review accepted the scope at 95/100. Resolved before drafting: inline Gemini alias, complete-directory semantics, separate check outcomes, synthetic result label and package-version input.
+The project discovery columns and duplicated expected-result explanation became native figures. The home-directory table remains reference material.
+Factual pass: article_review accepted draft digest `3c19e4eca9d11f3e884371c91bf4a12bb39d92600938b67afe657e374117c856` at 95/100.
+Humanize pass: named the diff as the actor instead of “is exported”; retained the value and default caveat.
+Added a dated local-trial ledger from REPLAY.md so readers can separate observed results from prescribed checks.
+Final review must check the revised ledger and rendered digest; the earlier acceptance does not cover those additions.
+Acceptance: server-rendered figures, accurate paths, explicit expected-result label, usable commands and source links.
+Verify 390px mobile and 1440px desktop in both themes, captions, contrast, keyboard copying and no document overflow.
+Final independent acceptance: article_review checked digest `04a7e2606f7682be655571591ea4d5bd21863d0b5962e57ba772341b1c673e5b` at 98/100.
+It inspected the mobile trial ledger and desktop, mobile, light and dark figure captures. No remaining findings.
+Local verification: four figures and two authoring cards render in SSR. Widths 390, 768 and 1440 have no overflow.
+Article-scoped contrast, heading and accessible-name checks passed in both themes. Keyboard copies matched both run commands.
+Typecheck, build, published CLI grammar and 2,926 tests passed. Existing canonical, admission and inbound links remain valid.

docs/editorial/portable-skills/SCREENSHOTS.md

@@ -1,7 +1,22 @@
 # Screenshots
 
-The pilot teaches a file format and discovery paths. Use copyable Markdown and a small path table.
-No screenshot belongs in the article. Screenshots cannot prove Agent execution.
+The pilot teaches a file format and discovery paths. Retain copyable Markdown and the path table.
+The user's visual enhancement request supersedes the initial text-only decision.
+Use native HTML figures for relationships and expected results, with visible captions.
+These figures are explanatory diagrams, not screenshots or execution evidence.
+
+| Figure | Reader question | Evidence and caption limit |
+| --- | --- | --- |
+| Project discovery diagram | Where does the same Skill go? | P02-P04. Show full project paths for the example. Gemini also accepts `.agents/skills`. Placement is not automatic synchronization. |
+| Four-stage check diagram | What does each check establish? | REPLAY.md and existing article. Stages are checks to perform, not measured Agent passes. |
+| Worked result | What should a useful review flag? | Exact published input. An expected result, not a captured Agent answer. The export alone does not prove a runtime default. |
+| Authoring Skill cards | Which source helps my next task? | P07. Readable source plus copyable run command. No usage or quality metrics. |
+| Local trial ledger | Which outcomes were observed? | REPLAY.md, dated 5 October 2026. Exact versions, Codex model, local scope and Claude/Gemini limits. No benchmark or compatibility score. |
+
+Keep all figure text in server-rendered HTML. Use real figures and figcaptions.
+Use the site's semantic colors, font tokens and border hierarchy.
+Stack nodes at narrow widths. Preserve the existing prose, code example and table as the text alternative.
+Do not invent interface screenshots, benchmark charts, speed comparisons or Agent completion claims.
 
 Capture layout evidence with task-named `dev-browser --headless`.
 Keep captures in `~/scratch/portable-skills/`.

layers/marketing/app/components/MarketingArticle.vue

@@ -89,4 +89,188 @@ function copyCommand(): void {
 .learn-article :deep(a:hover) {
   color: var(--ui-text-muted);
 }
+
+/* Native article diagrams retain readable, server-rendered text in both themes. */
+.learn-article :deep(.article-figure) {
+  margin-block: 2rem;
+  padding: 1rem;
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius);
+  color: var(--ui-text);
+}
+
+.learn-article :deep(.article-figure p) {
+  margin-block: 0.5rem;
+}
+
+.learn-article :deep(.article-figure code) {
+  white-space: normal;
+  overflow-wrap: anywhere;
+}
+
+.learn-article :deep(.article-figure figcaption) {
+  margin-top: 1rem;
+  color: var(--ui-text-muted);
+  font-size: 0.875rem;
+  line-height: 1.6;
+  text-align: center;
+}
+
+.learn-article :deep(.skill-source) {
+  position: relative;
+  width: fit-content;
+  max-width: 100%;
+  margin-inline: auto;
+  padding: 0.75rem 1rem;
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius);
+  background: var(--ui-bg-muted);
+  text-align: center;
+}
+
+.learn-article :deep(.discovery-paths) {
+  position: relative;
+  display: grid;
+  gap: 1rem;
+  margin-top: 1.5rem;
+  margin-left: 1rem;
+  padding-left: 1rem;
+  border-left: 1px solid var(--ui-border);
+}
+
+.learn-article :deep(.discovery-paths::before) {
+  position: absolute;
+  top: -1.5rem;
+  left: -1px;
+  height: 1.5rem;
+  border-left: 1px solid var(--ui-border);
+  content: '';
+}
+
+.learn-article :deep(.discovery-path) {
+  position: relative;
+  min-width: 0;
+}
+
+.learn-article :deep(.discovery-path::before) {
+  position: absolute;
+  top: 1.25rem;
+  left: -1rem;
+  width: 1rem;
+  border-top: 1px solid var(--ui-border);
+  content: '';
+}
+
+.learn-article :deep(.check-stages) {
+  display: grid;
+  gap: 1rem;
+  padding: 0;
+  list-style: none;
+}
+
+.learn-article :deep(.check-stages li) {
+  min-width: 0;
+  padding: 0;
+}
+
+.learn-article :deep(.check-stages li + li) {
+  padding-top: 1rem;
+  border-top: 1px solid var(--ui-border);
+}
+
+.learn-article :deep(.result-pair) {
+  display: grid;
+  gap: 1rem;
+}
+
+.learn-article :deep(.result-finding) {
+  margin-top: 1rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--ui-border);
+}
+
+.learn-article :deep(.authoring-skills) {
+  display: grid;
+  gap: 1rem;
+  margin-block: 1.5rem;
+}
+
+.learn-article :deep(.authoring-skill-card) {
+  min-width: 0;
+  padding: 1rem;
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius);
+}
+
+.learn-article :deep(.authoring-skill-card h3) {
+  margin-top: 0;
+  font-family: var(--font-mono);
+  font-size: 1rem;
+  overflow-wrap: anywhere;
+}
+
+.learn-article :deep(.authoring-skill-card a) {
+  display: inline-flex;
+  align-items: center;
+  min-height: 44px;
+}
+
+.learn-article :deep(.authoring-skill-card pre) {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+@media (min-width: 640px) {
+  .learn-article :deep(.skill-source::after) {
+    position: absolute;
+    top: 100%;
+    left: 50%;
+    height: 0.5rem;
+    border-left: 1px solid var(--ui-border);
+    content: '';
+  }
+
+  .learn-article :deep(.discovery-paths::before) {
+    position: absolute;
+    top: -1rem;
+    left: calc((100% - 2rem) / 6);
+    right: calc((100% - 2rem) / 6);
+    height: 0;
+    border-left: none;
+    border-top: 1px solid var(--ui-border);
+    content: '';
+  }
+
+  .learn-article :deep(.discovery-paths) {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+    margin-left: 0;
+    padding-left: 0;
+    border-left: none;
+  }
+
+  .learn-article :deep(.discovery-path) {
+    padding-top: 0.75rem;
+    border-top: 1px solid var(--ui-border);
+  }
+
+  .learn-article :deep(.discovery-path::before) {
+    top: -1rem;
+    left: 50%;
+    width: 0;
+    height: 1rem;
+    border-top: none;
+    border-left: 1px solid var(--ui-border);
+  }
+
+  .learn-article :deep(.check-stages),
+  .learn-article :deep(.result-pair),
+  .learn-article :deep(.authoring-skills) {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .learn-article :deep(.check-stages li + li) {
+    padding-top: 0;
+    border-top: none;
+  }
+}
 </style>