Skill/references/schlib_parameters.md

# Mandatory symbol parameters (.SchLib)

Vecmocon's Altium SOP (§5) requires every schematic-library symbol to carry a fixed set of
parameters in its component properties (the panel shown in Altium: *Properties → Parameters*).
This file defines that set, where each value comes from, and how the skill stamps them onto the
`.SchLib` symbol.

How the parameters get in: the skill writes them **directly into the `.SchLib` in pure Python**
via `scripts/schlib_write.py` — it rebuilds the OLE compound file around the enlarged component
`Data` stream while preserving every other byte (all other streams, the directory tree, the
Altium CLSIDs). It also **removes the Ultra-Librarian default params `Manufacturer_Name` and
`Manufacturer_Part_Number`** (which duplicate the SOP `Manufacturer` / `Manufacturer Part`), the
UL **`Copyright`** notice (Vecmocon symbols don't carry it), and the UL **`Component_Type`**
(underscore) — replaced by Vecmocon's own spaced **`Component Type`** parameter (see below).
The output is a ready `.SchLib`. Because this writes Altium's own format from outside Altium, the
script self-checks that the result re-opens as a valid OLE with the params present — but **always
open the result in Altium once to confirm it loads** before relying on it. (An older path,
`scripts/altium_params.py`, instead emits an Altium DXP script to stamp the same parameters from
inside Altium; keep it as a fallback if a particular file doesn't round-trip.)

## The parameter set

Use these exact Altium parameter names (they must match the symbol, per the SOP screenshot).
The **Comment** field is set to the MPN (SOP §4), and the **Description** field is the strict
string from `references/description_format.md` — the *same* string as the part's Excel
`Description` column. Both are written by `schlib_write.py` from the `comment` and `description`
keys of `params.json`; neither is optional.

| Parameter | Source | Notes |
|-----------|--------|-------|
| `Component Type` | derived | the part's **Class** — `Resistor`, `Capacitor`, `Diode`, `Transistor`, `IC`, … — from the taxonomy row for its typeid (`scripts/common.py:class_folder(typeid)`) |
| `Value` | datasheet | the component **value only** (no package), in shorthand — e.g. `1u`, `12p`, `100n`, `10k` |
| `Manufacturer Part` | datasheet | the MPN; also the **Comment** field |
| `Manufacturer` | datasheet | manufacturer name as printed, e.g. `YAGEO` |
| `Manufacturer Part 2` | **leave blank (for now)** | second-source MPN — left empty by default; see optional note below |
| `Manufacturer 2` | **leave blank (for now)** | second-source manufacturer — left empty by default |
| `Process` | derived | assembly process from package: SMD → `Reflow`, through-hole → `Wave`/`Manual`; confirm |
| `Vecmocon Part Code` | engineer | internal code (e.g. `VECESC2421`) — **not on the datasheet**; ask |
| `Operating Temperature` | datasheet | full range, e.g. `-55 °C to +125 °C` |
| `Tolerance` | datasheet | e.g. `1%` (or `±1%`) |
| `Datasheet` | derived | **Gitea link to the pushed `<MPN>_data.<ext>`** — see below (SOP marks this optional) |
| `ROHS` | datasheet | RoHS compliance, `Yes`/`No` |

**Read the datasheet-sourced values from the actual datasheet — don't echo whatever text was
handed to you.** Open the PDF, find each real value (`Value`, `Manufacturer Part`,
`Manufacturer`, `Operating Temperature`, `Tolerance`, `ROHS`, and `Process` by
inference from the package), and fill them verified. An honest blank beats a guess — the SOP
hides blank parameters, so a gap just stays empty until someone fills it. Only **one** field is
purely internal and must come from the engineer: `Vecmocon Part Code` — ask for it.

**The `Datasheet` field is a link, not a value read off the PDF.** Point it at the datasheet
this skill pushes into the part's Gitea folder (`<MPN>_data.<ext>`), so opening the symbol in
Altium clicks straight through to the exact datasheet used. Build it from the config
(`GIT_HOST`, `LIBRARY_REPO` in `config/gitea.env`) and the part's Class + tag:

```
https://<GIT_HOST>/<LIBRARY_REPO>/raw/branch/main/<Class>/<MPN>_<make>_<typeid>/<MPN>_data.<ext>
```

e.g. `https://gitea.vecmocon.com/nitishKumar/library/raw/branch/main/Diode/BAT46WJ_Nexperia_SCH/BAT46WJ_data.pdf`.
Use the `raw/branch/<default-branch>` form (not `src/…`) so the URL opens the PDF directly;
`<Class>` is `class_folder(typeid)` and `<MPN>_<make>_<typeid>` is the same tag the folder is
pushed under, so the link always resolves to the file that lands in Gitea. Fill this link even
on the first push of a new part — the push and the symbol write happen in the same run, so the
URL is valid as soon as the part folder lands. (If for some reason the datasheet isn't being
pushed to Gitea, leave `Datasheet` blank rather than writing a link that won't resolve.)

The second-source pair (`Manufacturer 2` / `Manufacturer Part 2`) is **left blank for now** —
don't populate it by default. It simply stays hidden in Altium until someone fills it later.

## Optional: second-source cross-reference (currently off)

**House preference right now is to leave `Manufacturer 2` / `Manufacturer Part 2` blank**, so do
not do this unless the engineer explicitly asks you to find a second source. It's documented
here so it can be switched on later without redesigning anything.

If asked to find a second source, it is an **equivalent part from a different manufacturer** that
could drop into the design unchanged:

1. **Pull the original's form-fit-function specs** from the datasheet — capacitance, voltage,
   tolerance, dielectric/temp class, package (for a cap); resistance, power, tolerance, package
   (for a resistor); and so on per type.
2. **Search for an equivalent from a *different* manufacturer** (distributor/parametric
   cross-reference, "equivalent to `<MPN>`", or another reputable maker's matching series). It
   must match **every** form-fit-function spec and be **at least as good** on tolerance /
   voltage / temperature — never worse.
3. **Fill** `Manufacturer 2` = its maker, `Manufacturer Part 2` = its exact MPN.

Two hard rules if this is ever used: **never invent an MPN** (only a part number you verified
exists; else leave blank), and **always flag the chosen second source for the engineer to
confirm** with the specs you compared.

## Building the parameter set

Collect the values into a `params.json` (same spirit as `part.json`). `component` is the
symbol's Library Ref (from `altium_refs.py`); omit it to apply to every component in the lib.

Two top-level fields sit alongside `parameters` and are **both mandatory**:

- **`description`** → the symbol's `ComponentDescription`. This must be **byte-identical to the
  part's Excel `Description` column** — the same strict `Class_TYPEID_…` string built to
  `references/description_format.md`. Build it once, use it in both places; never let the two
  drift. A symbol must never ship carrying Altium's `No Description Available` placeholder.
- **`comment`** → the Comment record's Text, which per SOP §4 is always the exact MPN.

Both are patched **in place**, so the records keep their other fields (Comment keeps its
Location/Color/FontID); only the parameter block is dropped and re-added.

```json
{
  "component": "CC0402FRNPO9BN120",
  "description": "Capacitor_CER_12pF_50V_±1%_0402_c0g",
  "comment": "CC0402FRNPO9BN120",
  "parameters": {
    "Component Type": "Capacitor",
    "Value": "12pF_0402",
    "Manufacturer Part": "CC0402FRNPO9BN120",
    "Manufacturer": "YAGEO",
    "Manufacturer Part 2": "0402N120F500CT",
    "Manufacturer 2": "Walsin Tech Corp",
    "Process": "Reflow",
    "Vecmocon Part Code": "VECESC2421",
    "Operating Temperature": "-55 °C to +125 °C",
    "Tolerance": "1%",
    "Datasheet": "https://gitea.vecmocon.com/nitishKumar/library/raw/branch/main/Capacitor/CC0402FRNPO9BN120_YAGEO_CER/CC0402FRNPO9BN120_data.pdf",
    "ROHS": "Yes"
  }
}
```

## Writing them into the symbol

Write the parameters straight into the `.SchLib`, producing a new file:

```bash
python scripts/schlib_write.py --schlib <in>.SchLib --params params.json --out <out>.SchLib
```

`params.json` may carry a `"remove"` list (defaults to `["Manufacturer_Name",
"Manufacturer_Part_Number", "Copyright", "Component_Type"]`); those Ultra-Librarian defaults are
stripped and the SOP params — including the spaced `Component Type` = Class — added. The script
also sets `ComponentDescription` from `"description"` and the Comment Text from `"comment"`, and
warns on stderr if `"description"` is missing — **treat that warning as an error** and re-run
with the Description rather than shipping the symbol. It targets the component named in `"component"` (its Library Ref / storage name),
or every component if omitted, and self-checks the output re-opens as a valid OLE with the
params and Description present. Deliver the
resulting `.SchLib`, and have the engineer open it in Altium once to confirm it loads, then Save
to Server with a revision note per the SOP.

The script needs the `olefile` package (`pip install olefile`) — its only non-stdlib
dependency. Install it if the import fails.

Scope note: the d