diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1816672 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# Agent guide — DataLex + +Guidance for AI agents (and humans) making changes here. Most of DataLex is yours +to evolve freely. The one thing to be careful about is the **shared design +contract** below. + +## ⚠️ Shared design contract with Governed Analytics Cloud — do not break + +DataLex is embedded inside the **Governed Analytics Cloud**, which reskins the +embedded surface to the global theme. That works only because DataLex exposes a +small, stable contract that the cloud drives from outside. The canonical source +is the cloud's `@duckcodeai/design-tokens` package (and `docs/adr/ADR-0002` in the +cloud repo). **Renaming or removing any of the following silently breaks the +cloud embed** — and the cloud's sync runs a contract check +(`scripts/embed-contract.test.mjs`) that will **fail the build** if you do: + +1. **Theme selector** — `data-theme` on `` (mirrored on `` by the + Shell), values **`paper` | `white` | `obsidian`**. Keep these theme blocks in + `packages/web-app/src/styles/datalex-design.css`. `white` is the cloud's crisp + light theme — do not drop it. +2. **Token vocabulary** — the shared semantic vars every surface reads: + `--bg-0..4`, `--bg-canvas`, `--text-primary/secondary/tertiary/muted`, + `--accent`/`--accent-hover`/`--accent-dim`/`--accent-fg`, + `--border-subtle/default/strong`. **No app-prefixed colour vars** (no + `--lux-color-*`). Rename a token → rename it in the cloud's design-tokens too. +3. **Theme persistence key** — `dm_theme` (the `uiStore` key). The cloud writes it + (and sets `data-theme`) to drive the embedded theme. Don't rename it. +4. **Layout classes the cloud's fit override targets** — `.app` (the shell grid), + `.activity-rail`, `.topbar`, `.topchrome`, `.left-resizer`. The cloud hides its + own chrome and collapses the activity-rail column by selecting these. Renaming + them re-opens the gap / brings back hidden chrome. + +If you must change any of the above, **coordinate with the cloud repo** +(`governed-analytics-cloud`): update `packages/design-tokens` + the +`embed-overrides/datalex.css`, and run `node scripts/embed-contract.test.mjs` +there. Standalone DataLex is unaffected by the cloud — these are just stability +guarantees on the names the cloud depends on. + +## General +- Web app: `packages/web-app` (React/Vite, Zustand, React Flow). Build: `npm run + build` inside that package. +- See `CONTRIBUTING.md` for setup, tests, and the release process. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 03f9037..e9c101d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -159,3 +159,14 @@ See [RELEASING.md](RELEASING.md) for the full process. Short version: bump `project.version` in `pyproject.toml`, move items from `[Unreleased]` into a new dated section in `CHANGELOG.md`, merge, then push a signed `vX.Y.Z` tag. CI publishes to PyPI automatically. + +## Shared design contract (Governed Analytics Cloud embed) + +DataLex is embedded by the Governed Analytics Cloud, which reskins it to the +global theme. A small set of names is a **shared contract** the cloud depends on +— don't rename them without coordinating: the `data-theme` values +(`paper`/`white`/`obsidian`), the `--bg-*`/`--text-*`/`--accent*`/`--border-*` +vars, the `dm_theme` storage key, and the `.app`/`.activity-rail`/`.topbar`/ +`.topchrome`/`.left-resizer` layout classes. The cloud's build runs a contract +check that fails on a break. See [`AGENTS.md`](AGENTS.md) for the full list and +the canonical source (`@duckcodeai/design-tokens`).