pyDuckHunt: tidy the common room and chart the road to release 🦆📚🪄

Author: teuk

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -25,9 +25,29 @@ body:
         - Partyline
         - Packaging and service
         - Documentation
+        - Translation or message language
         - Other
     validations:
       required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python version and launch method (foreground or systemd). No server address or private configuration is needed.
+      placeholder: Linux distribution, Python 3.x, foreground pilot
+    validations:
+      required: true
+  - type: dropdown
+    id: language
+    attributes:
+      label: Message language
+      options:
+        - English (en)
+        - French (fr)
+        - Both
+        - Not applicable
+    validations:
+      required: true
   - type: textarea
     id: reproduce
     attributes:

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Installation and troubleshooting
+    url: https://github.com/teuk/pyDuckHunt/blob/main/docs/TROUBLESHOOTING.md
+    about: Check language settings, first launch and common problems before reporting a bug.
   - name: Private security report
     url: https://github.com/teuk/pyDuckHunt/security/advisories/new
     about: Report vulnerabilities privately; never post credentials or private IRC data.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -21,9 +21,7 @@ body:
     id: replay
     attributes:
       label: Determinism and replay
-      description: Identify any clock, random, network or persistence boundary involved.
-    validations:
-      required: true
+      description: Optional technical context. If known, identify a clock, random, network or persistence boundary; player suggestions do not need an implementation plan.
   - type: checkboxes
     id: safety
     attributes:

.github/pull_request_template.md

@@ -2,13 +2,18 @@
 
 Describe the observable change and its bounded scope.
 
+Link a related issue if applicable. Explain any configuration or update step.
+
 ## Validation
 
 - [ ] Public-tree policy passes.
 - [ ] Relevant targeted tests pass.
 - [ ] Fast lane passes with `--progress`.
 - [ ] Full lane passes when the change is ready to merge.
 
+State which languages and environments were checked, and what remains untested.
+For message changes, confirm that formatting fields and private routing still work.
+
 ## Safety
 
 - [ ] No credential, private configuration, runtime state, log or real identity is included.

.github/workflows/ci.yml

@@ -82,9 +82,13 @@ jobs:
         run: python tools/validate.py --lane full --progress
 
   package:
-    name: Package smoke test
+    name: Install ${{ matrix.language }} / Python 3.13
     runs-on: ubuntu-latest
     timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [en, fr]
 
     steps:
       - name: Check out source
@@ -96,7 +100,29 @@ jobs:
           python-version: "3.13"
 
       - name: Run the safe beta installer
-        run: ./install.sh
+        run: ./install.sh --language ${{ matrix.language }}
 
       - name: Exercise installed command
         run: .venv/bin/pyduckhunt --help
+
+      - name: Check installed package and disabled private configuration
+        run: .venv/bin/python -B tools/check_installed.py --language ${{ matrix.language }}
+
+      - name: Preserve configuration on reinstall and reject a conflicting language
+        env:
+          EXPECTED_LANGUAGE: ${{ matrix.language }}
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          saved_config="$RUNNER_TEMP/pyduckhunt-config-before.toml"
+          install -m 600 config/pyduckhunt.toml "$saved_config"
+          ./install.sh
+          cmp --silent "$saved_config" config/pyduckhunt.toml
+          other_language=en
+          if [[ "$EXPECTED_LANGUAGE" == en ]]; then other_language=fr; fi
+          if ./install.sh --language "$other_language"; then
+            echo '[KO] Conflicting language was accepted.'
+            exit 1
+          fi
+          cmp --silent "$saved_config" config/pyduckhunt.toml
+          .venv/bin/python -B tools/check_installed.py --language "$EXPECTED_LANGUAGE"

CHANGELOG.md

@@ -5,6 +5,19 @@ these changes do not create a stable release or a tag.
 
 ## Unreleased
 
+### Public beta onboarding and release preparation
+
+- Keep the English-first README concise and add a documentation index,
+  troubleshooting guide and evidence-based beta exit roadmap.
+- Add language and environment fields to bug reports, simplify player feature
+  requests, and document the contribution and translation workflow.
+- Exercise fresh English and French editable installs separately in CI,
+  including installed messages, disabled private configuration, reinstall
+  preservation and rejection of conflicting language choices.
+- Correct the installer's final instructions: review the target and enable
+  the game before the connection-free pilot check, then launch separately.
+- Preserve game behavior, instance state, version and the no-release boundary.
+
 ### French and English messages
 
 - Add a complete English presentation catalogue, using the supplied Tcl 2.11

CONTRIBUTING.md

@@ -1,17 +1,45 @@
 # Contributing
 
-pyDuckHunt is developed in small, reviewable rounds.
+Bug reports, translation corrections and small pull requests are welcome.
+Check the [roadmap](docs/ROADMAP.md) and [existing issues](https://github.com/teuk/pyDuckHunt/issues)
+before starting a larger change. English and French reports are both welcome.
+
+## Report a problem
+
+Use the [bug form](https://github.com/teuk/pyDuckHunt/issues/new?template=bug_report.yml)
+with a commit, Python version, OS, message language and minimal reproduction.
+Replace people and channels with synthetic examples. See
+[troubleshooting](docs/TROUBLESHOOTING.md) before attaching diagnostics.
+Vulnerabilities belong in the [private security channel](SECURITY.md).
+
+## Prepare a change
+
+Fork the repository, clone your fork and create a topic branch from `main`.
+Run `./install.sh --language en` as your normal account to prepare `.venv`;
+installation does not connect to IRC. Use `--language fr` for a new French setup.
+
+Keep changes small and explain the player or operator problem they solve.
+Update the relevant guide and changelog when observable behavior changes.
+Retain the original author's attribution and project license.
+
+For translations, follow [catalogue maintenance](docs/LANGUAGES.md#maintaining-the-catalogue):
+preserve formatting fields, privacy routing and dynamic values. French and
+English use the same rules, entropy and replay state. Do not add a language fork
+to the game engine. Add a regression test when it demonstrates a real defect;
+simple wording corrections do not need tests that only repeat the new sentence.
 
 ## Local validation
 
 ```bash
 export PYTHONPATH=src
 .venv/bin/python tools/project_guard.py
-.venv/bin/python -m compileall -q src tools tests
+.venv/bin/python tools/validate.py --lane targeted --progress \
+  --test tests.unit.test_i18n
 .venv/bin/python tools/validate.py --lane fast --progress
 ```
 
-The full lane is reserved for an explicitly approved precommit round:
+Replace the targeted module with the tests relevant to your change. The full
+lane is reserved for the final precommit round; run it once with progress visible:
 
 ```bash
 export PYTHONPATH=src
@@ -23,3 +51,6 @@ material, generated exports or local helper scripts.
 
 Use a pull request for review. CI must pass on every supported Python version,
 and the full lane must pass before merge.
+Record what ran and what remains untested in the pull request. Live IRC acceptance
+is a separate check on an authorized test channel. Ordinary contributions create
+no tag or release; see [release workflow](docs/RELEASING.md).

README.md

@@ -9,6 +9,9 @@ A Duck Hunt game bot for IRC, with **English and French messages**, persistent
 scores, a shop and private administrator tools. Both languages share the same
 game rules and code.
 
+[Install](#install-in-english) · [Documentation](docs/README.md) ·
+[Roadmap](docs/ROADMAP.md) · [Report a bug](https://github.com/teuk/pyDuckHunt/issues/new/choose)
+
 ## Install in English
 
 Requires **Python 3.11+**, its `venv` module and Git. Run as your normal bot
@@ -30,18 +33,10 @@ to enable the game and launch it. No system service is installed automatically.
 **French:** use `./install.sh --language fr`. French is also the default for a
 new installation when `--language` is omitted.
 
-### Switching an existing instance to English
-
-Update the existing `[game]` section in **that instance's private configuration**:
-
-```toml
-language = "en"
-```
-
-Then restart that instance. Scores, inventory and scheduled flights are
-preserved. Re-running the installer never overwrites an existing configuration;
-it refuses an explicit language choice that conflicts with it.
-See [language settings](docs/LANGUAGES.md) for separate FR/EN instances.
+**Already installed?** Set `language = "en"` in the existing `[game]` section
+of your instance's private configuration, then restart it. Scores and inventory
+are preserved. See [switching languages](docs/INSTALL.md#change-the-language-of-an-existing-instance).
+The installer preserves existing configuration and refuses a conflicting language choice.
 
 ## Play
 
@@ -62,17 +57,21 @@ and [channel items](docs/CHANNEL_ACTIONS.md) for the details.
 
 ## Documentation
 
-- [Installation, first launch and updates](docs/INSTALL.md)
-- [Configuration](docs/CONFIGURATION.md) · [Languages](docs/LANGUAGES.md)
-- [Partyline and Owner commands](docs/PARTYLINE.md)
-- [Systemd service setup](docs/SYSTEMD_SERVICE.md)
-- [Web rankings](docs/RANKING_PAGE.md) · [Metrics](docs/METRICS_GRAFANA.md)
-- [Architecture](docs/ARCHITECTURE.md) · [Changelog](CHANGELOG.md)
+| You want to… | Start here |
+| --- | --- |
+| Install, configure or update a bot | [Installation](docs/INSTALL.md) · [Troubleshooting](docs/TROUBLESHOOTING.md) |
+| Understand the game | [Player profiles](docs/PLAYER_PROFILE.md) · [Shop](docs/SHOP.md) |
+| Run and administer an instance | [Operator guides](docs/README.md#run-and-administer) |
+| Fix a bug or improve a translation | [Contributing](CONTRIBUTING.md) · [Languages](docs/LANGUAGES.md) |
+
+[All documentation](docs/README.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md)
 
 ## Beta status
 
 This is **beta software**, distributed from `main`, and no tag or GitHub Release
 has been published yet. Back up your private configuration and state before updating.
+The [roadmap](docs/ROADMAP.md#before-a-release) lists the remaining acceptance
+work; there is no release date yet. Linux is the current deployment target.
 
 For development validation:
 

docs/README.md

@@ -0,0 +1,42 @@
+# Documentation
+
+New to pyDuckHunt? Start with [installation in English](INSTALL.md#install-in-english).
+Use `./install.sh --language fr` for French. Both instances use the same game engine.
+
+## Install and play
+
+| Guide | What it answers |
+| --- | --- |
+| [Install and update](INSTALL.md) | Prerequisites, language, first connection and updates |
+| [Configuration](CONFIGURATION.md) · [Languages](LANGUAGES.md) | Private settings and independent FR/EN instances |
+| [Troubleshooting](TROUBLESHOOTING.md) | Installation, connection, messages and recovery problems |
+| [Player profiles](PLAYER_PROFILE.md) · [Shot engine](SHOT_ENGINE.md) | Progression, fatigue, accuracy and shooting |
+| [Shop](SHOP.md) · [Channel items](CHANNEL_ACTIONS.md) | Equipment, bread and duck calls |
+| [Collection and carry](COLLECTION_AND_CARRY.md) | Letters, duck bags and capacity |
+| [Rare events](RARE_EVENTS.md) · [Legendary protection](LEGENDARY_PROTECTION.md) | Unusual ducks, loot and protection |
+| [Incidents](INCIDENTS.md) · [Nuisances](NUISANCES.md) · [Curses](CURSES.md) | Cross-player effects and countermeasures |
+
+## Run and administer
+
+| Guide | What it answers |
+| --- | --- |
+| [Operator pilot](OPERATOR_PILOT.md) · [Controlled pilot](CONTROLLED_PILOT.md) | Target allowlists and live acceptance |
+| [Systemd](SYSTEMD_SERVICE.md) · [Unit templates](../packaging/systemd/README.md) | Background services; adapt the supplied pilot paths |
+| [Partyline](PARTYLINE.md) | Owner authentication, private planning and administration |
+| [Persistence](PERSISTENCE.md) · [Privacy](PRIVACY.md) | Journal, snapshots and private data boundaries |
+| [Web rankings](RANKING_PAGE.md) · [Metrics](METRICS_GRAFANA.md) | Optional publication and monitoring |
+
+## Develop and review
+
+- [Contributing](../CONTRIBUTING.md): reproduce a bug, submit a change or a translation.
+- [Architecture](ARCHITECTURE.md): module responsibilities and deterministic state.
+- [Behavioral replay](BEHAVIORAL_REPLAY.md) · [Rendering](RENDERING.md): behavior and presentation contracts.
+- [IRC transport](IRC_TRANSPORT.md) · [Process shell](PROCESS_SHELL.md): connection and process boundaries.
+- [Runtime lifecycle](RUNTIME_LIFECYCLE.md) · [Runtime policy](RUNTIME_POLICY.md): dispatch, pacing and shutdown.
+- [Runtime adapters](RUNTIME_ADAPTERS.md) · [Settlement adapters](SETTLEMENT_ADAPTERS.md): clock, entropy and persistence integration.
+- [Roadmap](ROADMAP.md) · [Release workflow](RELEASING.md) · [Changelog](../CHANGELOG.md): current status and remaining work.
+- [Security policy](../SECURITY.md): report a vulnerability privately.
+
+Some detailed guides document the existing pilot deployment. Its account, paths
+and service names are examples, not requirements for your own server. Begin with
+the installation guide before adapting an optional integration.

docs/RELEASING.md

@@ -7,12 +7,12 @@ Release.
 pyDuckHunt remains development software until a stable version is explicitly
 approved. A normal commit must not create a tag or GitHub Release.
 
-## Candidate contract
+## Ordinary beta commits
 
 1. Start from a clean `main` branch and a reviewed public source tree.
 2. Run `tools/project_guard.py` and the relevant targeted tests.
 3. Run the fast lane while iterating.
-4. Run the full lane exactly once, visibly and immediately before the candidate
+4. Run the full lane exactly once, visibly and immediately before the final
    commit:
 
    ```bash
@@ -24,6 +24,24 @@ approved. A normal commit must not create a tag or GitHub Release.
 6. Verify the staged diff and scan it for credentials before committing.
 7. Push without rewriting public history and require GitHub Actions to pass.
 
+## Release acceptance
+
+The open gates are tracked in [the roadmap](ROADMAP.md#before-a-release).
+For a candidate, record its commit, tested OS/Python versions, fresh-install
+results in both languages, live IRC acceptance, persistence recovery, update and
+rollback results. Retain sensitive evidence privately and publish only a sanitized
+summary. A passing offline suite alone is not a live deployment qualification.
+
+Current CI runs fast validation on Python 3.11, 3.12 and 3.13, one full job on
+3.13, and separate fresh editable-install checks for English and French on 3.13.
+The install checks validate the generated configuration, packaged catalogue and
+configuration preservation without connecting to IRC. This is not yet a wheel
+or source-archive installation test, nor a claim that every Python/OS pair is qualified.
+
+GitHub branch protection, required checks and private vulnerability reporting
+are repository settings: maintainers must verify them on GitHub. Their presence
+cannot be inferred from checked-in templates or links.
+
 ## Stable releases
 
 A stable release additionally requires an explicit stable version, matching