Skip to content

Onboarding — partner organisations

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

> ▋
⏺

Organisation declared

✓ org: dezernat-zukunft written to the workspace CLAUDE.md — one line, no script

✓ charts, decks and briefs now carry their brand and voice

✓ everything not overridden is inherited from the network

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, pillar knowledge packsbraries. You inherit it; PR anything you'd improve.
  • shared/empn/ is EMPN's identity — house style, workspaces, 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

  • workspaces.md — the Drive folders your organisation's research lives in, one per pillar. 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/<workspace>/... 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:

  • 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.

For other infrastructure-coupled skill families (contacts pipeline, create-cover, the export pipeline behind branded charts and decks), see the Later / advanced section in Prerequisites. These aren't set up on partner Day 1.

Running the resolver

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

python3 .../setup_org.py            # generate symlinks for the resolved org
python3 .../setup_org.py --clean    # remove generated symlinks
python3 .../setup_org.py --dry-run  # show plan, change nothing

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

You should not have to run it by hand

The workspace CLAUDE.md runs setup_org.py --resolve at the start of every session, and the brand and identity skills run it too. --resolve writes nothing — it prints your org and the folders to look in, in order.

It gets your org from one line in that same CLAUDE.md:

org: dezernat-zukunft

That is the whole configuration. A CLAUDE.md is read at the start of every session in every runtime, so the slug arrives without a marker file, an environment variable, or anything for you to run. If the workspace has no org: line, the session runs on EMPN's identity and tells you so every time, offering to record yours. Answering once ends the reminder.

It is per-workspace, not per-machine, so one laptop can hold two organisations' workspaces without them fighting over a single setting — and a project folder can declare a different org from the vault root above it.

The symlinks that --ensure generates are a local convenience, not the mechanism. Nothing needs to be written inside the plugin folder, which is why a read-only plugin directory does not break anything.

If your vault's CLAUDE.md predates this, copy the header block from shared/empn/templates/workspace-CLAUDE.md, or just add the org: line yourself.

Full contract, including the exit codes: shared/org-resolution.md.

When something breaks

Symptom Likely cause Fix
Outputs branded EMPN despite override Resolution didn't run, or resolved to empn Run setup_org.py --resolve; check the org: line in your workspace CLAUDE.md holds your slug
Told your org is assumed, every session There is no org: line above the session's working directory Add one to the workspace CLAUDE.md, or run setup_org.py --write-org <slug> --workspace <root>
slug not in registry Typo in the org: line, 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 setup_org.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 setup_org.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.