@elaraai/east-codex-plugin 0.0.0-stage → 1.0.90

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,348 @@
1
+ ---
2
+ name: east-contribute
3
+ description: "Contribute a change to the East monorepo (elaraai/east-workspace) from a GitHub issue, end-to-end and to repo standard. Use when: (1) the user gives a GitHub issue number or URL for elaraai/east-workspace and asks to design/implement/fix it ('work on issue #42', 'implement this issue', 'fix #37'), (2) making any code change INSIDE the monorepo libs (east, east-node, east-c, east-py, e3, east-ui, or the dev-tooling: east-diagnostics, eslint-plugin-east, tsserver-plugin-east, east-codex-plugin) where you must follow the repo conventions/STANDARDS, the examples↔tests contract, East diagnostics, and the CI gates, (3) triaging which lib(s)/skills an issue affects and avoiding duplication of an existing capability, (4) taking a monorepo change from branch → implementation → build/test/lint + diagnostics → PR. NOT for building an application WITH East — use east-design / east-project for that."
4
+ ---
5
+
6
+ # East Monorepo Contributor Workflow (issue → PR)
7
+
8
+ Drive a GitHub issue from `elaraai/east-workspace` to a **verified, convention-compliant pull request** that resolves it. This skill is for contributing to the **monorepo itself** — fixing/extending `east`, `east-node`, `east-c`, `east-py`, `e3`, `east-ui`, and the dev-tooling libs — not for building an app with East.
9
+
10
+ You are a maintainer of a large, diverse, multi-language platform (TypeScript + Python + C). The dominant failure modes are: re-deriving a fix the issue already specifies, **duplicating a capability that already exists**, shipping East code that type-checks but breaks East idioms, and missing a CI gate (examples↔tests parity, regenerated plugin index, version drift). This skill exists to prevent those.
11
+
12
+ ## Before writing code — search the example index
13
+
14
+ Every East API has a tested example in the plugin's index — the index IS the
15
+ API reference, printed from each example's IR in TypeScript or python. Before
16
+ writing or changing East code:
17
+
18
+ 1. Call `search_east_examples` for each capability you
19
+ are about to use — `language: "python"` for east-py, `"typescript"`
20
+ otherwise. Summaries come back first: id, signature, the inputs and the
21
+ expected result, a few hundred bytes each.
22
+ 2. Fetch the one or two that match with `get_east_example`
23
+ and pattern your code on them.
24
+ 3. Do not read `node_modules/@elaraai/**` or `*.examples.ts` files wholesale,
25
+ and do not reason from `.d.ts` signatures: the index holds the same
26
+ programs, exact and far cheaper, and the signatures omit the runtime rules
27
+ that make East code correct.
28
+
29
+ Nothing is injected for you; the search is the step.
30
+
31
+ ## When this skill vs others
32
+
33
+ | Situation | Skill |
34
+ |---|---|
35
+ | "Fix / implement issue #N in east-workspace", change monorepo source | **east-contribute** (this) |
36
+ | "Build an app / I have a goal" — design a solution with East | east-design → east-project |
37
+ | Per-API how-to while implementing | the per-package skill: `east`, `e3`, `east-node-std`, `east-node-io`, `east-py*`, `east-ui`, `e3-ui` |
38
+
39
+ ## Inputs
40
+
41
+ An **issue number or URL** (e.g. `#42`, `https://github.com/elaraai/east-workspace/issues/42`). If `gh` is unavailable or the user pasted the body, work from the pasted text.
42
+
43
+ ```bash
44
+ gh issue view <n> --repo elaraai/east-workspace # read the WHOLE issue
45
+ gh label list --repo elaraai/east-workspace # taxonomy (most issues are unlabelled)
46
+ ```
47
+
48
+ ## The loop
49
+
50
+ ```
51
+ 0 UNDERSTAND read the whole issue; honor its scope (Acceptance criteria / Ship-this-release; leave Defer items)
52
+ 1 TRIAGE map issue → lib(s) → per-package skill(s); compute the CI blast radius
53
+ 2 DISCOVER check the feature register — does this capability already exist? (anti-duplication)
54
+ 3 TOOLING ensure East diagnostics are live; know the REAL gate is `make lint`
55
+ 4 REPRODUCE bugs: run the repro, confirm the root cause BEFORE editing. features: design to the issue's design
56
+ 5 IMPLEMENT edit src WITH TypeDoc; obey the East interop rules absolutely
57
+ 6 EAST CODE every public method touched gets a spec test AND an example() (HARD RULE)
58
+ 7 VERIFY make build → make test → make lint → address every diagnostic → downstream libs
59
+ 8 SYNC update SKILL.md/docs if public API changed; regenerate + commit the plugin index/.build
60
+ 9 PR branch → commit → PR linking the issue — ONLY after the user approves the push
61
+ ```
62
+
63
+ Do not skip 0, 2, or 7. The issue body usually already names the exact root-cause file and the intended fix — start there, don't re-derive. Implement to the stated scope and **no further** (honor `Defer` checklists).
64
+
65
+ ---
66
+
67
+ ## 0. Understand — read the whole issue
68
+
69
+ Issue bodies are highly structured. **Bugs**: `## Symptom` + a runnable reproduction + `## Root cause` (often citing the exact `file:guard`) + `## Fix` (sometimes two options) + `## Workaround`. **Features**: `## Summary` / `## Motivation` / `## Decision (design)` (concrete types/code) / `## Backward compatibility` / `## Scope / phasing` (a `Ship in this release` vs `Defer` checklist) / `## Acceptance criteria`. Some issues titled `Design:` want a **design/spec PR, not code** — produce the design, don't over-build.
70
+
71
+ Decide the deliverable type up front: **bug fix**, **feature (to acceptance criteria)**, **test-only** (the issue says "pure test addition; no product code"), or **design proposal**.
72
+
73
+ ## 1. Triage — issue → lib(s) → skills
74
+
75
+ Title prefixes are literal scopes. Map to the directory, then load the per-package skill before coding.
76
+
77
+ | Prefix / area | Directory | Per-package skill |
78
+ |---|---|---|
79
+ | `east:` (core language) | `libs/east` | `east` |
80
+ | `east-node:` std / io | `libs/east-node/packages/east-node-{std,io}` | `east-node-std` / `east-node-io` |
81
+ | `east-py:` | `libs/east-py/packages/east-py{,-std,-io,-datascience}` | `east-py` / `east-py-std` / `east-py-io` / `east-py-datascience` |
82
+ | `e3` | `libs/e3` | `e3` |
83
+ | `east-ui` / `causal` | `libs/east-ui/packages/{east-ui,e3-ui,e3-ui-cli}` | `east-ui` / `e3-ui` / `e3-ui-cli` |
84
+ | `east-c` | `libs/east-c` | **no per-API skill** — read `libs/east-c/CLAUDE.md`, use `make test-east-c` |
85
+ | dev-tooling | `libs/{east-diagnostics,eslint-plugin-east,tsserver-plugin-east,east-plugin,east-codex-plugin,east-codex-plugin}` | none — read the lib's README/CLAUDE.md |
86
+
87
+ **Blast radius (run the union locally — CI will).** A change to a core lib triggers downstream workflows via `paths:` filters:
88
+
89
+ - `libs/east` → tests for east, east-node, e3, east-c, east-py, east-ui, diagnostics
90
+ - `libs/east-node` → east-node, e3, east-c, east-py, east-ui
91
+ - `libs/e3` → e3, east-ui · `libs/east-c` → east-c, east-py · `libs/east-py` → east-py, e3
92
+ - any `libs/**/SKILL.md` or `libs/**/*.examples.ts(x)` → **plugin-artifacts** (checks the committed search index is current and that both plugins assemble)
93
+ - **every PR** → `version-drift` (`make check-version`)
94
+
95
+ Heuristic: always `make build` the union; run a downstream lib's **tests** when your change touches exported types or IR (anything `make test-export` would emit), otherwise the directly-edited lib's tests suffice plus a root `make build`.
96
+
97
+ ## 2. Discover — the feature register (don't duplicate)
98
+
99
+ **Before writing new code, confirm the capability doesn't already exist somewhere in the platform.** Mandatory — the same primitive often already lives in a sibling lib, and silent duplication is the most expensive mistake here. There is no single hand-maintained catalog (deliberately — it would rot against the sources below). The register is a **procedure** over the authoritative, low-staleness sources, plus the ownership map.
100
+
101
+ **Search order** (each step widens coverage past the previous step's blind spots):
102
+
103
+ 1. **Example index** (auto-generated, CI-enforced) — MCP tool `search_east_examples` (a.k.a. `search_east_examples`); try 2–3 keyword phrasings, optional `package` filter, `language: "python"` for the east-py spelling (every core example is stored as IR and printed in either language), `get_east_example` for one in full. Covers `east`, `east-node-std`, `east-node-io`, `east-py-datascience`, `east-ui`, `e3-ui` (+ a few hand-written `e3` stubs).
104
+ 2. **Per-lib `SKILL.md` API tables** — the designated per-package API registry; catches APIs with no `example()` yet. `rg -i "<symbol>" libs/**/SKILL.md`. (For `e3`, the SKILL.md is more complete than the index.)
105
+ 3. **Export barrels + built `.d.ts`** (compiler truth — the ONLY step that reaches the index/SKILL blind-spot libs: `east-c`, `east-node-cli`, `e3-*` internals, `east-py-std/io`, dev-tooling):
106
+ ```bash
107
+ rg -n "export (const|function|class|interface|type) <Name>" libs/*/src/index.ts libs/*/packages/*/src/index.ts
108
+ rg -n "\.<method>\(" libs/*/src libs/*/packages/*/src # expression/stdlib methods not in barrels
109
+ ```
110
+ 4. **In-flight work** — don't duplicate an open issue/PR:
111
+ ```bash
112
+ gh search issues --repo elaraai/east-workspace "<capability>" --state all
113
+ gh search prs --repo elaraai/east-workspace "<capability>" --state all
114
+ ```
115
+ 5. **The issue's own root-cause pointer** — if it cites `file:symbol`, start there.
116
+
117
+ **Capability-ownership map** — which lib owns a concern, and how to confirm coverage. It routes to the sources above (never restates signatures) and explicitly covers the libs the index/SKILL.md miss:
118
+
119
+ | Capability domain | Owning lib / package | Skill | Confirm via |
120
+ |---|---|---|---|
121
+ | Language core: types, expressions, collections, variants | `libs/east` | `east` | index / SKILL |
122
+ | File / HTTP / time / crypto (Node) | `east-node-std` | `east-node-std` | index / SKILL |
123
+ | SQL / NoSQL / S3 / formats / transfer | `east-node-io` | `east-node-io` | index / SKILL |
124
+ | Durable dataflow, datasets, CLI, content-addressing | `libs/e3` (e3-core/cli/types/api-*) | `e3` | SKILL + grep `libs/e3/packages/*/src` |
125
+ | ML / optimization / Bayesian / simulation (Python) | `east-py-datascience` | `east-py-datascience` | index / SKILL |
126
+ | Python runtime / std / io | `east-py{,-std,-io}` | `east-py*` | SKILL + grep (not indexed) |
127
+ | C runtime / IR execution / serialization | `libs/east-c` | — | grep `libs/east-c/**/src` + headers; `make test-east-c` |
128
+ | UI components / tags / decision surfaces | `east-ui`, `e3-ui` | `east-ui` / `e3-ui` | index / SKILL |
129
+ | Headless render / screenshot of a component or surface (CLI + programmatic) | `east-ui/packages/e3-ui-cli` | `e3-ui-cli` | SKILL + grep `libs/east-ui/packages/e3-ui-cli/src` |
130
+ | Dev tooling: diagnostics, eslint/tsserver plugin, scaffolds, the agent plugins | `east-diagnostics`, `eslint-plugin-east`, `tsserver-plugin-east`, `create`, `east-plugin` (+ `east-codex-plugin`, `east-codex-plugin`) | — | grep that lib's `src` + README |
131
+
132
+ If a near-match exists, **extend/reuse it** rather than adding a parallel implementation. If a genuinely new capability is needed, place it in the lib that owns the concern (dependency order: `east` → `east-node`/`e3`/`east-ui`; `east-c`/`east-py` consume exported IR). **Record what you searched in the PR body** so review can see duplication was checked. Adding a capability = "register" it: add the `example()` (auto-flows into the index via CI — §6/§8), update the lib SKILL.md table, and add a row here only if a new package/domain appeared.
133
+
134
+ ## 3. Tooling — make East diagnostics real
135
+
136
+ Plain `tsc` cannot see East idiom mistakes (hand-rolled variants, `some/none`, redundant casts, untracked data, JSX-vs-factory, …). Those are caught by **east-diagnostics**, surfaced three ways: the Codex plugin diagnostic hooks and LSP bridge (injects an `<east-code-review>` block after edits), `@elaraai/tsserver-plugin-east` (editor squiggles), and `@elaraai/eslint-plugin-east`'s `east/east-rules` in CI (`make lint`).
137
+
138
+ **Critical caveats — do not assume the squiggles will save you:**
139
+ - The auto-injection only fires for files that (a) end `.ts/.tsx/.js`, (b) literally contain the import substring `@elaraai/east`, and (c) sit in a detected East project. **At the monorepo root it may not fire at all.**
140
+ - Diagnostics on **first-party `libs/*/src/`** are intentionally **skipped** (lib factories legitimately use the flagged patterns). That is exactly where most issue fixes live — so for a typical fix you get **no squiggles**.
141
+ - Therefore: **the authoritative pre-commit gate is `make lint`** (runs `east/east-rules` over a real TS program) plus `make build` (native type errors). Treat a clean `make lint` + `make build` + every injected `<east-code-review>` item fixed as the gate. **Never silence a diagnostic** by adding it to `disabled` — fix the code.
142
+
143
+ A project wires the tooling via `tsconfig.json` `compilerOptions.plugins: [{ "name": "@elaraai/tsserver-plugin-east" }]` + the eslint plugin with type-aware linting (`projectService: true`). Scaffolds from `npm create @elaraai/{e3,east}` ship both preconfigured — never re-add. (In VS Code, the tsconfig plugin loads only when the **workspace** TypeScript version is selected.)
144
+
145
+ The active rule set (hand-rolled variants, `some`/`none`, redundant casts,
146
+ relative `src` imports, untracked data, JSX-vs-factory, …) is enumerated in
147
+ `libs/eslint-plugin-east/README.md` — read it there rather than from a list
148
+ here, which has already drifted once. What matters for the gate: `make lint`
149
+ runs all of them over a real TS program, and every one it reports is a fix, not
150
+ a suppression.
151
+
152
+ **Editing python? The tooling is different and you must run it yourself.**
153
+ `tsserver-plugin-east` and `eslint-plugin-east` see nothing in a `.py` file;
154
+ Pyright/Pylance has no plugin API, so there is no editor plugin to ride. The
155
+ python twins live in `east.diagnostics` and are surfaced five ways — `east-py
156
+ lint`, `east-py check`, the flake8 `EAS` codes, a pylsp plugin, and `east-py
157
+ lsp` — and `cd libs/east-py && make lint` runs the rules over every package's
158
+ own East bodies, which is the gate:
159
+
160
+ ```bash
161
+ cd libs/east-py
162
+ make lint # ruff + license headers + the East rules (east-py lint)
163
+ uv run east-py lint packages/… # the rules alone; --list-rules names all of them
164
+ uv run east-py check path/mod.py # the BUILD's errors — a wrong declared `out`, a refused
165
+ # capture, an IRAnalysisError; the rules cannot see these
166
+ ```
167
+
168
+ Two tiers, and the difference matters when you are chasing a failure: the
169
+ **rules** read the `ast` (syntactic — which names hold expressions, what python
170
+ does to them), while **`east-py check`** runs the build, which is the only way
171
+ to type-check a python East body because East's type checker IS the builder. A
172
+ clean `east-py lint` is necessary, not sufficient. Neither `mypy` nor `ruff`
173
+ sees either class of mistake.
174
+
175
+ ## 4. Reproduce (bugs) / design (features)
176
+
177
+ **Bug:** run the issue's reproduction and confirm the failure *before* editing — it proves the claimed root cause and prevents a wrong fix. Put a scratch repro under the owning lib's `test/` (or a temp file) using that lib's import convention (§6) so you don't trip `no-relative-src-import`.
178
+
179
+ **Feature:** implement the issue's `## Decision (design)` as written; don't invent an alternative API. If the design is ambiguous, ask rather than guess.
180
+
181
+ ## 5. Implement — src + TypeDoc + interop rules
182
+
183
+ Edit the source. **Every public API you add or change MUST carry a TypeDoc comment** (the #1 mandatory gate in every `STANDARDS.md`): present tense, verb-first; `@param name - description` and `@returns description` with **no types** (TS infers them); `@typeParam`; `{@link Symbol}`; `@internal`/`@deprecated` as needed.
184
+
185
+ `@throws` form is keyed on location: **expression classes** (`src/expr/`, `src/expr/libs/`) use prose `@throws East runtime error if …`; **regular classes** use `@throws {ErrorType} …`; **east-node platform fns** use `@throws {EastError}` with the exact user-facing message.
186
+
187
+ `@example` form is also keyed on location: **expression classes** use the full `East.function(...) → East.compile(...) → execution` flow with inline `// result` comments and one `const compiled =`, and must be validated with the `east_compile` MCP tool until they compile; **regular classes** use plain realistic usage (no `compile()`).
188
+
189
+ ### East interop — read the authority, don't trust a summary
190
+
191
+ East values have runtime representations that plain TS/Python intuition gets
192
+ wrong, and neither `tsc` nor `mypy` can see the mistakes. **This skill does not
193
+ restate the rules**: a copy here rots against the source, and a stale copy is
194
+ worse than no copy — it reads as authoritative while teaching a superseded
195
+ idiom. Open the convention doc for the language you are editing, plus the
196
+ per-package skill for the API you are calling:
197
+
198
+ | You are editing | Read first |
199
+ |---|---|
200
+ | TypeScript building/consuming East values | `docs/conventions/EAST_TS_INTEROP.md` + the `east` skill |
201
+ | Python building/consuming East values | `docs/conventions/EAST_PY_INTEROP.md` + the `east-py` skill (its expression-vs-eager surface table is the one that catches people) |
202
+ | A Python module wrapping an optional native library | `docs/conventions/PYTHON_OPTIONAL_DEPS.md` + that package's `CLAUDE.md` |
203
+ | An east-ui / e3-ui factory or renderer | `docs/conventions/EAST_UI_PROP_PATTERNS.md` + the `east-ui` / `e3-ui` skill |
204
+ | A platform function (any language) | the owning package's skill — it documents the decorator/registration shape |
205
+
206
+ Five invariants are shared by all of them, and each corrupts data silently
207
+ rather than failing loudly, so they are worth carrying in your head:
208
+
209
+ - **Construct variants and options with the constructors.** TS `variant("Tag", data)` / `some(x)` / `none`; Python `variant("case", value, Type)` / `some` / `none`. A `{type, value}` literal is not a variant — it lacks the brand East tells a variant by, so `isValueOf` rejects it and `East.value(x, T)` throws on it.
210
+ - **Compare with the East comparators**, never `===` / `<` / `sorted`. TS `equalFor` / `lessFor` / `compareFor`; Python `equal_for` / `less_for` / `compare_for` / `make_east_key`.
211
+ - **Derive decoded types from the East type**, never hand-roll a parallel mirror (TS `ValueTypeOf<typeof FooType>`).
212
+ - **Coerce and validate at the boundary** — `coerce_to` / `assert_value_of` — and let the platform-function decorator validate its declared output.
213
+ - **Never reimplement an east-c builtin.** Delegate to the value method or the `East.<Type>` namespace; Python `//` is not East `IntegerDivide`.
214
+
215
+ **Match the package you are in, not its oldest sibling.** How you read an
216
+ option, which guard helper wraps an optional import, which mypy overrides a
217
+ package needs — those are per-package current practice, and they diverge as
218
+ packages modernise. Read the code next to your change and that package's skill
219
+ before copying an idiom from elsewhere in the monorepo.
220
+
221
+ ### Review findings that keep recurring
222
+
223
+ Each of these shipped as a real bug here, and each survives a green `tsc`. The
224
+ rule is stated; the mechanics live in the doc named beside it.
225
+
226
+ - **HARD RULE — East values through East.** An East value is printed, read, compared, ordered, collected and typed through East's utilities — never a JavaScript stand-in — and tested over real, decoded East values. `String(x)` / `toISOString()` / `JSON.stringify`, `BigInt(text)` / `new Date(text)`, `typeof` / `instanceof`, `===` and subtracting sorts, a plain `Set` / `Map` keyed by structs, and `{ type, value }` casts each type-check clean, and several hid real bugs in the renderers (#960, #962). The UI packages' `make lint` fails on every one of them. See `docs/conventions/EAST_TS_INTEROP.md` §7–§11.
227
+ - **Decode/value TS types: derive, never hand-roll.** Where an East type exists, type its decoded JS shape `ValueTypeOf<typeof FooType>`. A hand-authored `interface FooValue` mirror — or a local `type Opt<T> = {type;value}` standing in for `OptionType` — drifts the moment the East type gains a field, with no compiler complaint: a renderer's hand-rolled `ConfigValue` silently missed three new config fields this way. See `east-ui-components/CLAUDE.md`.
228
+ - **east-ui / e3-ui renderers: theme recipes only, zero inline styles.** No `style={{…}}`, no inline Chakra style props — they bypass the theme, which follows the East Design System (claude.ai/design; its read-only download is `libs/east-ui/app_design_system/`, and the token guard `east-ui-components/src/theme/design-system.test.ts` fails when the theme drifts from it). A renderer sets data attributes and geometry only; an element with no recipe gets a new slot recipe using the theme's semantic tokens, never raw hex/px. Dynamic data bindings are the only exception, and nearby debt is not licence to add more. See the `east-ui` skill + `libs/east-ui/CLAUDE.md` › Canonical design source.
229
+ - **east-ui factories: reify mapper callbacks, never splice.** A per-row callback prop must become a real East function the factory *calls* inside the eager `.map`, not an expression tree spliced mid-map (double-eval + undefined captures). Behavior props stay pass-through `FunctionType`, lifted and never invoked at build time. See `docs/conventions/EAST_UI_PROP_PATTERNS.md`.
230
+ - **Before trusting a downstream type error, rebuild the chain.** A renderer type-checking a *stale* `dist` of its IR package (because the IR build `noEmitOnError`-aborted on an unrelated example) will silently miss new fields. After changing an IR type, build the IR package to **success** before believing the renderer compiles (see §7's stale-tree rule).
231
+ - **A doc or skill you contradict is part of your change.** If your fix moves a package off a documented idiom — a helper it no longer uses, a mypy override it no longer needs — update that convention doc / `CLAUDE.md` / `STANDARDS.md` in the same PR. Leaving the old text standing is how the next contributor reintroduces the thing you just removed.
232
+
233
+ ### e3's data layer — rules that keep it from drifting
234
+
235
+ The e3 data and execution layer drifted by growing a rule per door and a copy per runner. Four rules stop it:
236
+
237
+ - **A wire change names its migration.** A PR that adds or changes a field of a persisted or packaged type says which kind of wire it changes, as `docs/conventions/WIRE_MIGRATION.md` defines them. Packages are re-exported; a change to a stored form ships a repository upgrade step, which carries a repository an older release wrote forward in place, keeping its records' states and histories; no reader keeps a decoder for an earlier form.
238
+ - **A new object kind carries a kind tag.** An object that names other objects gets a `kind` tag that GC recognizes, and lands with its GC test in the same PR. GC deletes anything it cannot see.
239
+ - **Collections enter the store through the one door.** Write a collection dataset through `encodeDatasetBlob` (e3-types), never through an encoder of your own. A second door is how the store came to hold one value in several forms.
240
+ - **A runner capability ships on every runner at once.** east-node, east-c and east-py either all gain it in one change, with shared fixtures, or none does.
241
+
242
+ ## 6. East code in examples + tests (HARD RULE)
243
+
244
+ **Every distinct public method exercised by a `*.spec.ts` MUST have a matching `example()` export in the sibling `*.examples.ts`** (name-locked: `array.spec.ts` ↔ `array.examples.ts`, same dir). Examples are both CI-tested and extracted into the plugin search index — a missing example breaks the index-in-sync CI check.
245
+
246
+ **Import discipline (the one contradiction to get right):**
247
+ - **Core `libs/east` `*.spec.ts`** import from `../src/index.js` (a package cannot import its own published name). This is the *only* place `../src` is correct; the `no-relative-src-import` rule does not fire there because diagnostics skip first-party `src/`.
248
+ - **Core `libs/east` `*.examples.ts`** AND **all downstream** (`east-node-*`, `east-ui`, `e3-ui`) spec **and** examples import the **published name** (`@elaraai/east`, `@elaraai/east-node-std`, …). Never `../src` in downstream.
249
+
250
+ `example({ keywords, description, fn, inputs, returns })`: `keywords` (search terms — API names, types, concepts), `description` (also the test name), `fn` (an `East.function(...)`), `inputs` (`[]` for zero-arg), `returns` (**hand-verify it**). **Omit `returns` only** for `NullType` (side-effect) or `UIComponentType` — omitting it elsewhere makes the harness run `fn` as a bare statement and the assertion false-passes. Wire with named keys, placed before the related test: `assert.examples(test, { arrayGet: ex.arrayGet })` (downstream uses `Assert.examples`). Import examples with the `.js` extension: `import * as ex from "./array.examples.js";`.
251
+
252
+ Copyable skeleton (downstream package; for core `east` keep the `@elaraai/east` import in the examples file too):
253
+
254
+ ```ts
255
+ import { East, ArrayType, IntegerType, example } from "@elaraai/east";
256
+
257
+ export const arraySum = example({
258
+ keywords: ["array", "ArrayType", "sum"],
259
+ description: "sums an array of integers", // becomes the test name
260
+ fn: East.function([], IntegerType, ($) => {
261
+ const a = $.const([1n, 2n, 3n], ArrayType(IntegerType)); // explicit East type
262
+ return a.sum();
263
+ }),
264
+ inputs: [],
265
+ returns: 6n, // hand-verified; omit ONLY for NullType/UIComponentType
266
+ });
267
+ ```
268
+
269
+ **Per-lib test conventions — routing only; the lib's `STANDARDS.md` is the
270
+ authority for how to write the test**, and it is the file to update if the
271
+ convention changes:
272
+
273
+ - **east**: one file per type at `test/<name>.spec.ts`, harness from `./platforms.spec.js`; bodies are East functions asserted via `$(...)`.
274
+ - **east-node** (std/io): co-located `src/<mod>.spec.ts`, harness from `./test.js`; platform impls passed as `{ platformFns: ModuleImpl }`; `East.compileAsync()` when any impl is async.
275
+ - **e3**: co-located `src/<x>.spec.ts` on `node:test`. The rule that bites: **real filesystem only — never mock fs** (fresh `mkdtempSync` per test, cleaned in `afterEach` even on failure), and atomic writes are temp-file + rename with a retry for transient Windows `EPERM/EACCES/EBUSY/EEXIST`.
276
+ - **east-py-datascience** (hybrid TS+Python): TS holds **types + tests only**, Python holds the impl, and the East types must match **exactly** across both. Specs are `{ exportOnly: true }` and export IR that pytest replays; its **examples are `*.examples.ts` (TS), not Python.** Plain `east-py` / `east-py-std` / `east-py-io` are skill-file-only, pytest-tested, with **no `*.examples` requirement**.
277
+ - **east-ui / e3-ui**: public JSX **tags** desugar to the **same IR** as internal **factories**; every compilable `@example` is mirrored by an `example()` in `*.examples.tsx`. **Visual verification is a gate**: after a component/example change, rebuild and run the showcase's responsive suite (`cd libs/east-ui && make test-responsive`), and land a visual change with a visual invariant in `packages/east-ui-showcase/tests/responsive/` — computed styles measured in the page, in both themes. Never read a screenshot. e3-ui follows east-ui's `STANDARDS.md` verbatim.
278
+
279
+ ## 7. Verify — the gate
280
+
281
+ **Always `make`, never `npm run`/`pnpm run`.** (The "Before committing" checklists inside the `STANDARDS.md` files literally say `npm run test`/`npm run lint` — that wording is **superseded** by the monorepo `make` convention.) Raw pnpm only for `pnpm install <dep>`, `pnpm -r run`, or `pnpm --filter … run …` while debugging.
282
+
283
+ ```bash
284
+ make build # ALWAYS before test — tests resolve imports through each package's dist/; stale dist = stale test
285
+ make test
286
+ make lint # the authoritative East-idiom gate (east/east-rules) + ruff + clang-format
287
+ # scope to one lib while iterating:
288
+ cd libs/<lib> && make build && make test && make lint
289
+ cd libs/<lib> && make help # lib-specific extras (e3: make fuzz; east-c: make test-east-c; east-py: make typecheck/check/coverage)
290
+ ```
291
+
292
+ - **Local `dist/` is gitignored + built locally — a stale tree FAKES regressions.** Each package's `dist/` lags the *pulled source*, so a half-built tree throws phantom errors in files you never touched: a new export missing from `east/dist`, an `implicit-any` on a test `$`, a `value is not iterable` in beast2 serialization, an unresolved import. **When a build/test fails in a file you did not edit, suspect a stale tree FIRST** — don't blame your change. Before concluding anything is broken: **clean-rebuild the entire dependency chain** (`make clean && make build`, or at minimum `rm -rf` the `dist/` + `*.tsbuildinfo` of east → east-node → e3 → east-ui and rebuild them *in order*), and run **`pnpm install`** (a declared dep like `leaflet` may be unfetched). Then prove any remaining failure is pre-existing by stashing your diff (`git stash`) and re-running — a failure identical with your changes absent is not yours.
293
+ - **Integration tests** (east-node-io, east-py-io) need Docker: `make services-up` … `make services-down` (or `make test-all` for the full sweep).
294
+ - **east-c / east-py compliance** replay TS-exported IR — run `make test-export` first: each corpus lands under the checkout's own `tmp/`, where the root `paths.mk` points every gate (`EAST_TEST_IR_DIR` → `tmp/east-test-ir`, `EAST_DATASCIENCE_IR_DIR` → `tmp/east-py-datascience`, …). Then `cd libs/east-c && make test-east-c` / `cd libs/east-py && make check` — through make, which sets those variables; a gate run outside make skips its corpus or stops, saying to run it through make.
295
+ - **Address every injected `<east-code-review>` diagnostic** and every downstream lib in the blast radius.
296
+ - **Cross-platform**: CI runs east/east-c/east-py/east-node-std/create on ubuntu + macos-14 + windows-latest under Git Bash. Don't assume Linux-only paths, `/tmp`, `MAX_PATH`, or `cmd.exe` shell.
297
+
298
+ ## 8. Sync docs + regenerate the plugin index
299
+
300
+ If you changed public API: update that lib's `SKILL.md` API tables + decision tree **and** the companion `*.examples.ts`, in lockstep. Keep `SKILL.md` self-contained (three-column `Signature | Description | Example`, bold category headers, `❗` on throwing ops, no links to sibling `reference/` files). **Coordinate before editing a lib `SKILL.md` — they back the published plugin skills (the plugin symlinks to them).**
301
+
302
+ If you touched **any** `*.examples.ts(x)`, regenerate and **commit** the one committed artifact, the search index (CI `plugin-artifacts` fails on a diff). A `SKILL.md` or plugin `lib/hooks/mcp` change commits nothing generated: the plugins are assembled at build time, under `libs/east-plugin/marketplace/` (ignored), and the release publishes them to npm, where the `elaraai/plugins` catalog lists them.
303
+
304
+ ```bash
305
+ make -C libs/east-plugin index # regenerates libs/east-plugin/index.json — commit it
306
+ make -C libs/east-plugin package # assembles both plugins (a local marketplace for Codex and Codex); the plugin tests run over them
307
+ ```
308
+
309
+ (Authoring a *new plugin-native skill* like this one is directory-based: drop `libs/east-plugin/skills/<name>/SKILL.md`, add it to the repo-root `CLAUDE.md` "plugin-native" list; do **not** edit `plugin.json`/`marketplace.json`/`index.config.json`, and it does not feed the search index.)
310
+
311
+ ## 9. Branch → commit → PR (only after approval)
312
+
313
+ Implement and verify first. Then **stop and present the branch/commit/PR plan**; run `git`/`gh` only when the user explicitly approves the push (harness rule: commit/push only when asked).
314
+
315
+ - **Start from a fresh `main` by default.** Before beginning a new issue, `git checkout main && git pull`, *then* branch off it — otherwise you risk starting on a stale or already-merged feature branch you previously worked on, silently building/testing against a tree behind `origin`. (After pulling, the local `dist/` lags the fresher source, so clean-rebuild per §7.) **Exception:** when the developer explicitly tells you to continue on the current working branch — e.g. to add a change to an open PR — stay on it: do NOT `checkout main` / `pull` / `reset`, just keep committing to that branch.
316
+
317
+ - **Branch** off main: `elaraai/<type>/<slug>` (e.g. `elaraai/fix/e3-statestore-windows-rename-retry`). Never commit to main.
318
+ - **Commit**: Conventional Commits with a lib scope — `fix(e3): …`, `feat(east-ui): …`, `test(e3): …`, `chore(east-codex-plugin): …`. Reference the issue in the body (`Fixes #N`). Use the repository attribution policy for the actual contributing agent.
319
+ - **PR**: `gh pr create` with a body mirroring the issue's sections (`## Summary` / `## Root cause` / `## Fix` / `## Test` / `## Scope`) and **`Closes #<n>`** so merge auto-closes it. End the PR body with the Generated-with-Codex line. Note in the body what you searched in §2 (anti-duplication) and which downstream libs you verified.
320
+
321
+ ```bash
322
+ git checkout -b elaraai/fix/<slug>
323
+ git commit # message per above
324
+ gh pr create --repo elaraai/east-workspace --title "fix(<lib>): …" --body "…Closes #<n>…"
325
+ ```
326
+
327
+ ## Common traps
328
+
329
+ - **A new client-side UI platform function won't reach `ui()` tasks.** When you add an interactive platform function to **east-ui-components** (a `State.bind` / `Slice.bind` style runtime — e.g. `src/platform/slice/index.ts`), it self-registers at module load via `registerPlatformImplementation(MyImpl)`. That only populates east-ui-components' **registry** (`getRegisteredPlatformImplementations`), which **east-ui's own** reactive hooks read — so it works in a standalone east-ui preview/spec and looks done. But **e3-ui-components renders `ui()` tasks through HARD-CODED platform arrays that do NOT read that registry.** A function you forget to add there throws **`Platform function 'X' is not available`** (Region: `tasks.<task>.output.ReactiveComponent.<Component>`) — but *only* inside an e3 `ui()` task, so component/preview tests pass and the gap ships silently.
330
+ - **Fix — add `...MyImpl` to BOTH explicit arrays in `libs/east-ui/packages/e3-ui-components/src`:**
331
+ - `components/UITaskPreview.tsx` — the `scopedPlatforms` memo (`[...StateImpl, ...createScopedBindPlatform(manifest), ...createScopedFuncPlatform(…), ...createScopedRecordPlatform(…), ...OverlayImpl]`).
332
+ - `hooks/useDatasetValue.ts` — `[...StateImpl, ...BindPlatform, ...OverlayImpl]`.
333
+ - Import the impl from `@elaraai/east-ui-components/platform`. **Manifest-scoped** functions (data/func/record) go in via their `createScoped*(manifest…)` builder; **browser-local-state** functions (State, overlay, slice) go in **unscoped**, alongside `...StateImpl` / `...OverlayImpl`.
334
+ - Grep guard before you call a UI platform fn done: `rg -n "MyImpl" libs/east-ui/packages/e3-ui-components/src` must hit `UITaskPreview.tsx` **and** `useDatasetValue.ts`, not just the registering module.
335
+ - **Also rebuild + reinstall the `east-ui-preview` VS Code extension** — its webview bundles e3-ui-components, so a deployed package using the new fn renders blank / errors until the extension itself ships the array change. A version bump alone is not enough.
336
+
337
+ ## Do NOT
338
+
339
+ - **Bump versions.** All `@elaraai/*` share one version; `version-drift` (`make check-version`) fails on any drift. Releases are a separate `make set-version` / `chore: release vX.Y.Z` flow — not issue work.
340
+ - **Edit `e3-cloud` (east-aws)** — it's a separate closed-source repo. A fix reaches it only after a workspace release + lockstep update; say so in the PR rather than trying to change it.
341
+ - **Implement past the issue's scope** — honor `Defer` checklists.
342
+ - **Silence diagnostics** instead of fixing them; **mock the filesystem** in e3 tests; **hand-edit a lib `SKILL.md`** without coordinating.
343
+
344
+ ## Related skills
345
+
346
+ - **east-design** / **east-project** — for building *with* East (the opposite direction from this skill).
347
+ - **east**, **e3**, **east-node-std**, **east-node-io**, **east-py***, **east-ui**, **e3-ui** — the per-package API skills; load the one for the lib you're changing.
348
+ - **Canonical docs** (read the authoritative source, don't rely on this summary): `docs/conventions/{EAST_TS_INTEROP,EAST_PY_INTEROP,EAST_UI_PROP_PATTERNS,EXAMPLES_AUTHORING,MAKEFILE_TARGETS,PYTHON_OPTIONAL_DEPS,SKILLS_STANDARD}.md` and each `libs/<lib>/STANDARDS.md` + `CLAUDE.md`.
@@ -0,0 +1,233 @@
1
+ ---
2
+ name: east-design
3
+ description: "Design and architect a solution with East / e3 before writing code. Use when: (1) A developer describes a goal or problem rather than an API ('I want to build X', 'make/create an app that …', 'how should I structure Y', 'I have data in Z and need W', 'where do I start') and hasn't committed to an implementation — including a greenfield/empty directory before any project exists, (2) Identifying which business decision a solution should improve (East + e3 solutions are decision-oriented), (3) Deciding which East packages/skills a solution needs (east, e3, east-node-std, east-node-io, east-py-datascience, east-ui, e3-ui, east-ontology), (4) Working out the data flow — where data comes from (files, databases, S3, HTTP, APIs), how it is transformed, and where results go (datasets, exports, reports, decision surfaces), (5) Producing a design document with the architecture, the skills to load, and example search terms to ground the implementation."
4
+ ---
5
+
6
+ # East / e3 Solution Design
7
+
8
+ Turn a developer's goal into a concrete architecture **before** scaffolding or writing code. This skill is the front of the funnel: run discovery, decide which East packages the solution needs, sketch the data flow, and hand off to **east-project** (to scaffold) and the per-package skills (to implement).
9
+
10
+ You are designing, not coding. The output is a short design document the developer signs off on, not source files.
11
+
12
+ ## Before writing code — search the example index
13
+
14
+ Every East API has a tested example in the plugin's index — the index IS the
15
+ API reference, printed from each example's IR in TypeScript or python. Before
16
+ writing or changing East code:
17
+
18
+ 1. Call `search_east_examples` for each capability you
19
+ are about to use — `language: "python"` for east-py, `"typescript"`
20
+ otherwise. Summaries come back first: id, signature, the inputs and the
21
+ expected result, a few hundred bytes each.
22
+ 2. Fetch the one or two that match with `get_east_example`
23
+ and pattern your code on them.
24
+ 3. Do not read `node_modules/@elaraai/**` or `*.examples.ts` files wholesale,
25
+ and do not reason from `.d.ts` signatures: the index holds the same
26
+ programs, exact and far cheaper, and the signatures omit the runtime rules
27
+ that make East code correct.
28
+
29
+ Nothing is injected for you; the search is the step.
30
+
31
+ ## Start from the decision
32
+
33
+ East + e3 solutions are **decision-oriented**. A solution exists to improve a business **decision** and put defensible evidence behind it — not to move data or render a dashboard for its own sake ("decisions, not dashboards"). Design **backwards from the decision**: name the decision first, then work out what evidence it needs, what reasoning produces that evidence, and what data feeds the reasoning. The pipeline is the means; the committed decision is the end.
34
+
35
+ So before anything else, get a one-sentence answer to: **"What decision does this help someone make, and how would a better one show up?"** If the developer can't name a decision, the deliverable is probably a dashboard or report — that's fine, but say so explicitly, because it changes the design.
36
+
37
+ ### The platform stack (mental model)
38
+
39
+ Solutions sit on a fixed stack (the placemat in `docs/east-architecture.svg` / the workspace README). Design top-down — decision first, foundation last:
40
+
41
+ - **The decision loop** — what the end user does: **Observe** (see the evidence) → **Decide** (commit, with alternatives + override) → **Configure** (tune objectives, policies, assumptions) → **Trust** (provenance + audit trail on every output). The model recommends; it doesn't decide for them.
42
+ - **Access** — how the answer is surfaced: **Render** a UI (`east-ui` / `e3-ui`), **Ask** an agent, or **Serve** a typed API (`e3-api-*`).
43
+ - **The model** — the hub: an **economic ontology**, the typed graph of the business (objectives, processes, resources, decisions, KPIs, policies, data) wired by *drives / produces / constrains / measures / simulates*. Everything reads and reasons over the *same* model. Build it with the **east-ontology** skill.
44
+ - **The engine** — **Interact** (`*-std`: files/HTTP/time/crypto) · **Integrate** (`*-io`: SQL/NoSQL/S3) · **Reason** (`east-py-datascience`: optimization/ML/Bayesian/simulation) · **Compute** (`e3`: durable, content-addressed dataflow).
45
+ - **East** — the foundation: typed TypeScript compiled to one portable IR (TypeScript / Python / C).
46
+
47
+ The discovery groups below map onto these layers: data source → Integrate/Interact, compute → Reason, output → Access + the decision loop, durability → Compute.
48
+
49
+ ## Workflow
50
+
51
+ ```
52
+ 0. DECISION → name the decision being improved (one sentence) + how "better" shows up
53
+ 1. DISCOVER → ask the developer the questions below (use AskUserQuestion)
54
+ 2. MAP → turn answers into a capability list → skills to load
55
+ 3. SEARCH → search_east_examples for each capability; embed terms/extracts
56
+ 4. DESIGN → write the design doc (decision → evidence → data flow + skills + searches)
57
+ 5. CONFIRM → developer signs off, then hand to east-project + per-package skills
58
+ ```
59
+
60
+ Do **not** skip discovery. The most common design failures are (a) guessing the data source and execution model instead of asking, and (b) building a pipeline with no decision at the end of it. Use `AskUserQuestion` to ask several at once.
61
+
62
+ ## 1. Discover — the question bank
63
+
64
+ Ask only what you can't already infer from the developer's description. Group questions so you can ask 2–4 at a time.
65
+
66
+ **What decision is this for?** (the north star — drives everything else)
67
+
68
+ | Answer | Implication |
69
+ |---|---|
70
+ | A recurring operational choice (what to order/schedule/price/assign) | decision-oriented; the design culminates in a **decision surface** + the reasoning behind it |
71
+ | Improving several related decisions across a business area | model the area as an **economic ontology** first → **east-ontology** |
72
+ | A one-off analysis / report / dashboard, no decision to commit | not decision-oriented — say so; design a simpler read-only surface |
73
+ | Don't know yet | run a lightweight **east-ontology** elicitation to surface the decisions |
74
+
75
+ **Where does data come from?** (drives the I/O skills)
76
+
77
+ | Answer | Implication |
78
+ |---|---|
79
+ | Local files — CSV / JSON / text | **east-node-std** `FileSystem` (`readFile`, `readFileBytes`, `readDirectory`), parsed with **east**'s `blob.decodeCsv` / `parseJson`; a JSON too large to decode whole → `Json.open` |
80
+ | Spreadsheets / XML | **east-node-io** `Format.XLSX`, `Format.XML` |
81
+ | SQL database (SQLite / Postgres / MySQL) | **east-node-io** `SQL.*` |
82
+ | NoSQL (Redis / MongoDB) | **east-node-io** `NoSQL.*` |
83
+ | Object storage (S3) | **east-node-io** `Storage.S3` |
84
+ | FTP / SFTP transfer | **east-node-io** `Transfer.*` |
85
+ | HTTP / REST API | **east-node-std** `Fetch` |
86
+ | Compressed archives (gzip / zip / tar) | **east-node-io** `Compression.*` |
87
+ | Hand-authored / inline constants | plain **east** values, no I/O skill |
88
+
89
+ **What happens to the data?** (drives the compute skills)
90
+
91
+ | Answer | Implication |
92
+ |---|---|
93
+ | Filter / map / aggregate / reshape | pure **east** expressions |
94
+ | Join / group / pivot across sources | **east** collections (Dict, Set, `groupBy`, `toDict`) |
95
+ | Forecasting / regression / classification | **east-py-datascience** (XGBoost, LightGBM, NGBoost, GP, Torch) |
96
+ | Optimization / scheduling / routing | **east-py-datascience** (MADS, Optuna, SimAnneal, GoogleOr) |
97
+ | Bayesian inference / uncertainty | **east-py-datascience** (PyMC, MAPIE conformal) |
98
+ | Discrete-event simulation | **east-py-datascience** (Simulation) |
99
+ | Native code East can't express (a 3rd-party lib, bespoke algorithm) — Python or TS | a **project-owned platform module** → **east-project** (`--platform`), authored with **east** (`East.platform().implement()`) / **east-py** (`@East.platform_function`, callable in a body) |
100
+
101
+ **Where do results go?** (drives the output skills)
102
+
103
+ | Answer | Implication |
104
+ |---|---|
105
+ | A file or export on disk | **east-node-std** `FileSystem` / **east-node-io** `Format.*` |
106
+ | A queryable dataset / API result | **e3** datasets (`e3.export`, `e3 dataset get`) |
107
+ | An interactive decision surface or report | **east-ui** + **e3-ui** (`ui()`, `Data.bind`) |
108
+ | A static chart / table image | **east-ui** (rendered components) |
109
+ | Back into a database / S3 | **east-node-io** write side |
110
+
111
+ **How often and how durably does it run?** (drives e3 vs plain East)
112
+
113
+ | Answer | Implication |
114
+ |---|---|
115
+ | One-shot script, run by hand | plain **East** project (Node-only, AGPL-3.0) |
116
+ | Recurring / multi-step pipeline with caching | **e3** durable dataflow (BSL-1.1, Node + Python) |
117
+ | Reactive — recompute when inputs change | **e3** (content-addressable caching, `e3 watch`) |
118
+ | Interactive — users edit data and see results | **e3-ui** (`Data.bind` read/write/commit) |
119
+ | Needs Python compute (ML/opt) at all | **e3** (Python runtime) |
120
+
121
+ **Constraints to surface explicitly:**
122
+ - **Licensing** — plain East is AGPL-3.0; e3 is BSL-1.1. If the developer can't take BSL, the design must avoid e3 and Python compute.
123
+ - **Runtime** — Node-only vs Node + Python. Any `east-py-datascience` need pulls in Python, which means e3.
124
+ - **Secrets / credentials** — database URLs, S3 keys, API tokens → read from the environment at runtime (`Env.get` / `env_get`), never a literal in source: IR is content-addressed and replicated.
125
+
126
+ ## 2. Map — capability → skill + search terms
127
+
128
+ For each capability the answers surface, record (a) the skill to load and (b) the example-search query you'll run. This table is the heart of the design.
129
+
130
+ | Capability | Skill | `search_east_examples` query |
131
+ |---|---|---|
132
+ | Model the business / its decisions as a graph | east-ontology | `Ontology process kpi decision objective` |
133
+ | Decision surface — commit a choice with provenance | e3-ui | `Ontology Diff Data.bind commit` |
134
+ | Read/write local files, list a directory | east-node-std | `FileSystem readFile writeFile readDirectory` |
135
+ | HTTP fetch / REST | east-node-std | `Fetch http get post json` |
136
+ | Crypto / hashing / uuid | east-node-std | `Crypto hash uuid` |
137
+ | Spreadsheet parse/write | east-node-io | `XLSX read sheet parse rows` |
138
+ | SQL query | east-node-io | `SQL Postgres query select` |
139
+ | Redis / MongoDB | east-node-io | `NoSQL Redis MongoDB get set` |
140
+ | S3 storage | east-node-io | `S3 storage put get object` |
141
+ | Forecasting / boosting | east-py-datascience | `XGBoost forecast train predict` |
142
+ | Combinatorial optimization | east-py-datascience | `SimAnneal optimize assignment routing` |
143
+ | Black-box / hyperparameter opt | east-py-datascience | `Optuna MADS optimize objective` |
144
+ | LP / MIP / routing | east-py-datascience | `GoogleOr vehicle routing constraint` |
145
+ | Conformal / uncertainty | east-py-datascience | `MAPIE conformal NGBoost interval` |
146
+ | East transforms / collections | east | `map filter reduce groupBy toDict` |
147
+ | Variants / pattern match | east | `variant match some none` |
148
+ | e3 pipeline / tasks | e3 | `e3.input e3.task package export dataflow` |
149
+ | Interactive surface over live data | e3-ui | `ui Data.bind commit dataset` |
150
+ | Charts / tables / layout | east-ui | `Chart Line Table Stack layout` |
151
+ | Screenshot / visually verify a surface (CLI) | e3-ui-cli | `shot from-source png doctor` |
152
+
153
+ Always run the searches — the East API is large and idiom-heavy, and grounding the design in real examples beats guessing from type signatures. Nothing is injected for you: search (summaries first), then `get_east_example` for the closest match. Prefer **embedding the actual extract** of the 1–2 closest matches into the design doc; if a search is broad, record the **query** so the implementer reruns it.
154
+
155
+ ## 3. Design — the document
156
+
157
+ Produce a compact design doc (Markdown, shown to the developer — not yet a file unless they ask):
158
+
159
+ ```markdown
160
+ # Design: <goal>
161
+
162
+ ## Decision
163
+ <the decision this improves, in one sentence — or "none: a read-only report">
164
+ How "better" shows up: <what changes when the decision improves>
165
+
166
+ ## Evidence the decision needs
167
+ <the numbers / recommendation the user looks at to decide, and their provenance>
168
+
169
+ ## Project type
170
+ e3 | East — <why> (durability / Python / licensing)
171
+
172
+ ## Data flow (decision ← evidence ← reasoning ← data)
173
+ <source> → <transform/reason> → <evidence> → <decision surface>
174
+ (a short diagram or numbered steps; name each e3 input/task if e3)
175
+
176
+ ## Components
177
+ - <task/function name>: <responsibility> — skill: <skill>
178
+ - ...
179
+
180
+ ## Skills to load
181
+ - east-project (scaffold) → <e3|east>
182
+ - <skill>: <what it's used for>
183
+ - ...
184
+
185
+ ## Grounding examples
186
+ - <capability>: search `<query>` — <1-line note or inline extract>
187
+ - ...
188
+
189
+ ## Build sequence
190
+ 1. east-project: `npm create @elaraai/<e3|east> <name>`
191
+ 2. <implement task X with skill Y>
192
+ 3. ...
193
+ 4. run / verify: <command>
194
+
195
+ ## Open questions / risks
196
+ - <anything unresolved>
197
+ ```
198
+
199
+ Keep it tight. Lead with the decision; the components list maps 1:1 to e3 inputs/tasks (or East functions) so the implementer can start immediately.
200
+
201
+ ## 4. Hand off
202
+
203
+ Once the developer signs off:
204
+ - **east-project** scaffolds the skeleton (`npm create @elaraai/e3` or `@elaraai/east`).
205
+ - The per-package skills implement each component:
206
+ - task/pipeline wiring → **e3**
207
+ - function bodies & types → **east**
208
+ - file/HTTP I/O → **east-node-std**; DB/S3/format I/O → **east-node-io**
209
+ - ML / optimization tasks → **east-py-datascience**
210
+ - decision surfaces and reports → **east-ui** + **e3-ui**
211
+
212
+ ## Worked example
213
+
214
+ > "I have monthly sales spreadsheets in S3 and want a dashboard that forecasts next quarter."
215
+
216
+ Note the decision-first reframe — "a forecast dashboard" on its own has no decision to commit:
217
+
218
+ - **Decision**: how much stock to order per SKU next quarter; "better" = fewer stockouts *and* less overstock.
219
+ - **Evidence**: a per-SKU demand forecast *with uncertainty*, plus a recommended order quantity.
220
+ - **Source**: XLSX in S3 → `east-node-io` (`Storage.S3` + `Format.XLSX`).
221
+ - **Reason**: forecast → `east-py-datascience` (NGBoost for prediction intervals) → Python → **e3**.
222
+ - **Decision surface**: the forecast band + the recommended order, with an operator override → `east-ui` + `e3-ui`.
223
+ - **Execution**: recurring + reactive + Python ⇒ **e3 project** (BSL-1.1).
224
+ - **Searches**: `S3 storage get object`, `XLSX parse rows`, `NGBoost predict interval`, `Chart Band confidence`, `ui Data.bind commit`.
225
+ - **Build**: `npm create @elaraai/e3 reorder-planner` → e3 inputs (S3 config) → ingest task (east-node-io) → forecast task (east-py-datascience) → decision-surface ui task (e3-ui).
226
+
227
+ ## Related skills
228
+
229
+ - **east-project** — scaffolds and runs what this skill designs.
230
+ - **e3** / **east** — the execution engine and language the design targets.
231
+ - **east-node-std** / **east-node-io** — the I/O surface the data-flow questions map to.
232
+ - **east-py-datascience** — ML / optimization components.
233
+ - **east-ui** / **e3-ui** — decision surfaces and output components.