spacemolt-smx 0.1.0__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 (37) hide show
  1. spacemolt_smx-0.1.0/LICENSE +16 -0
  2. spacemolt_smx-0.1.0/PKG-INFO +216 -0
  3. spacemolt_smx-0.1.0/README.md +200 -0
  4. spacemolt_smx-0.1.0/pyproject.toml +32 -0
  5. spacemolt_smx-0.1.0/setup.cfg +4 -0
  6. spacemolt_smx-0.1.0/src/smx/__init__.py +3 -0
  7. spacemolt_smx-0.1.0/src/smx/cards/boarding.md +33 -0
  8. spacemolt_smx-0.1.0/src/smx/cards/combat.md +38 -0
  9. spacemolt_smx-0.1.0/src/smx/cards/exploration.md +33 -0
  10. spacemolt_smx-0.1.0/src/smx/cards/industry.md +27 -0
  11. spacemolt_smx-0.1.0/src/smx/cards/operations.md +37 -0
  12. spacemolt_smx-0.1.0/src/smx/cards/trade.md +36 -0
  13. spacemolt_smx-0.1.0/src/smx/cli.py +1108 -0
  14. spacemolt_smx-0.1.0/src/smx/fleet.py +175 -0
  15. spacemolt_smx-0.1.0/src/smx/knowledge.py +75 -0
  16. spacemolt_smx-0.1.0/src/smx/maintenance.py +334 -0
  17. spacemolt_smx-0.1.0/src/smx/mcp_profiles.py +21 -0
  18. spacemolt_smx-0.1.0/src/smx/paths.py +84 -0
  19. spacemolt_smx-0.1.0/src/smx/profiles.py +137 -0
  20. spacemolt_smx-0.1.0/src/smx/projection.py +61 -0
  21. spacemolt_smx-0.1.0/src/spacemolt_smx.egg-info/PKG-INFO +216 -0
  22. spacemolt_smx-0.1.0/src/spacemolt_smx.egg-info/SOURCES.txt +35 -0
  23. spacemolt_smx-0.1.0/src/spacemolt_smx.egg-info/dependency_links.txt +1 -0
  24. spacemolt_smx-0.1.0/src/spacemolt_smx.egg-info/entry_points.txt +2 -0
  25. spacemolt_smx-0.1.0/src/spacemolt_smx.egg-info/top_level.txt +1 -0
  26. spacemolt_smx-0.1.0/tests/test_backend_state.py +82 -0
  27. spacemolt_smx-0.1.0/tests/test_cli.py +154 -0
  28. spacemolt_smx-0.1.0/tests/test_fleet.py +74 -0
  29. spacemolt_smx-0.1.0/tests/test_fleet_cli.py +95 -0
  30. spacemolt_smx-0.1.0/tests/test_knowledge.py +29 -0
  31. spacemolt_smx-0.1.0/tests/test_maintenance.py +221 -0
  32. spacemolt_smx-0.1.0/tests/test_maintenance_cli.py +89 -0
  33. spacemolt_smx-0.1.0/tests/test_mcp_profiles.py +28 -0
  34. spacemolt_smx-0.1.0/tests/test_paths.py +40 -0
  35. spacemolt_smx-0.1.0/tests/test_profiles.py +67 -0
  36. spacemolt_smx-0.1.0/tests/test_projection.py +39 -0
  37. spacemolt_smx-0.1.0/tests/test_watch.py +118 -0
@@ -0,0 +1,16 @@
1
+ ISC License
2
+ https://spdx.org/licenses/ISC
3
+ =============
4
+ Copyright © 2026 trvny
5
+
6
+ Permission to use, copy, modify, and/or distribute this software for any
7
+ purpose with or without fee is hereby granted, provided that the above
8
+ copyright notice and this permission notice appear in all copies.
9
+
10
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
11
+ REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
12
+ AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
13
+ INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
14
+ LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
15
+ OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
16
+ PERFORMANCE OF THIS SOFTWARE.
@@ -0,0 +1,216 @@
1
+ Metadata-Version: 2.4
2
+ Name: spacemolt-smx
3
+ Version: 0.1.0
4
+ Summary: Ergonomic companion shell for the official SpaceMolt v2 CLI
5
+ Author: travnie
6
+ License-Expression: ISC
7
+ Project-URL: Homepage, https://github.com/travnie/twojstar/tree/main/spacemolt/smx
8
+ Project-URL: Source, https://github.com/travnie/twojstar
9
+ Project-URL: Issues, https://github.com/travnie/twojstar/issues
10
+ Keywords: spacemolt,cli,game,agent
11
+ Classifier: Programming Language :: Python :: 3
12
+ Requires-Python: >=3.14
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Dynamic: license-file
16
+
17
+ # smx
18
+
19
+ `smx` is a small human/agent-friendly companion for the official [SpaceMolt v2 client](https://github.com/SpaceMolt/client-v2).
20
+
21
+ The official `spacemolt` binary remains authoritative for API models, auth and sessions. `smx` adds safer ergonomics without maintaining a second client stack.
22
+
23
+ ## What it adds
24
+
25
+ - friendly aliases and kebab-case compatibility,
26
+ - `sell-all`, `nearby` and combined mission views,
27
+ - typo suggestions without automatic execution,
28
+ - passthrough to every official v2 command,
29
+ - lazy tactical cards through `smx guide`,
30
+ - canonical docs/gameplay MCP profiles through `smx mcp`,
31
+ - isolated gameplay profiles for concurrent players/agents,
32
+ - parallel `fleet` status and dock-safety checks,
33
+ - conservative read-only `watch` plus JSON field projection,
34
+ - local diagnostics and verified managed-backend updates.
35
+
36
+ ## Install
37
+
38
+ The installers put `smx` on the user PATH through uv (when available) or pipx and keep the managed official backend in smx private state. Both installers use `smx backend update`, which verifies the official release digest and version before atomic replacement.
39
+
40
+ Windows PowerShell:
41
+
42
+ ```powershell
43
+ .\install.ps1
44
+ ```
45
+
46
+ Linux/macOS:
47
+
48
+ ```bash
49
+ ./install.sh
50
+ ```
51
+
52
+ Use `-SkipBackend` / `--skip-backend` if the official client is managed separately. After the tool installer updates PATH, open a new terminal and verify:
53
+
54
+ ```bash
55
+ smx paths
56
+ smx --help
57
+ ```
58
+
59
+ Manual install:
60
+
61
+ ```bash
62
+ cd spacemolt/smx
63
+ python -m pip install .
64
+ # or: pipx install .
65
+ ```
66
+
67
+ Set `SMX_BACKEND` when the official binary is not discoverable as `spacemolt`.
68
+
69
+ ## Common commands
70
+
71
+ ```bash
72
+ smx status
73
+ smx nearby
74
+ smx missions --json
75
+ smx sell-all --dry-run
76
+ smx sell-all --keep fuel_cell,mission_widget
77
+
78
+ smx guide combat
79
+ smx guide combat --live
80
+
81
+ smx profiles
82
+ smx -p gremlin status
83
+ smx fleet
84
+ smx fleet check
85
+
86
+ smx --fields player.username,ship.fuel status
87
+ smx watch status --count 3 --interval 5
88
+
89
+ smx doctor
90
+ smx doctor --online
91
+ smx backend check
92
+ smx backend update
93
+
94
+ smx mcp
95
+ smx mcp gameplay
96
+ smx mcp docs --json
97
+
98
+ # Unknown smx commands pass through to official v2:
99
+ smx drone/list
100
+ smx shipping/active
101
+ ```
102
+
103
+ ## Invariants
104
+
105
+ 1. **Live v2 wins.** Official v2 CLI/OpenAPI and live game state outrank local cards.
106
+ 2. **No second auth/API stack.** `smx` composes official commands instead of reimplementing mechanics, retries or response models.
107
+ 3. **No fuzzy auto-execution.** Unknown commands may get suggestions, never automatic correction.
108
+ 4. **Knowledge stays lazy.** Bundled cards load only when requested; `--live` asks the current server guide.
109
+ 5. **MCP roles stay separate.** Docs MCP is for development; the full v2 preset is for gameplay.
110
+ 6. **Credentials stay outside worktrees.** Default sessions live in private smx state.
111
+ 7. **Parallel players use separate session files.** They never race on the official client's shared `activeAccount`.
112
+
113
+ ## Gameplay profiles and fleet
114
+
115
+ ```bash
116
+ smx profile migrate gremlin
117
+ smx profile add claude
118
+ smx profile login claude ClaudeBot
119
+ smx profile use gremlin
120
+ smx profiles
121
+
122
+ smx -p gremlin status
123
+ smx -p claude status
124
+
125
+ smx fleet
126
+ smx fleet --json
127
+ smx fleet --only-undocked
128
+ smx fleet check
129
+ ```
130
+
131
+ `profile login` prompts for the password; automation can use `--password-stdin`. Each profile receives a separate `SPACEMOLT_SESSION` path, so concurrent processes do not change each other's active account.
132
+
133
+ `fleet check` exits non-zero when a configured profile fails status or is undocked. A process-wide explicit `SPACEMOLT_SESSION` is rejected in fleet mode because it would defeat isolation.
134
+
135
+ Removing a profile deletes stored credentials and requires explicit confirmation:
136
+
137
+ ```bash
138
+ smx profile remove claude --yes
139
+ ```
140
+
141
+ ## Watch and projection
142
+
143
+ `--fields` requests official JSON and returns only selected paths:
144
+
145
+ ```bash
146
+ smx --fields player.username,ship.fuel,ship.cargo_used status
147
+ ```
148
+
149
+ `watch` repeats only commands classified as read-only:
150
+
151
+ ```bash
152
+ smx watch status
153
+ smx watch status --interval 5 --count 6 --fields player.username,ship.fuel
154
+ ```
155
+
156
+ Mutating commands are refused rather than repeated accidentally. `get_notifications` is watchable only with `clear=false`.
157
+
158
+ ## Backend maintenance
159
+
160
+ ```bash
161
+ smx doctor
162
+ smx backend status
163
+ smx doctor --online
164
+ smx backend check
165
+ smx backend update
166
+ ```
167
+
168
+ Managed updates only use official `SpaceMolt/client-v2` releases. Before replacing the backend, smx selects the matching asset, requires its published SHA-256 digest, verifies the download, executes `--version`, then replaces the binary atomically. An explicit `SMX_BACKEND` override is never silently replaced.
169
+
170
+ ## Tactical cards and MCP
171
+
172
+ ```bash
173
+ smx guide
174
+ smx guide combat
175
+ smx guide --search tackle
176
+ smx guide combat --json
177
+ smx guide combat --live
178
+
179
+ smx mcp gameplay # https://game.spacemolt.com/mcp/v2?preset=full
180
+ smx mcp docs # https://game.spacemolt.com/mcp/docs
181
+ ```
182
+
183
+ Cards are short tactical reminders, not a frozen game manual. When building/changing wrappers, query the docs MCP for exact contracts. See [DEVELOPMENT.md](DEVELOPMENT.md).
184
+
185
+ ## Local state and credentials
186
+
187
+ | Platform | Default smx state |
188
+ | --- | --- |
189
+ | Windows | `%LOCALAPPDATA%\smx` |
190
+ | Linux | `$XDG_STATE_HOME/smx`, or `~/.local/state/smx` |
191
+ | macOS | `~/Library/Application Support/smx` |
192
+
193
+ Default session state lives under that directory; profiles use `profiles/<name>/session.json`, and the managed backend is shared under `bin/`.
194
+
195
+ Overrides:
196
+
197
+ - `SMX_PROFILE`: profile for this process,
198
+ - `SMX_STATE_DIR`: whole smx state directory,
199
+ - `SPACEMOLT_SESSION`: exact session file, highest session-path priority,
200
+ - `SMX_BACKEND`: backend executable, higher priority than managed/PATH lookup.
201
+
202
+ The official client stores credentials in session JSON and uses mode `0600` where supported. Never commit or share session files.
203
+
204
+ ## Requirements
205
+
206
+ - Python 3.14+
207
+ - official `SpaceMolt/client-v2` CLI, managed by smx or supplied through `SMX_BACKEND`
208
+ - no Python runtime dependencies
209
+
210
+ ## Inspiration
211
+
212
+ The UX borrows ideas from [`vcarl/sm-cli`](https://github.com/vcarl/sm-cli), [`CoinAnole/spacemolt-cli`](https://github.com/CoinAnole/spacemolt-cli) and [`rsned/spacemolt`](https://github.com/rsned/spacemolt), while keeping the official v2 client as the source of truth.
213
+
214
+ ## Published package
215
+
216
+ A public PyPI release is prepared through [the SMX packaging workflow](PUBLISHING.md). After the first successful publish, `uv tool install spacemolt-smx` installs the `smx` command. Until then, use the existing `install.sh` / `install.ps1` scripts above.
@@ -0,0 +1,200 @@
1
+ # smx
2
+
3
+ `smx` is a small human/agent-friendly companion for the official [SpaceMolt v2 client](https://github.com/SpaceMolt/client-v2).
4
+
5
+ The official `spacemolt` binary remains authoritative for API models, auth and sessions. `smx` adds safer ergonomics without maintaining a second client stack.
6
+
7
+ ## What it adds
8
+
9
+ - friendly aliases and kebab-case compatibility,
10
+ - `sell-all`, `nearby` and combined mission views,
11
+ - typo suggestions without automatic execution,
12
+ - passthrough to every official v2 command,
13
+ - lazy tactical cards through `smx guide`,
14
+ - canonical docs/gameplay MCP profiles through `smx mcp`,
15
+ - isolated gameplay profiles for concurrent players/agents,
16
+ - parallel `fleet` status and dock-safety checks,
17
+ - conservative read-only `watch` plus JSON field projection,
18
+ - local diagnostics and verified managed-backend updates.
19
+
20
+ ## Install
21
+
22
+ The installers put `smx` on the user PATH through uv (when available) or pipx and keep the managed official backend in smx private state. Both installers use `smx backend update`, which verifies the official release digest and version before atomic replacement.
23
+
24
+ Windows PowerShell:
25
+
26
+ ```powershell
27
+ .\install.ps1
28
+ ```
29
+
30
+ Linux/macOS:
31
+
32
+ ```bash
33
+ ./install.sh
34
+ ```
35
+
36
+ Use `-SkipBackend` / `--skip-backend` if the official client is managed separately. After the tool installer updates PATH, open a new terminal and verify:
37
+
38
+ ```bash
39
+ smx paths
40
+ smx --help
41
+ ```
42
+
43
+ Manual install:
44
+
45
+ ```bash
46
+ cd spacemolt/smx
47
+ python -m pip install .
48
+ # or: pipx install .
49
+ ```
50
+
51
+ Set `SMX_BACKEND` when the official binary is not discoverable as `spacemolt`.
52
+
53
+ ## Common commands
54
+
55
+ ```bash
56
+ smx status
57
+ smx nearby
58
+ smx missions --json
59
+ smx sell-all --dry-run
60
+ smx sell-all --keep fuel_cell,mission_widget
61
+
62
+ smx guide combat
63
+ smx guide combat --live
64
+
65
+ smx profiles
66
+ smx -p gremlin status
67
+ smx fleet
68
+ smx fleet check
69
+
70
+ smx --fields player.username,ship.fuel status
71
+ smx watch status --count 3 --interval 5
72
+
73
+ smx doctor
74
+ smx doctor --online
75
+ smx backend check
76
+ smx backend update
77
+
78
+ smx mcp
79
+ smx mcp gameplay
80
+ smx mcp docs --json
81
+
82
+ # Unknown smx commands pass through to official v2:
83
+ smx drone/list
84
+ smx shipping/active
85
+ ```
86
+
87
+ ## Invariants
88
+
89
+ 1. **Live v2 wins.** Official v2 CLI/OpenAPI and live game state outrank local cards.
90
+ 2. **No second auth/API stack.** `smx` composes official commands instead of reimplementing mechanics, retries or response models.
91
+ 3. **No fuzzy auto-execution.** Unknown commands may get suggestions, never automatic correction.
92
+ 4. **Knowledge stays lazy.** Bundled cards load only when requested; `--live` asks the current server guide.
93
+ 5. **MCP roles stay separate.** Docs MCP is for development; the full v2 preset is for gameplay.
94
+ 6. **Credentials stay outside worktrees.** Default sessions live in private smx state.
95
+ 7. **Parallel players use separate session files.** They never race on the official client's shared `activeAccount`.
96
+
97
+ ## Gameplay profiles and fleet
98
+
99
+ ```bash
100
+ smx profile migrate gremlin
101
+ smx profile add claude
102
+ smx profile login claude ClaudeBot
103
+ smx profile use gremlin
104
+ smx profiles
105
+
106
+ smx -p gremlin status
107
+ smx -p claude status
108
+
109
+ smx fleet
110
+ smx fleet --json
111
+ smx fleet --only-undocked
112
+ smx fleet check
113
+ ```
114
+
115
+ `profile login` prompts for the password; automation can use `--password-stdin`. Each profile receives a separate `SPACEMOLT_SESSION` path, so concurrent processes do not change each other's active account.
116
+
117
+ `fleet check` exits non-zero when a configured profile fails status or is undocked. A process-wide explicit `SPACEMOLT_SESSION` is rejected in fleet mode because it would defeat isolation.
118
+
119
+ Removing a profile deletes stored credentials and requires explicit confirmation:
120
+
121
+ ```bash
122
+ smx profile remove claude --yes
123
+ ```
124
+
125
+ ## Watch and projection
126
+
127
+ `--fields` requests official JSON and returns only selected paths:
128
+
129
+ ```bash
130
+ smx --fields player.username,ship.fuel,ship.cargo_used status
131
+ ```
132
+
133
+ `watch` repeats only commands classified as read-only:
134
+
135
+ ```bash
136
+ smx watch status
137
+ smx watch status --interval 5 --count 6 --fields player.username,ship.fuel
138
+ ```
139
+
140
+ Mutating commands are refused rather than repeated accidentally. `get_notifications` is watchable only with `clear=false`.
141
+
142
+ ## Backend maintenance
143
+
144
+ ```bash
145
+ smx doctor
146
+ smx backend status
147
+ smx doctor --online
148
+ smx backend check
149
+ smx backend update
150
+ ```
151
+
152
+ Managed updates only use official `SpaceMolt/client-v2` releases. Before replacing the backend, smx selects the matching asset, requires its published SHA-256 digest, verifies the download, executes `--version`, then replaces the binary atomically. An explicit `SMX_BACKEND` override is never silently replaced.
153
+
154
+ ## Tactical cards and MCP
155
+
156
+ ```bash
157
+ smx guide
158
+ smx guide combat
159
+ smx guide --search tackle
160
+ smx guide combat --json
161
+ smx guide combat --live
162
+
163
+ smx mcp gameplay # https://game.spacemolt.com/mcp/v2?preset=full
164
+ smx mcp docs # https://game.spacemolt.com/mcp/docs
165
+ ```
166
+
167
+ Cards are short tactical reminders, not a frozen game manual. When building/changing wrappers, query the docs MCP for exact contracts. See [DEVELOPMENT.md](DEVELOPMENT.md).
168
+
169
+ ## Local state and credentials
170
+
171
+ | Platform | Default smx state |
172
+ | --- | --- |
173
+ | Windows | `%LOCALAPPDATA%\smx` |
174
+ | Linux | `$XDG_STATE_HOME/smx`, or `~/.local/state/smx` |
175
+ | macOS | `~/Library/Application Support/smx` |
176
+
177
+ Default session state lives under that directory; profiles use `profiles/<name>/session.json`, and the managed backend is shared under `bin/`.
178
+
179
+ Overrides:
180
+
181
+ - `SMX_PROFILE`: profile for this process,
182
+ - `SMX_STATE_DIR`: whole smx state directory,
183
+ - `SPACEMOLT_SESSION`: exact session file, highest session-path priority,
184
+ - `SMX_BACKEND`: backend executable, higher priority than managed/PATH lookup.
185
+
186
+ The official client stores credentials in session JSON and uses mode `0600` where supported. Never commit or share session files.
187
+
188
+ ## Requirements
189
+
190
+ - Python 3.14+
191
+ - official `SpaceMolt/client-v2` CLI, managed by smx or supplied through `SMX_BACKEND`
192
+ - no Python runtime dependencies
193
+
194
+ ## Inspiration
195
+
196
+ The UX borrows ideas from [`vcarl/sm-cli`](https://github.com/vcarl/sm-cli), [`CoinAnole/spacemolt-cli`](https://github.com/CoinAnole/spacemolt-cli) and [`rsned/spacemolt`](https://github.com/rsned/spacemolt), while keeping the official v2 client as the source of truth.
197
+
198
+ ## Published package
199
+
200
+ A public PyPI release is prepared through [the SMX packaging workflow](PUBLISHING.md). After the first successful publish, `uv tool install spacemolt-smx` installs the `smx` command. Until then, use the existing `install.sh` / `install.ps1` scripts above.
@@ -0,0 +1,32 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "spacemolt-smx"
7
+ version = "0.1.0"
8
+ description = "Ergonomic companion shell for the official SpaceMolt v2 CLI"
9
+ readme = "README.md"
10
+ requires-python = ">=3.14"
11
+ authors = [{ name = "travnie" }]
12
+ license = "ISC"
13
+ license-files = ["LICENSE"]
14
+ keywords = ["spacemolt", "cli", "game", "agent"]
15
+
16
+ classifiers = [
17
+ "Programming Language :: Python :: 3",
18
+ ]
19
+
20
+ [project.urls]
21
+ Homepage = "https://github.com/travnie/twojstar/tree/main/spacemolt/smx"
22
+ Source = "https://github.com/travnie/twojstar"
23
+ Issues = "https://github.com/travnie/twojstar/issues"
24
+
25
+ [project.scripts]
26
+ smx = "smx.cli:main"
27
+
28
+ [tool.setuptools.packages.find]
29
+ where = ["src"]
30
+
31
+ [tool.setuptools.package-data]
32
+ smx = ["cards/*.md"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ """smx: ergonomic companion shell for the official SpaceMolt v2 client."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,33 @@
1
+ # Boarding field card
2
+
3
+ > Boarding is high-value and high-friction. Use the live `boarding` guide for exact current thresholds and hull bonuses.
4
+
5
+ ## Setup
6
+
7
+ - You need boarding capability plus fit marines.
8
+ - Boarding commits the ship: weapons are suppressed and defensive stance benefits are reduced.
9
+ - Get the target close and keep its shields below the current boarding threshold.
10
+
11
+ ## During the fight
12
+
13
+ - Use the board stance once conditions are favorable.
14
+ - Boarding links are contested. Another same-tick attempt involving either hull can reject yours.
15
+ - Do not casually destroy the hull you are trying to steal. That kills the prize and can kill your marines.
16
+ - Personnel losses matter. A ship without enough fit crew may stop functioning.
17
+
18
+ ## Capture does not mean "teleported to garage"
19
+
20
+ - A successful capture becomes an intact prize at the battle location.
21
+ - Claim it and send it to an accessible station.
22
+ - Recovery consumes fuel and the prize can stall, be intercepted or be recaptured.
23
+ - Use prize service actions to refuel, repair, stop, resume or redirect when needed.
24
+
25
+ ## Personnel logistics
26
+
27
+ - Keep enough fit crew on your active ship when assigning prize crew.
28
+ - Recruit and treat personnel at suitable station services.
29
+ - Field medical and allied personnel-transfer options can rescue an operation, but are not magic infinite crew fountains.
30
+
31
+ ## Rule of thumb
32
+
33
+ Capture only when the hull, modules or cargo justify the recovery chain. Otherwise wreck salvage may be faster and safer.
@@ -0,0 +1,38 @@
1
+ # Combat field card
2
+
3
+ > Compact local reference. Live `help`, battle state and server guides always win if mechanics changed.
4
+
5
+ ## Before shooting
6
+
7
+ - Check `get_ship`: weapons, ammo, fit and speed.
8
+ - Check `get_status`: hull, shields, fuel and current commitments.
9
+ - Check `get_system`: police level and whether you are volunteering for an expensive lesson.
10
+ - Carry spare ammo. Decide your exit condition before the first shot.
11
+
12
+ ## Range and positioning
13
+
14
+ - Battles use Outer → Mid → Inner → Engaged rings.
15
+ - If your reach is longer, create distance. If your guns are short-range, close hard.
16
+ - Speed affects tracking, maneuvering and escape.
17
+ - `spacemolt_battle/status` (`smx spacemolt_battle/status`) is your main per-tick dashboard.
18
+
19
+ ## Damage cheat sheet
20
+
21
+ - **Thermal**: strong into armor.
22
+ - **Void**: bypasses shields, but armor resists it heavily.
23
+ - **EM**: control tool against speed and damage output.
24
+ - **Energy / explosive**: broad all-round choices.
25
+ - Do not pick damage by raw number alone. Match the target's tank.
26
+
27
+ ## Survive the fight
28
+
29
+ - `brace`: buy time and regenerate shields.
30
+ - `evade`: reduce incoming punishment while repositioning or escaping.
31
+ - `flee`: start early. Tackle can stop progress.
32
+ - If warp-disrupted, remove the tackle source first.
33
+ - In fleets: focus fire. Typical priority is logistics → tackle → DPS.
34
+
35
+ ## Aftermath
36
+
37
+ - Wrecks are valuable and persist. Note the location if you cannot salvage now.
38
+ - Repair, reload, refuel and re-check insurance before the next risky sortie.
@@ -0,0 +1,33 @@
1
+ # Exploration field card
2
+
3
+ > The galaxy is large; fuel mistakes are embarrassingly local.
4
+
5
+ ## Before leaving
6
+
7
+ - Check `get_status`, `get_ship`, `get_system`.
8
+ - Plan the route and fuel margin before a long jump chain.
9
+ - Police level 0 means nobody is coming to save you.
10
+ - Set a sensible home base before operating far from your old one.
11
+
12
+ ## In the field
13
+
14
+ - Use route finding instead of hand-waving the map.
15
+ - Survey when the system and your equipment justify it.
16
+ - Scan unknown actors before treating them as scenery.
17
+ - Keep cargo capacity for discoveries, salvage or emergency supplies.
18
+
19
+ ## Record what matters
20
+
21
+ Use the captain's log for:
22
+ - profitable resources,
23
+ - dangerous systems,
24
+ - useful stations,
25
+ - player contacts,
26
+ - unfinished routes,
27
+ - current short-term objective.
28
+
29
+ ## Frontier discipline
30
+
31
+ - Refuel before you are "almost low".
32
+ - Do not drag irreplaceable cargo through lawless space for no reason.
33
+ - If you abort a long movement client-side, verify your actual location before issuing another move.
@@ -0,0 +1,27 @@
1
+ # Industry field card
2
+
3
+ > Recipes, facility routing and inputs evolve. Use live catalog/guide output for exact numbers.
4
+
5
+ ## Mining
6
+
7
+ - Check the POI resource state before wasting ticks.
8
+ - Oversized mining arrays may be inefficient or unusable on depleted deposits.
9
+ - Mining trains the relevant skill automatically.
10
+
11
+ ## Crafting
12
+
13
+ - Inspect the live recipe catalog first.
14
+ - In current v2, crafting jobs consume inputs from station storage, not loose cargo.
15
+ - Use a dry-run quote before expensive jobs.
16
+ - Real facilities keep working while you leave; workshop hand-crafting may pause when you undock.
17
+ - Avoid duplicating a job just because output has not appeared yet. Crafting completes over later ticks.
18
+
19
+ ## Facility choice
20
+
21
+ - Fastest, cheapest and prefer-own routing can produce different answers.
22
+ - Public facilities may charge rental fees.
23
+ - Faction and allied facilities can be strategically better than raw speed.
24
+
25
+ ## Scaling
26
+
27
+ Mining → refining → crafting is a natural industrial loop, but market demand should decide what deserves mass production.
@@ -0,0 +1,37 @@
1
+ # Operations field card
2
+
3
+ > Boring habits are overpowered because replacement ships are not free.
4
+
5
+ ## Session start
6
+
7
+ - Read status, notifications and the captain's log.
8
+ - Reconfirm the current objective before burning ticks.
9
+ - Check fuel, hull, cargo and outstanding mission/freight obligations.
10
+
11
+ ## Continuity
12
+
13
+ Keep the newest captain's-log entry useful:
14
+ - current goal,
15
+ - progress number,
16
+ - next action,
17
+ - important contact or location,
18
+ - unresolved danger or debt.
19
+
20
+ Older notes can hold discoveries and history; the newest one should answer "what was I doing?"
21
+
22
+ ## Survival
23
+
24
+ - Keep valuables in station storage when not needed.
25
+ - Buy insurance before high-risk work and remember it is not permanent.
26
+ - Re-arm and refuel before long travel or combat.
27
+ - Check notifications after consequential actions and before committing to another risky one.
28
+
29
+ ## Multiplayer edge
30
+
31
+ - Read local/system/faction chat when context matters.
32
+ - Useful allies, trade partners and rescue contacts are persistent game assets.
33
+ - Record names worth remembering instead of relying on human memory after five chaotic sessions.
34
+
35
+ ## Authority rule
36
+
37
+ Static cards are reminders, not scripture. If `smx guide <topic> --live`, live help, or current server output disagrees, trust the server.
@@ -0,0 +1,36 @@
1
+ # Trade field card
2
+
3
+ > Prices and station economies are live data. Treat every static route as suspicious until checked again.
4
+
5
+ ## Before buying
6
+
7
+ - Inspect the local market and order depth, not just the headline price.
8
+ - Use market analysis when available.
9
+ - Compare stations before moving bulk cargo.
10
+ - Account for fuel, travel time, taxes, danger and opportunity cost.
11
+
12
+ ## Cargo discipline
13
+
14
+ - Keep mission, fuel and strategic items out of bulk liquidation.
15
+ - `smx sell-all --dry-run` before a large unload.
16
+ - Use `--keep item_a,item_b` for things you refuse to sell.
17
+ - Expensive cargo belongs in storage when you are not actively hauling it.
18
+
19
+ ## Arbitrage loop
20
+
21
+ 1. Check buy and sell depth.
22
+ 2. Estimate actual executable quantity.
23
+ 3. Route to the destination and re-check the book.
24
+ 4. Move only the amount your hold and risk budget justify.
25
+ 5. Sell into real demand, not yesterday's fantasy spread.
26
+
27
+ ## Freight
28
+
29
+ - Sealed freight has deadlines, recovery windows and liability.
30
+ - If late, delivery or return may still be cheaper than default.
31
+ - Do not break seals just because the clock turned red.
32
+ - Use the live shipping status/profile commands before accepting more liability.
33
+
34
+ ## Social edge
35
+
36
+ Good contacts can beat raw market math. Trade offers, faction intel and local chat can reveal demand before public prices fully react.