@agimon-ai/doompi-ui 0.0.1-alpha.21 → 0.0.1-alpha.22

package/README.md

@@ -1,43 +1,85 @@
 # @agimon-ai/doompi-ui
 
-**Space is a menu only when you are not writing.**
+DoomPi's shared terminal interface, Leader Space host, theme, overlays, and UI registries.
 
-This is Doompi's TUI: editor, header, modeline, footer, overlays, theme, and the leader-key
-registry that ties its packages together. Pressing `SPC` on an empty draft opens the map;
-pressing it inside a prompt still types a space. No stolen keystrokes and no pile of slash
-commands to memorize.
+The [DoomPi distribution](https://www.npmjs.com/package/@agimon-ai/doompi) loads this package as core. Extension authors can depend on its public contracts without adopting the full distribution.
 
-This is part of [Doompi](https://www.npmjs.com/package/@agimon-ai/doompi). Most users get
-it with the distribution; install it directly when building a Pi extension against the
-Doom UI contracts.
+> **Alpha:** UI and contribution contracts may change between releases.
+
+## Requirements
+
+- Node.js 22.19.0 or newer
+- Pi 0.84.2
+- Pi TUI 0.84.2
 
 ## Install
 
+To load the UI directly in Pi:
+
 ```bash
-npm install @agimon-ai/doompi-ui
+pi install npm:@agimon-ai/doompi-ui
 ```
 
-## How it loads
+DoomPi users should not add it to a layer; the distribution loads it before layer contributions.
+
+## Commands and keys
+
+| Input        | Behavior                                                                           |
+| ------------ | ---------------------------------------------------------------------------------- |
+| `Ctrl+Space` | Opens Leader Space from anywhere in the editor                                     |
+| `SPC`        | Opens Leader Space only when the current draft is empty; otherwise inserts a space |
+| `/tools`     | Opens the current tool and MCP inventory                                           |
+| `/config`    | Opens settings contributed by active extensions                                    |
 
-Doompi loads the UI as core. It is not a layer and does not appear in `.doom/modes.yaml`.
-The bare package name follows its Pi manifest and loads the Pi adapter; the explicit
-`/extensions/pi` subpath does the same job when an adapter path is required.
+The registry rejects or diagnoses conflicting Leader contributions instead of silently replacing an existing binding. Diagnostics are recorded through telemetry and shown as TUI warnings when a UI is attached.
+
+## Contribute to Leader Space
+
+```ts
+import { registerDoomLeaderContribution } from '@agimon-ai/doompi-ui/leader';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+export function registerReviewLeader(pi: ExtensionAPI): () => void {
+  return registerDoomLeaderContribution(pi, {
+    source: '@example/review-extension',
+    bindings: [
+      {
+        id: 'review.open',
+        path: [{ key: 'r', label: 'review', detail: 'open review tools' }],
+        command: { name: 'review' },
+      },
+    ],
+  });
+}
+```
 
-## Leader
+Dispose the returned registration during shutdown so reloads cannot retain stale bindings.
 
-- `SPC` opens the leader map when the draft is empty.
-- `SPC e c` opens the Doompi config panel.
-- Other extensions contribute bindings through `@agimon-ai/doompi-ui/leader` instead of
-  hardcoding their own key trees.
+## TUI and headless sessions
 
-Conflicts are handled by the registry, so two packages cannot silently claim the same
-chord.
+The editor, header, footer, overlays, Leader menu, and notifications require an interactive TUI. The underlying typed contribution registries can still be installed and queried in headless sessions, but UI-only commands have no panel to render. Provide a tool, RPC, or CLI route when a capability must also work headlessly.
+
+## Theme
+
+The package publishes `@agimon-ai/doompi-ui/themes/doom-pi-dark.json`. DoomPi synchronizes that resource and selects it by default. Set `DOOMPI_THEME` to select another available Pi theme for the UI adapter.
 
 ## Public API
 
-The package exposes the leader registry, shared UI state, rendering helpers, tool chrome,
-header/footer/editor components, and the Doom Pi dark theme. Use declared exports rather
-than reaching into `dist/`; `package.json` carries the complete list.
+Declared exports cover Leader registration, UI state, rendering, tool chrome, header/footer/editor components, configuration and tools overlays, telemetry integration, and theme helpers. Use these exports rather than importing generated `dist` paths.
+
+```ts
+import { registerDoomLeaderContribution } from '@agimon-ai/doompi-ui/leader';
+import { DEFAULT_THEME_NAME } from '@agimon-ai/doompi-ui/theme';
+```
+
+## Development
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agimon-ai/doompi-ui",
-  "version": "0.0.1-alpha.21",
+  "version": "0.0.1-alpha.22",
   "description": "Doom-inspired interactive UI extension for Pi",
   "keywords": [
     "ai",
@@ -144,8 +144,8 @@
   },
   "dependencies": {
     "yaml": "2.9.0",
-    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.21",
-    "@agimon-ai/doompi-telemetry": "0.0.1-alpha.21"
+    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.22",
+    "@agimon-ai/doompi-telemetry": "0.0.1-alpha.22"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",