Skip to content

Onboarding — partner organisations

Once you've followed Quick start and /tutorial runs, the plugin is working with EMPN-defaults output. This page is about making it produce your outputs — your logo, your voice, your themes, your source tiers.

What customisation looks like

The plugin separates how from who.

  • skills/ is the how — methodology, hand-offs, fan-out logic. Universal across the network. You inherit it as-is.
  • shared/_common/ holds universal rules — writing patterns, EU process knowledge, search and monitor patterns, theme knowledge libraries. You inherit it; PR anything you'd improve.
  • shared/empn/ is EMPN's identity — house style, themes, folder conventions, visuals. Acts as the canonical reference and the default fallback when you haven't overridden a file.
  • shared/<your-slug>/ is your overlay. Sparse — only the files you want to differ from EMPN.

When a skill loads house-style.md, the resolver walks <your-slug>/ → _common/ → empn/ and returns the first match. The model never picks the org; the symlink does.

For the architectural detail and a diagram, see How it works.

What to override, in what order

Day 1, if you want anything other than EMPN-branded outputs

  • org-identity.md — your web URL, headquarters, contact email, one-line blurb, network position. Every closing slide, brief footer, and contact line reads this file. Without overriding, your decks say "EMPN" at the bottom.
  • visuals/ — logos, design tokens, fonts. The directory is symlinked wholesale, so you ship a full visuals/ tree. Start by copying EMPN's as a template: 
    cp -r plugins/empn-core/shared/empn/visuals/ plugins/empn-core/shared/<your-slug>/visuals/
    Then replace the brand-specific files: logos in logos/, palette in design-tokens.yaml, font URLs in webfonts.css.

Within the first weeks

  • themes.md — the research themes your organisation works on. EMPN's five (fiscal, energy, monetary, industrial, cross-topic) are unlikely to match yours exactly.
  • folder-conventions.md — your workspace tree if it differs from EMPN's 05_Projects/<theme>/... layout.
  • house-style.md — voice, citation rules, forbidden phrases, uncertainty markers. Worth overriding only if your editorial standards diverge meaningfully from EMPN's.
  • presentation-structure.md — deck section conventions, slide budget, slide-level rules.

Probably never

  • narrative-arc.md is empirically derived from EMPN's own brief corpus. Inherit it unless you have a different signature structure backed by your own published work.
  • filename-convention.md — almost always fine as-is.

Constraints to flag

A few parts of the plugin are tied to specific infrastructure and won't customise cleanly without a separate conversation:

  • CRM. The contacts pipeline is HubSpot-coupled, with EMPN-specific custom properties. Salesforce or Pipedrive would require a new writer script — talk to the maintainer first.
  • Tracker hosting. tracker-publish assumes Cloudflare Pages plus a DNS zone on your domain.
  • Font hosting. webfonts.css carries hardcoded URLs at empn.eu. Your version needs to point at your own font host, or bundle fonts locally.

Running the resolver

overlay_setup.py is idempotent. Run it whenever you've changed your overlay or pulled a plugin update.

python3 .../overlay_setup.py            # generate symlinks for current EMPN_ORG
python3 .../overlay_setup.py --clean    # remove generated symlinks
python3 .../overlay_setup.py --dry-run  # show plan, change nothing

Output ends with a line like linked 27 canonical path(s), skipped 0; active slug = <your-slug>.

When something breaks

Symptom Likely cause Fix
Outputs branded EMPN despite override overlay_setup.py hasn't run, or EMPN_ORG unset Set the env var, run setup
slug not in registry Typo in EMPN_ORG, or org not on the allow-list yet Check spelling, or ask maintainer to add your org
overlay folder missing Slug is on the list but shared/<slug>/ doesn't exist Create the folder with a README.md placeholder
Markdown link in a skill goes 404 A canonical symlink is missing Re-run overlay_setup.py
Chart still in EMPN colours Partner override of design-tokens.yaml not loaded Verify shared/visuals symlink target; clear chart cache
Cowork ignores skill triggers Sync incomplete, or SKILL.md frontmatter broken Restart Cowork; check YAML validity

For anything else, send the maintainer the error and the output of overlay_setup.py --dry-run.

Adding a new partner organisation

If your organisation isn't on the pre-prepared list (arena-ide, dezernat-zukunft, institut-avant-garde), see Contributing — register a new organisation. One-line PR.