docs(markup): clarify native note composition

[benvinegar]

Summary

• Add one concise ground rule explaining that Hunk supplies the outer note frame while STML defines the body; borders remain available for useful sibling or nested hierarchy.
• Reframe the guide's named patterns as small syntax examples that demonstrate mechanics rather than preferred layouts.
• Explicitly describe STML as an open composition grammar whose elements can be combined, omitted, repeated, and nested freely.
• Replace task-specific example content with neutral fragments and add regression coverage for both guidance points.

Testing

• bun run typecheck
• bun run lint
• bun test src/ui/lib/stml (45 passed)
• Previewed the updated guide with bun src/main.tsx markup guide

This PR description was generated by Pi using OpenAI GPT-5.3 Codex

[greptile-apps]

Greptile Summary

This PR updates the STML authoring guide to clarify that agent-generated markup renders as the body inside Hunk's existing note frame, not as a standalone card replacing it. It adds a new "Composition" section with explicit guidance on border depth and structure, updates the intro example to demonstrate unboxed badge-first usage, and renames the "Titled card" example to "Focused inset" to align with the new guidance.

• Adds a ## Composition section to guide.ts with four actionable rules: start unboxed, use bordered boxes as insets, keep borders one level deep, and don't wrap the full body.
• Replaces the old <card border-color=...> example with a <box border ...> focused inset, and updates the closing paragraph to reinforce the new pattern.
• Adds a regression test in guide.test.ts that anchors the exact phrases agents are expected to learn, preventing accidental guide drift.

Confidence Score: 5/5

Safe to merge — changes are confined to guide prose, one test, and a changeset file with no runtime logic touched.

All three changed files are documentation or test fixtures. The guide string is a template literal with no branching logic; the new test guards the exact phrases agents are expected to learn, so any future accidental text drift will be caught immediately. The stmlGuideSnippets extractor is unchanged and the existing layout tests continue to cover every fenced snippet at the reference width.

No files require special attention.

Important Files Changed

Filename	Overview
src/ui/lib/stml/guide.ts	Adds Composition section and updates examples to reinforce unboxed-first, one-border-level guidance; no logic changes.
src/ui/lib/stml/guide.test.ts	Adds a string-presence test covering the new composition guidance phrases; all existing tests remain intact.
.changeset/teach-stml-note-composition.md	New patch-level changeset entry for the hunkdiff package; description matches the scope of changes.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Hunk note frame\n(drawn by Hunk: author, source location)"] --> B["STML body\n(rendered from --markup / markup field)"]
    B --> C["Verdict badge + plain summary text\n(start unboxed)"]
    C --> D{"Evidence needed?"}
    D -- "single inset" --> E["<box border> inset\n(one border level)"]
    D -- "comparison / metrics" --> F["<row gap>\n  <box border> sibling A\n  <box border> sibling B"]
    D -- "no extra framing" --> G["Plain text, badges, gauges"]
    E -. "FORBIDDEN" .-> H["<box border> inside another <box border>"]
    F -. "FORBIDDEN" .-> H

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A["Hunk note frame\n(drawn by Hunk: author, source location)"] --> B["STML body\n(rendered from --markup / markup field)"]
    B --> C["Verdict badge + plain summary text\n(start unboxed)"]
    C --> D{"Evidence needed?"}
    D -- "single inset" --> E["<box border> inset\n(one border level)"]
    D -- "comparison / metrics" --> F["<row gap>\n  <box border> sibling A\n  <box border> sibling B"]
    D -- "no extra framing" --> G["Plain text, badges, gauges"]
    E -. "FORBIDDEN" .-> H["<box border> inside another <box border>"]
    F -. "FORBIDDEN" .-> H

Loading

_{Reviews (1): Last reviewed commit: "docs(markup): clarify native note compos..." | Re-trigger Greptile}