Docs: clarify optional assets/content datasets in repo docs #145

New issue

Closed

opened 2026-04-20 11:34:04 +00:00 by pokebedrock-bot · 0 comments

pokebedrock-bot commented

2026-04-20 11:34:04 +00:00

(Migrated from github.com)

Summary

Several contributor-facing docs still describe assets/content/** as part of the repository's tracked structure and imply the per-item Pokemon/move JSON datasets are versioned in git. In the current repository checkout there is no tracked assets/content/ tree, and scripts/build-search-index.ts explicitly treats those locale-scoped JSON directories as optional inputs.

Evidence

git ls-files / the current repo tree shows assets/README.md, assets/diagrams/.gitkeep, and assets/images/.gitkeep, but no tracked assets/content/** files.
scripts/build-search-index.ts uses readOptionalJsonDirectory(...) for assets/content/<locale>/{pokemon,moves} and warns/continues when those directories are absent.
DOCUMENTATION.md currently presents assets/content/ in the directory map despite saying it documents tracked repository contents.
docs/en/handbook/repo-structure.md and docs/es/handbook/repo-structure.md still say the split datasets are tracked in git.
The changelog entries for v2.1.0 also mention non-locale assets/content/pokemon/ / assets/content/moves/ paths, which no longer match the current script/docs contract.

Impact

New contributors get an inaccurate picture of what is actually committed in this repo versus what is an optional/generated upstream dataset input. That makes the repo inventory stale and can send people looking for files that do not exist.

Acceptance criteria

Contributor-facing docs distinguish the tracked assets/ layout from optional/generated assets/content/<locale>/... inputs.
DOCUMENTATION.md no longer presents nonexistent tracked assets/content/** paths as part of the live repo tree.
Path examples for split content datasets use the current locale-scoped layout.
The update stays docs-only and passes npm run ci.

## Summary Several contributor-facing docs still describe `assets/content/**` as part of the repository's tracked structure and imply the per-item Pokemon/move JSON datasets are versioned in git. In the current repository checkout there is no tracked `assets/content/` tree, and `scripts/build-search-index.ts` explicitly treats those locale-scoped JSON directories as optional inputs. ## Evidence - `git ls-files` / the current repo tree shows `assets/README.md`, `assets/diagrams/.gitkeep`, and `assets/images/.gitkeep`, but no tracked `assets/content/**` files. - `scripts/build-search-index.ts` uses `readOptionalJsonDirectory(...)` for `assets/content/<locale>/{pokemon,moves}` and warns/continues when those directories are absent. - `DOCUMENTATION.md` currently presents `assets/content/` in the directory map despite saying it documents tracked repository contents. - `docs/en/handbook/repo-structure.md` and `docs/es/handbook/repo-structure.md` still say the split datasets are tracked in git. - The changelog entries for v2.1.0 also mention non-locale `assets/content/pokemon/` / `assets/content/moves/` paths, which no longer match the current script/docs contract. ## Impact New contributors get an inaccurate picture of what is actually committed in this repo versus what is an optional/generated upstream dataset input. That makes the repo inventory stale and can send people looking for files that do not exist. ## Acceptance criteria - Contributor-facing docs distinguish the tracked `assets/` layout from optional/generated `assets/content/<locale>/...` inputs. - `DOCUMENTATION.md` no longer presents nonexistent tracked `assets/content/**` paths as part of the live repo tree. - Path examples for split content datasets use the current locale-scoped layout. - The update stays docs-only and passes `npm run ci`.