# BlockNinja Core

Go code 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.

> **Scope rule:** core is ONLY for code needed by **two or more** of those
> entities. Code with a single consumer belongs in that consumer's repo. The
> standing direction is to shrink core — when a package's consumer count drops
> to one, it gets migrated out.

> **Not a plugin SDK.** Plugins must **not** treat `block/core` as their SDK —
> in the wasm-plugin era they are standalone artifacts built against the wasm
> ABI (owned by the CMS: `cms/backend/abi/`, `cms/docs/abi/`). Core previously
> served as the plugin SDK; that role is gone, and remaining plugin-era
> surface here is legacy to be worked off, not a precedent.

## Package Structure

| Package | Purpose |
|---------|---------|
| `plugin/` | PluginRegistration, CoreServices, RegisterFunc |
| `blocks/` | BlockMeta, BlockFunc, BlockRegistry interface, BlockContext |
| `blocks/builtin/` | Reusable block implementations (HTMLBlock) |
| `templates/` | TemplateRegistry interface |
| `templates/bn/` | Synced copy of the cms-authored bn chrome (see below) |
| `auth/` | Claims types, context extractors |
| `content/` | Content access interface |
| `settings/` | Settings access interface |
| `gating/` | Access gating evaluation |
| `crypto/` | Encrypt/Decrypt interface |
| `render/` | Rich text rendering utilities |
| `video/` | Video embed URL parsing |
| `ai/` | AI tool registry interface and types |
| `rbac/` | Role type definition |

### `templates/bn/` is a synced copy — do not edit here

The bn page chrome (head / toolbar / engagement / asset_hooks) is authored in
`cms/backend/templates/bn` and copied here via the cms `make sync-templates`
target, solely so guest-side plugin templates can compile it into their wasm.
check-safety (check 31) fails cms commits while the copies drift. Change the
chrome in cms, sync, then commit + tag + push here.

## Usage

```go
import "git.dev.alexdunmow.com/block/core/blocks"
```

Versioned via git tags through the Gitea module proxy — never `replace`
directives. All consumers are in-house; no backwards-compatibility shims —
change the API and update the consumers.