# Training Console Public Surface v1

This document defines the current public-facing Training module surface for `ai-ict`.

## Product Position

- Training is a separate public module from the trading workbench.
- The public browser entry is `/training`.
- The trading workbench stays at `/`.
- Training assets live in `src/web/training.html` and `src/web/training.js`.

## Dashboard Entry

- available cases
- user progress
- attempt start
- annotation note save
- attempt submit
- public case fields only

## API Surface

| Method | Path | Capability |
| --- | --- | --- |
| GET | `/training/cases` | list cases with status, skill tag, instrument, and limit filters |
| GET | `/training/cases/{case_id}` | read one public case |
| GET | `/training/cases/export` | export a public package with the same case filters |
| POST | `/training/cases/import` | import a versioned public package with cases plus tasks |
| POST | `/training/attempts` | start an attempt for one case |
| POST | `/training/attempts/{attempt_id}/annotations` | save an annotation payload for one attempt |
| POST | `/training/attempts/{attempt_id}/submit` | submit an attempt with optional score data |
| GET | `/training/progress` | list progress with user, skill tag, and limit filters |

## Validation And Errors

Training public error catalog:

- deterministic public validation errors
- `400` with `invalid_json_body`
- `400` with `missing_required_json_field:<field>`
- `400` with `invalid_json_field:<field>`
- `400` with `invalid_path_param:<field>`
- `400` with `invalid_limit_query_param:limit`
- `404` with `not_found`
- `500` with `internal_server_error`
- masks raw internals

Package CLI public errors:

- one-line JSON
- `input_file_not_found`
- `input_path_is_directory`
- `output_path_is_directory`
- `output_path_unwritable`

## Package Smoke

- public package
- public export
- public output
- internal solution details are excluded from exported public JSON
- fixture path: `tests/fixtures/training_case_package_m6.json`
- example command: `.venv/bin/python scripts/run_training_case_package.py --input tests/fixtures/training_case_package_m6.json --output /tmp/training_case_public_export.json`