bbdfe4e changed the materials-status logo example in SKILL.md but left
dist/kami.zip on the old content, so the package staleness check failed
in CI and Claude Desktop users would have downloaded the stale runbook.
Claude-Session: https://claude.ai/code/session_01T1B2mDXwfQsgTw7QuMnEyP
Three claims no longer matched the tree: the PDF /Author is written by
render.py not build.py, the responsive-screenshot rule moved to section
12, and the CJK font chain listed the same family twice.
The ZIP rebuild rule contradicted itself across two lines, one demanding
a refresh and one leaving it to judgment on an overlapping trigger set,
so they are now one rule.
Package freshness is also the precondition for answering a reporter:
main reaches npx skills add immediately while Claude Desktop users
download the release asset, so the reply has to name the channel that
carries the fix.
The example status block used a repo-relative 'assets/client-logo.svg'
that does not exist. Skill managers that validate referenced support
files during fetch (Hermes) treated it as a real asset and rejected the
install. A client-supplied logo never lives inside the skill package, so
the absolute-path form is both accurate and inert to path validators.
Make artifact briefs, capability checks, screenshots, and required assets fail closed. Preserve the last good render, move heavy tests onto the covered CI path, and require exact tag, SHA, and package identity before release upload.
The DO/DON'T card grid read as generic AI output and broke the page's
hairline editorial language; the ledger reuses the existing row idiom.
Also aligns the stale orange-era rgba value in zh/tw copy with the
ink-blue brand.
check / render and verify (push) Has been cancelled
V1.11.0 shipped while CI had been red for seven consecutive runs. The
flow had no step that looked at it, and a full local pass was treated as
the verdict, which it is not: local green says the working copy is fine,
CI green says a clean checkout is fine, and only the second describes
what a user downloads. The failure itself was a test reading gitignored
build output, so it could only ever pass on a machine that had built.
Claude-Session: https://claude.ai/code/session_01KgPeQ4ApebVquCZQXWKCfx
--check-fonts reads the text spans of a rendered PDF, so it needs
pymupdf. The verify-render job installed only weasyprint and pypdf, and
the step exited 2 on the missing dependency instead of judging any fonts.
Claude-Session: https://claude.ai/code/session_01KgPeQ4ApebVquCZQXWKCfx
The single-page density test pointed at assets/examples/one-pager.pdf,
which is build output and gitignored, so it passed locally and failed on
every fresh checkout. CI has been red since the test landed, through a
release, because local runs were treated as the verdict.
The fixture is now synthesised: an A4 page filled with parchment and
inked across the top third, which also pins the expected verdict rather
than inheriting whatever the template currently renders. Without PyMuPDF
the test skips, matching how the rest of the density suite behaves in the
lint-and-test job.
Claude-Session: https://claude.ai/code/session_01KgPeQ4ApebVquCZQXWKCfx
The homepage quick-reference table advertised a 0.5pt closed border with a
6pt radius for code blocks, a closed 0.5pt brand border for marking a
card, and an 8pt-radius data card. The first is the double-ring pitfall
templates are failed for, the second sits outside the three registered
left-rule weights, and the third uses a radius no template has ever set,
around a component (.metric) whose whole point is that it is not a card.
All five locale pages carried it, in four places each.
--check-docs reads Markdown fences, so it could not see any of this: the
site teaches in prose. site_facts.py now reads the rendered copy of every
locale page and fails on the combinations the design system forbids
outright, which is the surface where a stale recipe does the most damage,
since both readers and crawlers take it as current.
Claude-Session: https://claude.ai/code/session_01KgPeQ4ApebVquCZQXWKCfx
Three of these are the same shape: a convention with no gate behind it.
dist/kami.zip had no drift check. plugins/ has one and CI runs it, but
the archive Claude Desktop users download was verified for structure
only, so editing a source file and forgetting package-skill.sh left
every check green while the ZIP served the old content. The package test
now compares each entry against the file it was built from.
.callout shipped in two shapes: transparent in one-pager, ivory fill
plus radius in long-doc and equity-report, with the quick-reference
table describing only the first. One class, two forms, is what teaches a
reader that the shape is theirs to choose. It is now the filled form
everywhere, padding tightening per density, and the specs say so. The
neighbouring wording is settled too: .quote shares the rule but takes no
fill, and that is the line between a quotation and a raised passage.
CI never checked which family drew the CJK text, so a broken font
install would have shipped looking merely fine.
Claude-Session: https://claude.ai/code/session_01KgPeQ4ApebVquCZQXWKCfx
The rule shipped at four widths. Three of them are a real distinction:
2.5pt opens a section or document, 2pt lifts an aside out of the reading
flow, 1.4pt edges a block whose fill already carries the weight. The
fourth was drift, one-pager's .callout sitting at 1.8pt while the same
component is 2pt in long-doc and equity-report.
Collapsing all four into one value was the tempting fix and the wrong
one: it would flatten three roles into a single mark. What was missing
was the rule itself, which lived only in the templates and had to be
inferred by reading all of them. design.md now states it, and a test
holds the set closed, because a component at two widths is what teaches
a reader of these templates that the number is theirs to pick.
Claude-Session: https://claude.ai/code/session_01KgPeQ4ApebVquCZQXWKCfx
An agent copies a documented recipe before it reads a template, so the
docs are a shipped artifact and nothing was scanning them. CHEATSHEET.md
taught a .card pairing a 0.5pt border with an 8pt radius, the double-ring
pitfall templates are failed for, against --border-cream, a token defined
nowhere in the repo. design.md carried the same recipe plus --border-warm,
--ring-warm and --ring-deep, all equally dead, and a slide line-height the
templates set 0.10 tighter.
--check-docs scans every fenced css/html block with the template rule set
and resolves every var() against tokens.json plus what the shipped
templates define. It reuses the exemptions the template scan already
makes: SVG colors answer to the diagram palette, a `--x: #hex` line
declares rather than spends, and a line tagged /* avoid */ is the lesson.
The quick-reference tables now point at components the templates ship
instead of handing out recipes. Assembling a container from a recipe is
how a page ends up carrying three unrelated emphasis languages, and the
two most copied entries, an 8pt-radius data card and a brand left bar on
every section head, were exactly the drift showing up in generated
documents.
Claude-Session: https://claude.ai/code/session_01KgPeQ4ApebVquCZQXWKCfx
Sweep miss from the previous commit: the chain rewrite skipped
assets/demos wholesale, but these three carry the same parchment
--serif stack as the templates and would fall through to a system sans
in a box without the commercial primary.
demo-agent-slides keeps Charter leading its SVG chain on purpose: it is
a Latin-only deck, and the per-glyph split that reordering fixes only
happens once CJK text is present. Rendered output is unchanged (verified
by rendering the pre-change HTML through the same pipeline: zero pixel
delta), so the demo PDFs and PNGs are left as they are.
Claude-Session: https://claude.ai/code/session_01KgPeQ4ApebVquCZQXWKCfx
For SVG text a leading Latin serif ends the stack walk: characters it
has no glyph for go to fontconfig per glyph instead of continuing down
the declared list, so the CJK families written after it never get their
turn. Diagram labels rendered mid-word in two faces, with Hiragino
Mincho drawing some ideographs of a word and Songti SC the rest.
Also widens the chain with the alias names the same fonts carry across
distributions (Source Han Serif CN, Noto Serif SC, SimSun), so a sandbox
without the commercial primary lands on a serif rather than a system
sans. The -en templates keep Charter first: they are Latin documents.
Claude-Session: https://claude.ai/code/session_01KgPeQ4ApebVquCZQXWKCfx
A missing CJK serif produces no fallback boxes. It silently substitutes a
sans that still reads, so a perceptual pass signs off on a page whose
typography is no longer the system's, and the commercial primary never
ships inside the skill package, so a sandboxed install hits this by
default.
--check-fonts reads the rendered PDF's span table and names the family
that drew the body ideographs, failing on a non-serif substitution or on
text split across two families. --check-visual runs it inline, since that
was checklist item 1 all along. --check-style applies the template lint
rules to a produced document, counting distinct emphasis fills so one
form reused stays clean while a new container per idea does not.
scan_density skipped page 1 as a cover exemption, which left one-page
documents with no scanned page at all.
Claude-Session: https://claude.ai/code/session_01KgPeQ4ApebVquCZQXWKCfx
Agents landing from a search have no way to learn what Kami is for, how to
call it, or who maintains it without parsing marketing HTML. These pages and
their markdown twins state it directly, and say plainly that there is no
hosted API rather than leaving an agent to probe for one.
The site is a static deploy of this repo, so every agent-facing discovery
document has to be a committed file. Generating them keeps the version, the
MCP tool list, and the template catalog tied to their single source instead
of a hand-copied duplicate that rots on the next release.
The role-to-token table lived in design.md and mermaid.md on top of the JSON
both call the source. design.md now points instead of reprinting, so a token
change touches the JSON and one prose copy rather than three.
AGENTS.md and CLAUDE.md both load into every session here, and CLAUDE.md had
become a Chinese fork of rules it claimed to delegate. AGENTS.md now keeps the
facts an agent gets wrong without them and drops the rows that restate a
filename; the command list defers to build.py --help, which the two hand copies
had already drifted from. CLAUDE.md is an English pointer with only the
Claude-side workflow that is genuinely not repository policy.
Release notes, release flow, and demo regeneration move to docs/release.md
rather than references/, which ships inside the plugin mirror and the archive.
SKILL.md loads in full on every fire, so the sections that disqualify
themselves in their own first line were the expensive part. Deck pre-flight
("skip this step for every doc type except slides") moves to a reference,
the 15-row diagram table gives way to a router since diagrams.md already owns
selection, maintainer-mode checks are deleted as a straight copy of AGENTS.md,
and fonts collapses to the two facts that must not drift out of production.md.
Also fixes the contradiction where Step 1 told the agent to always read every
reference while Step 3's tier table existed to prevent exactly that, and routes
mermaid.md, which no path in the file reached.
anti-patterns.md had six duplicate rule ids (24, 41-45), which broke the
cross-file citation scheme; rows are renumbered contiguously 1..54 and every
citation site moved with them, including the prose reference inside the file.
The typography contradictions are resolved against what the templates actually
ship rather than by preference: CJK body letter-spacing is 0.3pt, the default
tag swatch is the registered --tag-bg token, the rgba ladder collapses to the
two tints that exist, and the metric row is documented as a print/screen split
instead of two pitfalls contradicting each other. The PPTX palette drifted from
slides.py and named two constants that exist nowhere in the repo.
sitemap.xml lastmod was two weeks behind the index pages it describes.
A feature row (a visual on one side, the points on the other) is the most
common way a landing page's feature section goes wrong, and no template ships
one, so nothing recorded how to build it. The instinct that produces it
("alternate the sides so it does not look like a product list") is the same
thing that breaks it: a fixed visual track against a 1fr copy track leaves
slack on every row, and mirroring drops that slack into the gutter, where it
reads as a hole and pulls the copy closer to the page edge than to the thing it
describes. Mirroring also moves the copy's left edge every other row, which is
the only structure a short bullet list has.
Section 11 now carries the positive spec: compute the slack first, keep it on
the outer trim, mirror a text mass but never a short list, run every row the
same way, and buy variety with unequal weight rather than alternation. It also
records the three geometric rescues that do not work, so they are not retried.
Anti-pattern #41 is the compact form.
check_off_palette blanks the :root block before scanning, so an
off-palette token defined but never used as a literal hex escaped every
guard. A dead #a64f33 terracotta second accent hid in portfolio this
way, against the single ink-blue accent invariant. Scan :root token
definitions too (print templates only; screen-local tokens and the
registered --breaking-* stay exempt), remove the dead token across the
portfolio locales, and correct the stale "orange highlight" comment in
resume that no longer matched the ink-blue .hl.
Architecture diagrams that live in a user's repository need a
lifecycle, not a one-shot render: without a trio contract and an
evidence pass, every redraw loses the previous intent, and future
capabilities keep getting drawn as shipped facts.
Empty-scan guards for the four config checks and two KO tests, a site
version-badge assertion tied to VERSION, a packaging coverage gate so a
new tracked script cannot silently miss the zip, a sibling placeholder
parity test locking the #38 bug class, merged multi-block :root parsing,
one-sided cross-template var drift reporting, Marp CSS joining the lint
scan, shared walk/rel/pdf helpers, single-file update-check marker with
portable version sort, and PID-suffixed font temp files with EXIT trap.
Issue #38's degradation class recurred beyond the resume project cards:
portfolio project blocks, resume repo/event/role/metric rows, one-pager
second-section bullets, and long-doc body paragraphs all carried rich
hints on block 1 and bare or drifted hints on later siblings. Fillers
follow the nearest placeholder, so degraded hints produce degraded copy.
Blocks 2 and 3 of the resume project cards carried degraded placeholder hints (CN lost the position cue entirely); unify all three blocks to the full first-block hints across CN/EN/KO and their plugin mirrors. Add SKILL.md Step 4.2, a pre-build recruiter pass that checks prose quality mechanical checks cannot see, with row definitions sourced from references/resume-writing.md.
Closes#38
changelog CN/KO templates referenced an undefined --mono var, so inline
<code> fell back to the serif stack instead of monospace; define it to
match changelog-en. Guard checks.py fitz.open against malformed PDFs so
the orphan/density/balance checks report ERROR instead of a traceback.
Make highlight.py palette lazy so importing it never reads tokens.json
on a half-installed checkout. Extract pure density/rhythm/orphan seams
and repoint the density test off its reimplemented thresholds onto the
real logic. Align README template count and refresh sitemap lastmod.
CLAUDE.md-only rules never reach Codex and other runtimes that read
AGENTS.md, so product-level hard rules must live there; the precedence
note stops the two files from drifting apart silently.
Architecture panoramas kept getting crammed into the single 9-node
figure. Boards now have their own reference rules (five fixed layers,
bands over cards, judgment-style copy, 4px connector standoff), a
template with a real five-layer demo, and the diagram count moves to
18 across docs, site locales, the print demo, and the skill package.
The Metric component sample used 6 doc types while its sibling values
(Accent 1, Rules 8) are real stats, so align it to the actual eight
document templates.
Reframe the FAQ (JSON-LD and visible) across all five locales from "nine
template types" to eight document templates plus a landing-page system,
matching the README, registry, and llms.txt. Swap the portfolio gallery
card for the white-paper print one-pager so the print capability is
visible on every locale homepage; the portfolio demo stays tracked.
Put the white-paper print one-pager in the README showcase grid so the
print capability is visible at a glance; it replaces the redundant second
resume cell (Korean), and the Korean resume demo stays tracked for reuse.
Reframe "Nine types" as eight document templates plus a landing-page
system, matching the registry, the demo metric, and llms.txt.
Dogfood the print variant with a one-page Kami intro rendered on white,
and link it from the README Print bullet as the worked example. Demos are
excluded from the skill package, so this adds no package weight.
Tw93