# Two-sided service silkscreen

The `silkscreen` AI-owned stage runs after analysis/net review and before the final native 3D tour. Plan label space at placement time. Read the reusable 3rd party fab's silkscreen skill (internal).


Treat silkscreen as the board's built-in service manual. Add useful information generously, with a visual hierarchy and space between labels. Do not fill space with ambiguous or unreadable text.

## Process profile and provenance

For the 3rd party fab profile requested by Adam (Adom CEO, 2026-09-16), use approximately 0.8 mm reference designators and 0.5 mm secondary value text where space allows. He reports that the 3rd party fab's UV fiber laser process can render readable 0.5 mm text. This is a named process target, not a universal fab minimum or a measured acceptance result. Verify the current station profile for stroke width, contrast, mask registration and clearances; retain the profile/version and inspect a physical coupon when fabrication qualification is required. Do not infer minimum stroke from text height. Preserve other fabs' rules and never disable DRC globally to force microtext through. Treat two-sided marking cost as a property of the selected service, not a universal free option.

## Plan before placement; finish after copper stabilizes

1. Read the actual schematic, BOM, board and approved requirements. Build a label manifest with text, source, reference/net, face, size, orientation and purpose. Reserve service-label space during placement. Finalize after routing, pours and analysis, before final DRC and the 3D tour. Return here whenever a pinout, rating or placement changes.
2. Put board name, function, revision and an enduring project/documentation link on the board. Use an approved logo if available. Keep decoration subordinate to connection and safety information. Do not invent certifications, copyright ownership or electrical ratings.
3. Label power inputs and returns, polarity, connector pin 1 and every accessible signal, machine pin/contact functions, programming/debug pinout, switch actions, LED meanings, test points and mounting orientation. Verify pin labels against actual numbered pads and nets, not the connector's apparent geometry. A net name does not establish a safe voltage or current rating. Print voltage range, maximum current and other limits only with approved design evidence; distinguish input rating, rail nominal voltage and absolute maximum.
   Every test point MUST have visible silkscreen identifying both its reference and verified net/signal or measurement function. Prioritize these labels before ordinary component values. Keep them adjacent to the accessible probe pad, or use a short unambiguous leader/key on the same accessible face when crowded. Check complete test-point coverage against the actual board; missing or ambiguous labels are unresolved findings, never silently omitted. Repeat on the opposite face when useful for mounted-board debugging, without implying a probe pad exists there.

4. Use approximately 1.2–2.0 mm for board identity and critical connection labels, 0.8 mm for references and 0.5 mm for values/secondary notes under the named 3rd party fab profile. These are starting sizes, not mandatory packing rules. Prefer horizontal text and consistent reading directions; rotate to follow a connector only when that aids use. Use familiar engineering notation (10k, 100nF, 4.7uF); distinguish value, tolerance and voltage rating. Give every resistor/capacitor its reference plus a nearby value; search microtext placements before declaring a space constraint. Long IC MPNs may belong in a back-side key rather than in congested assembly space.
Keep each reference unmistakably associated with its own component. Prefer reducing reference font size locally over moving a label farther away. Aim for complete reference coverage; use a short clear leader only when proximity alone is ambiguous. Treat approximately 0.8 mm as an initial reference size, not a minimum. For dense 3rd party fab artwork Adam explicitly permits secondary values at 0.3 mm or even 0.2 mm (2026-09-16); try 0.5, 0.3 then 0.2 mm while preserving the ref/value pairing and required stroke/spacing. These tiny sizes are user-requested artwork options, not independently verified laser-process capability. Keep the actual sizes and any unresolved physical legibility/DFM limits in the review; do not silently omit labels or globally weaken fab rules. Inspect the result at actual size and close-up.

5. For every machine pin, machine contact and edge-pin connector, repeat its reference/pin number and verified signal or power function on BOTH faces. A mounted board may expose only one side during debugging. Put the repeated labels beside the same physical connection where possible; when crowded, use a short clear leader to the actual connection on that face; a remote keyed legend is supplementary only. A pinout table on the other face alone does not satisfy this check. Review both faces in the mounted-access context, with bottom text correctly mirrored and pin numbering preserved. Use both F.SilkS and B.SilkS (or the EDA's native equivalents). Bottom text must read correctly when viewed from underneath, with the EDA's proper mirror setting; do not reverse the string. Put a clear pinout/service key on the less crowded face, mapped to reference and pad number. Copper/pour labels identify a verified net; avoid implying that hidden traces are visible or electrically isolated.
6. Protect exposed pads, solder-mask openings, test contacts, holes, board edges, fiducials, optical windows, component courtyards and mechanical interfaces. Consider visible space with components fitted: body footprints may obscure text even when DRC passes. Retain assembly-only markings on fabrication layers if useful, but do not count them as visible silkscreen. Never move copper or parts merely to force extra text without a recorded design return.
7. Inspect both faces at realistic physical scale and enlarged, in native 2D, native assembled 3D and fabrication plots. Check overlaps, legibility, bottom mirroring, ref/value association, clip-to-mask losses and labels covered by components. Run native DRC with the selected fab profile; compare new violations to the baseline. Keep manufacturing uncertainties explicit.
8. Save the label manifest, before/after plots, native review images and DRC comparison. Prove connectivity, placement, zones, model transforms and board outline unchanged for a silk-only edit. Record unresolved labels rather than inventing them.

## Flow and bridge ownership

AI Flow orchestrates this as a `silkscreen` step and records review evidence. Native text insertion, layer/mirror settings, font metrics, visibility, plotting and DRC belong to the EDA bridge. Discover current verbs; request missing reusable operations from the owning bridge. An offline board-copy script is a transparent fallback, not a new competing bridge API. Do not use mouse clicks in KiCad workflows that prohibit them.

Film a slow top/bottom overview and a brief connector-label close-up in the native EDA. Keep raw recordings, then budget roughly 3–5 seconds in the final two-minute film; publish detailed readable plots separately. A render proves appearance, not laser-process qualification.

## Record the silkscreen being built

Start the native editor window recording BEFORE the first label mutation. Show references and their smaller value labels appearing one at a time, or in small meaningful groups chosen by the AI (a ref/value pair, a connector pinout, or a local circuit block). Keep enough dwell for the actual recorder to capture each change; inspect the contact sheet instead of assuming a fixed delay guarantees a frame. Frame the active region so text and its component remain visible, with occasional whole-board context and a face change for bottom markings.

Keep the recording running through actual revision: moves, rotations, font reductions, value pairing, overlap fixes and rejected placements should be visible in their real order. Preserve native undo and stable item identifiers where the bridge supports them. Save a sidecar event list with timestamps, affected references/IDs, operation, old/new text/position/size and a concise reason. Record explicit reasons and actions, not private chain-of-thought. Reusable add/update/delete text, refresh and undo operations belong in the EDA bridge; AI Flow chooses the sequence, records evidence and composes the result. Do not invent an unsupported bridge command or silently replace the entire board for each label.

If incremental native editing is unavailable, report that bridge gap and retain honest intermediate saved-board checkpoints and before/after evidence. A reconstruction from checkpoints or a reveal of finished labels MUST be identified as a replay; it is not footage of the original placement or reasoning. Do not manufacture rework to make the film interesting. The existing ESC v16 top/bottom review is final-state evidence, not a progressive-placement recording.

Retain the full raw, uncaptioned step clip and offer a separate detailed action cut that shows population and real rework. In the final two-minute video use roughly 3–5 seconds of accelerated population, including a representative correction when one occurred, ending on the final labelled board. Keep exact step/run clocks and chronological provenance. Put explanations in the composed narration/captions, never in the raw clip. Finish with native top/bottom inspection and DRC; a pleasing animation does not establish label coverage or fabrication legibility.

## Contact labels must preserve physical association on both faces

Place every machine-contact, machine-pin and edge-connector label beside its actual physical connection on BOTH faces, not merely in a remote pinout table. Treat a table as supplementary reference only; it never satisfies positional labelling. Verify each face against pad coordinates and numbering, including bottom mirroring. Record unresolved space constraints rather than claiming table coverage completes this requirement.

Separate the primary reference (for example MC10) from the secondary verified function (DSHOT). Use independently sized native text items: the function is smaller than the reference, allowing the pair to stay near the contact. Keep the pair visually grouped and readable in one direction; prefer consistent horizontal rows along a dense contact bank over alternating rotations that obscure association. Reduce size locally when necessary under the selected fabrication profile.

When proximity is still ambiguous, draw a short curved silkscreen leader from the label group toward its particular contact. Use a gentle arc or rounded path with an unmistakable endpoint outside exposed copper and solder-mask openings. Do not run a leader through another label, contact, part body, hole, board edge or another leader; keep clearance from unrelated silk. Avoid ornamental curves and crossings. Inspect both faces in native 2D and assembled 3D at contact-bank close-up scale, checking that each label and each leader points to exactly one intended connection. Native DRC remains required; a leader must not become clipped silk or resemble an electrical trace in the documentation.

Film real leader placement and ref/function resizing as part of progressive silkscreen capture. Native text, curves and undo operations belong in the EDA bridge; AI Flow owns the guidance, coverage checks, recording and composition. Retain source-to-pad mapping and unresolved physical font/stroke limits in the manifest.

## Complete local value coverage

For the requested 3rd party fab profile, attempt a nearby value for EVERY resistor and capacitor, including rotated components and references. Search both orientations and adjacent sides at 0.5, 0.3 and 0.2 mm as needed, preserving an unmistakable reference/value association. Do not skip values merely because the reference is rotated, an initial placement fails, or a bottom table exists. Repack nearby silk or use a clear short leader when necessary. Audit actual-board value coverage and report each unresolved value explicitly; a back-side key is supplementary, not completion. Retain native mask/overlap checks and distinguish requested artwork sizes from measured physical legibility.

## Keep both native views current after every update

After EVERY board, footprint, silkscreen, library-binding or 3D-model update, update BOTH the native 2D board editor and its associated 3D viewer before reporting or showing the result. A file write, successful transfer, DRC result or web preview is not a refreshed native view. Verify the exact saved board path/revision in the editor, then regenerate/reload the 3D view and inspect the changed features after painting settles. Capture evidence from both exact windows; confirm models, markings and layer visibility, not only the window titles.

Use supported native refresh/reload commands through the owning EDA bridge. If an offline edit or model cache requires closing and reopening, inspect unsaved changes and dialogs first, preserve user work, close only task-owned stale windows, reopen the latest board, and open its linked 3D viewer. Never save stale editor contents over a newer disk revision. Keep one current editor/viewer pair rather than accumulating old windows. Re-discover HWNDs after reopening; preserve the user's foreground and view preferences unless showing a view was requested. Refresh a completed edit or coherent batch promptly; do not wait until the final video. If either view cannot be verified, state which one remains stale and resolve it before claiming the update is shown.

## Search space before shrinking text

Treat 0.2 mm as an exceptional fallback, not a successful default. Start with the largest sensible font for the information hierarchy and search nearby positions, rotations and both sides of the component. Use the native EDA's stroke-font bounds, stroke width, justification, rotation and mirrored bottom-face transform. If only estimated bounds are available, identify them as estimates and validate every accepted batch with native plots/DRC and assembled 3D visibility.

Build obstacles from fitted component bodies, individual pads and solder-mask openings, vias/holes, board edges, existing silk and text. Do not replace a collection of separated obstacles with one enormous bounding box that discards useful gaps. Keep reference/value pairs associated but retain separate text rectangles so empty space between them remains usable. Solve each face with its own obstacles; a copied top layout is not a validated bottom layout.

Search alternative positions at each useful font size, then jointly repack neighboring label groups. Use a bounded search with backtracking or beam alternatives so an early label does not permanently consume the best space. Favor complete coverage, readable font sizes and short unmistakable association; preserve connector pin-row order. Reserve and validate curved leader paths too. Report unresolved labels rather than hiding or silently omitting them. Never move copper or components merely to fit text without a design return.

Use `adom-aiflow silkscreen-layout --input candidates.json --out layout.json --ai-thread <thread> --run <run>` for the shared bounding-box candidate search. Input carries board bounds, fixed obstacle rectangles and label groups with alternative native-derived rectangles, font sizes, positions and anchors. A candidate may provide several `boxes` for an intact ref/value pair or leader segments. This is a bounded weighted search, not proof of a global optimum; it does not edit the board. Native text measurement/insertion/refresh remains the EDA bridge's job. Apply by stable item identity, never by text alone: duplicate values and repeated pinout tables are common.

Run native clearance/overlap checks, compare findings against the inherited baseline, then inspect actual-size legibility and close-up association on both faces. Revise the candidates when validation rejects them; do not just call the search successful. Refresh both the 2D editor and its linked 3D viewer after an accepted batch. Record genuine placement and rework in the silkscreen step clip.

### Candidate geometry evidence

`tools/native-text-bounds.py --svg front.svg --labels labels.json --layer F.SilkS --out bounds.json` measures native stroke paths from a single-face KiCad SVG export. Export each face separately through the bridge. The label manifest contains `labels` with `text`, `x`, `y`, `size`, `angle` and `layer`. The helper reports its nearest-text matching method and SVG hash; inspect ambiguous duplicate/multiline mappings. It is a fallback geometry reader, not a native live text-metrics API. Preserve stable item IDs for application.

A `silkscreen-layout` input has `bounds: [xmin,ymin,xmax,ymax]`, `obstacles: [{box: [...]}]`, and `labels: [{id,anchor:[x,y],candidates:[{font,position:[x,y],box:[...]}]}]`. Optional candidate `boxes` describes separate rectangles for grouped text/leader segments; every rectangle must be clear. Optional `orderGroup` and numeric `order` preserve increasing connector-row Y. `beamWidth` and `candidatesPerLabel` bound the search. The score weights font size, distance and movement; it cannot promise the global optimum. All outputs retain `nativeVerified: false` until separate native review evidence is recorded.

For tightly coupled regions, set `solver: "milp"` to use SciPy/HiGHS mixed-integer selection with `solverSeconds`, `milpPerFont`, `preferredMinimumFont`, and `smallFontPenalty`. This optional engine needs SciPy; the default beam engine uses Python's standard library. Candidate pruning must preserve alternatives at every font size. Solver optimality only concerns the finite supplied candidate set, never all possible board artwork.

`tools/silkscreen-leaders.py --input candidates.json --out routed-candidates.json` accepts per-label `leaderTargets` and `routeBounds`, uses a bounded grid search around fixed rectangles, and appends leader segment bounds to each candidate. The final selection prevents those reserved paths crossing other selected text/routes. It retains alternatives per font size. Native application may gently round corners inside the cleared envelope; validate the actual resulting curves. Failure to route a leader must trigger repacking or an explicit unresolved finding.

### Complete obstacle coverage is required

Before placing or accepting silkscreen, enumerate every fitted model, via and drilled hole across the entire board, on both faces. Record coverage counts and stable IDs. A local search region does not excuse leaving the rest of the board unchecked. Project the actual fitted 3D model into the board plane with its scale, offset, rotation and footprint transform; include overhangs. Conservative transformed model bounds are acceptable when a tighter silhouette is unavailable. F.Fab, courtyard or pad envelopes are fallbacks, not proof of fitted-body coverage: a footprint can have no Fab drawing, and the space between separated pads can still be occupied by the body. Missing model geometry must be reported and supplied a documented conservative envelope, never a tiny placeholder that silently allows text beneath the component.

Reserve every via hole on both faces, including tented vias when visible labeling is the requirement, and use the larger of the hole keepout and actual exposed mask opening. Also reserve through holes, slots, exposed pads and existing silk. Check actual stroked text extents, not just its anchor. After each re-layout, audit ALL existing labels and leaders against this complete obstacle set. A collision-free position is not enough: keep each reference/value next to its own component or add a clear, noncrossing leader. Do not move a label beside a different component merely to clear an obstacle. Native DRC and fitted 3D visibility are separate acceptance checks; a DRC baseline does not establish readable assembled silkscreen. Refresh and inspect both native 2D and 3D views before presenting the result.

## Optional live silkscreen dashboard

Offer `silkscreen-dashboard show` with the run and ai-thread flags. The shared observer renders real timestamped solver events, sampled candidate bounds and reasons, selected proposals and unresolved labels, in 2D and a fitted-model 3D preview. `silkscreen-layout --events <run>/silkscreen-dashboard/events.jsonl` emits these without AI/provider calls or deliberate solver pauses. Read `tools/silkscreen-dashboard/SKILL.md` for the manifest, transform limits, lifecycle and recording contract. Live and replay are visibly distinct; replay exports are not raw native CAD footage. Selected proposals remain unverified until native application, DRC and assembled visibility checks pass. Fusion/Altium adapters are not implemented merely because the manifest is tool-neutral.

### Release quality: references, values and visual association

Do not accept a fresh solve based on text-object coverage alone. Place each reference
and required value atomically; reference text is larger, value text is normally
60–80% of reference height. Reserve both before placing the next component. Keep
connector rows in physical pin order and preserve that constraint on both faces.
An old layout is a comparison baseline, never evidence that a new solver succeeded.

Where a nearby component could be mistaken for the label's owner, provide a short
curved pointer to the intended component's visible rim. Where space permits, a
shared outline may group the component and its reference/value. These graphics
must clear mask openings, drilled holes, other bodies and all text. Avoid extra
lines where proximity already makes ownership unambiguous. If no safe association
can be drawn, repack or flag it for review; do not silently mark it complete.

Release proof includes a solve from empty label occupancy without old positions as
candidates, name/value hierarchy and completeness checks, connector-order checks,
collision checks including fitted models and vias, native EDA readback and DRC,
and human-readable top/bottom review with the full event replay. Show bottom from
below with readable text, or explicitly mirror text in a top-view projection.

Machine contacts and machine pins use an outside-first policy: the label sits
between the contact and the nearest board edge whenever feasible. Preserve row
order and side consistency; report inside fallbacks. Printed contact/name/value
frames default on (`contactBorders: true`), with `--no-contact-borders` for a solve
without them. Reserve every frame stroke during placement, and report any small
clearance gaps required around holes. This preference applies to both board faces.

### Board-specific importance pass before layout
The AI first identifies how the real board will be connected, powered, serviced and
debugged. Rank interfaces by their importance to those tasks, using verified board,
schematic and spec data. Write that ranking into the solve input; do not give every
label equal weight. Reserve prominent connection labels first, then component
reference/value pairs and secondary service notes. Only print voltage/current
ratings supported by the design review, never guessed ratings.

ESC / BLDC controller rule: PHASE A, PHASE B and PHASE C are prominent motor-terminal
names, normally targeting 1.0–1.4 mm where geometry permits, on both service faces.
Battery input and polarity/ground also deserve prominent identification. Phase
names are primary interface labels, not small component values: their MC/connector
reference can be smaller. Preserve the mapping to the actual terminal nets; never
infer phase order from screen position. Programming/debug labels remain legible but
must not consume the space reserved for power and motor connections. Document any
geometry-driven reduction from the desired hierarchy.


### Documentation sections are atomic
Board identity, instructions, warnings and service-reference tables must retain semantic sections. Preserve row order, a shared readable alignment, consistent line spacing and a larger heading. Place or resize the whole block; never sort individual lines by length or scatter them on generic center-column anchors. Bottom blocks align in the actual bottom-face reading orientation. Keep reference tables supplementary to labels beside physical connectors. Report an unresolved section rather than silently disassembling it. Replay one section at a time and expose its text heights.

Documentation blocks default to left-aligned visible glyphs, not merely aligned calculation boxes. Use the readable left edge on both faces, including bottom reflection. The dashboard must not recenter a shorter font rendering inside the EDA-measured box. Native exports may use equivalent centered anchors computed from measured glyph bounds, provided the actual ink shares the left edge.

### Visual consistency across connector groups
Treat repeated connector labels as a designed row or column. Prefer shared outer border rails, common widths/heights, padding, reference/value hierarchy and consistent spacing. Solve these at group level before independent placement. Reserve actual strokes against holes, masks and bodies. Never stretch borders after collision checks. Use consistent safe clearance gaps where needed; report any individual inside placement or sizing exception. Apply semantic importance first: ESC PHASE A/B/C are prominent functional labels. Documentation sections retain ordered, left-aligned text and headings rather than scattered rows.

Pin-label alignment is target-facing, not universally centered: right-align ink for labels left of their pad, left-align for labels right of their pad. Evaluate this in the visible face orientation, reversing it for the bottom view. Store the electrical target and alignment intent, keep measured native bounds, and avoid wasted visual gap between ink and the pad. Center only when it improves an intentionally symmetric group.


## Final documentation and priority review
Prefer readable documentation blocks in open board interior, not crowded rim space. Include a verified description of what the board does, based on its project wiki/spec. Physical connector, test-point and contact labels remain local on both faces. Check interior alternatives across readable sizes before using an edge fallback; reflow coherent sections around holes, never scatter their sentences. Preserve left-aligned visible text, heading hierarchy and ordered rows. Record reasons and selected font heights. The complete priority/pass checklist is in AI Flow `docs/silkscreen-priority-pass.md`; its ordered requirements apply before native DRC and both-view visual acceptance.

## Full-board process recording
For a short silkscreen population video, prefer a fixed full-board camera with Follow placement off. Preserve the selected follow setting when recording; do not silently enable it. Record every accepted placement group at a readable event cadence, top and bottom separately, with only the active face visible and the bottom shown from below. Keep the whole board inside the frame. Accelerate the recorded footage with ffmpeg to the requested duration rather than skipping placement events. Distinguish event replay from live solver timing. Finish with refreshed native EDA 3D evidence; for a one-minute film, reserve about ten seconds for that proof. Close-up follow mode remains optional for detailed review.