sim-cli-core 0.3.6__tar.gz → 0.3.7__tar.gz

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.
Files changed (131) hide show
  1. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/CLAUDE.md +2 -2
  2. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/PKG-INFO +48 -100
  3. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/README.md +47 -99
  4. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/docs/DEVELOPMENT.md +5 -3
  5. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/docs/agent-readability.md +8 -7
  6. sim_cli_core-0.3.7/docs/architecture/skills-layering-plan.md +68 -0
  7. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/docs/architecture/version-compat.md +7 -7
  8. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/docs/plugin-install.md +19 -21
  9. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/pyproject.toml +1 -1
  10. sim_cli_core-0.3.7/src/sim/_plugin_install.py +172 -0
  11. sim_cli_core-0.3.7/src/sim/_skills/sim-cli/SKILL.md +94 -0
  12. sim_cli_core-0.3.7/src/sim/_skills/sim-cli/gui/SKILL.md +239 -0
  13. sim_cli_core-0.3.7/src/sim/_skills/sim-cli/gui/snippets/dismiss_named_dialog.py +19 -0
  14. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/cli.py +36 -78
  15. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/compat.py +13 -16
  16. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/describe.py +10 -23
  17. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/driver.py +1 -1
  18. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/gui/__init__.py +1 -1
  19. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/inspect.py +2 -2
  20. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/plugins.py +37 -21
  21. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/server.py +1 -1
  22. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_compat.py +2 -3
  23. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_describe.py +8 -1
  24. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_init_setup.py +3 -2
  25. sim_cli_core-0.3.7/tests/base/test_plugin_install.py +92 -0
  26. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_plugins.py +5 -4
  27. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/gui/test_connect_tools_field.py +1 -1
  28. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/uv.lock +1 -1
  29. sim_cli_core-0.3.6/docs/architecture/skills-layering-plan.md +0 -306
  30. sim_cli_core-0.3.6/src/sim/_plugin_install.py +0 -352
  31. sim_cli_core-0.3.6/tests/base/test_plugin_install.py +0 -248
  32. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/.github/workflows/publish.yml +0 -0
  33. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/.gitignore +0 -0
  34. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/CONTRIBUTING.md +0 -0
  35. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/LICENSE +0 -0
  36. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/NOTICE +0 -0
  37. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/assets/architecture.svg +0 -0
  38. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/assets/banner.svg +0 -0
  39. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/assets/logo.svg +0 -0
  40. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/docs/architecture/multi-session-and-config.md +0 -0
  41. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/__init__.py +0 -0
  42. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/__main__.py +0 -0
  43. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/_timeout.py +0 -0
  44. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/config.py +0 -0
  45. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/drivers/__init__.py +0 -0
  46. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/gui/LICENSES/ATTRIBUTION.md +0 -0
  47. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/gui/_pywinauto_tools.py +0 -0
  48. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/gui/_win32_dialog.py +0 -0
  49. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/history.py +0 -0
  50. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/runner.py +0 -0
  51. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/session.py +0 -0
  52. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/testing/__init__.py +0 -0
  53. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/src/sim/testing/protocol_conformance.py +0 -0
  54. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/__init__.py +0 -0
  55. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/__init__.py +0 -0
  56. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_cli.py +0 -0
  57. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_config.py +0 -0
  58. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_connect.py +0 -0
  59. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_driver_discovery.py +0 -0
  60. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_history.py +0 -0
  61. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_lint.py +0 -0
  62. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_lint_public_corpus.py +0 -0
  63. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_logs.py +0 -0
  64. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_multi_session.py +0 -0
  65. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_protocol_conformance.py +0 -0
  66. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_python_floor_audit.py +0 -0
  67. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/base/test_run.py +0 -0
  68. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/conftest.py +0 -0
  69. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/drivers/__init__.py +0 -0
  70. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/execution/calculix_e2e_cantilever_run.py +0 -0
  71. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/execution/coolprop/water_props.py +0 -0
  72. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/execution/elmer_e2e_heat_square.py +0 -0
  73. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/execution/gmsh_e2e_sphere_mesh.py +0 -0
  74. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/execution/lammps_e2e_lj_nvt.py +0 -0
  75. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/execution/meshio_e2e_gmsh_to_vtk.py +0 -0
  76. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/execution/pymfem_e2e_poisson.py +0 -0
  77. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/execution/pyvista_e2e_sphere_stats.py +0 -0
  78. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/execution/scikit_fem_e2e_poisson.py +0 -0
  79. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/execution/scikitrf/short_load.py +0 -0
  80. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/execution/su2_e2e_inviscid_bump.py +0 -0
  81. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/comsol/comsol_good.py +0 -0
  82. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/comsol/comsol_no_client.py +0 -0
  83. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/comsol/comsol_no_import.py +0 -0
  84. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/hypermesh_good.py +0 -0
  85. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/hypermesh_gui.py +0 -0
  86. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/hypermesh_no_import.py +0 -0
  87. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/hypermesh_no_usage.py +0 -0
  88. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/hypermesh_syntax_error.py +0 -0
  89. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/isaac/bad_import_order.py +0 -0
  90. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/isaac/bad_no_close.py +0 -0
  91. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/isaac/bad_no_simapp.py +0 -0
  92. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/isaac/hello_world.py +0 -0
  93. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/isaac/import_franka.py +0 -0
  94. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/isaac/not_isaac.py +0 -0
  95. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/isaac/official_hello_world.py +0 -0
  96. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/isaac/replicator_cubes.py +0 -0
  97. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/isaac/syntax_error.py +0 -0
  98. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/isaac/warehouse_sdg.py +0 -0
  99. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/matlab/empty_model.mdl +0 -0
  100. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/matlab/empty_model.slx +0 -0
  101. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/matlab/matlab_ok.m +0 -0
  102. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/mfem_good.py +0 -0
  103. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/mfem_no_import.py +0 -0
  104. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/mfem_no_mesh.py +0 -0
  105. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/mfem_syntax_error.py +0 -0
  106. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/mock_fail.py +0 -0
  107. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/mock_solver.py +0 -0
  108. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/newton/basic_pendulum.json +0 -0
  109. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/newton/cable_twist.py +0 -0
  110. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/newton/robot_g1.json +0 -0
  111. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/not_simulation.py +0 -0
  112. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/pybamm/pybamm_bad_import.py +0 -0
  113. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/pybamm/pybamm_crate_sweep.py +0 -0
  114. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/pybamm/pybamm_no_solve.py +0 -0
  115. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/pybamm/pybamm_spm_good.py +0 -0
  116. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/skfem_good.py +0 -0
  117. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/skfem_no_import.py +0 -0
  118. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/skfem_no_solve.py +0 -0
  119. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/fixtures/skfem_syntax_error.py +0 -0
  120. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/gui/__init__.py +0 -0
  121. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/gui/test_gui_facade.py +0 -0
  122. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/inspect/__init__.py +0 -0
  123. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/inspect/_extract_comsol_Tmax.py +0 -0
  124. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/inspect/test_channel_3_4_5_9.py +0 -0
  125. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/inspect/test_gui_probes.py +0 -0
  126. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/inspect/test_inspect_types.py +0 -0
  127. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/inspect/test_probes.py +0 -0
  128. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tests/inspect/test_snippet_timeout.py +0 -0
  129. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tools/audit_python_floor.py +0 -0
  130. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tools/extract_driver.py +0 -0
  131. {sim_cli_core-0.3.6 → sim_cli_core-0.3.7}/tools/lint-public-corpus.py +0 -0
@@ -11,7 +11,7 @@ The runtime supports two execution modes:
11
11
  - **One-shot** (`sim run script --solver=X`): subprocess execution, result stored as a numbered run, `sim logs` to browse.
12
12
  - **Persistent session** (`sim serve` + `sim connect/exec/inspect/disconnect`): a long-lived HTTP server holds a live solver session; agents send code snippets and inspect state without restarting the solver.
13
13
 
14
- The companion repo `sim-skills/` contains per-solver agent skills, reference docs, demo workflows, and integration tests that drive this runtime.
14
+ The shared runtime skill is bundled at `src/sim/_skills/sim-cli/` and synced into agent skill directories by `sim plugin sync-skills`. Per-solver agent skills ship inside their own `sim-plugin-<solver>` packages.
15
15
 
16
16
  ## Commands
17
17
 
@@ -137,7 +137,7 @@ Solver plugin tests live in their own plugin repos. Tests in this repo cover the
137
137
  - Global run history lives in `~/.sim/history.jsonl` (append-only; override dir via `SIM_HOME`); git-ignored
138
138
  - The server supports multiple concurrent sessions keyed by `X-Sim-Session` header; a solver name can only be live once per server process (driver instances are module-level singletons)
139
139
  - Project uses `uv` for dependency locking (`uv.lock`)
140
- - Companion knowledge / skills / workflows live in the sibling `sim-skills/` tree, one folder per solver
140
+ - The shared runtime skill lives at `src/sim/_skills/sim-cli/`; per-solver skills ship in their `sim-plugin-<solver>` packages (synced via `sim plugin sync-skills`)
141
141
 
142
142
  ## Releases
143
143
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: sim-cli-core
3
- Version: 0.3.6
3
+ Version: 0.3.7
4
4
  Summary: Make every engineering tool agent-native — a CLI runtime that lets LLM agents launch, drive, and observe CAD/CAE software
5
5
  Project-URL: Homepage, https://github.com/svd-ai-lab/sim-cli
6
6
  Project-URL: Repository, https://github.com/svd-ai-lab/sim-cli
@@ -79,7 +79,7 @@ engineering review.
79
79
  `sim` is for agents and people trying to get real simulation work done.
80
80
 
81
81
  - **CAE engineers who already script solvers** and want an agent to help
82
- automate COMSOL, Fluent, MATLAB, LTspice, Abaqus, HFSS, and similar tools
82
+ automate COMSOL, Abaqus, HFSS, Fluent, MATLAB, LTspice, and similar tools
83
83
  without losing inspection and recovery between steps.
84
84
  - **Design engineers and occasional simulation users** who have agent
85
85
  experience and want an agent-assisted workflow: ask for a simulation, watch
@@ -97,12 +97,10 @@ Plugin authoring, runtime internals, and driver protocol details live in
97
97
  LLMs can often write solver scripts, but a one-shot script is a weak workflow:
98
98
  it hides intermediate state, fails late, and makes recovery difficult.
99
99
 
100
- `sim` gives an agent a small, repeatable control surface:
101
-
102
- ```text
103
- check readiness → attach to live session → inspect model state
104
- → run one bounded CAE step → verify result/state → save checkpoint/artifacts
105
- ```
100
+ `sim` gives an agent a small, repeatable control surface — detect the
101
+ environment, attach to a live session, inspect state, run one bounded step,
102
+ verify, and checkpoint. See [The agent loop](#the-agent-loop) for the full
103
+ sequence.
106
104
 
107
105
  A bounded CAE step is one small modeling, meshing, solving, or postprocessing
108
106
  action that can be inspected and verified before continuing. Examples: create a
@@ -149,24 +147,19 @@ uv run sim check comsol
149
147
  uv run sim plugin doctor comsol --deep
150
148
  ```
151
149
 
152
- Use `.agents/skills` for Codex and GitHub Copilot projects. For Claude Code,
153
- sync to `.claude/skills` instead:
154
-
155
- ```bash
156
- uv run sim plugin sync-skills --target .claude/skills --copy
157
- ```
150
+ The `sync-skills` target depends on your agent: use `.agents/skills` for Codex
151
+ and GitHub Copilot, or `.claude/skills` for Claude Code. Substitute that path in
152
+ any `sync-skills` command shown below.
158
153
 
159
154
  ### Without uv
160
155
 
161
156
  If you cannot use `uv`, create a normal Python virtual environment, install
162
157
  `sim-cli-core` and the solver plugin into that environment, then run `sim`
163
- from the activated environment.
164
-
165
- macOS/Linux:
158
+ from the activated environment:
166
159
 
167
160
  ```bash
168
161
  python -m venv .venv
169
- source .venv/bin/activate
162
+ source .venv/bin/activate # Windows PowerShell: .\.venv\Scripts\Activate.ps1
170
163
  python -m pip install --upgrade pip
171
164
  python -m pip install sim-cli-core sim-plugin-comsol
172
165
  sim plugin sync-skills --target .agents/skills --copy
@@ -174,89 +167,56 @@ sim check comsol
174
167
  sim plugin doctor comsol --deep
175
168
  ```
176
169
 
177
- Windows PowerShell:
170
+ ## Hand the task to your agent
178
171
 
179
- ```powershell
180
- py -m venv .venv
181
- .\.venv\Scripts\Activate.ps1
182
- python -m pip install --upgrade pip
183
- python -m pip install sim-cli-core sim-plugin-comsol
184
- sim plugin sync-skills --target .agents/skills --copy
185
- sim check comsol
186
- sim plugin doctor comsol --deep
187
- ```
172
+ After setup, give your agent the **engineering goal in plain language** — the
173
+ simulation you want and the quantity you want reported. You do not need to
174
+ recite the operating loop: the bundled solver skill already enforces the
175
+ inspect / verify / checkpoint discipline once the agent loads it.
188
176
 
189
- ## Hand this prompt to your agent
177
+ Two things are still worth telling the agent explicitly:
190
178
 
191
- After setup, give your coding agent a direct instruction like this:
179
+ - Run `sim` through this project with `uv run sim ...` so it sees the project's
180
+ installed plugins.
181
+ - Don't guess solver API names — inspect the live model or the solver's local
182
+ docs first. If you change something manually in the solver GUI, ask the agent
183
+ to re-inspect live state before continuing.
192
184
 
193
- ```text
194
- Use the installed solver skill. Run sim through this project with
195
- `uv run sim ...`. Check my local solver installation before connecting. Work
196
- one bounded step at a time: connect, inspect the session, execute a small step,
197
- inspect last.result and the live model state, then save or update a checkpoint
198
- before continuing. Do not guess solver API names; inspect the live model or the
199
- solver's local docs first. If I make manual changes in the solver UI,
200
- re-inspect the live state before continuing instead of assuming your previous
201
- script still matches the model. Report saved artifacts, numerical checks,
202
- warnings, and anything that still needs human engineering review.
203
- ```
185
+ A concrete example follows below.
204
186
 
205
187
  ## Example: COMSOL and Codex on one machine
206
188
 
207
- If COMSOL and Codex are on the same machine, start by installing the COMSOL
208
- plugin and syncing its bundled skill into the `.agents/skills` project target:
209
-
210
- ```bash
211
- uv add sim-cli-core sim-plugin-comsol
212
- uv run sim plugin sync-skills --target .agents/skills --copy
213
- uv run sim check comsol
214
- uv run sim plugin doctor comsol --deep
215
- ```
216
-
217
- Then ask Codex:
189
+ Follow [Quick Start](#quick-start-agent-setup) to install `sim-cli-core` and
190
+ `sim-plugin-comsol` and sync the skill — those commands already use COMSOL.
191
+ Then ask Codex for the actual task:
218
192
 
219
193
  ```text
220
- Use the installed COMSOL skill. Start by checking COMSOL through `uv run sim
221
- check comsol`. If you need a visible live COMSOL Desktop session, use:
222
-
223
- uv run sim connect --solver comsol --ui-mode gui --driver-option visual_mode=shared-desktop
224
-
225
- After connecting, inspect session.health and comsol.model.identity. Confirm the
226
- live model binding is healthy before treating the GUI as synchronized. For
227
- non-trivial work, establish a case folder and save .mph checkpoints after major
228
- layers. Build and solve one bounded step at a time.
194
+ Simulate the natural-convection cooling of attached `pcb.mph` and report the
195
+ maximum junction temperature. Use the installed COMSOL skill. Check COMSOL with
196
+ `uv run sim check comsol` first. If you need a visible live COMSOL Desktop
197
+ session, connect with `--ui-mode gui`.
229
198
  ```
230
199
 
200
+ The prompt names a goal and a quantity to report — not a list of `sim`
201
+ sub-steps. The COMSOL skill supplies the rest: session health and model
202
+ identity checks, checkpoint policy, and step-by-step build/solve discipline.
203
+
231
204
  For COMSOL-specific details such as shared Desktop mode, offline `.mph`
232
205
  inspection, Desktop attach fallback, model identity checks, and checkpoint
233
206
  policy, follow the bundled COMSOL skill.
234
207
 
235
208
  ## Why CLI-first?
236
209
 
237
- sim-cli is CLI-first because engineering simulation is file-based,
238
- scriptable, local, artifact-heavy, and long-running.
239
-
240
- CAE agents need to work with solver executables, model files,
241
- Python/Java/journal scripts, shell commands, logs, checkpoints, plots,
242
- and artifacts. A CLI command surface composes with all of that and
243
- matches how Codex CLI, Claude Code, and other coding agents already
244
- operate.
210
+ Engineering simulation is file-based, scriptable, local, artifact-heavy, and
211
+ long-running. CAE agents work with solver executables, model files,
212
+ Python/Java/journal scripts, shell commands, logs, checkpoints, and plots — a
213
+ CLI command surface composes with all of that and matches how Codex CLI, Claude
214
+ Code, and other coding agents already operate.
245
215
 
246
- MCP is useful for API-style integrations and remote tool discovery,
247
- but a broad MCP surface can add context overhead and wrapper
248
- maintenance. For COMSOL, Abaqus, Ansys Workbench, OpenFOAM, LTspice,
249
- and similar solvers, sim-cli keeps the source of truth as a small,
250
- auditable command loop:
251
-
252
- ```text
253
- check readiness → attach to live session → inspect model state
254
- → run one bounded CAE step → verify result/state → save checkpoint/artifacts
255
- ```
256
-
257
- Solver plugins provide solver-specific behavior. Agent skills teach
258
- Codex, Claude Code, and other agents when and how to use the CLI
259
- safely.
216
+ MCP is useful for API-style integrations and remote tool discovery, but a broad
217
+ MCP surface adds context overhead and wrapper maintenance. For COMSOL, Abaqus,
218
+ Ansys Workbench, OpenFOAM, LTspice, and similar solvers, sim-cli keeps the
219
+ source of truth as a small, auditable command loop.
260
220
 
261
221
  ## The agent loop
262
222
 
@@ -329,18 +289,12 @@ solver can be reached:
329
289
 
330
290
  ```bash
331
291
  uv run sim plugin list
332
-
333
- # Codex or Copilot
334
- uv run sim plugin sync-skills --target .agents/skills --copy
335
-
336
- # Claude Code
337
- uv run sim plugin sync-skills --target .claude/skills --copy
338
-
292
+ uv run sim plugin sync-skills --target .agents/skills --copy # or .claude/skills for Claude Code
339
293
  uv run sim check <solver>
340
294
  uv run sim plugin doctor <solver> --deep
341
295
  ```
342
296
 
343
- For direct wheel, Git, local checkout, or non-uv workflows, see
297
+ For direct wheel, Git, local checkout, or non-uv package workflows, see
344
298
  [docs/plugin-install.md](docs/plugin-install.md).
345
299
 
346
300
  ## Project setup with sim.toml
@@ -369,12 +323,7 @@ Then a fresh checkout can run:
369
323
  ```bash
370
324
  uv sync
371
325
  uv run sim setup --dry-run
372
-
373
- # Codex or Copilot
374
- uv run sim plugin sync-skills --target .agents/skills --copy
375
-
376
- # Claude Code
377
- uv run sim plugin sync-skills --target .claude/skills --copy
326
+ uv run sim plugin sync-skills --target .agents/skills --copy # or .claude/skills for Claude Code
378
327
  ```
379
328
 
380
329
  ## Common commands
@@ -384,15 +333,14 @@ uv run sim plugin sync-skills --target .claude/skills --copy
384
333
  | `uv run sim plugin list` | Show plugins visible in this project environment. |
385
334
  | `uv run sim plugin info <solver>` | Show plugin metadata and compatibility summary. |
386
335
  | `uv run sim plugin doctor <solver> --deep` | Check plugin wiring plus local solver detection. |
387
- | `uv run sim plugin sync-skills --target .agents/skills --copy` | Materialize installed plugin skills for Codex or Copilot. |
388
- | `uv run sim plugin sync-skills --target .claude/skills --copy` | Materialize installed plugin skills for Claude Code. |
336
+ | `uv run sim plugin sync-skills --target .agents/skills --copy` | Materialize installed plugin skills for your agent (`.claude/skills` for Claude Code). |
389
337
  | `uv run sim check <solver>` | Detect local or remote solver installs. |
390
338
  | `uv run sim connect --solver <solver>` | Open a persistent solver session. |
391
339
  | `uv run sim exec --file step.py` | Run one bounded step in the live session. |
392
340
  | `uv run sim inspect <target>` | Query session, result, or solver-specific state. |
393
341
  | `uv run sim run script.py --solver <solver>` | Run a deterministic one-shot script. |
394
342
  | `uv run sim disconnect` | Tear down the active session. |
395
- | `uv run sim setup` | Apply plugin declarations from `sim.toml` when you use them. |
343
+ | `uv run sim setup` | Validate `sim.toml` and report declared plugin package specs. |
396
344
 
397
345
  Run `uv run sim describe` for a machine-readable command manifest, or
398
346
  `uv run sim <command> --help` for exact options.
@@ -38,7 +38,7 @@ engineering review.
38
38
  `sim` is for agents and people trying to get real simulation work done.
39
39
 
40
40
  - **CAE engineers who already script solvers** and want an agent to help
41
- automate COMSOL, Fluent, MATLAB, LTspice, Abaqus, HFSS, and similar tools
41
+ automate COMSOL, Abaqus, HFSS, Fluent, MATLAB, LTspice, and similar tools
42
42
  without losing inspection and recovery between steps.
43
43
  - **Design engineers and occasional simulation users** who have agent
44
44
  experience and want an agent-assisted workflow: ask for a simulation, watch
@@ -56,12 +56,10 @@ Plugin authoring, runtime internals, and driver protocol details live in
56
56
  LLMs can often write solver scripts, but a one-shot script is a weak workflow:
57
57
  it hides intermediate state, fails late, and makes recovery difficult.
58
58
 
59
- `sim` gives an agent a small, repeatable control surface:
60
-
61
- ```text
62
- check readiness → attach to live session → inspect model state
63
- → run one bounded CAE step → verify result/state → save checkpoint/artifacts
64
- ```
59
+ `sim` gives an agent a small, repeatable control surface — detect the
60
+ environment, attach to a live session, inspect state, run one bounded step,
61
+ verify, and checkpoint. See [The agent loop](#the-agent-loop) for the full
62
+ sequence.
65
63
 
66
64
  A bounded CAE step is one small modeling, meshing, solving, or postprocessing
67
65
  action that can be inspected and verified before continuing. Examples: create a
@@ -108,24 +106,19 @@ uv run sim check comsol
108
106
  uv run sim plugin doctor comsol --deep
109
107
  ```
110
108
 
111
- Use `.agents/skills` for Codex and GitHub Copilot projects. For Claude Code,
112
- sync to `.claude/skills` instead:
113
-
114
- ```bash
115
- uv run sim plugin sync-skills --target .claude/skills --copy
116
- ```
109
+ The `sync-skills` target depends on your agent: use `.agents/skills` for Codex
110
+ and GitHub Copilot, or `.claude/skills` for Claude Code. Substitute that path in
111
+ any `sync-skills` command shown below.
117
112
 
118
113
  ### Without uv
119
114
 
120
115
  If you cannot use `uv`, create a normal Python virtual environment, install
121
116
  `sim-cli-core` and the solver plugin into that environment, then run `sim`
122
- from the activated environment.
123
-
124
- macOS/Linux:
117
+ from the activated environment:
125
118
 
126
119
  ```bash
127
120
  python -m venv .venv
128
- source .venv/bin/activate
121
+ source .venv/bin/activate # Windows PowerShell: .\.venv\Scripts\Activate.ps1
129
122
  python -m pip install --upgrade pip
130
123
  python -m pip install sim-cli-core sim-plugin-comsol
131
124
  sim plugin sync-skills --target .agents/skills --copy
@@ -133,89 +126,56 @@ sim check comsol
133
126
  sim plugin doctor comsol --deep
134
127
  ```
135
128
 
136
- Windows PowerShell:
129
+ ## Hand the task to your agent
137
130
 
138
- ```powershell
139
- py -m venv .venv
140
- .\.venv\Scripts\Activate.ps1
141
- python -m pip install --upgrade pip
142
- python -m pip install sim-cli-core sim-plugin-comsol
143
- sim plugin sync-skills --target .agents/skills --copy
144
- sim check comsol
145
- sim plugin doctor comsol --deep
146
- ```
131
+ After setup, give your agent the **engineering goal in plain language** — the
132
+ simulation you want and the quantity you want reported. You do not need to
133
+ recite the operating loop: the bundled solver skill already enforces the
134
+ inspect / verify / checkpoint discipline once the agent loads it.
147
135
 
148
- ## Hand this prompt to your agent
136
+ Two things are still worth telling the agent explicitly:
149
137
 
150
- After setup, give your coding agent a direct instruction like this:
138
+ - Run `sim` through this project with `uv run sim ...` so it sees the project's
139
+ installed plugins.
140
+ - Don't guess solver API names — inspect the live model or the solver's local
141
+ docs first. If you change something manually in the solver GUI, ask the agent
142
+ to re-inspect live state before continuing.
151
143
 
152
- ```text
153
- Use the installed solver skill. Run sim through this project with
154
- `uv run sim ...`. Check my local solver installation before connecting. Work
155
- one bounded step at a time: connect, inspect the session, execute a small step,
156
- inspect last.result and the live model state, then save or update a checkpoint
157
- before continuing. Do not guess solver API names; inspect the live model or the
158
- solver's local docs first. If I make manual changes in the solver UI,
159
- re-inspect the live state before continuing instead of assuming your previous
160
- script still matches the model. Report saved artifacts, numerical checks,
161
- warnings, and anything that still needs human engineering review.
162
- ```
144
+ A concrete example follows below.
163
145
 
164
146
  ## Example: COMSOL and Codex on one machine
165
147
 
166
- If COMSOL and Codex are on the same machine, start by installing the COMSOL
167
- plugin and syncing its bundled skill into the `.agents/skills` project target:
168
-
169
- ```bash
170
- uv add sim-cli-core sim-plugin-comsol
171
- uv run sim plugin sync-skills --target .agents/skills --copy
172
- uv run sim check comsol
173
- uv run sim plugin doctor comsol --deep
174
- ```
175
-
176
- Then ask Codex:
148
+ Follow [Quick Start](#quick-start-agent-setup) to install `sim-cli-core` and
149
+ `sim-plugin-comsol` and sync the skill — those commands already use COMSOL.
150
+ Then ask Codex for the actual task:
177
151
 
178
152
  ```text
179
- Use the installed COMSOL skill. Start by checking COMSOL through `uv run sim
180
- check comsol`. If you need a visible live COMSOL Desktop session, use:
181
-
182
- uv run sim connect --solver comsol --ui-mode gui --driver-option visual_mode=shared-desktop
183
-
184
- After connecting, inspect session.health and comsol.model.identity. Confirm the
185
- live model binding is healthy before treating the GUI as synchronized. For
186
- non-trivial work, establish a case folder and save .mph checkpoints after major
187
- layers. Build and solve one bounded step at a time.
153
+ Simulate the natural-convection cooling of attached `pcb.mph` and report the
154
+ maximum junction temperature. Use the installed COMSOL skill. Check COMSOL with
155
+ `uv run sim check comsol` first. If you need a visible live COMSOL Desktop
156
+ session, connect with `--ui-mode gui`.
188
157
  ```
189
158
 
159
+ The prompt names a goal and a quantity to report — not a list of `sim`
160
+ sub-steps. The COMSOL skill supplies the rest: session health and model
161
+ identity checks, checkpoint policy, and step-by-step build/solve discipline.
162
+
190
163
  For COMSOL-specific details such as shared Desktop mode, offline `.mph`
191
164
  inspection, Desktop attach fallback, model identity checks, and checkpoint
192
165
  policy, follow the bundled COMSOL skill.
193
166
 
194
167
  ## Why CLI-first?
195
168
 
196
- sim-cli is CLI-first because engineering simulation is file-based,
197
- scriptable, local, artifact-heavy, and long-running.
198
-
199
- CAE agents need to work with solver executables, model files,
200
- Python/Java/journal scripts, shell commands, logs, checkpoints, plots,
201
- and artifacts. A CLI command surface composes with all of that and
202
- matches how Codex CLI, Claude Code, and other coding agents already
203
- operate.
169
+ Engineering simulation is file-based, scriptable, local, artifact-heavy, and
170
+ long-running. CAE agents work with solver executables, model files,
171
+ Python/Java/journal scripts, shell commands, logs, checkpoints, and plots — a
172
+ CLI command surface composes with all of that and matches how Codex CLI, Claude
173
+ Code, and other coding agents already operate.
204
174
 
205
- MCP is useful for API-style integrations and remote tool discovery,
206
- but a broad MCP surface can add context overhead and wrapper
207
- maintenance. For COMSOL, Abaqus, Ansys Workbench, OpenFOAM, LTspice,
208
- and similar solvers, sim-cli keeps the source of truth as a small,
209
- auditable command loop:
210
-
211
- ```text
212
- check readiness → attach to live session → inspect model state
213
- → run one bounded CAE step → verify result/state → save checkpoint/artifacts
214
- ```
215
-
216
- Solver plugins provide solver-specific behavior. Agent skills teach
217
- Codex, Claude Code, and other agents when and how to use the CLI
218
- safely.
175
+ MCP is useful for API-style integrations and remote tool discovery, but a broad
176
+ MCP surface adds context overhead and wrapper maintenance. For COMSOL, Abaqus,
177
+ Ansys Workbench, OpenFOAM, LTspice, and similar solvers, sim-cli keeps the
178
+ source of truth as a small, auditable command loop.
219
179
 
220
180
  ## The agent loop
221
181
 
@@ -288,18 +248,12 @@ solver can be reached:
288
248
 
289
249
  ```bash
290
250
  uv run sim plugin list
291
-
292
- # Codex or Copilot
293
- uv run sim plugin sync-skills --target .agents/skills --copy
294
-
295
- # Claude Code
296
- uv run sim plugin sync-skills --target .claude/skills --copy
297
-
251
+ uv run sim plugin sync-skills --target .agents/skills --copy # or .claude/skills for Claude Code
298
252
  uv run sim check <solver>
299
253
  uv run sim plugin doctor <solver> --deep
300
254
  ```
301
255
 
302
- For direct wheel, Git, local checkout, or non-uv workflows, see
256
+ For direct wheel, Git, local checkout, or non-uv package workflows, see
303
257
  [docs/plugin-install.md](docs/plugin-install.md).
304
258
 
305
259
  ## Project setup with sim.toml
@@ -328,12 +282,7 @@ Then a fresh checkout can run:
328
282
  ```bash
329
283
  uv sync
330
284
  uv run sim setup --dry-run
331
-
332
- # Codex or Copilot
333
- uv run sim plugin sync-skills --target .agents/skills --copy
334
-
335
- # Claude Code
336
- uv run sim plugin sync-skills --target .claude/skills --copy
285
+ uv run sim plugin sync-skills --target .agents/skills --copy # or .claude/skills for Claude Code
337
286
  ```
338
287
 
339
288
  ## Common commands
@@ -343,15 +292,14 @@ uv run sim plugin sync-skills --target .claude/skills --copy
343
292
  | `uv run sim plugin list` | Show plugins visible in this project environment. |
344
293
  | `uv run sim plugin info <solver>` | Show plugin metadata and compatibility summary. |
345
294
  | `uv run sim plugin doctor <solver> --deep` | Check plugin wiring plus local solver detection. |
346
- | `uv run sim plugin sync-skills --target .agents/skills --copy` | Materialize installed plugin skills for Codex or Copilot. |
347
- | `uv run sim plugin sync-skills --target .claude/skills --copy` | Materialize installed plugin skills for Claude Code. |
295
+ | `uv run sim plugin sync-skills --target .agents/skills --copy` | Materialize installed plugin skills for your agent (`.claude/skills` for Claude Code). |
348
296
  | `uv run sim check <solver>` | Detect local or remote solver installs. |
349
297
  | `uv run sim connect --solver <solver>` | Open a persistent solver session. |
350
298
  | `uv run sim exec --file step.py` | Run one bounded step in the live session. |
351
299
  | `uv run sim inspect <target>` | Query session, result, or solver-specific state. |
352
300
  | `uv run sim run script.py --solver <solver>` | Run a deterministic one-shot script. |
353
301
  | `uv run sim disconnect` | Tear down the active session. |
354
- | `uv run sim setup` | Apply plugin declarations from `sim.toml` when you use them. |
302
+ | `uv run sim setup` | Validate `sim.toml` and report declared plugin package specs. |
355
303
 
356
304
  Run `uv run sim describe` for a machine-readable command manifest, or
357
305
  `uv run sim <command> --help` for exact options.
@@ -35,7 +35,8 @@ src/sim/
35
35
  driver.py DriverProtocol + result dataclasses
36
36
  compat.py Version-compat profiles + layered skill resolution
37
37
  plugins.py Plugin discovery, listing, info
38
- _plugin_install.py Explicit install / uninstall sources
38
+ _plugin_install.py Migration shim for retired package mutation commands
39
+ _skills/ sim-cli shared runtime skills bundled with the wheel
39
40
  drivers/
40
41
  __init__.py Plugin registry — discovers external plugins
41
42
  via the `sim.drivers` entry-point group at
@@ -90,10 +91,11 @@ execute even when the directive is present in the input file.
90
91
 
91
92
  ## Layered skill composition
92
93
 
93
- Skills in [`sim-skills`](https://github.com/svd-ai-lab/sim-skills) use a layered directory structure to handle SDK and solver version differences:
94
+ Plugin-bundled skills can use a layered directory structure to handle SDK and
95
+ solver version differences:
94
96
 
95
97
  ```
96
- sim-skills/<driver>/
98
+ _skills/<driver>/
97
99
  base/ shared — always loaded
98
100
  sdk/<sdk_version>/ override when SDK API differs
99
101
  solver/<solver_version>/ override when solver behavior differs
@@ -58,8 +58,8 @@ top-level keys (`stdout`, `stderr`); never inside `message`.
58
58
  | `LINT_FAILED` | `sim lint` produced at least one error-level diagnostic. |
59
59
  | `RUN_FAILED` | The solver returned non-zero or the driver detected an error in the output. |
60
60
  | `SESSION_NOT_FOUND` | `--session <id>` does not match any active session on the server. |
61
- | `PLUGIN_NOT_FOUND` | `sim plugin install` received an invalid explicit source, or a plugin name is not installed. |
62
- | `PLUGIN_INSTALL_FAILED` | `pip install` for a plugin returned non-zero. |
61
+ | `PLUGIN_NOT_FOUND` | A requested plugin name is not registered in this environment. |
62
+ | `PLUGIN_INSTALL_RETIRED` | A retired plugin package mutation command was invoked; use `uv add` / `uv remove` instead. |
63
63
  | `PROTOCOL_VIOLATION` | A driver returned a value that doesn't match `DriverProtocol`. |
64
64
  | `NONINTERACTIVE_INPUT_REQUIRED` | `--no-interactive` is set and the command would otherwise prompt. |
65
65
 
@@ -74,7 +74,7 @@ and the JSON schema emitted by `sim describe --error-codes`.
74
74
  | 1 | Run-level failure (solver returned non-zero, lint produced diagnostics). |
75
75
  | 2 | User error (bad args, unknown command). |
76
76
  | 3 | Environment error (solver not installed). |
77
- | 4 | Plugin error (`sim plugin install` failed, plugin doctor FAIL). |
77
+ | 4 | Plugin error (retired mutation command invoked, plugin doctor FAIL). |
78
78
 
79
79
  `sim plugin doctor --all` exits with a count of FAILed plugins (so it works
80
80
  in `&&` chains).
@@ -106,10 +106,11 @@ name = "local_plugin"
106
106
  wheel = "./vendor/sim_plugin_local-1.2.0-py3-none-any.whl" # local, air-gapped
107
107
  ```
108
108
 
109
- `sim init` creates a starter `sim.toml`. `sim setup` reads it and ensures
110
- plugins/server config/workspace are in place. `sim config show --json`
111
- prints the resolved config; `sim config validate <file>` checks a file
112
- against the schema without applying it.
109
+ `sim init` creates a starter `sim.toml`. `sim setup` reads it, validates it,
110
+ and reports declared plugin package specs; package installation belongs to
111
+ the uv project (`uv add sim-cli-core <plugin-package-spec>`). `sim config
112
+ show --json` prints the resolved config; `sim config validate <file>` checks
113
+ a file against the schema without applying it.
113
114
 
114
115
  ### Resolution order (later overrides earlier)
115
116
 
@@ -0,0 +1,68 @@
1
+ # Skills Layering
2
+
3
+ This document records the current skill packaging model.
4
+
5
+ ## Ownership
6
+
7
+ - `sim-cli` owns shared runtime skills under `src/sim/_skills/sim-cli/`.
8
+ - Solver plugins own solver-specific skills under their package-local
9
+ `_skills/<solver>/` directory and expose them through the `sim.skills`
10
+ entry-point group.
11
+ - A local `SIM_SKILLS_ROOT` can override plugin-bundled skills during
12
+ development, but it is not the default public distribution path.
13
+
14
+ The old external shared-skill repository is archival. New public solver
15
+ workflow guidance should live with the plugin package that owns the driver.
16
+
17
+ ## Runtime Sync
18
+
19
+ `sim plugin sync-skills` materializes:
20
+
21
+ 1. the bundled `sim-cli` runtime skill, and
22
+ 2. every installed plugin skill discoverable through `sim.skills`.
23
+
24
+ The command does not install packages. Agents add packages with `uv add`, then
25
+ sync and verify:
26
+
27
+ ```bash
28
+ uv add sim-cli-core <plugin-package-spec>
29
+ uv run sim plugin sync-skills --target .agents/skills --copy
30
+ uv run sim check <solver>
31
+ uv run sim plugin doctor <solver> --deep
32
+ ```
33
+
34
+ Use `.agents/skills` for Codex and GitHub Copilot. Use `.claude/skills` for
35
+ Claude Code.
36
+
37
+ ## Layered Layout
38
+
39
+ Version-sensitive plugin skills may use this layout:
40
+
41
+ ```text
42
+ _skills/<driver>/
43
+ SKILL.md
44
+ base/
45
+ sdk/<sdk-slug>/
46
+ solver/<solver-slug>/
47
+ ```
48
+
49
+ `compatibility.yaml` can declare:
50
+
51
+ ```yaml
52
+ profiles:
53
+ - name: solver_2025_sdk_1
54
+ solver_versions: ["2025"]
55
+ sdk: ">=1,<2"
56
+ active_sdk_layer: "1.x"
57
+ active_solver_layer: "2025"
58
+ ```
59
+
60
+ The `/connect` response includes `active_sdk_layer` and
61
+ `active_solver_layer` so an agent can pick the correct skill layer after the
62
+ Step-0 version probe.
63
+
64
+ ## Validation
65
+
66
+ `verify_skills_layout(root, profiles)` checks that declared layers exist in an
67
+ explicit skills root. Plugin packages should also test that their packaged
68
+ `_skills/<solver>/SKILL.md` exists and that the `sim.skills` entry point loads.