feat: add speaking skill stub samples for A1, A2, B1 (fixes #31)

.github/workflows/ci.yml

@@ -16,11 +16,25 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+      - name: Cache pip
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-${{ matrix.python-version }}-
+            ${{ runner.os }}-pip-
       - name: Install
         run: |
           python -m pip install -U pip
           pip install -e ".[dev]"
-      - name: Ruff
+          pip install pytest-cov
+      - name: Ruff check
         run: ruff check src tests
-      - name: Pytest
-        run: pytest -q
+      - name: Ruff format
+        run: ruff format --check src tests
+      - name: Pytest with coverage
+        run: pytest -q --cov=src --cov-report=term --cov-report=xml --cov-fail-under=30
+      - name: Type check
+        run: python -m compileall src tests

CONTRIBUTING.md

@@ -0,0 +1,103 @@
+# Contributing to NokaMan
+
+Thanks for helping improve NokaMan. This guide covers the local setup, validation commands, and MergeOS bounty flow for first-time contributors.
+
+## Target Repository
+
+Open pull requests against the public product repository:
+
+https://github.com/mergeos-bounties/NokaMan
+
+Do not target private mirrors or unrelated forks. Bounty work lands on the public `NokaMan` repository, normally against the `master` branch.
+
+## Local Setup
+
+NokaMan requires Python 3.11 or newer.
+
+```bash
+git clone https://github.com/mergeos-bounties/NokaMan.git
+cd NokaMan
+python3.11 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e ".[dev]"
+```
+
+For the optional desktop GUI, install the GUI extra:
+
+```bash
+python -m pip install -e ".[dev,gui]"
+```
+
+## Run the Project
+
+Use the CLI to confirm the package is installed correctly:
+
+```bash
+nokaman version
+nokaman languages list
+nokaman demo --lang en
+```
+
+For the optional GUI:
+
+```bash
+nokaman-gui
+# or
+nokaman gui
+```
+
+## Tests and Checks
+
+Run the focused checks before opening a PR:
+
+```bash
+python3.11 -m compileall src tests
+python3.11 -m pytest -q
+python3.11 -m ruff check src tests
+```
+
+If the local `build` package is available, also run:
+
+```bash
+python3.11 -m build
+```
+
+For documentation-only changes, `pytest` and `ruff` are still useful because they catch accidental packaging or import regressions.
+
+## Good First Issue Path
+
+1. Pick an issue labeled `good first issue`, `help wanted`, or `bounty`.
+2. Read the full issue description and acceptance criteria.
+3. Comment `I claim this bounty` on the issue before starting.
+4. Create a feature branch from the latest `master`.
+5. Keep the change scoped to the issue. Avoid unrelated refactors, dependency changes, or CI changes.
+6. Run the checks listed above.
+7. Open a PR to `mergeos-bounties/NokaMan` and include `Fixes #<issue-number>`.
+
+## MergeOS Bounty Claim Flow
+
+For MergeOS MRG bounties:
+
+1. Star `https://github.com/mergeos-bounties/NokaMan` and `https://github.com/mergeos-bounties/mergeos`.
+2. Comment `I claim this bounty` on the NokaMan bounty issue.
+3. Comment on MergeOS Claim Token #1 with a link to the bounty issue.
+4. Open a PR to the public NokaMan repository.
+5. Include a short summary, test output, and any required screenshots or artifacts from the issue.
+
+Maintainers review the PR and credit MRG after merge according to the bounty policy.
+
+## Pull Request Checklist
+
+- The PR targets `mergeos-bounties/NokaMan`.
+- The PR description links the issue with `Fixes #<issue-number>`.
+- The change is limited to the requested scope.
+- Tests and checks are listed in the PR description.
+- Documentation, screenshots, or artifacts required by the issue are included.
+
+## Development Notes
+
+- Do not push directly to `master`.
+- Do not force-push shared branches.
+- Do not add new dependencies unless the issue explicitly requires them.
+- Do not change CI, packaging, or release configuration for a documentation-only issue.

PROGRESS.md

@@ -6,6 +6,8 @@
 
 ## ✅ 已完成
 
+- Added `CONTRIBUTING.md` for bounty #18 with setup, tests, good-first-issue path, and MergeOS claim flow.
+- Added README links to the contribution guide.
 - Harness initialized for NokaMan bounty #11.
 - Confirmed actual FastAPI and SDK payload fields before defining contracts.
 - Added JSON Schema contracts, TypeScript interfaces, and contract smoke tests.
@@ -21,13 +23,13 @@
 
 ## 🔄 进行中
 
-- Commit, push, and open PR for issue #11.
+- Open PR for issue #18.
 
 ---
 
 ## 📋 待办
 
-- Commit, push, and open PR for issue #11.
+- Open PR for issue #18 with `Fixes #18`.
 
 ---
 

README.md

@@ -21,9 +21,11 @@
 - [CLI reference](#cli-reference)
 - [App integration contracts](#app-integration-contracts)
 - [Languages & rubrics](#languages--rubrics)
+- [Supported language catalog](docs/LANGUAGES.md)
 - [Diagrams](#diagrams)
 - [Repository layout](#repository-layout)
 - [Development](#development)
+- [Contributing](#contributing)
 - [MergeOS bounties](#mergeos-bounties)
 - [License](#license)
 
@@ -110,6 +112,8 @@ nokaman rubrics list
 nokaman-gui
 ```
 
+For a browser demo that talks to the local FastAPI app, see [`web/README.md`](web/README.md).
+
 ---
 
 ## CLI reference
@@ -119,15 +123,20 @@ nokaman-gui
 | `nokaman version` | Version + language codes |
 | `nokaman demo -l en` | Full multi-skill evaluation demo |
 | `nokaman languages list` | Supported languages + frameworks |
+| `nokaman languages coverage` | Language x skill sample coverage matrix |
 | `nokaman rubrics list [-l en]` | Skill rubrics |
+| `nokaman rubrics explain -l en` | Print rubric skill weights, notes, frameworks, and bands |
 | `nokaman eval text …` | Evaluate free text |
-| `nokaman train …` | Toy calibration |
+| `nokaman eval batch --out data/out/batch.json` | Score every sample and write a JSON CEFR hit-rate report |
+| `nokaman train …` | Toy calibration with config/report exports |
 | `nokaman gui` / `nokaman-gui` | **Qt desktop app** (needs `.[gui]`) |
 | `nokaman serve` | Optional FastAPI |
 
 ```powershell
 nokaman demo -l vi
 nokaman demo -l ko
+nokaman eval batch --out data/out/batch.json
+nokaman train toy --config configs/example.yaml
 nokaman-gui
 ```
 
@@ -146,6 +155,16 @@ reverse-engineering demo output.
 | `schemas/demo_response.schema.json` | `GET /assess/demo/{lang}` and `demo_payload()` |
 | `sdk/typescript/index.ts` | TypeScript interfaces for request and response payloads |
 
+Optional FastAPI endpoints:
+
+| Endpoint | Purpose |
+| --- | --- |
+| `GET /languages` | List supported language codes, display names, and frameworks |
+| `POST /assess` | App-facing text assessment alias |
+| `POST /assess/text` | Text assessment with language, text, and skill |
+| `GET /assess/demo/{lang}` | Multi-skill demo payload |
+| `POST /assess/placement` | Placement score from multiple answers |
+
 Example TypeScript use:
 
 ```typescript
@@ -172,6 +191,7 @@ console.log(assessment.cefr, assessment.score, assessment.framework_bands);
 ## Languages & rubrics
 
 Rubrics and samples live under `data/`. Extend by adding rubric JSON + samples, then register in `nokaman.rubrics.registry`.
+See [docs/LANGUAGES.md](docs/LANGUAGES.md) for the supported language catalog, CEFR/JLPT/TOPIK/HSK mappings, and language-pack extension steps.
 
 | Code | Typical use |
 | --- | --- |
@@ -215,6 +235,7 @@ src/nokaman/
   rubrics/        # language metadata + skills
   data/loader.py
   train/toy_train.py
+web/              # no-build browser demo for the FastAPI app
 docs/screenshots/
 docs/diagrams/
 ```
@@ -230,12 +251,16 @@ nokaman demo -l en
 python scripts/capture_gui_shots.py   # refresh GUI screenshots
 ```
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, test commands, the good-first-issue path, and the MergeOS bounty claim flow.
+
 ---
 
 ## MergeOS bounties
 
 Star + claim bounty → PR to **master** with demo JSON / screenshots → MRG **25–200**.  
-See org policy on [mergeos](https://github.com/mergeos-bounties/mergeos).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the contributor path and org policy on [mergeos](https://github.com/mergeos-bounties/mergeos).
 
 ---
 

configs/example.yaml

@@ -0,0 +1,5 @@
+# Minimal calibration config for `nokaman train toy --config configs/example.yaml`.
+run_id: example-calibration
+epochs: 3
+seed: 7
+resume: true

data/fixtures/fairness_report.json

@@ -0,0 +1,103 @@
+{
+  "suite": "length_matched_en_ko_ja",
+  "model": "ToyAbilityModel",
+  "skill": "writing",
+  "languages": [
+    "en",
+    "ko",
+    "ja"
+  ],
+  "rows": [
+    {
+      "id": "en_daily_notes",
+      "language": "en",
+      "char_count": 63,
+      "token_count": 14,
+      "score": 53.48,
+      "cefr": "B1",
+      "script_bonus": 4.0
+    },
+    {
+      "id": "en_weekend_plan",
+      "language": "en",
+      "char_count": 61,
+      "token_count": 13,
+      "score": 53.46,
+      "cefr": "B1",
+      "script_bonus": 4.0
+    },
+    {
+      "id": "ko_daily_notes",
+      "language": "ko",
+      "char_count": 27,
+      "token_count": 11,
+      "score": 51.66,
+      "cefr": "B1",
+      "script_bonus": 8.0
+    },
+    {
+      "id": "ko_weekend_plan",
+      "language": "ko",
+      "char_count": 26,
+      "token_count": 9,
+      "score": 50.74,
+      "cefr": "B1",
+      "script_bonus": 8.0
+    },
+    {
+      "id": "ja_daily_notes",
+      "language": "ja",
+      "char_count": 32,
+      "token_count": 3,
+      "score": 58.05,
+      "cefr": "B1",
+      "script_bonus": 8.0
+    },
+    {
+      "id": "ja_weekend_plan",
+      "language": "ja",
+      "char_count": 35,
+      "token_count": 3,
+      "score": 58.05,
+      "cefr": "B1",
+      "script_bonus": 8.0
+    }
+  ],
+  "by_language": {
+    "en": {
+      "n": 2,
+      "mean_chars": 62,
+      "mean_tokens": 13.5,
+      "mean_score": 53.47,
+      "mean_script_bonus": 4.0
+    },
+    "ko": {
+      "n": 2,
+      "mean_chars": 26.5,
+      "mean_tokens": 10,
+      "mean_score": 51.2,
+      "mean_script_bonus": 8.0
+    },
+    "ja": {
+      "n": 2,
+      "mean_chars": 33.5,
+      "mean_tokens": 3,
+      "mean_score": 58.05,
+      "mean_script_bonus": 8.0
+    }
+  },
+  "metrics": {
+    "score_spread": 6.85,
+    "token_spread": 10.5,
+    "max_mean_score_language": "ja",
+    "min_mean_score_language": "ko"
+  },
+  "bias_notes": [
+    "Token counts vary despite matched content length, indicating tokenizer sensitivity."
+  ],
+  "mitigations": [
+    "Track score spread on length-matched multilingual fixtures before releases.",
+    "Review script-specific tokenization because CJK/Hangul characters are tokenized differently.",
+    "Calibrate language-specific priors with labeled learner samples before production use."
+  ]
+}