@tetherto/mdk-react-devkit 0.0.0-stage → 0.12.1

package/AGENT_READY.md

@@ -0,0 +1,265 @@
+<!-- markdownlint-disable MD041 -->
+# Agent-ready contract — `@tetherto/mdk-react-devkit`
+
+The single source of truth for **what to ship with every public export** so
+AI agents and humans can both consume the devkit reliably. Linked from the
+root [`AGENTS.md`](../../AGENTS.md), referenced by every error the
+`check:agent-ready` CI gate emits, and bundled in the npm tarball so
+downstream agents can read it too.
+
+> If you're new to the agent-first design, read [`docs/AGENT_FIRST.md`](../../docs/AGENT_FIRST.md) first, it's the
+> architecture tour. **This file is the contract** every public export must
+> satisfy.
+
+## TL;DR
+
+Three tiers, one decision:
+
+| Tier          | Use when…                                            | Must add                                          |
+| ------------- | ---------------------------------------------------- | ------------------------------------------------- |
+| `agent-ready` | LLMs / non-experts pick this component directly | JSDoc summary + `@category` + `@domain` + `@tier` + `@kernelCapability` + `USAGE.md` + `*.example.tsx` |
+| `advanced`    | Engineers extending the library use it directly      | JSDoc summary + `@category` + `@domain` + `@tier` |
+| `internal`    | Implementation detail, never part of the public API  | `@tier internal` (the registry generator drops these — no `USAGE.md` or examples required) |
+
+```mermaid
+flowchart TD
+  ask{"Will an LLM (or non-expert) pick this directly when building a page?"}
+  ask -- yes --> agentReady["@tier agent-ready (+ USAGE.md + example + @kernelCapability)"]
+  ask -- no --> ask2{"Is it exported for downstream engineers to compose with?"}
+  ask2 -- yes --> advanced["@tier advanced"]
+  ask2 -- no --> internal["@tier internal (hidden from registry)"]
+```
+
+## Required JSDoc tags
+
+| Tag                 | Required for                               | Allowed values                                                 |
+| ------------------- | ------------------------------------------ | -------------------------------------------------------------- |
+| `@tier`             | every public export                        | `agent-ready` &#124; `advanced` &#124; `internal`              |
+| `@category`         | tier ≠ `internal`                          | `charts` &#124; `tables` &#124; `cards` &#124; `forms` &#124; `dialogs` &#124; `navigation` &#124; `layout` &#124; `widgets` &#124; `dashboards` &#124; `actions` &#124; `feedback` &#124; `misc` |
+| `@domain`           | tier ≠ `internal`                          | `mining-operations` &#124; `financial-reporting` &#124; `device-management` &#124; `generic` |
+| `@kernelCapability` | `agent-ready` **with** `@domain ≠ generic` | `hashrate-monitoring` &#124; `pool-performance` &#124; `energy-consumption` &#124; `incident-alerts` &#124; `device-telemetry` &#124; `device-management` &#124; *(extendable)* — required for mining domains, skipped for generic primitives |
+| `@example`          | optional, encouraged                       | inline TSX in the JSDoc                                        |
+
+The first paragraph of the JSDoc above an export becomes the registry
+`description`. Keep it ≤ 200 chars; longer prose belongs in co-located
+[`USAGE.md`](src/domain/components/active-incidents-card/USAGE.md)
+next to each export (see skeleton in [`CONTRIBUTING.md`](../../../CONTRIBUTING.md))
+or the filled reference under [Pointers](#pointers).
+
+## Paste-ready templates
+
+### Agent-ready component
+
+```tsx
+/**
+ * One-paragraph summary. Describe what the component renders and the
+ * canonical use case. Don't list every prop, the registry captures those
+ * automatically.
+ *
+ * @category cards
+ * @domain mining-operations
+ * @kernelCapability incident-alerts
+ * @tier agent-ready
+ */
+export const MyCard = forwardRef<HTMLDivElement, MyCardProps>(
+  function MyCard(props, ref) { /* ... */ },
+);
+```
+
+Plus, next to the component file:
+
+```
+my-card/
+  index.tsx
+  my-card.example.tsx       ← runnable example, imports only from "@tetherto/mdk-react-devkit"
+  USAGE.md                  ← summary + props table + minimal example + notes
+```
+
+`USAGE.md` skeleton:
+
+```markdown
+# MyCard
+
+One-paragraph summary of what the component does.
+
+## Props
+
+| Prop  | Status   | Type     | Default | Description       |
+| ----- | -------- | -------- | ------- | ----------------- |
+| `foo` | Required | `string` | —       | The primary thing |
+
+## Minimal example
+
+```tsx
+<MyCard foo="hello" />
+```
+
+## Notes
+
+- Anything non-obvious about composition, accessibility, performance.
+```
+
+> **How this renders — write the prose, let the pipeline own props & examples.**
+> The docs site does **not** render `USAGE.md` verbatim. `<ComponentDoc>`
+> renders the description (from your JSDoc), the props table (from the registry
+> types), and the runnable examples (from `*.example.tsx`) *structurally* from
+> those authoritative sources. To avoid printing the same thing twice, it then
+> strips the leading `# Title`, the `## Props` section, and the
+> `## Example`/`## Examples` section out of your `USAGE.md` before rendering the
+> rest — so only your **intro paragraph and `## Notes`** (and any other prose)
+> reach the page.
+>
+> Practical takeaways when authoring `USAGE.md`:
+> - Put your effort into the **summary and Notes** — composition, gotchas,
+>   accessibility, performance. That prose is what the site actually shows, and
+>   the pipeline can't generate it.
+> - The `## Props` and example blocks above are **optional and harmless**: the
+>   site ignores them, but an agent reading `USAGE.md` straight off disk sees
+>   the raw file, so keeping it self-contained still helps. If you keep them,
+>   keep them accurate — the props table in the
+>   registry (from your types) is the source of truth, not this copy.
+
+### Advanced component
+
+```tsx
+/**
+ * One-paragraph summary aimed at engineers extending the library.
+ *
+ * @category layout
+ * @domain generic
+ * @tier advanced
+ */
+export const InternalLayoutHelper = (/* … */) => { /* ... */ };
+```
+
+No `USAGE.md`, no example required, JSDoc is enough.
+
+### Internal export
+
+```tsx
+/** @tier internal */
+export const _privateHelper = () => { /* ... */ };
+```
+
+The registry generator drops internal entries entirely. Nothing else
+required, but prefer **not exporting** if it truly is private.
+
+### Agent-ready hook
+
+```tsx
+/**
+ * Read the current device list for the active site. Updates whenever
+ * telemetry refresh ticks.
+ *
+ * @category data
+ * @domain device-management
+ * @kernelCapability device-management
+ * @tier agent-ready
+ *
+ * @returns devices keyed by id, plus an `isLoading` flag.
+ */
+export const useDevices = (): UseDevicesResult => { /* ... */ };
+```
+
+## How the gate runs
+
+```bash
+# Locally
+npm run check:agent-ready --workspace @tetherto/mdk-react-devkit
+```
+
+```bash
+# As part of the full suite (lint + typecheck + format + agent-ready + tests)
+npm run fullcheck
+# Auto-runs on every PR that touches ui/ or CI infra, as the
+# "🤖 Agent-readiness contract (UI)" job in the root .github/workflows/ci.yml.
+```
+
+The check loads [`dist/registry.json`](./dist/registry.json), applies the
+rules above, and compares against
+[`scripts/agent-ready-baseline.json`](scripts/agent-ready-baseline.json):
+
+- A violation **not** in the baseline is a hard error (exit 1).
+- A violation **in** the baseline is reported as debt and does not fail the
+  build.
+- The baseline can only ever shrink. After fixing a JSDoc gap, run:
+
+```bash
+npm run check:agent-ready --workspace @tetherto/mdk-react-devkit -- --update-baseline
+git add packages/react-devkit/scripts/agent-ready-baseline.json
+```
+
+To audit total debt locally (ignore the baseline):
+
+```bash
+node packages/react-devkit/scripts/check-agent-ready.mjs --no-baseline
+```
+
+The `USAGE.md` prop-table policy (`check-usage-proptables.mjs`, also run by
+`check:agent-ready`) works the same way against its own
+[`scripts/usage-proptable-baseline.json`](scripts/usage-proptable-baseline.json).
+That baseline is additionally guarded in root CI by the **🔒 USAGE baseline
+monotonicity** job, which compares it against the pull request base as sets:
+removing a path passes, adding one fails. So the baseline cannot be grown to
+baseline-in a new prop table — it can only shrink as tables migrate to JSDoc.
+
+## Error catalogue
+
+Every rule emitted by `check:agent-ready` and the one-line fix:
+
+| Error id                                | Fix                                                                                          |
+| --------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `missing-tier`                          | Add `@tier agent-ready` / `advanced` / `internal`. Every public export must declare its audience |
+| `missing-description`                   | Add a JSDoc summary above the export — the first paragraph is captured into the registry     |
+| `description-too-short`                 | Replace the auto-generated placeholder with a 1–2 sentence summary. Must be ≥40 chars and not match `"<Name> component."` / `"Use <Name> hook."` templates. |
+| `missing-category`                      | Add `@category <bucket>` (see "Required JSDoc tags" above for the allowed values)            |
+| `missing-domain`                        | Add `@domain <area>` — one of `mining-operations`, `financial-reporting`, `device-management`, `generic`. |
+| `agent-ready-missing-usage`             | Create `USAGE.md` next to the component (summary + props table + minimal example + notes)    |
+| `agent-ready-missing-example`           | Add `<name>.example.tsx` next to the component (mock data only; imports must use `@tetherto/mdk-react-devkit`). |
+| `agent-ready-missing-kernel-capability` | Add at least one `@kernelCapability <id>` tag so agents can find the component by capability |
+
+## Navigating by intent
+
+Once a component is `agent-ready`, an LLM can find it via two layered
+surfaces, none of which require model calls:
+
+### 1. O(1) lookup indexes ([`dist/registry.json`](./dist/registry.json) → `indexes`)
+
+The registry ships indexes alongside the flat arrays:
+
+```jsonc
+"indexes": {
+  "componentsByName":          { "ActiveIncidentsCard": 0, "DataTable": 1, /* … */ },
+  "componentsByCategory":      { "charts": ["LineChartCard", …], … },
+  "componentsByDomain":        { "mining-operations": [...], … },
+  "componentsByKernelCapability": { "hashrate-monitoring": [...], … },
+  "componentsByTier":          { "agent-ready": [...] }
+}
+```
+
+`componentsByName[<Name>]` returns the index into `components[]` — true O(1).
+The other indexes return arrays of names; agents combine them with the
+`byName` lookup.
+
+### 2. Navigating the manifests
+
+The deterministic decision flow agents follow — every step is a plain read of
+a `dist/*.json` file:
+
+```mermaid
+flowchart TD
+  intent["User intent (free text)"] --> step3["registry.json — intersect `indexes`\n(byDomain / byKernelCapability / byCategory)"]
+  step3 --> step4["Read the entry's `usageDoc` + `examples`"]
+  step4 --> scaffold["Write src/pages/&lt;Name&gt;.tsx + routes.ts entry"]
+  scaffold --> verify["tsc --noEmit + oxlint &lt;generated-file&gt;"]
+```
+
+## Pointers
+
+- Registry schema: [`scripts/registry-types.ts`](scripts/registry-types.ts)
+- Reference for "well-documented agent-ready component":
+  [`src/domain/components/active-incidents-card/`](src/domain/components/active-incidents-card/USAGE.md)
+- Reference for "well-documented agent-ready hook" — coming when we tier
+  the first hook as `agent-ready`.
+- Downstream usage (consumer apps): [`AGENTS.md`](../../AGENTS.md).
+- Architecture tour: [`docs/AGENT_FIRST.md`](../../docs/AGENT_FIRST.md).

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Tether
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# @tetherto/mdk-react-devkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The React UI layer of the MDK toolkit. It bundles the generic UI
+primitives and the mining-domain components into a single package whose
+internal layout keeps the two layers clearly separated:
+
+> **Contributing or extending the devkit?** Read
+> [`AGENT_READY.md`](AGENT_READY.md) first — it's the contract every public
+> export must satisfy (JSDoc tags, tier system, `USAGE.md` + example
+> requirements). `npm run check:agent-ready` enforces it.
+
+> **Building features in a consuming app?** Read the machine-readable
+> manifests — `registry.json` here,
+> `@tetherto/mdk-react-adapter/hooks.json` and
+> `@tetherto/mdk-ui-foundation/stores.json` next door. See
+> [`AGENTS.md`](../../AGENTS.md) for how to navigate them.
+
+- [`src/primitives/`](./src/primitives/index.ts) — framework-agnostic-ish UI primitives built on Radix UI,
+  design tokens, formatting utilities and types.
+- [`src/domain/`](./src/domain/index.ts) — mining-domain components, presentation
+  hooks (under `utils/`), constants, and types. Zustand stores live in
+  `@tetherto/mdk-ui-foundation`; store hooks and `MdkProvider` live in
+  `@tetherto/mdk-react-adapter`.
+
+## Installation
+
+This is a workspace package; depend on it from another workspace:
+
+```json
+{
+  "dependencies": {
+    "@tetherto/mdk-react-devkit": "*"
+  }
+}
+```
+
+## Usage
+
+### Subpath imports (preferred — better tree-shaking)
+
+```tsx
+import { Button, Dialog } from "@tetherto/mdk-react-devkit/primitives";
+import { useNotification } from "@tetherto/mdk-react-devkit/domain";
+// Store hooks and Query client — not separate devkit subpaths:
+import { devicesStore } from "@tetherto/mdk-ui-foundation";
+import { useDevices, useTimezone } from "@tetherto/mdk-react-adapter";
+```
+
+Presentation hooks ship on `./domain` (or the top-level barrel), not
+`@tetherto/mdk-react-devkit/hooks` — that subpath is not in [`package.json`](./package.json)
+`exports`.
+
+### Top-level barrel
+
+```tsx
+import { Button, useNotification } from "@tetherto/mdk-react-devkit";
+```
+
+### Styles
+
+```tsx
+import "@tetherto/mdk-react-devkit/styles.css";
+import "@tetherto/mdk-react-devkit/styles-domain.css"; // only if using domain (mining-domain) components
+```
+
+Import `styles.css` **first** — it defines the design tokens the domain styles reference.
+Apps that only use primitives (`./primitives`) can omit `styles-domain.css` and ship ~70 KB less CSS.
+
+Or in SCSS:
+
+```scss
+@use "@tetherto/mdk-react-devkit/styles" as *;
+```
+
+See [STYLING.md](../../docs/STYLING.md) for the cascade-layer model, the public design
+tokens (`--mdk-*` custom properties), and supported component-class
+overrides.
+
+## Subpath exports
+
+| Subpath | Resolves to | Purpose |
+| --- | --- | --- |
+| `.` | `dist/index.{js,d.ts}` | Top-level barrel (`primitives` + `domain`) |
+| `./primitives` | `dist/primitives/index.{js,d.ts}` | Generic UI primitives |
+| `./domain` | `dist/domain/index.{js,d.ts}` | Mining-domain layer: components, presentation hooks, constants, types |
+| `./registry.json` | [`dist/registry.json`](./dist/registry.json) | Machine-readable component + hook registry |
+| `./styles.css` | [`dist/styles.css`](./dist/styles.css) | Design tokens + core primitives (~18 KB gz) |
+| `./styles-domain.css` | [`dist/styles-domain.css`](./dist/styles-domain.css) | Mining-domain component styles (~70 KB gz); import after `styles.css` |
+| `./styles` | [`src/primitives/styles/_mixins.scss`](./src/primitives/styles/_mixins.scss) | SCSS mixins (`@use`) |
+| [`./tokens.scss`](./src/primitives/components/dropdown-menu/tokens.scss) | [`src/primitives/styles/_colors.scss`](./src/primitives/styles/_colors.scss) | Design-token CSS variables (`@use`) |
+| `./src/styles/index.scss` | [`src/domain/styles/index.scss`](./src/domain/styles/index.scss) | Domain SCSS entry (advanced) |
+
+For reading `registry.json`, `USAGE.md` files, and examples, see
+[`AGENTS.md`](../../AGENTS.md). Adapter hook and store manifests:
+`@tetherto/mdk-react-adapter/hooks.json`, `@tetherto/mdk-ui-foundation/stores.json`.
+
+### Hooks and data (not separate devkit subpaths)
+
+| Need | Import from |
+| --- | --- |
+| Store hooks (`useAuth`, `useDevices`, `useTimezone`, …) | `@tetherto/mdk-react-adapter` |
+| Zustand stores outside React | `@tetherto/mdk-ui-foundation` |
+| Presentation hooks (`useNotification`, …) | `@tetherto/mdk-react-devkit/domain` or `.` |
+| TanStack `QueryClient` factory | `@tetherto/mdk-ui-foundation` (`createMdkQueryClient`) |
+
+There is no `./hooks` or `./api` export today; those capabilities are reached
+through `./domain`, the adapter, or the foundation package.
+
+## Charts: which engine
+
+The devkit ships two charting engines, each for a different kind of data:
+
+| Data | Use | Engine |
+| --- | --- | --- |
+| A time series: values over time, zoomable, with a time-range selector | `LineChart`, `LineChartCard`, `ThresholdLineChart` | `lightweight-charts` |
+| Categories or parts of a whole: per site, per period, shares | `BarChart`, `AreaChart`, `DoughnutChart`, `AverageDowntimeChart`, `OperationsEnergyCostChart` | Chart.js (`react-chartjs-2`) |
+| A single value against a range | `GaugeChart` | SVG, no chart engine |
+| A grid of cells coloured by value | `Heatmap` | DOM, no chart engine |
+
+Wrap any of them in `ChartContainer` for the title, legend, range selector and loading / empty states; `LineChartCard`
+already does. Both engines are code-split into async chunks that load when a chart first renders, so an app that uses only
+one never downloads the other.
+
+## Build strategy
+
+- **TypeScript** — `tsc -p tsconfig.build.json` emits ESM JS + `.d.ts`
+  into `dist/`. A small post-process ([`scripts/strip-style-imports.mjs`](./scripts/strip-style-imports.mjs))
+  removes the side-effect `.scss` / `.css` imports from emitted JS
+  because styles are in the Vite-built [`dist/styles.css`](./dist/styles.css) and
+  [`dist/styles-domain.css`](./dist/styles-domain.css), not in the TS output.
+- **CSS** — Vite compiles two SCSS entry points into [`dist/styles.css`](./dist/styles.css) (design tokens + core primitives) and [`dist/styles-domain.css`](./dist/styles-domain.css) (mining-domain components). PostCSS ([`postcss-mdk-layer.mjs`](./postcss-mdk-layer.mjs)) wraps top-level rules in `@layer mdk` and prepends `@layer base, mdk, app;`.
+- **Registry** — `npm run build:registry` emits [`dist/registry.json`](./dist/registry.json). Run `npm run check:agent-ready` before changing
+  public exports (also runs in root `npm run fullcheck`).
+- **SCSS source** — [`_mixins.scss`](./src/primitives/styles/_mixins.scss) and [`_colors.scss`](./src/primitives/styles/_colors.scss) stay exposed as
+  subpath exports so downstream apps can `@use` them from their own SCSS.
+
+## Development
+
+```bash
+npm run dev                    # watch CSS + TS
+npm run build                  # build:ts + build:scss + build:registry
+npm run build:ts               # TypeScript only
+npm run build:scss             # Vite → dist/styles.css + dist/styles-domain.css
+npm run build:registry         # dist/registry.json
+npm run check:agent-ready      # contract gate (needs registry build)
+npm run typecheck
+npm run test
+```

package/dist/domain/components/active-incidents-card/active-incidents-card.example.d.ts

@@ -0,0 +1 @@
+export declare const ActiveIncidentsCardExample: () => import("react").JSX.Element;

package/dist/domain/components/active-incidents-card/active-incidents-card.example.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Runnable example for ActiveIncidentsCard.
+ */
+import { ActiveIncidentsCard } from '@tetherto/mdk-react-devkit';
+const mockItems = [
+    {
+        id: '1',
+        severity: 'critical',
+        title: 'Miner 0xA1 offline',
+        body: 'No telemetry received in 2 min.',
+        subtitle: '2 min ago',
+    },
+    {
+        id: '2',
+        severity: 'high',
+        title: 'Container 03 temp >78°C',
+        body: 'Sustained above warning threshold.',
+        subtitle: '12 min ago',
+    },
+    {
+        id: '3',
+        severity: 'medium',
+        title: 'Pool latency elevated',
+        body: 'Round-trip 220ms (baseline 80ms).',
+        subtitle: '1 h ago',
+    },
+];
+export const ActiveIncidentsCardExample = () => {
+    return (_jsx(ActiveIncidentsCard, { label: "Active Alerts", items: mockItems, onItemClick: (id) => {
+            // oxlint-disable-next-line no-console
+            console.log(`open alert ${id}`);
+        } }));
+};