@px-lsp/server 0.3.0 → 0.3.1

package/src/features/locText.ts

@@ -0,0 +1,223 @@
+/**
+ * paradox/locText: a localization value as the PLAYER reads it.
+ *
+ * paradox/lookupLoc answers the value verbatim, which is what an editor needs.
+ * A panel that SHOWS the value needs the sentence. Measured over the 609
+ * `culture_parameter_*` values one game ships: 280 carry a real datafunction
+ * call, 145 of them the single shape
+ * `[GetTrait('rough_terrain_expert').GetName( GetNullCharacter )]`, and 130
+ * values nest another key as `$key$`. A form that prints those verbatim shows
+ * the modder brackets instead of "The Rough Terrain Expert Commander Trait is
+ * more common".
+ *
+ * Nothing here is written for one game. The words come from the loc index, the
+ * KIND a `Get<Something>('name')` chain names comes from the definition index,
+ * and the loc key that kind's names take comes from the active profile's
+ * schema. A profile whose schema knows the kind resolves the chain; one whose
+ * schema does not falls back to the definition name and says so, which is the
+ * same behavior for every game without a line of per-game code.
+ *
+ * No `vscode` imports: unit-tested in plain Node.
+ */
+import type { LocTextResult, LocTextValue } from "@px-lsp/protocol/protocol";
+import { chipFor, stripFormatting, tokenize } from "../gui/textResolve";
+
+export interface LocTextDeps {
+  /** The configured language's value for a loc key, or undefined. */
+  loc(key: string): string | undefined;
+  /**
+   * The definition kinds a name is indexed under, shadow-resolved, WITHOUT the
+   * loc_key kind (every name a value mentions is also a loc key).
+   */
+  kindsOf(name: string): string[];
+  /**
+   * The loc key patterns a kind's names take (`$` = the name), most specific
+   * first, straight off the schema entry. An unknown kind has none.
+   */
+  patternsOf(kind: string): string[];
+}
+
+/**
+ * The value, plus one level of whatever it inlines. A `$key$` hop or a
+ * resolved chain lands on another value that may itself hold markup (the
+ * `court_physician` key IS a `[GetCourtPositionType(...).GetName()]` call),
+ * and one more pass turns that into words. Deeper is the game's own business.
+ */
+const MAX_DEPTH = 2;
+
+/**
+ * `$key$`, with an optional format spec (`$VALUE|0$`). A key the loc index has
+ * is substituted; anything else stays verbatim and marks the value unresolved,
+ * because a slot the panel cannot fill is not a word.
+ */
+const NESTED_KEY = /\$([A-Za-z0-9_.\-']+)(?:\|[^$]*)?\$/g;
+
+/** `[prestige_i]`: an icon the game draws and plain text has no glyph for. */
+const ICON_TAG = /^[a-z0-9_]+_i$/;
+
+/** `[culture|E]`: a link to a game concept, shown as that concept's word. */
+const CONCEPT_LINK = /^([A-Za-z0-9_]+)\|[A-Za-z]+$/;
+
+/** `Localize('k')` / `Concept('k')` / `Concept('k','shown')`. */
+const LOCALIZE_CALL = /^(?:Localize|Concept)\s*\(\s*'([^']*)'(?:\s*,\s*'([^']*)')?\s*\)$/;
+
+/**
+ * `SelectLocalization( HasDlcFeature('x'), 'on', 'off' )`: the game picks by a
+ * condition the server cannot evaluate. The first branch is the one the
+ * feature-on player reads, which is what a creator preview should show.
+ */
+const SELECT_CALL = /^SelectLocalization\s*\(.*?,\s*'([^']*)'\s*,\s*'([^']*)'\s*\)$/s;
+
+/**
+ * `Get<Something>('name')` followed by member hops:
+ * `GetTrait('brave').GetName( GetNullCharacter )`, `GetMaA('bowmen').GetName`,
+ * `GetCourtPositionType('x').GetName()`.
+ */
+const DEF_CHAIN = /^Get(\w+)\s*\(\s*'([^']+)'\s*\)\s*((?:\.\s*\w+\s*(?:\([^()]*\))?\s*)*)$/;
+
+/** The members that mean "the name the player reads", measured in the corpus. */
+const NAME_MEMBERS = new Set(["GetName", "GetTypeName", "GetNameNoTooltip"]);
+
+/** The concept kind's own schema entry states the key a `[x|E]` link reaches. */
+const CONCEPT_KIND = "game_concept";
+
+/** `men_at_arms` -> `MenAtArms`, the spelling a datafunction name would use. */
+function pascal(kind: string): string {
+  return kind
+    .split("_")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join("");
+}
+
+/** The key patterns to try for a kind, most specific first, `$` last. */
+function patternsWithFallback(kind: string | null, deps: LocTextDeps): string[] {
+  const own = kind === null ? [] : deps.patternsOf(kind);
+  return [...new Set([...own, "$"])];
+}
+
+/** The first pattern that resolves for `name`, or undefined. */
+function locOfName(name: string, kind: string | null, deps: LocTextDeps): string | undefined {
+  for (const pattern of patternsWithFallback(kind, deps)) {
+    const value = deps.loc(pattern.replace("$", name));
+    if (value !== undefined && value !== "") return value;
+  }
+  return undefined;
+}
+
+/**
+ * The kinds to try for `Get<Head>('name')`, best first: a kind whose PascalCase
+ * spelling the function name carries (`GetCourtPositionType` -> `court_position`)
+ * outranks the rest, and a name the index does not know still gets the bare
+ * `$` pattern from `patternsWithFallback`.
+ */
+function candidateKinds(head: string, name: string, deps: LocTextDeps): (string | null)[] {
+  const kinds = deps.kindsOf(name);
+  const named = kinds.filter((kind) => head.includes(pascal(kind)));
+  const rest = kinds.filter((kind) => !named.includes(kind));
+  return [...named, ...rest, null];
+}
+
+interface Rendered {
+  text: string;
+  resolved: boolean;
+}
+
+/**
+ * A value a call resolved to, as words. One more pass turns its own markup
+ * into text; past {@link MAX_DEPTH} the formatting is stripped and the rest
+ * kept, so the recursion cannot run away on a self-referencing key.
+ */
+function inline(value: string, deps: LocTextDeps, depth: number): Rendered {
+  if (depth + 1 >= MAX_DEPTH) return { text: stripFormatting(value).trim(), resolved: true };
+  return render(value, deps, depth + 1);
+}
+
+/** One `[ ... ]` expression as words, and whether it became any. */
+function renderFn(fn: string, deps: LocTextDeps, depth: number): Rendered {
+  // `|0`, `|V`, `|E`: format specifiers after the chain. The concept-link form
+  // needs its suffix, so it is matched before they are dropped.
+  const concept = CONCEPT_LINK.exec(fn.trim());
+  if (concept) {
+    const value = locOfName(concept[1], CONCEPT_KIND, deps);
+    return value === undefined ? { text: concept[1], resolved: false } : inline(value, deps, depth);
+  }
+
+  const source = fn.split("|")[0].trim();
+  if (ICON_TAG.test(source)) return { text: "", resolved: true };
+
+  const localize = LOCALIZE_CALL.exec(source);
+  if (localize) {
+    const key = localize[2] ?? localize[1];
+    const value = deps.loc(key);
+    return value === undefined ? { text: key, resolved: false } : inline(value, deps, depth);
+  }
+
+  const select = SELECT_CALL.exec(source);
+  if (select) {
+    const value = deps.loc(select[1]);
+    return value === undefined ? { text: select[1], resolved: false } : inline(value, deps, depth);
+  }
+
+  const chain = DEF_CHAIN.exec(source);
+  const members = chain ? [...chain[3].matchAll(/\.\s*(\w+)/g)].map((m) => m[1]) : [];
+  if (chain && members.length > 0 && NAME_MEMBERS.has(members[members.length - 1])) {
+    const name = chain[2];
+    for (const kind of candidateKinds(chain[1], name, deps)) {
+      const value = locOfName(name, kind, deps);
+      if (value !== undefined) return inline(value, deps, depth);
+    }
+    return { text: name, resolved: false };
+  }
+
+  // Anything else is a value only the running game has. The chain's last word
+  // is what the preview shows, never an invented one.
+  return { text: chipFor(source), resolved: false };
+}
+
+/** `$key$` hops, one level per pass; an unfilled slot stays and marks the value. */
+function substituteKeys(s: string, deps: LocTextDeps, resolved: { ok: boolean }): string {
+  return s.replace(NESTED_KEY, (whole, key: string) => {
+    const value = deps.loc(key);
+    if (value === undefined) {
+      resolved.ok = false;
+      return whole;
+    }
+    return value;
+  });
+}
+
+function render(raw: string, deps: LocTextDeps, depth: number): Rendered {
+  const state = { ok: true };
+  const parts = tokenize(substituteKeys(raw, deps, state)).map((part) => {
+    if (part.fn === undefined) return { text: stripFormatting(part.literal ?? ""), resolved: true };
+    const out = renderFn(part.fn, deps, depth);
+    if (!out.resolved) state.ok = false;
+    return out;
+  });
+  // A dropped icon leaves the space on both sides of it behind.
+  const text = parts
+    .map((part) => part.text)
+    .join("")
+    .replace(/[ \t]{2,}/g, " ")
+    .trim();
+  return { text, resolved: state.ok };
+}
+
+/** One value rendered; exported for the unit test and for other server features. */
+export function renderLocValue(raw: string, deps: LocTextDeps): LocTextValue {
+  const out = render(raw, deps, 0);
+  return { raw, text: out.text, resolved: out.resolved };
+}
+
+export function computeLocText(keys: readonly string[], deps: LocTextDeps): LocTextResult {
+  const values: Record<string, LocTextValue> = {};
+  for (const key of keys) {
+    if (key in values) continue;
+    const raw = deps.loc(key);
+    // A key the loc index cannot find is absent: the client already shows the
+    // key itself there, and an empty string would read as a defined blank.
+    if (raw === undefined) continue;
+    values[key] = renderLocValue(raw, deps);
+  }
+  return { values };
+}

package/src/features/snippetList.ts

@@ -0,0 +1,83 @@
+/**
+ * The `paradox/snippets` answer: everything a host can offer to insert at a
+ * cursor in one script document.
+ *
+ * Two sources, both derived. The document's folder decides its definition kind,
+ * and that kind's measured skeleton (schema/skeletons.ts) supplies the
+ * definition and its child blocks. The cursor's block context decides which
+ * engine triggers/effects are legal there, and each of those contributes the
+ * block form of the `usage:` example its own script_docs entry ships
+ * (features/blockSnippets.ts). Nothing is added that the game did not state.
+ */
+import type { SnippetItem } from "@px-lsp/protocol/protocol";
+import type { TokenData } from "@px-lsp/protocol/types";
+import { detectContextFromParse } from "../context";
+import type { ParseResult } from "../parser";
+import type { KindSkeleton } from "../schema/skeletons";
+import { blockTemplateFor } from "./blockSnippets";
+import { skeletonsFor } from "./definitionSkeletons";
+
+/**
+ * Engine tokens the answer carries. A picker filters as the user types, so the
+ * cap is only about payload: the list is frequency-ordered, and past ~60 the
+ * tail is tokens nobody reaches for by name.
+ */
+const MAX_TOKENS = 60;
+
+export function buildSnippetList(
+  parse: ParseResult,
+  offset: number,
+  kind: string | null,
+  skeletons: Record<string, KindSkeleton> | undefined,
+  tokens: TokenData[],
+  counts: Record<string, number>
+): SnippetItem[] {
+  const out: SnippetItem[] = kind
+    ? skeletonsFor(parse, kind, skeletons).map((offer) => ({
+        id: offer.id,
+        label: offer.label,
+        detail: offer.detail,
+        form: offer.form,
+        snippet: offer.text.snippet,
+        plain: offer.text.plain,
+      }))
+    : [];
+
+  const { context } = detectContextFromParse(parse, offset);
+  const seen = new Set<string>();
+  const candidates: Array<{ token: TokenData; count: number }> = [];
+  for (const token of tokens) {
+    // The same context gate key-position completion applies: a trigger block
+    // takes no effects and an effect block takes no triggers.
+    if (context === "trigger" && (token.kind === "effect" || token.kind === "modifier")) continue;
+    if (context === "effect" && (token.kind === "trigger" || token.kind === "modifier")) continue;
+    if (seen.has(token.name)) continue;
+    if (!blockTemplateFor(token)) continue;
+    seen.add(token.name);
+    candidates.push({ token, count: counts[token.name] ?? 0 });
+  }
+  candidates.sort((a, b) => b.count - a.count || (a.token.name < b.token.name ? -1 : 1));
+  for (const { token } of candidates.slice(0, MAX_TOKENS)) {
+    const template = blockTemplateFor(token)!;
+    out.push({
+      id: token.name,
+      label: token.name,
+      detail: `${token.kind} block, from the game's own usage example`,
+      form: "token",
+      snippet: template.snippet,
+      plain: template.plain,
+    });
+    // An example that marks fields `# optional` offers both: the required
+    // fields, and the whole thing. The pair costs one cap slot, not two.
+    if (template.full)
+      out.push({
+        id: `${token.name}.full`,
+        label: `${token.name} (all fields)`,
+        detail: `${token.kind} block with its optional fields, from the game's own usage example`,
+        form: "token",
+        snippet: template.full.snippet,
+        plain: template.full.plain,
+      });
+  }
+  return out;
+}

package/src/games/ck3/index.ts

@@ -3,6 +3,7 @@
  * and bundled-data import, assembled behind the GameProfile interface.
  */
 import type { GameProfile } from "../profile";
+import type { SkeletonData } from "../../schema/skeletons";
 import { ck3Meta } from "./meta";
 import { BLOCK_REF_FIELDS, CK3_SCHEMA, PREFIX_REFS, REF_FIELDS } from "./schema";
 import { STRUCTURE_SOURCES } from "./structures";
@@ -13,6 +14,8 @@ import { CK3_SAVE_SCHEMA } from "./saveSchema";
 // and scripts/build-gui-schema.ts for regeneration.
 import BUNDLED_DATA_TYPES from "../../../data/ck3/dataTypes.json";
 import GUI_SCHEMA from "../../../data/ck3/guiSchema.json";
+// Definition skeletons measured over the vanilla tree (scripts/build-skeletons.ts).
+import SKELETONS from "../../../data/ck3/skeletons.json";
 
 export const ck3Profile: GameProfile = {
   ...ck3Meta,
@@ -30,8 +33,21 @@ export const ck3Profile: GameProfile = {
     scripted_gui: { key: "scope", default: "character" },
   },
   modifierPlaceholders: CK3_MODIFIER_PLACEHOLDERS,
+  // The three triggers the measured condition shapes need. Over the game's own
+  // 21 dynasty legacy tracks every `is_shown` opens with `has_dlc_feature`, and
+  // over its 105 dynasty perks every `can_be_picked` is either
+  // `has_dlc_feature = <feature>` (10) or `<scripted trigger> = yes` (44).
+  conditionValues: {
+    // triggers.log enumerates the whole set on the trigger itself.
+    has_dlc_feature: { from: "docList" },
+    // `has_game_rule = unrestricted_dynasty_legacies_all` names a SETTING, and
+    // a setting is an inner block of a game_rule (00_game_rules.txt).
+    has_game_rule: { from: "innerKeys", kind: "game_rule", except: ["categories", "default"] },
+    scripted_trigger: { from: "kind", kind: "scripted_trigger" },
+  },
   bundledDataTypes: BUNDLED_DATA_TYPES,
   guiSchema: GUI_SCHEMA,
+  skeletons: (SKELETONS as unknown as SkeletonData).kinds,
   saveSchema: CK3_SAVE_SCHEMA,
   wikiNote: "Source: CK3 wiki (may lag behind the current game version)",
   diagnosticSource: "ck3-script",

package/src/games/ck3/meta.ts

@@ -12,9 +12,12 @@ export const ck3Meta: GameMeta = {
   shortName: "CK3",
   engine: "jomini",
   descriptor: "mod",
-  configDirName: ".ck3modding",
+  configDirName: ".px-toolkit",
+  legacyConfigDirName: ".ck3modding",
   docsFolderName: "Crusader Kings III",
   steamAppId: 1158310,
+  // Verified on the 1.19 install: dlc_001.dds .. dlc_029.dds.
+  dlcIconDir: "gfx/interface/icons/dlc",
   eventNamespaces: true,
   // The engine's own default metrics: they were measured on this game's font,
   // and the layout engine reuses them for games whose probe has not run.
@@ -22,6 +25,60 @@ export const ck3Meta: GameMeta = {
   guiTextMetrics: GITAN_MEASURED_METRICS,
   scaffolds: CK3_SCAFFOLDS,
   tiger: { binaryName: "ck3-tiger", repoSlug: "amtep/tiger", confName: "ck3-tiger.conf" },
+  // Visual creators. Every row is backed by a folder the schema table already
+  // indexes and a shape read out of the game's own files:
+  //   trait          common/traits, documented by common/traits/_traits.info
+  //   dynasty_legacy common/dynasty_legacies, per _dynasty_legacies.info
+  //                  ("Dynasty Legacies are containers for perks"); the perks
+  //                  themselves live in common/dynasty_perks (`legacy = <track>`)
+  //   culture        common/culture/cultures (00_arabic.txt: color, ethos,
+  //                  heritage, language, traditions, name_list, parents…)
+  //   culture_tradition common/culture/traditions, whose _traditions.info adds
+  //                  `category` and `layers` to the shape _cultural_traits.info
+  //                  documents for every cultural trait
+  //   dynasty_tree   NOT a definition kind: history/characters linked by
+  //                  father/mother/dynasty/house (history/characters/*.txt)
+  creators: [
+    {
+      kind: "trait",
+      label: "Trait Creator",
+      icon: "sparkles",
+      tip: "Design a character trait and write it into the mod.",
+    },
+    {
+      kind: "dynasty_legacy",
+      label: "Dynasty Legacy Creator",
+      icon: "layers",
+      tip: "Build a legacy track and its perks.",
+    },
+    {
+      kind: "culture",
+      label: "Culture Creator",
+      icon: "globe",
+      tip: "Compose a culture from the game's own pillars and traditions.",
+    },
+    {
+      kind: "culture_tradition",
+      label: "Tradition Creator",
+      icon: "flame",
+      tip: "Design a culture tradition, its layered icon and its modifiers.",
+    },
+    {
+      kind: "dynasty_tree",
+      label: "Dynasty Tree",
+      icon: "users",
+      tip: "See and edit a dynasty's characters across history.",
+    },
+  ],
+  // Measured on the 1.19 install: common/modifier_definition_formats/ holds 13
+  // files documented by _definitions.info in the same folder (decimals, color,
+  // prefix/suffix/negative_suffix as loc keys, percent, already_percent,
+  // hidden, no_difference_sign), and gui/texticons.gui holds the `texticon`
+  // blocks a `[gold_i]` in one of those loc values resolves to.
+  modifierFormats: {
+    folder: "common/modifier_definition_formats",
+    textIcons: "gui/texticons.gui",
+  },
   // Date-format keys verified in ck3.exe 1.19 (the gamedate.cpp string block);
   // formats mirror game/localization/english/core_l_english.yml. Vanilla
   // appends $ERA$/$ERA_BCE$ itself - dropped here, the {era} slot replaces it.
@@ -64,4 +121,27 @@ export const ck3Meta: GameMeta = {
   // "" keeps the pre-profile cache filenames (docsCache.json, vanillaIndex-*.json)
   // so existing users' caches survive the M2 restructure.
   cacheSuffix: "",
+  // Coat-of-arms coverage measured against this install (1.19.0.6, 2026-09-03):
+  // parseCoaFile reads all 2992 vanilla definitions in the 10 files of
+  // common/coat_of_arms/coat_of_arms with 0 parse errors, and 100% of both the
+  // 7800 texture references (1629 files, every one decoding) and the 15327
+  // colors resolve, the named ones out of the 112 in common/named_colors. 239
+  // flags (8.0%) carried something the model dropped, 387 of those 399 keys
+  // being `depth` on an instance, which the model now carries; Vic3, which has
+  // shipped the builder since 0.3.2, drops something on 8.3% of its flags, so
+  // CK3 is no worse off.
+  flagBuilder: true,
+  // Measured on this install (1.19.0.6, 2026-09-03): the in-game designer's
+  // own files are all present and parse - 38 visible patterns of 42 rows in
+  // gfx/coat_of_arms/patterns/50_coa_designer_patterns.txt, 1576 visible
+  // emblems of 1578 rows in 13 categories in
+  // colored_emblems/50_coa_designer_emblems.txt, 13 palette colors in
+  // color_palettes/50_coa_designer_palettes.txt, 35 whole layouts in
+  // emblem_layouts/50_coa_designer_emblem_layouts.txt, the
+  // `coa_designer_blank_default` template in
+  // common/coat_of_arms/coat_of_arms/99_coa_designer_templates.txt and 35
+  // preview frames under gfx/interface/coat_of_arms. Victoria 3 ships no
+  // gfx/coat_of_arms/color_palettes or emblem_layouts at all, and EU5 no coa
+  // designer either, so neither sets this.
+  coaDesigner: true,
 };

package/src/games/ck3/schema.ts

@@ -1,7 +1,7 @@
 /**
  * The bundled CK3 schema table (rework plan AD-3). One entry per game folder
  * we understand; community-editable in-repo, extendable per-workspace via
- * .ck3modding/schema.json.
+ * .px-toolkit/schema.json.
  *
  * Every entry was verified against a real CK3 install (game version with
  * common/ ~150 subfolders): the folder was listed, a file opened, and the
@@ -29,7 +29,20 @@ const CK3_SCHEMA_BASE: SchemaEntry[] = [
   { path: "localization", kind: "loc_key", ext: ".yml", extraction: "loc-key" },
 
   // --- Characters, traits, interactions ---
-  { path: "common/traits", kind: "trait", requiredLoc: ["trait_$"], rootScopes: ["character"] },
+  // locPatterns and iconFolder verbatim from common/traits/_traits.info
+  // ("== Loc/icon ==": "the name key is trait_<key>, and the desc key is
+  // trait_<key>_desc", "The default icon path is
+  // gfx/interface/icons/traits/<trait>.dds"). trait_$_desc stays OUT of
+  // requiredLoc: schemaVanilla.test.ts measures it at 90.4% of vanilla traits,
+  // under the 95% bar a missing-loc diagnostic needs.
+  {
+    path: "common/traits",
+    kind: "trait",
+    requiredLoc: ["trait_$"],
+    locPatterns: ["trait_$", "trait_$_desc"],
+    iconFolder: "gfx/interface/icons/traits",
+    rootScopes: ["character"],
+  },
   {
     path: "common/character_interactions",
     kind: "character_interaction",
@@ -97,13 +110,43 @@ const CK3_SCHEMA_BASE: SchemaEntry[] = [
   { path: "common/court_types", kind: "court_type" },
 
   // --- Culture ---
-  { path: "common/culture/cultures", kind: "culture", requiredLoc: ["$"] },
-  { path: "common/culture/pillars", kind: "culture_pillar" },
+  {
+    path: "common/culture/cultures",
+    kind: "culture",
+    requiredLoc: ["$"],
+    // Every one of the 244 vanilla cultures defines all three keys in
+    // game/localization/english/culture/cultures_l_english.yml (`bedouin`,
+    // `bedouin_prefix`, `bedouin_collective_noun`), measured 244/244 in
+    // 2026-09. requiredLoc keeps only `$` because the diagnostic that hangs
+    // off it is the conservative one; a creator writes the whole set.
+    locPatterns: ["$", "$_prefix", "$_collective_noun"],
+  },
+  {
+    path: "common/culture/pillars",
+    kind: "culture_pillar",
+    // One folder, five families: game/common/culture/pillars/_pillars.info
+    // documents `type = ethos/heritage/language/martial` on top of the common
+    // cultural-trait shape, and the files spell it that way
+    // (00_ethos.txt `type = ethos`, 00_martial_custom.txt `type =
+    // martial_custom`, 00_head_determination.txt `type = head_determination`).
+    groupKey: "type",
+    // Measured 2026-09-04 in game/localization/english against the 162 vanilla
+    // pillars: `$_name` 160, `$_desc` 9, bare `$` 4. The _pillars.info doc
+    // names only the generic-desc fallback, so the name pattern is a measurement.
+    requiredLoc: ["$_name"],
+    locPatterns: ["$_name", "$_desc"],
+  },
   {
     path: "common/culture/traditions",
     kind: "culture_tradition",
     // def names already carry the `tradition_` prefix; loc key is `<name>_name`.
     requiredLoc: ["$_name"],
+    // All 196 vanilla traditions also define `$_desc`, measured 196/196 in
+    // game/localization/english against common/culture/traditions in 2026-09
+    // (`tradition_winter_warriors_name` / `_desc`). requiredLoc keeps only
+    // `$_name` because the diagnostic that hangs off it is the conservative
+    // one; a creator writes the whole set.
+    locPatterns: ["$_name", "$_desc"],
     rootScopes: ["culture"],
   },
   { path: "common/culture/innovations", kind: "innovation", requiredLoc: ["$"], rootScopes: ["culture"] },
@@ -125,8 +168,33 @@ const CK3_SCHEMA_BASE: SchemaEntry[] = [
   // dynasties top-level keys are numeric ids; huge and never typed → not completable.
   { path: "common/dynasties", kind: "dynasty", completable: false },
   { path: "common/dynasty_houses", kind: "dynasty_house", completable: false },
-  { path: "common/dynasty_legacies", kind: "dynasty_legacy" },
-  { path: "common/dynasty_perks", kind: "dynasty_perk" },
+  // _dynasty_legacies.info, "Generated loc keys: key + "_name"". All 21 vanilla
+  // legacies define it (measured 2026-09-03), so it clears the requiredLoc bar.
+  // $_desc is not in the .info doc, but all 21 vanilla tracks define it
+  // (localization/english/dynasty_legacies/legacies_l_english.yml, e.g.
+  // blood_legacy_track_desc), so a creator asks for it too; it stays out of
+  // requiredLoc, where only the keys the doc itself states belong.
+  // iconFolder: window_dynasty_legacy.gui draws the picture from
+  // "[DynastyLegacy.GetIcon]", a code-side path with no script key behind it,
+  // and the files it finds are gfx/interface/icons/dynasty/<track key>.dds
+  // (22 files for the 21 tracks). Name-derived, so a creator writes the
+  // picture under the track's own name and never a path into the block.
+  // A track reads a SECOND name-derived picture, the window's illustration at
+  // gfx/interface/illustrations/legacy_tracks/<key>.dds ("[DynastyLegacy.
+  // GetTrackIcon]", 21 files); iconFolder holds one path, so that one is left
+  // to ck3-tiger, which names it as a missing-file warning on the track.
+  {
+    path: "common/dynasty_legacies",
+    kind: "dynasty_legacy",
+    requiredLoc: ["$_name"],
+    locPatterns: ["$_name", "$_desc"],
+    iconFolder: "gfx/interface/icons/dynasty",
+  },
+  // _dynasty_perks.info, "Generated loc keys: key + "_name"" — and only that:
+  // all 105 vanilla perks define $_name, none defines $_desc (measured
+  // 2026-09-03 over localization/english). No iconFolder: gfx/interface/icons
+  // has a dynasty folder for the tracks and nothing for the perks.
+  { path: "common/dynasty_perks", kind: "dynasty_perk", locPatterns: ["$_name"] },
 
   // --- Activities & schemes ---
   { path: "common/activities/activity_types", kind: "activity_type", rootScopes: ["character"] },
@@ -190,7 +258,15 @@ const CK3_SCHEMA_BASE: SchemaEntry[] = [
   // remaining common/ folder with a standard top-level `name = { ... }`
   // layout, verified by parsing vanilla files. Ordered by definition count.
   { path: "common/game_concepts", kind: "game_concept", requiredLoc: ["game_concept_$"] },
-  { path: "common/domiciles/buildings", kind: "domicile_building", rootScopes: ["character", "domicile"] },
+  {
+    path: "common/domiciles/buildings",
+    kind: "domicile_building",
+    rootScopes: ["character", "domicile"],
+    // Measured 2026-09-04: all 1620 vanilla domicile buildings define
+    // `$_domicile_building` (109 also `$_domicile_building_desc`), none a bare `$`.
+    requiredLoc: ["$_domicile_building"],
+    locPatterns: ["$_domicile_building", "$_domicile_building_desc"],
+  },
   { path: "common/domiciles/types", kind: "domicile_type", rootScopes: ["character"] },
   { path: "common/artifacts/features", kind: "artifact_feature" },
   { path: "common/artifacts/feature_groups", kind: "artifact_feature_group" },

package/src/games/ck3/structures.ts

@@ -824,6 +824,43 @@ const CURATED: Record<string, StructureSpec> = {
 const KEY_PATCHES: Record<string, Record<string, Partial<KeySpec> & { doc?: string }>> = {
   trait: {
     valid_sex: { values: "enum:all|male|female", doc: "Which sex can have the trait. Default: all." },
+    // `opposites = { chaste }` in game/common/traits/00_traits.txt: the entries
+    // are trait names. Deliberately NOT a global REF_FIELD - scripted_relations
+    // spells the same key over relation names (00_scripted_relations.txt,
+    // `friend = { opposites = { rival ... } }`), and a global row would
+    // mis-resolve there.
+    opposites: { refKinds: ["trait"] },
+  },
+  culture: {
+    // game/common/culture/cultures/00_arabic.txt: `traditions = {
+    // tradition_tribe_unity ... }` names definitions of
+    // common/culture/traditions, and `parents = { bedouin assyrian }` names
+    // other cultures (bedouin is the top-level key of the same file).
+    traditions: { refKinds: ["culture_tradition"] },
+    parents: { refKinds: ["culture"] },
+    // The five pillar keys all name definitions of common/culture/pillars
+    // (00_arabic.txt: `ethos = ethos_stoic heritage = heritage_arabic
+    // language = language_arabic martial_custom = martial_custom_male_only
+    // head_determination = head_determination_domain`, each of them a
+    // top-level key in common/culture/pillars/00_*.txt). One folder, so one
+    // ref kind; the pillar's own `type` sorts the five pickers apart (the
+    // schema entry's groupKey).
+    ethos: { refKinds: ["culture_pillar"] },
+    heritage: { refKinds: ["culture_pillar"] },
+    language: { refKinds: ["culture_pillar"] },
+    martial_custom: { refKinds: ["culture_pillar"] },
+    head_determination: { refKinds: ["culture_pillar"] },
+    // `name_list = name_list_bedouin` (00_arabic.txt) names a top-level key of
+    // common/culture/name_lists (00_arabic.txt line 1 there).
+    name_list: { refKinds: ["name_list"] },
+  },
+  dynasty_perk: {
+    // _dynasty_perks.info spells the block `traits = { trait_name = int }`, and
+    // game/common/dynasty_perks/00_dynasty_perks.txt writes it that way
+    // (blood_legacy_4: `beauty_good_1 = 100`, `fecund = 50`), so the entry keys
+    // are trait names and the numbers are AI chances. Per-KIND and not a global
+    // RefField: `traits` elsewhere is a history list, a filter, a count.
+    traits: { refKinds: ["trait"] },
   },
   scheme_type: {
     category: { values: "enum:personal|contract|hostile" },

package/src/games/eu5/index.ts

@@ -8,9 +8,11 @@
  * upstream, commit and license) and has NOT been checked against a live EU5
  * install. Folder→kind mappings are only as right as those rules are; report
  * gaps with the "Schema gap" issue form, and work around them locally with the
- * `<mod>/.eu5modding/schema.json` overlay.
+ * `<mod>/.px-toolkit/schema.json` overlay.
  */
 import type { GameProfile } from "../profile";
+import type { SkeletonData } from "../../schema/skeletons";
+import SKELETONS from "../../../data/eu5/skeletons.json";
 import type { RefField, SchemaEntry } from "../../schema/types";
 import { JOMINI_VARIABLE_BLOCK_REFS } from "../jomini/variables";
 import { eu5Meta } from "./meta";
@@ -68,6 +70,10 @@ export const eu5Profile: GameProfile = {
   blockRefFields: { ...JOMINI_VARIABLE_BLOCK_REFS },
   // No `_*.info` docs ship with EU5, so the structures layer has no source.
   structureSources: {},
+  // Nobody here owns EU5, so its vanilla tree has never been measured and
+  // data/eu5/skeletons.json is empty. Wired anyway: a harvest run on a machine
+  // that has the game turns skeletons on with no code change.
+  skeletons: (SKELETONS as unknown as SkeletonData).kinds,
   modifierPlaceholders: {},
   // No bundled wiki tokens in the preview cut, so nothing ever renders this.
   wikiNote: "",

package/src/games/eu5/meta.ts

@@ -16,12 +16,16 @@ export const eu5Meta: GameMeta = {
   // EU5 mods carry .metadata/metadata.json (plus a required thumbnail.png);
   // descriptor.mod is at most a vestigial launcher artifact.
   descriptor: "metadata",
-  configDirName: ".eu5modding",
+  configDirName: ".px-toolkit",
+  legacyConfigDirName: ".eu5modding",
   docsFolderName: "Europa Universalis V",
   // EU5's `script_docs` console command writes to Documents/.../docs, not logs/.
   scriptDocsSubdir: "docs",
   dataTypesCommand: "dump_data_types",
   steamAppId: 3450310,
+  // dlcIconDir deliberately absent: no live install has been checked, so the
+  // Workshop panel shows this game's DLC (read from `<gameDir>/dlc/`) with the
+  // folder's own thumbnail.png, and falls back to Steam when there is none.
   eventNamespaces: true,
   scaffolds: EU5_SCAFFOLDS,
   // uiFont and guiTextMetrics deliberately absent: neither the font file nor