docs: consolidate documentation and AI config, remove dead files - #21
Merged
Merged
Conversation
Documentation
- Rewrite README.md: fix broken root-level links (DEVELOPMENT.md, ROADMAP.md),
point to the systemd units actually shipped in systemd/ instead of a
hand-written one, and document .env configuration.
- Rewrite docs/INDEX.md as a task-oriented index of all 48 guides; docs/README.md
and tests/README.md become pointers rather than competing structure listings.
- Merge RESTART_LOOP_TROUBLESHOOTING.md and DOCKER_COMPOSE_FIX.md into
docs/TROUBLESHOOTING.md, and TEST_COVERAGE.md into docs/TESTING.md.
- Delete 15 historical process docs plus all of docs/archive/ (17 files); that
record lives in CHANGELOG.md and git history.
AI configuration
- Add AGENTS.md as the single source of truth, following the ai-template-repo
convention. It replaces AGENT_INSTRUCTIONS.md and the 317-line .cursorrules,
which duplicated each other, and corrects what both got wrong: the auth
decorator is @require_permission("<scope>"), scripts source
scripts/lib/common.sh rather than redefining colors and PROJECT_DIR, and this
repo uses npm rather than pnpm.
- Add CLAUDE.md, .cursor/rules/project.mdc, .clinerules, .windsurfrules and
.github/copilot-instructions.md as thin pointers; reduce .cursorrules to one.
Dead files
- Remove root .eslintrc.json and .eslintignore: linting runs inside web/, whose
.eslintrc.cjs sets root: true, so neither was ever read.
- Remove root playwright.config.js and tests/e2e/browser/: stale duplicates of
web/playwright.config.js and web/tests/e2e/, as that directory's own README
already noted.
- Remove web/playwright-report/index.html, a 520 KB generated report.
Correctness
- Fix 160 references to ./manage.sh and 5 to ./setup-rpi.sh; neither file exists
at the repo root and nothing creates them.
- Use "docker compose" rather than "docker-compose" throughout, matching the
Makefile's COMPOSE detection and the systemd units.
- Add .env.example, which the Makefile told users to copy but did not exist.
- Sync pytest markers in pyproject.toml with tests/api/pytest.ini, which was
missing performance, contract and e2e; --strict-markers would have failed a
run started from the repo root. Drop the duplicate [tool.coverage] block so
.coverage-config.ini is the only coverage config.
- .gitignore: add .mypy_cache/, playwright-report/, test-results/, and fix
"!server.jar # comment" -- gitignore has no inline comments, so that pattern
matched a literal filename.
Verified: docker compose config validates, all scripts pass bash -n, eslint is
clean, 221 pytest tests pass at 42% coverage (threshold 40%), 144 Vitest tests
pass, and 0 internal markdown links are broken.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
github-actions
Bot
added
documentation
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Unresolved moderate issues remain in server-type documentation, Compose fallback guidance, a stale troubleshooting link, and coverage configuration.
Get a fresh assessment by requesting another Copilot review.
Review effort: Lite
Findings: 2
Open (2)
What changed in this PR
This PR consolidates documentation and AI configuration, removes obsolete files, and corrects stale command and configuration references.
Changes:
- Centralized guidance in
AGENTS.mdwith tool-specific pointers. - Consolidated documentation, testing, and troubleshooting guides.
- Corrected script, Compose, environment, pytest, and ignore-file configuration.
- Removed dead configurations, duplicate tests, historical docs, and generated artifacts.
| File | Summary |
|---|---|
tests/TEST_SUMMARY.md |
Removed obsolete test summary. |
tests/README.md |
Simplified test documentation. |
tests/e2e/browser/visual-regression.spec.js |
Removed duplicate browser test. |
tests/e2e/browser/user-journey.spec.js |
Removed duplicate browser test. |
tests/e2e/browser/README.md |
Removed stale browser-test guide. |
tests/e2e/browser/analytics.spec.js |
Removed duplicate browser test. |
tests/COMPLETE_TEST_SUMMARY.md |
Removed obsolete test summary. |
tests/ANALYTICS_TESTS.md |
Removed obsolete analytics summary. |
pyproject.toml |
Synchronized pytest markers and coverage configuration. |
playwright.config.js |
Removed stale root configuration. |
docs/WORKSPACE_ENHANCEMENTS.md |
Removed obsolete summary. |
docs/TESTING.md |
Consolidated testing and coverage guidance. |
docs/TEST_COVERAGE.md |
Removed superseded coverage guide. |
docs/SETUP_CHECKLIST.md |
Removed obsolete checklist. |
docs/RESTART_LOOP_TROUBLESHOOTING.md |
Removed superseded troubleshooting guide. |
docs/README.md |
Simplified documentation pointer. |
docs/RBAC.md |
Corrected documentation links. |
docs/RASPBERRY_PI_OPTIMIZATIONS.md |
Updated Compose commands. |
docs/RASPBERRY_PI_COMPATIBILITY.md |
Updated Compose commands. |
docs/QUICK_REFERENCE.md |
Corrected command references. |
docs/PERFORMANCE_BENCHMARKING.md |
Updated Compose command. |
docs/OPTIMIZATION_SUMMARY.md |
Removed obsolete summary. |
docs/OPTIMIZATION_COMPLETE.md |
Removed obsolete summary. |
docs/MULTI_WORLD.md |
Corrected management script paths. |
docs/MULTI_ARCHITECTURE.md |
Corrected setup and Compose commands. |
docs/MOD_SUPPORT.md |
Corrected management script paths. |
docs/MINECRAFT_SERVER_SETUP.md |
Corrected management script paths. |
docs/MINECRAFT_MANAGEMENT.md |
Corrected API documentation link. |
docs/LOG_MANAGEMENT.md |
Corrected management script paths. |
docs/LINTING.md |
Updated AI guidance link. |
docs/INSTALL.md |
Corrected installation commands. |
docs/DOCUMENTATION_CONSOLIDATION_PLAN.md |
Removed obsolete plan. |
docs/DOCKER_COMPOSE_FIX.md |
Removed superseded Compose guide. |
docs/DEVELOPMENT.md |
Updated development commands. |
docs/CURSOR_CONFIGURATION.md |
Updated AI configuration guidance. |
docs/CONSOLIDATION_SUMMARY.md |
Removed obsolete summary. |
docs/CONFIGURATION_EXAMPLES.md |
Corrected command examples. |
docs/CLOUD_BACKUP.md |
Corrected management script paths. |
docs/CLEANUP_OPTIMIZATIONS_SUMMARY.md |
Removed obsolete summary. |
docs/CI_CD.md |
Corrected management script command. |
docs/archive/TESTING_FINAL_SUMMARY.md |
Removed archived documentation. |
docs/archive/TESTING_ENHANCEMENTS.md |
Removed archived documentation. |
docs/archive/SUMMARY.md |
Removed archived documentation. |
docs/archive/RPI5_OPTIMIZATIONS_SUMMARY.md |
Removed archived documentation. |
docs/archive/RPI5_ACTION_CHECKLIST.md |
Removed archived documentation. |
docs/archive/README.md |
Removed archived documentation. |
docs/archive/IMPLEMENTATION_SUMMARY.md |
Removed archived documentation. |
docs/archive/IMPLEMENTATION_SUMMARY_P1.md |
Removed archived documentation. |
docs/archive/IMPLEMENTATION_SUMMARY_docs.md |
Removed archived documentation. |
docs/archive/GAMEPLAY_FEATURES_IMPLEMENTED.md |
Removed archived documentation. |
docs/archive/CONSOLIDATION_NOTES.md |
Removed archived documentation. |
docs/archive/CI_CD_PIPELINE.md |
Removed archived documentation. |
docs/archive/CI_CD_OPTIMIZATIONS.md |
Removed archived documentation. |
docs/archive/CI_CD_ENHANCEMENTS.md |
Removed archived documentation. |
docs/archive/API_DOCUMENTATION.md |
Removed archived documentation. |
docs/API_KEYS.md |
Corrected security documentation link. |
docs/ADVANCED_OPTIMIZATIONS.md |
Removed obsolete summary. |
CONTRIBUTING.md |
Updated command references. |
CLAUDE.md |
Added pointer configuration. |
CHANGELOG.md |
Documented cleanup changes. |
AGENTS.md |
Added centralized project guidance. |
.windsurfrules |
Added pointer configuration. |
.gitignore |
Added generated-file exclusions and corrected patterns. |
.github/copilot-instructions.md |
Added pointer configuration. |
.eslintrc.json |
Removed unused root ESLint configuration. |
.eslintignore |
Removed unused root ESLint ignore file. |
.env.example |
Added environment template. |
.cursor/rules/project.mdc |
Added pointer configuration. |
.clinerules |
Added pointer configuration. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Addresses both findings from the Copilot review. .env.example advertised `spigot` and `forge` as SERVER_TYPE values. The dispatcher in scripts/download-server.sh handles only vanilla, paper and fabric; `spigot` exits 1 with a pointer to BuildTools and `forge` falls through to "Unknown server type". Corrected the list and explained what spigot and Forge actually require. docs/UPDATE_MANAGEMENT.md carried the same claim about spigot and is fixed too. .coverage-config.ini is not a filename coverage.py auto-discovers, and coverage only reads config from the current directory. Every documented entry point runs from tests/api, so the root pyproject.toml was never reached from there -- verified by planting broad exclude_lines in it and seeing the statement count stay at 2230 with cwd=tests/api, while dropping to 66 with cwd=repo root. The practical effect was that `make test-api` and the documented `cd tests/api && pytest -v` applied no exclusions and no fail_under, which predates this branch. Adding --cov-config to tests/api/pytest.ini fixes that and makes every entry point agree with the Makefile and CI, which already passed the flag explicitly. Before: TOTAL 2230 1293 42%, no threshold check. After: TOTAL 2220 1284 42.16%, "Required test coverage of 40.0% reached". Verified: 221 pytest tests pass via `make test-api`, eslint clean, compose validates, all scripts pass bash -n, 0 broken markdown links. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Repository cleanup spanning documentation, AI assistant configuration, and dead files. No runtime behaviour changes.
Documentation
README.md: fixed broken root-level links (DEVELOPMENT.md,ROADMAP.mdlive indocs/), replaced a hand-written systemd unit with the one actually shipped insystemd/, and documented.envconfiguration including theCONTAINER_MEMORY_LIMIT>MEMORY_MAXrule thatdocker-compose.yml's own comment blames for restart loops.docs/INDEX.mdas a task-oriented index of all 48 guides.docs/README.mdandtests/README.mdare now short pointers instead of competing structure listings that had already drifted out of date.RESTART_LOOP_TROUBLESHOOTING.mdandDOCKER_COMPOSE_FIX.mdintodocs/TROUBLESHOOTING.md, andTEST_COVERAGE.mdintodocs/TESTING.md.docs/archive/(17 files). That record lives inCHANGELOG.mdand git history.docs/goes from 66 active + 17 archived to 48 active.AI configuration
Consolidated onto the
ai-template-repoconvention:AGENTS.mdis the single source of truth, everything else is a thin pointer.AGENTS.md, replacingAGENT_INSTRUCTIONS.md(735 lines) and the fat.cursorrules(317 lines), which were roughly 70% duplicates of each other. It also corrects what both had wrong:@require_permission("<scope>"), not@require_api_keyscripts/lib/common.shfor colors,PROJECT_DIRand thecompose()wrapper rather than redefining themCLAUDE.md,.cursor/rules/project.mdc,.clinerules,.windsurfrulesand.github/copilot-instructions.mdas pointers; reduced.cursorrulesto one.Dead files removed
.eslintrc.jsonand.eslintignore— linting runs insideweb/, whose.eslintrc.cjssetsroot: true, so neither was ever read.playwright.config.jsandtests/e2e/browser/— stale duplicates ofweb/playwright.config.jsandweb/tests/e2e/. That directory's own README already said the tests had moved.web/playwright-report/index.html— a 520 KB generated report that had been committed.Correctness fixes
./manage.shand 5 to./setup-rpi.sh: neither file exists at the repo root and nothing creates them. All now point at./scripts/.docker-compose→docker composethroughout, matching theMakefile'sCOMPOSEdetection and the systemd units..env.example— theMakefiletold users to copy it, but it did not exist.pyproject.tomlwithtests/api/pytest.ini, which was missingperformance,contractande2e. With--strict-markersenabled, a run started from the repo root would have failed. Also dropped the duplicate[tool.coverage]block so.coverage-config.iniis the only coverage config..gitignore: added.mypy_cache/,playwright-report/,test-results/, and fixed!server.jar # Keep server.jar if manually placed— gitignore has no inline comments, so that pattern was matching a literal filename.Type of Change
Checklist
Verification
docker compose configbash -non every script inscripts/npm run lint(--max-warnings 0)docs/INDEX.mdvsdocs/on disk77 files changed, 910 insertions, 10,403 deletions.
Related Issues
None.
🤖 Generated with Claude Code