http service with health, extension listing, profile validation, run planning, async run jobs, job inspection, and report retrieval

docs/LOCAL-SERVICE-API.md

@@ -0,0 +1,114 @@
+# Guide Board Local Service API
+
+Status: draft
+Created: 2026-05-07
+
+## Purpose
+
+The local service API is a thin HTTP facade over the same discovery, validation,
+planning, execution, and report contracts used by the CLI. It is intended for
+local development, containerized operation, and future UI integration.
+
+It does not change certification boundaries: guide-board prepares structured
+evidence and assessment packages, but it does not issue certifications or audit
+assurance.
+
+## Start
+
+```sh
+PYTHONPATH=src python3 -m guide_board serve --host 127.0.0.1 --port 8080
+```
+
+External extension repositories use the same top-level option as the CLI:
+
+```sh
+PYTHONPATH=src python3 -m guide_board \
+  --extension-dir ../open-cmis-tck \
+  serve --host 127.0.0.1 --port 8080
+```
+
+Paths supplied to request bodies are resolved relative to the configured
+`--root` unless they are absolute paths.
+
+## Endpoints
+
+### `GET /health`
+
+Returns service status, configured root, and in-memory job counts.
+
+### `GET /extensions`
+
+Lists bundled and configured external extensions using the same discovery logic
+as `guide-board extensions list`.
+
+### `POST /profiles/validate`
+
+Validates a target or assessment profile.
+
+```json
+{
+  "kind": "target",
+  "path": "profiles/targets/sample-repository.json"
+}
+```
+
+Use `"kind": "assessment"` for assessment profiles.
+
+### `POST /assessments/plan`
+
+Builds a run plan without starting a run.
+
+```json
+{
+  "target": "profiles/targets/sample-repository.json",
+  "assessment": "profiles/assessments/sample-noop.json"
+}
+```
+
+An optional `extension_dirs` array can add request-specific external extension
+locations.
+
+### `POST /runs`
+
+Starts an assessment run in a background thread and returns a job record.
+
+```json
+{
+  "target": "profiles/targets/sample-repository.json",
+  "assessment": "profiles/assessments/sample-noop.json",
+  "output_dir": "runs/sample-noop"
+}
+```
+
+The HTTP job status is `queued`, `running`, `succeeded`, or `failed`. A
+`succeeded` job means the guide-board executor completed and wrote its normal
+run directory; the assessment result itself is still reported separately as
+`completed`, `failed`, `blocked`, or `infrastructure_error`.
+
+### `GET /runs`
+
+Lists known in-memory jobs for the current service process.
+
+### `GET /runs/{job_id}`
+
+Returns a single job record with request metadata, result paths, or execution
+errors.
+
+### `GET /runs/{job_id}/reports`
+
+Returns the Markdown report content, assessment package JSON, retention summary,
+and their filesystem paths after a job has succeeded.
+
+## Container Mode
+
+The core container can run the service through the existing entrypoint:
+
+```sh
+podman run --rm -p 8080:8080 \
+  -v "$PWD/runs:/runs" \
+  guide-board-core:local \
+  --root /opt/guide-board serve --host 0.0.0.0 --port 8080
+```
+
+The service keeps job state in memory. Durable run evidence remains in the
+mounted output directory.