[danielgerlag]

Part of #33

What changed

README.md is rewritten as a front page for newcomers:

• The pitch, then four one-line points on what the kernel does differently (governance in the kernel, the plugin lifecycle, providers as plugins, versioned distributions), then a status line: alpha, desktop is the reference distribution, macOS primary with Linux in CI, not published to npm, MIT.
• Run a harness headless quotes examples/headless/src/main.ts exactly.
• Quickstart is unchanged.
• Architecture is one paragraph per layer, without the validation rules. The contracts paragraph describes main after refactor(contracts): plugin-owned contracts, part 4 (mcp, mcp-apps, feedback, a2a) #54: the root holds defineCommand, defineEvent and the kernel's schemas (including the MCP server config personas embed), defines no plugin commands, and its only event is borg.channel.inboundMessage. Plugin-owned schemas ship from @borg/plugin-<name>/contract.
• Boundaries and the desktop app are short summaries that link to docs/. The macOS packaging commands stay. There is a License section.

docs/boundaries.md (new) holds the full boundary rule list from the README, read from scripts/check-plugin-boundaries.mjs and the other two check:boundaries scripts on main. One rule was corrected: ./contract requires the tsconfig named by the package's build script (default tsconfig.main.json) to list src/contract.ts, src/*.ts or src/**/*.ts.

docs/desktop.md (new) holds the desktop setup and feature detail from the README, unchanged.

docs/plugin-authoring.md gets only the same tsconfig correction and a link to docs/boundaries.md.

CONTRIBUTING.md links to docs/boundaries.md and notes the /contract exception to the plugin import rule.

Headless example

• examples/headless (@borg/example-headless) defines a four-plugin distribution (borg.config.sqlite, borg.secrets.dev, borg.mock-llm, borg.hello), boots it with createKernel() in plain Node, calls borg.hello.getStatus once, and stops. The kernel won't start without a config store and a secret store, which is why those two plugins are in it.
• To make that work without reaching into package paths, plugins/{config-sqlite,secrets-dev,mock-llm,hello}/package.json now export ./borg.plugin.json. That's the only change outside docs, examples and workspace wiring.
• examples/* is added to pnpm-workspace.yaml, the vitest include and tsconfig.tests.json. The lockfile diff is the new importer entry only.
• examples/headless/test/headless.test.ts runs the built dist/main.js and expects borg.hello: Kernel alive. It also checks that the README code block matches the file byte for byte. pnpm test builds first, so both CI jobs run it without a new CI step.

Merge of main

The branch merges origin/main at fa68858 (#54) normally, with no force-push. Nothing in the docs describes plugin schemas as still sitting in the root or points to #31 as in progress.

Gates (local, Linux, Node 24, pnpm 12.0.0)

• install --frozen-lockfile ✅
• check:boundaries ✅
• typecheck ✅
• test: 140 files, 935 tests, including the example ✅
• test:e2e (xvfb): 44 passed, 2 skipped, 0 failed ✅

Left for #33

• ESLint: flat config, a pnpm lint script, and a CI step, in a separate PR.
• Examples: the examples/ item is covered by examples/headless, which pnpm test runs. A plugin-authoring example (a plugin package under examples/) could follow if wanted.
• The Linux CI job item was already done by ci: run e2e on Linux and make tray-title assertions platform-aware #43.