ea-modeling

Logic: AI + AI Power Tools checks. Mostly AI orchestration over deterministic operations.

What it is for

Use it to build and change model content, from a few elements to hundreds, in your modeling language's vocabulary. You end with model content written in the order EA needs, with each write proven by counting back, reading back or rendering.

ea-modeling is the working method for building and maintaining a Sparx EA repository through the server. The AI loads it whenever it is about to create or change model content: packages, elements, tagged values, connectors, diagrams and class members. It adds no operation of its own. It tells the AI the order to work in, which of several overlapping operations to choose, which behaviors of EA surprise people, and how to prove a write landed.

It exists because EA reports success it has not earned. A call that returns success has written something. It has not necessarily put the element where you meant, applied the stereotype the way EA's profile engine reads it, or drawn a readable diagram. Every pattern in the skill either prevents a known defect or catches one.

The skill covers sixteen topics: pre-flight, the choice between the server and in-process scripting, build order, root-package and name-encoding defects, element creation and stereotype persistence, MDG diagram types, layout, connector rendering, diagram notes, connectors, placement counts, verification, MDG tag rules, idempotency, error recovery, token economy and diagnostics. Class-level modeling, the database schema and custom diagram styling sit in reference files.

Capabilities it uses

When to use it, and when not

Use it for any session that constructs or modifies a repository through the server: loading a catalog, building a model from source documents, adding elements and connectors to an existing model, creating and populating diagrams, adding attributes and operations to classes, or fixing what a build got wrong. The AI loads it after the ea-start-here preflight.

How it works

Not every session needs every step. A request to add one connector starts at step 7 and still uses step 1.

1. Answer from a read, not from memory. (AI Power Tools, AI) Any question about current model state ("does X exist?", "what is in package P?", "what tags does E carry?") is answered from a read made in the current turn. The AI never asserts model state from an earlier turn. It carries identifiers across turns and not names. After a session boundary it re-orients with get_repository_info and a query. If a verification is too expensive, it says so ("created earlier, not re-verified") and does not guess.
2. Pre-flight. AI Power Tools list_root_packages shows every package at the top of the tree, including EA's default "Model" node, so the AI knows the right parent for a top-level package. get_repository_info confirms the project file and EA version. If it fails, EA is not running or the server is not connected, and the AI stops before any write.
3. Choose the method by volume. AI Up to about 30 elements go through the server's bulk operations. Between 30 and 100 either the server or scripting works. Above 100 elements in a one-shot insert, in-process scripting (Specialize, then Scripting, in EA) is faster and costs no AI context. Running that script inside EA is AI with computer use; otherwise you. Verification, gap analysis and refinement always go through the server, and diagram authoring always does. For mixed work, seed with a script and verify and refine through the server.
4. Build in order. (AI + AI Power Tools) Always in this sequence: package hierarchy (parents before children), elements (create, then set all tagged values immediately), connectors, diagrams (create, set the diagram's style, add elements, set the Notes), then verification. Elements come before connectors because a connector needs both of its ends to exist.
5. Create packages and check their stored form. (AI Power Tools, AI) The AI verifies the created package's parent, and for any name containing &, <, > or " it reads the stored name back and corrects it if EA encoded it.
6. Create elements with their tags in the same call. AI Power Tools create_element and the items inside create_elements_bulk accept tagged values, saving a round trip per tag.
7. Create connectors, after confirming both ends exist. (AI chooses, AI Power Tools writes) The AI chooses the connector type and stereotype from the relationship being modeled, then calls create_connector or create_connectors_bulk.
8. Create and populate diagrams. (AI + AI Power Tools) create_diagram_in_language for an MDG diagram type, otherwise create_diagram plus update_diagram to set its style. Then add_elements_to_diagram_bulk, then a layout if wanted, then a Notes sentence as the last step.
9. Verify with counts, then with a picture. (AI + AI Power Tools) Counts, tag reads and connector queries, then a rendered diagram. The AI then looks at EA itself. AI with computer use; otherwise you
10. Recover from interruption by auditing, not rebuilding. (AI + AI Power Tools) After a break the AI reconnects, counts what exists against the specification, and resumes from the first missing item.
11. Manage tokens and sessions. AI Minimal responses, batched verification, summaries and not listings, and one session per build phase.
12. Approve what matters. You You approve the build plan, the mapping of source material to stereotypes and tags, and any delete or restructure.

Navigation diagrams are a separate mechanism. Creating diagrams in the build covers ordinary diagrams. If the diagrams are meant to be click-through drill-downs over a hierarchy, that is ea-navigation-diagrams. After a load that creates elements with parentage, or after any analysis that happens to reveal a hierarchy, the AI checks whether to offer navigation diagrams. It does not make a new call just to look.

Everything runs one at a time. EA drives all of its automation calls through a single thread. Parallel package, element or connector creation races inside EA's package tree and produces intermittent errors. The assistant therefore creates one at a time. Reads can run a few at a time, though sequential is safer. The way to cut latency is a bulk operation (create_elements_bulk, create_connectors_bulk, add_elements_to_diagram_bulk), not parallel single calls.

Root package and package names. The assistant creates the top-level package under an identifier the server reports, checks the stored parent, and fixes it at once if wrong, before any child package is built. The fix is a targeted direct change to the model database, or deleting and recreating a package that has no children. Take the parent from list_root_packages and not from what the stored value looks like: a parent of 0 can be rejected where the "Model" node works. EA can also HTML-encode special characters in a package name on some paths, so Operations & Support can be stored as Operations & Support, which breaks path lookups. The AI reads the stored name back and corrects it with update_package.

Element creation.

Set tagged values inline at creation. One call per element replaces a call per tag, roughly five times fewer round trips for a typical catalog element. create_element_in_language takes no tagged values and rejects them, so the AI tags what it creates with update_element (all tags in one call) or set_tagged_value, both of which are idempotent by tag name.

create_elements_bulk reports how many were created, skipped and failed, and a failure does not abort the batch. Each result carries a status, and a note when a property could not be applied or when the stated type disagrees with what the stereotype or language expects. Westbrook illustration: a Business Application is created in the WBA technology as WBABusinessApplication and then tagged with criticality, lifecycle, businessOwner, technicalOwner, dataClassification and regulatoryScope. You substitute your own technology, stereotypes and tags.

Enumeration values are exact. Mission Critical with a space fails a conformance check where Mission-Critical passes. Owner tags take a team or a role and never a person's name.

Stereotypes are stored in more than one place. This is the most common source of silent failures. EA records a simple stereotype on the element, a fully qualified stereotype for profile-aware tools, and a separate record that applies an MDG profile to the element. The profile record is what EA's technology engine and diagram rendering read. If an element does not render correctly in a technology-aware diagram, the profile was never applied (no record) or the technology was not loaded when the stereotype was applied (a record without the qualified name). The fix is to delete the element and recreate it with the technology loaded, preferably through create_element_in_language. The most common cause of a rejected qualified stereotype is a base metaclass that does not match what the profile expects, and an element's type cannot be changed after creation. For create_element_in_language, pass the registered technology id (for example WBA); the qualified stereotype carries the same prefix, for example WBA::WBABusinessApplication.

Diagrams.

• Technology diagram types. Prefer create_diagram_in_language with a technology id and diagram type. It sets the EA base type and the technology's diagram style in one call. Otherwise create_diagram with the EA base type, then update_diagram to set the style. For example, an ArchiMate Application diagram is a Logical diagram carrying the ArchiMate application style, a BPMN business process is an Analysis diagram carrying the BPMN style, and UML Class and Sequence diagrams are native types needing no style.
• Layout. layout_diagram accepts exactly four styles: Orthogonal, Hierarchical, Circular and Sequence. Anything else returns a structured error that lists the valid styles, and no layout runs. add_elements_to_diagram_bulk lays out automatically by default: if any element is given explicit coordinates, no layout runs and the coordinates are kept. If none is, a layout inferred from the diagram type runs (Sequence for Activity and BPMN, Hierarchical for Logical, Class, Component and Deployment, Circular for State, Orthogonal otherwise), and the response says which. Pass a "no layout" setting to skip it, or a style name to force one, which discards supplied coordinates.
• Why a connector line may not show. A stored presentation entry for a connector styles it; it does not make it visible. EA draws the relationship between two elements on the same diagram with or without one. The entry carries route, color, width, label placement and the hidden flag, and EA's own layout pass writes it. Adding connectors to a diagram is therefore not a repair for a line you cannot see. If a line is missing, check in order: are both ends placed on this diagram (by far the most common cause); does the connector exist with the expected ends; and is it hidden. get_diagram also reports links EA is merely drawing, so do not rely on one field to decide whether a stored entry exists. Query when the answer matters.
• Notes on every diagram. create_diagram and create_diagram_in_language leave Notes empty, and the server does not write one. The AI sets it as the last step, after elements are placed, with one sentence: the type and purpose (why someone would open the diagram), the name only if it adds information, and at least one element the diagram contains. A note written before content exists can only restate the name, and a generic note is worse than an empty field because it looks documented. update_diagram touches only the properties it is given, so an unrelated update never clears an existing note.

Connectors. Illustrative Westbrook choices:

The Westbrook technology (WBA) declares three connector stereotypes: Uses, Flows and realizes, the last in lower case. EA stores a connector's stereotype bare, as Uses, so you write it unqualified. What ties a connector to the technology is a separate record that EA writes when the qualified stereotype (WBA::Uses) is applied, which update_connector does. A connector created with only the bare stereotype can be tied to WBA, to another language that has a stereotype of the same name, or to nothing, so check the binding by reading the connector back. ConsumesService and a capitalized Realizes are not declared by the technology, and EA permits a free-text stereotype on a connector, so a model can carry them. You substitute your own vocabulary. Connector stereotype choice can decide whether a governance rule fires. In the Westbrook example, rule WBA-LFY-001 flags a connector from a Strategic or Current element to a Deprecated one when its stereotype is one of Uses, ConsumesService, Realizes or Flows. The comparison is an exact string match, so a connector stored as realizes does not match Realizes, and in practice the rule checks Uses and Flows. A plain unstereotyped Association does not trigger it either, so use one deliberately for an intentional link to a Deprecated element. The lessons for any rule set are to choose connector stereotypes on purpose, and to keep the spelling a rule matches and the spelling the technology declares the same. The AI always confirms both ends exist before creating a connector. To remove a connector stereotype it clears the property and checks the stereotype is blank.

Counts are recursive. Element counts roll up through a package tree. A shared service used by several capability areas belongs in a top-level or shared package, not inside one area's sub-package, or it inflates every ancestor's count. Before placing, the AI compares the target subtree's count with the expected range. list_package_tree with element counts gives subtree sizes.

Idempotency and error recovery. The AI never assumes the repository is empty. Before creating a package, element or connector it checks for a match by name (or find_elements_by_name, or a connector query on ends and stereotype), and when it finds one it records the existing identifier and skips the create. Bulk operations are idempotent by design, so a re-run reports skipped and not duplicates. If a build is interrupted, the AI reconnects, counts what exists against the specification and resumes from the next uncompleted item. A wrong name is fixed with update_package or update_element. A wrong package parent is fixed as described above. move_element moves an element between packages.

Class-level modeling. Attributes, operations and operation parameters on an existing element are a separate layer with their own identifier rules: create_attribute, list_attributes, update_attribute, delete_attribute, create_operation, list_operations, update_operation, delete_operation and add_parameter. Each member has a small integer identifier and a GUID, and the identifier an update takes differs from the one a delete takes, so guessing fails. Both are in the response of every create and list call. The AI finds an attribute or operation by listing the owning element's members and filtering. Rules the skill teaches:

• A default value is set with the dedicated default input. A fresh create shows an unset default as empty, while a later read shows EA's own placeholder <none>, so a check for "empty" misses it.
• add_parameter is not an upsert. A second call for a name already on the same operation fails, because the server reads the collection back and sees EA ignored the write. To change or remove a parameter, recreate the owning operation, or make a direct change in the database.
• create_element_in_language fails for a stereotype the technology does not declare, and nothing is created. The AI checks the declared stereotypes with get_mdg_from_runtime.
• After any create or update the AI verifies with a query scoped to the one element. A broad unfiltered query once timed out while EA was in use elsewhere.

Direct queries. execute_sql is the most reliable verification tool. EA's schema is inconsistent, and guessing column names is the most common source of errors, so the AI calls describe_table before any non-trivial query. The server also pre-validates a query and suggests the right column name before a round trip to EA. Points that surprise people: some tables name a column differently from their neighbors; there are several stores for tagged values, and reading the wrong one returns nothing and not an error (get_element_tags with cross-references reads all of them); parent columns mean different things in different tables, and the diagram's parent column holds the owning element, which is what the composite-diagram mechanism uses; every package has a mirror element row, so write paths must keep both consistent, which is a reason to prefer the operations for writes; and a stereotype defined by a technology is stored on the element, not in the list of profile stereotypes. execute_sql accepts changing statements by default and reports that a write was performed. A caller can ask for non-reading statements to be refused. A raw write changes the database directly, and EA's open session does not resync until it reloads, so the skill keeps raw writes for reads, analysis and verification, with two exceptions: the package-parent fix and the navigation flag. execute_sql can cap the number of rows returned, which limits the response and not the work EA does.

Custom images and vendor icons. Iconography is two parts: the artwork in EA's Image Manager, and a pointer from each diagram placement to it. Setting one without the other does nothing visible. The assistant adds the image (add_image), points the placed element at it (set_element_image, with an optional label under the picture), and renders with verify_diagram. The element must already be placed on the diagram; add_image needs a local file (.qea or .qeax); only PNG, EMF and WMF are accepted (other raster formats are refused and the conversion is named); success means the pointer is stored and read back, not that the picture renders; and clear_element_image clears one placement and keeps the artwork.

EA ships AWS, Azure, Google Cloud and generic data-platform icon sets in its own installation, thousands of icons. Importing one of those files does not make its icons assignable. Two operations read the libraries in place and download nothing. find_icon searches by name and provider, ranking exact, then normalized, then token, then partial matches, newest vintage first, and reports when the model already holds the icon. set_element_icon reuses the image if the model has it, otherwise loads it (local files only), then sets it, storing it as <provider> <vintage> - <name>, for example AWS v19 - AWS Lambda. The skill's judgment rules: check list_images first; choose the icon, do not match names automatically (a caption is not an icon name, so Amazon S3 output bucket wants Amazon Simple Storage Service (S3)); containers and labels such as Region 1 have no icon; show you candidates when more than one fits; set only the icons the diagram uses, because the full set is tens of megabytes; and say so when a glyph does not exist and never substitute a near miss. An icon larger than 1 MB, the limit add_image applies, is not read from a library; none that EA ships comes close. If find_icon cannot locate the icon folder, it says so, and an environment setting points it there.

Custom Style. set_custom_style and set_custom_styles_bulk control how one placement is drawn: shape, opacity, text alignment, rotation, border style and stacked cards. They work only on placements EA created itself (dragged in the interface, or imported). A placement added through the API lacks the identifier these controls need, so the call reports that and changes nothing. Measured on EA 17.1, about half of the placements in a working model carried the identifier and every API-added one did not. For a generated diagram the AI uses set_diagram_object_appearance for fill, font color, border color and width, size and stacking order, which all work on API-placed elements. The server refuses to invent the identifier on purpose. Leaving a control out leaves it alone, the word "default" resets it, and an unrecognized value is refused.

Illustration: confirming a technology before tagging. The skill carries a short reference showing how an organization verifies its own technology before tagging, using Westbrook as the example. The rule: confirm the technology is loaded before setting tagged values, and know which tags apply to which stereotypes. For Westbrook, six base tags apply to all 15 element stereotypes, and four AI tags apply only to WBAAIGateway, WBAAIService and WBAAIModel. Three further tags, pciScopeJustification, product and vendor, are declared on only some stereotypes, and the three connector stereotypes carry their own tags. The first successful tagged-value response carries the fully qualified tag name, which confirms the tag schema is honored. A customer does not have the Westbrook technology. You substitute your own technology id, stereotypes and tag rules. Confirm the technology is loaded and enabled with get_mdg_from_runtime or ea-mdg-assess, which reads both Locations where a model stores a technology, then confirm tag names and values against its definition. The Westbrook demonstration also defines a pre-demo state with no AI Gateway or AI Service elements. That belongs to the demo fixture and is not guidance for a customer model.

Token and session management. Context, not time, exhausts a session. Mutating calls return a minimal result unless full detail is requested. The AI verifies in batch with one query rather than looping get_element, and prefers summarize_stereotype_usage, summarize_connector_patterns and summarize_tagged_value_usage over assembling summaries from lists. list_elements_in_package returns only the identifier, GUID and name by default. The bulk path saves about 95 percent of round-trip overhead for catalog work. Large builds are split one session per phase, each opened with a targeted count and not "work out the state of the repository", with a build plan requested before any call. At a usage limit the AI finishes the current operation, captures state with one query, clears the conversation, and restarts from three to five lines of state. Approximate costs: 10 specs through create_elements_bulk about 800 to 1,200 tokens; the same ten as single calls about 3,000 to 5,000; a default listing of 50 elements about 400 to 800, and 8,000 to 15,000 with full detail; a ten-row query about 300 to 600. These are approximations, not a budget. By task: bulk authoring from a defined specification suits a small model (or a script); verification and gap analysis suit a mid-tier model; designing a new MDG Technology or other open-ended trade-offs suits the strongest.

Verify in EA's interface. AI with computer use; otherwise you EA reports a failed operation as a modal dialog that holds the automation connection, and no response shows it. If a call appears to hang, the AI looks at EA's screen, reads the dialog and uses its message to correct the call before concluding anything. Dialogs stack, so it dismisses them from the front. Windows reporting EA as "Responding" means nothing. After any diagram create or edit, the AI reloads the diagram and looks at it. Without computer use it says so: you take a screenshot of the dialog and paste it into the conversation so the AI can analyze it, then you dismiss the dialog so processing can continue, and you look at the diagram and say what you see. It never reports a hang it has not diagnosed or a diagram it has not seen. When driving EA directly, it waits 2 to 5 seconds after a menu click and up to 15 seconds after opening a .qea, and does not retry until it has confirmed the earlier action failed. See Shared references.

Diagnostics mode. Opt-in. With EA_MCP_DIAGNOSTICS=1 in the server's environment, a failing, erroring or timed-out call writes a Markdown report with the call's inputs, the stack trace, EA build information and the last 25 calls. On a failure or hang the AI stops, asks for diagnostics to be enabled, reproduces, and you review the report and email it to help@novocircle.com. get_repository_info reports whether diagnostics is active. See ea-diagnostic and Diagnostics.

What you get

• Packages, elements, tagged values, connectors, diagrams and class members built in the right order, with identifiers reported back.
• A count-back against your specification, a sample read-back of tags, and a rendered diagram with a specific Notes sentence.
• Stated checks: what was verified and what was not.

Tools it relies on

• Packages (Packages): list_root_packages, create_package, update_package, list_package_tree, find_packages_by_name, duplicate_package.
• Elements (Elements): create_element, create_element_in_language, create_elements_bulk, update_element, get_element, find_elements_by_name, list_elements_in_package, move_element.
• Connectors (Connectors): create_connector, create_connectors_bulk, update_connector, list_connectors_for_element, get_connectors_for_element_filtered.
• Class members (Class members): attribute, operation and parameter operations.
• Tagged values (Tagged values): set_tagged_value, get_element_tags, list_tagged_values, delete_tagged_value, and the connector tag operations.
• Diagrams (Creating and finding diagrams, Opening and laying out, Placing elements and connectors, Verifying a diagram): creation, population, layout, rendering and verification.
• Appearance, images and icons (Element appearance, Custom style, Custom images, Vendor icon libraries): per-placement appearance, add_image, list_images, set_element_image, clear_element_image, find_icon, set_element_icon.
• Verification and summaries (Summaries, Direct queries): execute_sql, describe_table, list_ea_tables, and the summarize_* operations.
• get_repository_info (Project) and get_mdg_from_runtime (Discovering technologies).
• Server modules: the SQL guard and schema catalog (SQL guard), diagnostics (Diagnostics) and the icon library reader (Icon library reader).
• Shared references: westbrook-example.md, latency.md and ea-ui-verification.md.

Sample prompts

1. "Create a package called Payments under the Westbrook Bank root and add three Business Application elements: Payment Gateway, Customer Portal and ACH Return Handler. Tag each with criticality and lifecycle." Pre-flight, one package create with a parent check, one bulk create with inline tags, then a count-back.
2. "Add a Uses connector from Customer Portal to Payment Gateway, and show both on a new application diagram." Verifies both ends exist, creates the connector, creates the diagram, places both elements, sets a Notes sentence, and renders it.
3. "Load this spreadsheet of 120 capabilities into Westbrook Bank as elements with a lifecycle tag, and tell me when to stop and verify." Volume decision (server bulk against scripting), phased load, a count-back against the 120 rows, and at the end a check on whether to offer navigation diagrams.
4. "Create a class called CustomerRiskProfile with attributes assetId and riskScore, and an operation validate that returns Boolean with a strict parameter." Creates the class, then attributes, operation and parameter, using the right identifiers and reading the members back.
5. "Some of the Westbrook elements I created last week don't render with the application stereotype in the diagram. Find out why." Checks the profile application on each element, reports which were created before the technology was loaded, and proposes delete and recreate.
6. "Put the AWS Lambda and S3 icons on the data-pipeline diagram, only on the elements that really are those services." Reads the placed elements, runs find_icon per concept, shows candidates where more than one fits, sets only the icons the diagram uses, and renders the result.

Recommended models

Ratings are guidance based on the kind of reasoning the skill needs, not measured benchmarks.

Checking accuracy and completeness

1. Count back. After a load, compare counts with the specification: a count per package subtree, and the created, skipped and failed totals from each bulk call. Correct: counts match and failed is zero. Red flag: a nonzero skipped count on a first run, which means elements with those names already existed.
2. Tag coverage, by populated value. Run summarize_tagged_value_usage scoped to the stereotype. Correct: the populated count equals the element count for every required tag. The plain count means rows present, because EA creates the row when a stereotype is applied whether or not it is filled in. Red flag: a high count and a populated count of zero.
3. Stereotype binding. summarize_stereotype_usage shows each stereotype as bound to a profile (healthy) or ad hoc (the string is not tied to a profile). Cross-check one element for a profile record with a qualified name, and run summarize_observed_metaclasses for the stereotype. Correct: not heterogeneous.
4. Connector completeness. For each specified relationship, list_connectors_for_element or a connector query on both ends and stereotype returns exactly one result. Red flag: two connectors with the same ends and stereotype (a retry without idempotency), or none.
5. Diagram fidelity. verify_diagram reloads and renders and returns placed geometry. Correct: every specified element is placed, the Notes field is non-empty and specific, and the picture is readable with no clipped names. Compare the number of placements with the intended element count. Never accept a success response alone.
6. Name and parent integrity. Read the stored package names: no &. The root package's parent matches the intended parent.
7. Idempotence. Re-run the same bulk specification. Correct: nothing created, every item skipped.
8. Fresh-turn rule. In a long session, ask the AI about a specific element's state. Correct: the answer is preceded by a read in that turn.

Limitations

• Raw writes can leave EA stale. execute_sql permits writes by default, and a write changes the database directly. EA's open session does not resync until it reloads. The skill confines raw writes to the package-parent fix and the navigation flag.
• add_image and the library load inside set_element_icon need a local file (.qea or .qeax). On a server connection or a cloud connection, load artwork through EA's Image Manager AI with computer use; otherwise you and use set_element_image.
• Custom Style does not reach API-placed elements. The limit is in the API route, because placements EA created itself carry the identifier these controls need. Use set_diagram_object_appearance.
• Suppressing connectors while placing is not absolute. add_elements_to_diagram_bulk with connectors turned off does not fully suppress connector drawing: EA's own layout pass can write presentation entries for connectors between placed elements, and EA still draws a relationship between two placed elements regardless. Pass "no layout" to guarantee no stored entry, then lay out separately if you need both. The call warns when entries survive.
• A package move, and a parameter update or delete, are done by a direct change or a recreate.
• A write EA rejects can be reported as success at some call sites. Verify every write by reading it back.
• Identifier schemes differ between updates and deletes for attributes and operations.
• Technology load state is session-scoped. Loaded is not enabled: EA reports a technology disabled in Manage Technology as loaded. The state of an embedded technology is best established with get_mdg_from_runtime, which reports a disabled one as registered but not enabled, or with ea-mdg-assess, and not by querying the model's own records.
• Verify the profile binding after the first element of a new kind. Whether a plain create carrying a technology's stereotype binds the profile depends on the technology being loaded at that moment. Check the profile record on the first element you create.
• Rule ids and the demo state in the skill are Westbrook-specific. WBA-LFY-001, the pre-demo and post-demo states and the exact-count expectations are the demo fixture, illustrations of a technique and not requirements.
• Windows only, EA running. The server attaches to a running EA over COM. Starting EA and opening the model is a separate step, described in ea-start-here.