Add entity-component editor teaching example

[concordia-claw]

Provide a runnable roommate simulation for learning Concordia entity-component design through the GUI and CLI. Alice uses standard minimal, Bob uses basic, and Conversation uses dialogic. Their components implement the player entity and game master entity roles assigned by the configured engine. The primary guide explains each concept and teaches matching graphical and typed lessons.

Use the example

From this example branch's checkout, in a Python environment:

python -m pip install -e .
python -m examples.project_editor.run --port 8080 --model-backend none

Open http://127.0.0.1:8080/. Choose minimal · player entity · prefab in Prefab or named preset, press Add instance, set Entity name and Instructions · initial text, add a constant component and Save draft. The prefab uses its registered defaults independently of Alice's settings. Named presets supply their own starting settings; Duplicate copies an entity's edited definition.

With Node.js available, another terminal can attach:

concordia-session --url http://127.0.0.1:8080 interactive --draft design.json

In that prompt, starting with a fresh example draft:

add instance minimal --id Charlie
set Charlie params.name '"Charlie"'
set Charlie params.custom_instructions '"Charlie listens carefully."'
validate
save
inspect Charlie

The complete lesson also adds a component, exports/reopens a design, inspects runtime fields and uses log analysis. GUI and terminal drafts are local to their clients and publish only through explicit Save.

Review map and behavior

The shared picker and CLI catalog include installed standard/contrib prefab classes using stable module/class keys. Configured aliases such as minimal and named presets retain their own defaults. Unsupported extra-component additions fail explicitly; required application-owned objects and engine suitability remain prefab-specific. See the discovery reference.

• examples/project_editor/template.py registers standard prefab factories, named initial settings, prefab creation keys, compatible components and typed references. JSON uses a registered input contract; unsupported files receive field errors. The reference gives recovery steps.
• examples/project_editor/run.py builds previews with NoLanguageModel, configures the shared SimulationServer/ProjectEditor, and binds the selected model only on explicit execution. Run begins with 10 requested steps capped by the saved maximum of 40. The numeric field selects each run's length. Sequential and Simultaneous are registered launcher choices; actual engine identity is shown.
• Model selection uses the standard factory. Together credential precedence is an optional local masked prompt, TOGETHER_API_KEY, then the adapter's TOGETHER_AI_API_KEY fallback. Diagnostics expose source names only. Environment-based operation needs no prompt. See launcher and adapter options.
• Completed runs produce a project definition, structured log and portable log HTML under the selected output directory. Preview/edit/save do not execute the simulation. Runtime dynamic edits use shared component validation at an acknowledged pause boundary; the saved definition and retained runtime remain distinct.
• entity_guide_test.py exercises the visible picker and copied CLI lesson; run_test.py covers launcher/registration contracts and the copied guide.

Dependencies and checks

This draft depends on editor library #314 and independent Together adapter #388. Review the example-specific files under examples/project_editor/; library behavior is reviewed in #314 and adapter behavior in #388. With origin configured as concordia-claw/concordia and both branches fetched,
a focused local comparison uses living branch refs:

git diff origin/feat/editor-project-roundtrip-001 origin/feat/android-project-editor-demo-001 -- examples/project_editor

For the complete example regression suite, run:

python -m pytest -q -n 0 examples/project_editor

It covers registration/building, model-selection validation, sanitized provider-error feedback, run-control integration and GUI/CLI authoring. Focused example verification passes 69 launcher tests plus 2 GUI/CLI guide and action-spec tests, using actual prefab construction with intercepted transports and execution guards. The synced library passes 194 affected tests, with 38 focused catalog tests rerun after final assertions. Scoped formatting/lint/types pass. Hosted code/example/CodeQL checks are distinct from CLA and workflow-security gates.

python -m pytest -q -n 0 examples/project_editor/run_test.py
python -m pytest -q -n 0 examples/project_editor/entity_guide_test.py examples/project_editor/run_action_spec_test.py

Seven mock/no-model Social Deception/State Formation engine regressions also pass. No external provider run is part of this verification. Chromium coverage does not establish physical Android behavior, and a complete asynchronous social-media editor session is not exercised. The command reference documents browser-local presentation, explicit CLI files and viewer framing limits.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.