Phase 7: documentation scaffold and README improvements

coding-agent-marvin8 commented

2026-06-11 04:56:49 +00:00

(Migrated from codeberg.org)

Closes #18

Summary

README.md: adds a "Handling large PRs" prose section documenting the size gate (WUMING_MAX_DIFF_LINES) and the 300-line hunk-size cap.
docs/ scaffold: mkdocs.yml (Material theme, same structure as zaojun) plus five content pages: index, deploying-on-woodpecker guide, configuration reference, agents reference, and license.
ROADMAP.md: Phase 5 heading marked ✓; all Phase 7 items marked [x]; Phase 7 heading marked ✓.
pyproject.toml: adds [project.optional-dependencies] docs group with mkdocs-material>=9 so contributors can build docs locally via uv run --with mkdocs-material mkdocs serve.

Closes #18 ## Summary - **README.md**: adds a "Handling large PRs" prose section documenting the size gate (`WUMING_MAX_DIFF_LINES`) and the 300-line hunk-size cap. - **docs/ scaffold**: mkdocs.yml (Material theme, same structure as zaojun) plus five content pages: index, deploying-on-woodpecker guide, configuration reference, agents reference, and license. - **ROADMAP.md**: Phase 5 heading marked ✓; all Phase 7 items marked `[x]`; Phase 7 heading marked ✓. - **pyproject.toml**: adds `[project.optional-dependencies] docs` group with `mkdocs-material>=9` so contributors can build docs locally via `uv run --with mkdocs-material mkdocs serve`.

coding-agent-marvin8 commented

2026-06-11 06:24:39 +00:00

(Migrated from codeberg.org)

mkdocs.yml line 36 — @marvin8

I was expecting to see mike in the set of plugins.

✅ Added in commit 1b83cec — mike plugin with alias_type: redirect and canonical_version: latest is now in mkdocs.yml, matching the zaojun config. Also added mike>=2 to the [project.optional-dependencies] docs group in pyproject.toml.

[`mkdocs.yml` line 36](https://codeberg.org/marvin8/wuming/pulls/19#issuecomment-17255675) — @marvin8 > I was expecting to see `mike` in the set of plugins. ✅ Added in commit `1b83cec` — `mike` plugin with `alias_type: redirect` and `canonical_version: latest` is now in `mkdocs.yml`, matching the zaojun config. Also added `mike>=2` to the `[project.optional-dependencies] docs` group in `pyproject.toml`.

coding-agent-marvin8 commented

2026-06-11 06:24:46 +00:00

(Migrated from codeberg.org)

docs/getting-started/deploying-on-woodpecker.md line 113 — @marvin8

'automatically raised to 16384' uses a backtick for the number

✅ Fixed in commit 1b83cec — backtick removed from the bare number 16384 in this file and in the equivalent sentence in docs/reference/configuration.md and docs/reference/agents.md.

[`docs/getting-started/deploying-on-woodpecker.md` line 113](https://codeberg.org/marvin8/wuming/pulls/19#issuecomment-17255762) — @marvin8 > 'automatically raised to `16384`' uses a backtick for the number ✅ Fixed in commit `1b83cec` — backtick removed from the bare number 16384 in this file and in the equivalent sentence in `docs/reference/configuration.md` and `docs/reference/agents.md`.

coding-agent-marvin8 commented

2026-06-11 06:24:53 +00:00

(Migrated from codeberg.org)

docs/getting-started/deploying-on-woodpecker.md line 10 — @marvin8

'write issues' permission is used for PR comments. Consider clarifying if this is the correct terminology

🔴 Not changed. WuMing posts PR review comments via POST /repos/{owner}/{repo}/issues/{index}/comments — the API path is under issues, so the required token scope in Forgejo is Issues: Write. The text is correct for the Forgejo/Codeberg permission model.

[`docs/getting-started/deploying-on-woodpecker.md` line 10](https://codeberg.org/marvin8/wuming/pulls/19#issuecomment-17255759) — @marvin8 > 'write issues' permission is used for PR comments. Consider clarifying if this is the correct terminology 🔴 Not changed. WuMing posts PR review comments via `POST /repos/{owner}/{repo}/issues/{index}/comments` — the API path is under `issues`, so the required token scope in Forgejo is **Issues: Write**. The text is correct for the Forgejo/Codeberg permission model.

coding-agent-marvin8 commented

2026-06-11 06:24:59 +00:00

(Migrated from codeberg.org)

docs/reference/agents.md line 67 — @marvin8

Missing period at end of sentence.

🔴 Not changed — the sentence at that position already ends with a period: …backend you have configured in WUMING_BACKEND. This was a false positive.

[`docs/reference/agents.md` line 67](https://codeberg.org/marvin8/wuming/pulls/19#issuecomment-17255783) — @marvin8 > Missing period at end of sentence. 🔴 Not changed — the sentence at that position already ends with a period: `…backend you have configured in `WUMING_BACKEND`.` This was a false positive.

coding-agent-marvin8 commented

2026-06-11 06:25:06 +00:00

(Migrated from codeberg.org)

docs/reference/agents.md line 64 — @marvin8

Same issue as above: backtick around '16384'. Use plain numbers for token counts.

✅ Fixed in commit 1b83cec — backtick removed from the bare number 16384.

[`docs/reference/agents.md` line 64](https://codeberg.org/marvin8/wuming/pulls/19#issuecomment-17255765) — @marvin8 > Same issue as above: backtick around '16384'. Use plain numbers for token counts. ✅ Fixed in commit `1b83cec` — backtick removed from the bare number 16384.

coding-agent-marvin8 commented

2026-06-11 06:25:12 +00:00

(Migrated from codeberg.org)

docs/reference/agents.md line 60 — @marvin8

deepseek-chat and deepseek-reasoner are model names. Clarify that these are specific to DeepSeek backend.

✅ Fixed in commit 1b83cec — added a sentence after the example: "The example above uses DeepSeek model names; substitute the appropriate identifier for Anthropic or Ollama backends." The WUMING_AGENTS row in configuration.md also now notes that model names are backend-specific.

[`docs/reference/agents.md` line 60](https://codeberg.org/marvin8/wuming/pulls/19#issuecomment-17255771) — @marvin8 > `deepseek-chat` and `deepseek-reasoner` are model names. Clarify that these are specific to DeepSeek backend. ✅ Fixed in commit `1b83cec` — added a sentence after the example: "The example above uses DeepSeek model names; substitute the appropriate identifier for Anthropic or Ollama backends." The `WUMING_AGENTS` row in `configuration.md` also now notes that model names are backend-specific.

coding-agent-marvin8 commented

2026-06-11 06:31:31 +00:00

(Migrated from codeberg.org)

docs/reference/agents.md line 4 — @marvin8

Typo: 'run concurrently' should be 'are run concurrently' or 'run in parallel' for clarity.

🔴 Not changed. "Agents run concurrently" uses run as an intransitive verb (subject–verb), which is grammatically correct. "Are run concurrently" (passive) is equally valid but not an improvement. Keeping the active form.

[`docs/reference/agents.md` line 4](https://codeberg.org/marvin8/wuming/pulls/19#issuecomment-17255777) — @marvin8 > Typo: 'run concurrently' should be 'are run concurrently' or 'run in parallel' for clarity. 🔴 Not changed. "Agents run concurrently" uses `run` as an intransitive verb (subject–verb), which is grammatically correct. "Are run concurrently" (passive) is equally valid but not an improvement. Keeping the active form.

coding-agent-marvin8 commented

2026-06-11 06:31:37 +00:00

(Migrated from codeberg.org)

docs/reference/configuration.md line 31 — @marvin8

Same as above: backtick around '16384'. Use plain number formatting.

✅ Fixed in commit 1b83cec — backtick removed from the bare number 16384.

[`docs/reference/configuration.md` line 31](https://codeberg.org/marvin8/wuming/pulls/19#issuecomment-17255768) — @marvin8 > Same as above: backtick around '16384'. Use plain number formatting. ✅ Fixed in commit `1b83cec` — backtick removed from the bare number 16384.

coding-agent-marvin8 commented

2026-06-11 06:31:44 +00:00

(Migrated from codeberg.org)

docs/reference/configuration.md line 24 — @marvin8

The example uses deepseek-chat which is model-specific. Consider noting that model names depend on the backend.

✅ Fixed in commit 1b83cec — appended "Model names are backend-specific." to the WUMING_AGENTS table cell.

[`docs/reference/configuration.md` line 24](https://codeberg.org/marvin8/wuming/pulls/19#issuecomment-17255774) — @marvin8 > The example uses `deepseek-chat` which is model-specific. Consider noting that model names depend on the backend. ✅ Fixed in commit `1b83cec` — appended "Model names are backend-specific." to the `WUMING_AGENTS` table cell.

coding-agent-marvin8 commented

2026-06-11 06:34:56 +00:00

(Migrated from codeberg.org)

README.md line 74 — @marvin8

What data have you got that "hunking" is a good strategy here?

🔴 Not changing the behaviour — hunk truncation was implemented in Phase 5 (already merged) and this PR only documents it. The design question is fair but out of scope here; if you want to revisit the truncation strategy, that belongs in a separate issue.

[`README.md` line 74](https://codeberg.org/marvin8/wuming/pulls/19#issuecomment-17255426) — @marvin8 > What data have you got that "hunking" is a good strategy here? 🔴 Not changing the behaviour — hunk truncation was implemented in Phase 5 (already merged) and this PR only documents it. The design question is fair but out of scope here; if you want to revisit the truncation strategy, that belongs in a separate issue.

coding-agent-marvin8 commented

2026-06-11 06:35:03 +00:00

(Migrated from codeberg.org)

README.md line 75 — @marvin8

The description says 'the first and last lines' but the hunk may have more than two lines.

✅ Fixed in commit 1b83cec. The original description was factually wrong — truncate_large_hunks() in diff.py replaces the entire hunk with a single stub line (+[... N lines truncated — too large for review ...]), not first+last lines. The README now reads: "replaced with a single stub line showing the line count" with a concrete example of the stub format.

[`README.md` line 75](https://codeberg.org/marvin8/wuming/pulls/19#issuecomment-17255756) — @marvin8 > The description says 'the first and last lines' but the hunk may have more than two lines. ✅ Fixed in commit `1b83cec`. The original description was factually wrong — `truncate_large_hunks()` in `diff.py` replaces the entire hunk with a **single stub line** (`+[... N lines truncated — too large for review ...]`), not first+last lines. The README now reads: "replaced with a single stub line showing the line count" with a concrete example of the stub format.

Rows
Columns

Phase 7: documentation scaffold and README improvements #19

Summary