Lessons — docade-plush@1

Rules derived from real verdicts. Never speculative advice. See docs/07-CORPUS-LEARNING.md.

Seven of these were promoted to docs/corpus/craft/ on 2026-08-19, which is loaded into every compile for every client and lane. They stayed here too: the general rule is what transfers, and the concrete instance is what makes it legible. The originals are the evidence for the general form.

L-005's rarity hexes, L-006's tier contract and L-007's plush vocabulary stay lane rules — they collapse into nothing without docade in the sentence.

L-001 — The plate wins arguments with the prompt

From: run r-20260818-4648, all candidates.

The compiled prompt said, verbatim, "No black outline or keyline anywhere" and "No rim light and no back-edge glow of any kind." The output had both, because the reference plate contained two near-black fills doing contour duty and the model elaborated them into lighting.

Apply: when conditioned output shows a treatment the brief forbids, fix the plate before touching the wording. Negations lose to images. A plate teaches everything it contains, faults included.

Effectiveness: applied at v1 by retinting the plate (scripts/tint-plate.mjs). Keyline and rim both disappeared in r-20260818-f2bd. Confirmed once.

L-002 — Name what to keep and what to override

From: runs r-20260818-4648, -f2bd, -33b3.

The plate is flat and has no weight; the lane needs weight. Prompts that only described the target produced either the plate's flatness or the model's default photorealism. Prompts that explicitly split the instruction — keep the fill structure and shading discipline, override the flatness with volume and contact — landed between the two.

Apply: every brief in this lane states both halves. Never assume the model will infer which properties of the reference are the point.

Effectiveness: applied on three runs, held on all three.

L-003 — Describe how a quality shows, not that it is wanted

From: run r-20260818-42e1, and carried forward.

Asking for "weight" did nothing. Describing how weight appears — arms flattening where they press down, broad occlusion underneath — produced it, even on the model that failed every other principle.

Apply: for each principle, write the observable, not the adjective.

Effectiveness: the only principle that passed on the very first probe.

L-004 — A generated asset must be rendered on a flat ground, because the cutout depends on it

From: run r-20260818-8ce3, two of three candidates.

No model here can emit a transparent background, so transparency is produced by keying out the ground in normalize. That makes the generation prompt responsible for something it looks unrelated to: if the model invents a photographic surface or a textured setting, there is no flat ground to key, and a rectangular slab of it survives onto the finished asset.

It is the most visible defect the pipeline can produce, and it passed mechanical QA — coverage and edge-occupancy both looked healthy with a third of the frame still attached.

Apply: every brief in a cutout lane states the flat single-colour background explicitly, and says why. qa.mechanical now fails a candidate whose cutout leaves full opaque rows or columns.

Effectiveness: new, one occurrence. Watch it.

L-005 — The plate carries structure, not hue

From: direction B's first conditioned pass, and Justin's choice of it.

The plate was violet, so when a crab came back orange I recorded it as a palette break and "fixed" it with an absolute hue lock. Both judgements were wrong.

#ff6b35 (streak) and #ffb020 (ticket) are committed docade tokens — that crab was on palette, not off it. And the deeper error was reading the plate as a colour reference at all: it carries fill structure, construction and level of simplification. Hue is a per-piece decision.

The consequence of getting it wrong would have been eighteen collectibles in a single hue, which is a set that does not feel like a collection — precisely the opposite of what the lane is for.

Apply: condition on the plate for structure. Choose each piece's base hue from the committed palette to suit the creature and to vary across the set. Shading stays darker values of that piece's own hue, which is what keeps principle 3 and the recolour economics intact.

Effectiveness: new. It reversed a rule I had written one pass earlier, which is the argument for testing a preference rather than defending it.

L-006 — Rarity is carried by shape and flat accent, never by light

From: probe r-20260818-1d47, and the reference pair r-20260818-bd0e.

The obvious rarity signals — glow, sparkle, shimmer, rim light — are all baked lighting, and baked lighting is computed for one base colour. Using any of them would have broken tintability, which is the economics the whole lane rests on.

What works instead, verified at 80px with no label beside a common piece:

• rare — a flat #4ac8ff accent on a small number of parts, plus one signature feature a common does not have.
• legendary — a flat #ffb020 accent and the most dramatic silhouette in the set. The whale's gold tail and the stag's gold antlers are both readable as legendary at card size, and both are just shapes.

Refinement found in the same pass: a legendary's base hue must contrast with its accent. Gold on the violet stag is instant; gold on the orange dandelion-lion is the weakest read of the seven, because the accent stops being a second signal and becomes more of the same.

Apply: rarity is an accent fill and a silhouette decision. Never a lighting decision. Choose the legendary's base hue against its gold.

L-007 — Plush antlers are solid forms, not linework

From: reference sheet piece 4, run r-20260818-bd0e.

docade's own sheet calls the stag's antlers "the finest linework in the catalog" and warns to check at 80px before approving. Rendered as a plush toy's antlers — thick, solid, simplified lobes — they hold completely at 80px and read as antlers.

The generalisation matters more than the stag: this lane has a jackalope, a narwhal tusk, a mammoth's tusks, spiral ram horns, crystal ibex horns and a toucan beak ahead of it. Every one of them is a thin thing in the real animal.

Apply: any feature that is fine or branching on the real creature becomes a thick, solid, simplified plush form. The rule is not "draw it smaller", it is "a stuffed toy could not be sewn that way."

L-008 — A collectible's body hue comes from the signal colours, never the neutrals

From: batch r-20260818-0ab0 / -e74d, six of ten pieces.

The contract said "one base hue chosen from the committed palette." The compiler obeyed it exactly and gave the bear #f5f3ff and the raccoon a neutral — both genuinely in the palette, both catastrophic as a body colour. They came back washed out, barely separating from the #262c4a they must sit on, and reading as realistic teddy bears rather than as this lane's pieces.

The palette has two kinds of colour in it and the contract did not say so. Five signals are for artwork; five neutrals are chrome for the interface. Naming them in one list invited exactly this.

Apply: body hue is one of the five signals. Neutrals are eyes, teeth and small trim only. Where a set needs six distinguishable pieces from five hues, separate two of them by value rather than reaching for a neutral.

Effectiveness: new. Caught in review before anything shipped, which is the argument for judging a batch as a set rather than a piece at a time.

L-009 — Hue is a property of the set, not of the piece

From: the Forest batch, r-20260818-8b4b.

Told to pick a base hue "to suit the creature", six pieces each chose well and the set came back four-sixths orange. A fox is orange, a bear is warm, an owl is tawny, a deer is russet — every individual choice defensible, and the set a failure at exactly the thing it exists for: being a collection of six distinguishable cards.

I made it worse by telling the bear "streak orange suits a bear" without checking that the already-approved fox was orange. The compiler cannot see outside its own batch, so it cannot catch this. The brief has to carry it.

Apply: state the hues a set's approved pieces already hold, and require a new piece to take an unused one. Assign hue at the set level before generating, never leave it to per-piece judgement.

L-010 — A signature feature survives 80px by being a mass in the ACCENT colour

2026-08-19, sunbaked/jackalope, three attempts.

The confirmed reference sheet settled this rule: "Antlers and every other fine feature become thick solid plush forms, because linework dies at 80px." I applied it as written and the piece failed twice.

• v1 — "thick solid simplified plush horns, chunky padded felt uprights." Came back as thin branching sprigs. Gone at 80px.
• v2 — harder still: "as fat as the ear beside it, exactly one stubby forward prong, nothing thinner than an ear." Came back genuinely thick — and still failed, because it was violet, the body hue, with cyan only on the tips. A thick shape in the body colour merges into the body's silhouette. At 80px it read as a rabbit with four ears.
• v3 — each antler one fat padded slab filled entirely in flat token cyan #4ac8ff, edge to edge, no violet in it. Reads instantly, and beside the common gold jackrabbit in the same set the rare is unmistakable.

The rule is not "thick". Thickness is necessary and not sufficient. A feature reads at card size when it is a solid mass in a colour that differs from the body — which is to say, silhouette and local colour do the work together, exactly as the style contract says separation is achieved everywhere else ("no outline — separation is by value and local colour").

The approved stag had already proven this and I did not transfer it: its antlers worked because they were a gold slab on a violet body, not merely because they were fat. Two renders bought a lesson that was sitting in an exemplar.

How to apply. For any rare or legendary whose rarity rides on one feature, spend the rarity accent ON THAT FEATURE as a full flat fill — not as trim, not as tips. Cyan antlers, gold tusks, cyan fins. The accent and the signature feature are the same decision, not two.

L-011 — The set hue plan must be computed, not written

2026-08-19, frostline. Second occurrence of L-009 in a different disguise. L-009 was the compiler choosing hues per piece; the fix was to state the plan in the brief. But the plan was then prose I typed, and prose cannot be checked: I wrote "seal = accent violet" into a set whose rare and legendary were already violet. Three of six on one hue, gold unused, on exactly the pieces where hue has to help carry rarity.

lib/hueplan.mjs now computes the plan and — the part that matters — validates any plan, computed or overridden, inside art brief, before the estimate. The rules it enforces:

• Every body hue is a signal colour; never a neutral (L-008).
• A set of n pieces spans min(n, 5) distinct hues.
• A rare's base is not the rare accent; a legendary's is not the legendary accent.
• Rare and legendary do not share a base hue.
• When a hue must repeat, the repeat lands on two commons — a common wearing the legendary's hue spends the legendary's distinctiveness and buys nothing.

One measurement came out of building it. Choosing the legendary's base by hue angle alone picks cyan for a gold accent (159° away) over violet (148°), which is backwards: gold on cyan is two light fills touching and disappears at 80px, while gold on violet is light on dark. The contract already knew — "gold on violet reads instantly; gold on orange is weak" — so the selector weights lightness difference above hue angle, and hue only breaks ties.

L-012 — Batch review cannot see the collection

From: meadow/rabbit and sunbaked/jackrabbit, 2026-08-19.

meadow/rabbit came back a gold sitting rabbit with upright ears. So had sunbaked/jackrabbit, approved two batches earlier. Each piece is good. Each set is coherent. Together they are two cards that look the same, which is a defect in a collectible grid however good either one is alone.

Nothing in the loop could catch it. The compiler sees one batch. The batch sheet shows six pieces that happen to be siblings. It was obvious within seconds of all sixty being on one page, and invisible before that.

Apply: render art contact docade/plush and look at it before declaring the lane produced. Judge it for what a set sheet cannot show — duplicated silhouettes across sets, tier signals that drifted between sets, sets that read as one set.

Effectiveness: new, one occurrence, and it cost one re-run. The general form is in docs/corpus/craft/collection-coherence.md.