api: GET /api/system + POST /api/explore, OpenAPI spec updated in code

lib/openapi.ts

@@ -100,6 +100,74 @@ export const openApiSpec = {
         },
       },
     },
+    '/api/system': {
+      get: {
+        summary: 'Current system state',
+        description:
+          'The bodies of the current solar system — planets and their moons (nested via parent) with hazard/explored flags — plus the save inventory and turn counter. Auto-initializes a new game when no save exists yet.',
+        operationId: 'getSystem',
+        responses: {
+          200: {
+            description: 'Current system state',
+            content: {
+              'application/json': {
+                schema: { $ref: '#/components/schemas/SystemState' },
+              },
+            },
+          },
+        },
+      },
+    },
+    '/api/explore': {
+      post: {
+        summary: 'Explore a planet or moon',
+        description:
+          'Scans one body of the save with a deterministic haul (a resource and/or a part, or nothing), marks it explored, increments the turn counter, accumulates finds into inventory and writes an explore event. Returns the fresh system state plus this scan outcome.',
+        operationId: 'explorePlanet',
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/ExploreRequest' },
+            },
+          },
+        },
+        responses: {
+          200: {
+            description: 'Fresh system state plus the scan outcome',
+            content: {
+              'application/json': {
+                schema: { $ref: '#/components/schemas/ExploreResult' },
+              },
+            },
+          },
+          400: {
+            description: 'Malformed body or non-integer planetId',
+            content: {
+              'application/json': {
+                schema: { $ref: '#/components/schemas/Error' },
+              },
+            },
+          },
+          404: {
+            description: 'Unknown planet id',
+            content: {
+              'application/json': {
+                schema: { $ref: '#/components/schemas/Error' },
+              },
+            },
+          },
+          409: {
+            description: 'Body was already explored (each can only be scanned once)',
+            content: {
+              'application/json': {
+                schema: { $ref: '#/components/schemas/Error' },
+              },
+            },
+          },
+        },
+      },
+    },
   },
   components: {
     schemas: {
@@ -147,6 +215,74 @@ export const openApiSpec = {
         },
         required: ['systemId'],
       },
+      Planet: {
+        type: 'object',
+        properties: {
+          id: { type: 'integer' },
+          name: { type: 'string' },
+          type: { type: 'string', description: 'Body class, e.g. TERRESTRIAL or GAS GIANT' },
+          hazard: { type: 'boolean' },
+          explored: { type: 'boolean', description: 'True once scanned — each body can only be explored once' },
+          parent: { type: ['integer', 'null'], nullable: true, description: 'NULL for a planet, the parent planet id for a moon' },
+        },
+        required: ['id', 'name', 'type', 'hazard', 'explored', 'parent'],
+      },
+      InventoryItem: {
+        type: 'object',
+        properties: {
+          kind: { type: 'string', enum: ['resource', 'part'] },
+          name: { type: 'string' },
+          qty: { type: 'integer' },
+        },
+        required: ['kind', 'name', 'qty'],
+      },
+      FoundItem: {
+        type: 'object',
+        properties: {
+          kind: { type: 'string', enum: ['resource', 'part'] },
+          name: { type: 'string' },
+          qty: { type: 'integer' },
+        },
+        required: ['kind', 'name', 'qty'],
+      },
+      SystemState: {
+        type: 'object',
+        properties: {
+          systemId: { type: 'integer' },
+          systemName: { type: 'string' },
+          planets: {
+            type: 'array',
+            description: 'Planets and moons in display order — a moon always follows its parent row',
+            items: { $ref: '#/components/schemas/Planet' },
+          },
+          inventory: { type: 'array', items: { $ref: '#/components/schemas/InventoryItem' } },
+          turn: { type: 'integer', description: 'Turn counter — one per jump or exploration' },
+        },
+        required: ['systemId', 'systemName', 'planets', 'inventory', 'turn'],
+      },
+      ExploreRequest: {
+        type: 'object',
+        properties: {
+          planetId: { type: 'integer', description: 'planets.id of the body to scan (planet or moon)' },
+        },
+        required: ['planetId'],
+      },
+      ExploreResult: {
+        allOf: [
+          { $ref: '#/components/schemas/SystemState' },
+          {
+            type: 'object',
+            properties: {
+              outcome: {
+                type: 'array',
+                description: 'What this scan found — may be empty (some scans find nothing)',
+                items: { $ref: '#/components/schemas/FoundItem' },
+              },
+            },
+            required: ['outcome'],
+          },
+        ],
+      },
       Error: {
         type: 'object',
         properties: {