lovstudio-hanzi-lens

Hanzi Lens

Turn one Han character into a source-backed visual explanation. The character is the subject: do not infer a person's character, fate, relationships, or identity unless the user explicitly changes the scope.

character
→ Unicode + font coverage
→ source hierarchy
→ fact / commentary / interpretation boundary
→ semantic model
→ professional Exhibit
→ domain + visual release gates

Required references

Read these completely before authoring:

references/research-standard.md
references/visual-grammar.md
references/output-contract.md

Read references/user-config.md when brand or output configuration is unresolved.

The dependency lovstudio-professional-infographic is mandatory. Read its SKILL.md and required references before creating or reviewing the Exhibit.

Non-negotiable outcome

For the standard visual route, deliver:

a verified reading with region or standard attached;
Unicode identity and a passing glyph-coverage report;
form analysis that distinguishes semantic, phonetic, and uncertain parts;
historical lexicography with exact source labels;
at least two classical examples in context;
one governing semantic relationship, not a dictionary card wall;
an explicit boundary between fact, commentary, interpretation, and visual metaphor;
editable exhibit/poster.html and high-resolution exhibit/poster.png;
source.md, research.json, brief.md, font-report.json, exhibit/audit.json, and hanzi-audit.json;
full-size and thumbnail human review.

Never invent oracle-bone or bronze forms, turn a modern component mnemonic into historical etymology, flatten regional readings into one standard, or use unsupported rarity and auspiciousness scores.

Workflow

0. Resolve context and ask once

Use conversation context to prefill the character, focus, locale, aspect, and brand. Before running the first generation command, use AskUserQuestion once for the smallest unresolved choice. Recommended defaults:

scope: character only;
locale: compare mainland and Taiwan standards when they differ;
output: explanation + professional infographic;
aspect: 16:9 master;
brand: shared user profile.

Do not re-ask options the user already fixed. If the runtime does not expose AskUserQuestion, ask one concise plain-text question.

1. Create the research project

python3 "$SKILL_DIR/scripts/hanzi_lens.py" inspect "翕"

python3 "$SKILL_DIR/scripts/hanzi_lens.py" scaffold "翕" \
  --request "解释「翕」这个汉字" \
  --locale both \
  --output-dir "<project>"

The scaffold is intentionally incomplete and non-destructive. Never write into a non-empty output directory.

2. Prove that the glyph can render

Run before visual authoring:

python3 "$SKILL_DIR/scripts/hanzi_lens.py" font-check "翕" \
  --portable \
  --output "<project>/font-report.json"

For Extension B and later ideographs, IVS sequences, or a zero-match result, select and test an explicit font file. Do not substitute an image of a different glyph.

3. Research by source level

Browse and verify the character. Follow references/research-standard.md. Record exact evidence in source.md and structured evidence in research.json.

Required distinctions:

Layer	Meaning
Standard / dictionary fact	Current code point, reading, radical, strokes, recorded sense
Historical lexicography	What a named historical dictionary says
Commentary	What a named commentator infers from that dictionary
Interpretation	A modern synthesis supported by the above
Visual metaphor	Geometry used to help comprehension, never presented as paleography

If sources disagree, show the disagreement. Do not silently choose the most poetic version.

4. Build the semantic model

Complete research.json and brief.md before visual code.

Choose one governing relationship:

tension or motion, such as inward ↔ outward;
root meaning → semantic branches;
form component → function → recorded use;
two or more characters × consistent criteria;
documented chronological form evolution.

Every visible branch, arrow, coordinate, or contrast must map to a source ID.

Run the domain preflight:

python3 "$SKILL_DIR/scripts/hanzi_lens.py" audit \
  --project "<project>"

Warnings about a missing Exhibit are expected at this stage; research errors must be fixed before continuing.

5. Write the action title and scaffold the Exhibit

The title must state a supported finding about the character. Avoid topic labels such as “认识某字”.

python3 "$SKILL_DIR/scripts/hanzi_lens.py" exhibit \
  --project "<project>" \
  --title "<source-supported action title>" \
  --template driver-tree \
  --aspect 16:9

Template guidance is in references/visual-grammar.md. The generated template is only a semantic skeleton. Replace every placeholder while preserving the dependency's auditable data-* contracts.

6. Author for the character, not around it

Make the target glyph a dominant plotted mark, not a decorative watermark.
Use form, motion, contrast, or semantic branching as the main visual proof.
Use code-rendered HTML/CSS/SVG for all text, glyphs, labels, quotes, and sources.
Generated imagery is rarely needed. It must never fabricate ancient forms, calligraphy attribution, or pseudo-script.
Put regional reading differences and scholarly disputes next to the relevant mark.
Keep the brand subordinate.

7. Render and inspect

python3 "$SKILL_DIR/scripts/hanzi_lens.py" render \
  --project "<project>" \
  --scale 2

Open exhibit/poster.png at original size and at approximately 320 px wide. Review:

Can the reader repeat the governing insight after five seconds?
Does the glyph remain the subject?
Does the visual prove the title without reading every quote?
Can every claim be traced to a source ID?
Are fact, commentary, interpretation, and metaphor distinguishable?
Are rare glyphs, regional readings, and caveats legible?
Is there any generic card wall, fake ancient form, or empty container?

Revise deliberately. A machine pass is not the final judgment.

8. Run the strict release gate

python3 "$SKILL_DIR/scripts/hanzi_lens.py" audit \
  --project "<project>" \
  --human-review passed \
  --review-note "<full-size and thumbnail evidence>" \
  --strict

Release only when both the Hanzi domain audit and the delegated professional infographic audit pass with zero errors and zero warnings.

CLI reference

python3 "$SKILL_DIR/scripts/hanzi_lens.py" --help
python3 "$SKILL_DIR/scripts/hanzi_lens.py" inspect --help
python3 "$SKILL_DIR/scripts/hanzi_lens.py" scaffold --help
python3 "$SKILL_DIR/scripts/hanzi_lens.py" font-check --help
python3 "$SKILL_DIR/scripts/hanzi_lens.py" exhibit --help
python3 "$SKILL_DIR/scripts/hanzi_lens.py" render --help
python3 "$SKILL_DIR/scripts/hanzi_lens.py" audit --help

User configuration

Resolution order:

explicit CLI flags;
LOVSTUDIO_HANZI_LENS_* environment variables;
shared LOVSTUDIO_SKILLS_* environment variables;
${LOVSTUDIO_SKILLS_PROFILE:-$HOME/.lovstudio/skills/profile.json};
safe defaults under $HOME/Documents.

Relevant variables:

Variable	Meaning
`LOVSTUDIO_HANZI_LENS_OUTPUT_DIR`	Hanzi Lens output root
`LOVSTUDIO_HANZI_LENS_INFOGRAPHIC_SKILL_DIR`	Dependency skill directory
`LOVSTUDIO_SKILLS_OUTPUT_DIR`	Shared output root
`LOVSTUDIO_SKILLS_INSTALL_DIR`	Shared skill installation directory
`LOVSTUDIO_SKILLS_PROFILE`	Shared profile JSON
`LOVSTUDIO_SKILLS_BRAND_PROFILE`	Shared brand profile

Never hard-code a private workspace or brand path into a reusable project.