# Core SDK

Go module `git.dev.alexdunmow.com/block/core`.

**Purpose: core exists ONLY for code that must be shared between first-party
BlockNinja entities** — the **CMS**, the **orchestrator**, the **ninja CLI**,
and any future entity that genuinely needs to share code with the others.

## Admission test

Before adding anything here, ask: **do two or more first-party entities need
this code?**

- Needed by only one entity → it belongs in that entity's repo, not core.
- Needed by plugins → it does NOT belong here (see below); plugins build
  against the wasm ABI, whose contract the CMS owns (`cms/backend/abi/`,
  `cms/docs/abi/`).

The standing direction (Captain, 2026-07-07) is to **shrink core**: prefer
moving code out to its single consumer over adding more in. When a package's
consumer count drops to one, migrate it out.

## Critical Rules

- **Core is NOT for plugins.** Plugins are standalone wasm artifacts built
  against the wasm ABI, not this module. (Core was previously the plugin SDK;
  that role is gone, and remaining plugin-era surface is legacy to be worked
  off, not a precedent.)
- **NEVER use `replace` directives in go.mod** — not in this repo, not in any
  consumer. All module resolution goes through the Gitea module proxy. If you
  need to test local changes, tag and push a version.
- All consumers are in-house — no backwards compatibility shims needed. Just
  change the API and update consumers.

## Special case: `templates/bn/` is a synced copy, do not author here

The bn page chrome (head / toolbar / engagement / asset_hooks) is **authored
in `cms/backend/templates/bn`** and mechanically copied here (`make
sync-templates` in cms) solely so guest-side plugin templates can compile it
into their wasm. check-safety check 31 fails cms commits while the copies
drift. Never edit these files here directly — change them in cms and sync.
`templates/bn/validation.go` is intentionally divergent (cms's version bridges
the SDK ValidationTracker under both context keys) and is NOT part of the sync
set. Spec: cms `docs/superpowers/specs/2026-07-07-bn-chrome-single-source-design.md`.