Problem
The public docs glob (config/assets.js → allGuides: 'modules/*/doc/guides/*.md') unconditionally picks up the scaffolding sample guides shipped in modules/home/doc/guides/00-welcome.md + 01-quickstart.md. Any downstream project that ships its own welcome / quickstart guides (in another module) gets a duplicate-slug collision: two guides resolve to /docs/welcome and /docs/quickstart, and public.docs.tree emits duplicate guide slug "…" — later guide wins while one guide is silently shadowed.
The integration test modules/public/tests/public.docs.integration.tests.js enforces new Set(slugs).size === slugs.length, so the collision is a hard failure downstream. There is no config-level way to exclude the samples — the glob runs last in config/index.js (line ~159), replacing any files.guides override, and only module activation filters the list (the home module must stay active).
Affected file(s)
config/assets.js (allGuides glob)modules/home/doc/guides/00-welcome.md, modules/home/doc/guides/01-quickstart.md (sample content)modules/public/services/public.docs.service.js / modules/public/helpers/public.docs.tree.js (slug dedup)
Steps to reproduce
- Downstream project adds
modules/<x>/doc/guides/00-welcome.md + 01-quickstart.md with its own content.
npm run test:integration → Public docs integration tests › the tree contains the shipped sample guides grouped into categories fails: Expected: N Received: N-2 (duplicate slugs).
Suggested fix
Make the sample guides non-colliding or excludable, e.g. one of:
- Relocate samples out of the auto-glob (an
examples/ dir not matched by modules/*/doc/guides/*.md), or
- Gate sample-guide inclusion behind a config flag (
config.docs.includeSampleGuides, default true upstream, downstream sets false), or
- Namespace the sample slugs (
home-welcome / home-quickstart) so they never collide with a downstream's canonical welcome/quickstart.
Context: surfaced when a downstream absorbed the samples for the first time via /update-stack; downstream worked around it by removing the two sample files locally (a content-only drift exception) — a proper upstream fix would let the samples stay ISO.
Problem
The public docs glob (
config/assets.js→allGuides: 'modules/*/doc/guides/*.md') unconditionally picks up the scaffolding sample guides shipped inmodules/home/doc/guides/00-welcome.md+01-quickstart.md. Any downstream project that ships its ownwelcome/quickstartguides (in another module) gets a duplicate-slug collision: two guides resolve to/docs/welcomeand/docs/quickstart, andpublic.docs.treeemitsduplicate guide slug "…" — later guide winswhile one guide is silently shadowed.The integration test
modules/public/tests/public.docs.integration.tests.jsenforcesnew Set(slugs).size === slugs.length, so the collision is a hard failure downstream. There is no config-level way to exclude the samples — the glob runs last inconfig/index.js(line ~159), replacing anyfiles.guidesoverride, and only module activation filters the list (thehomemodule must stay active).Affected file(s)
config/assets.js(allGuidesglob)modules/home/doc/guides/00-welcome.md,modules/home/doc/guides/01-quickstart.md(sample content)modules/public/services/public.docs.service.js/modules/public/helpers/public.docs.tree.js(slug dedup)Steps to reproduce
modules/<x>/doc/guides/00-welcome.md+01-quickstart.mdwith its own content.npm run test:integration→Public docs integration tests › the tree contains the shipped sample guides grouped into categoriesfails:Expected: N Received: N-2(duplicate slugs).Suggested fix
Make the sample guides non-colliding or excludable, e.g. one of:
examples/dir not matched bymodules/*/doc/guides/*.md), orconfig.docs.includeSampleGuides, default true upstream, downstream sets false), orhome-welcome/home-quickstart) so they never collide with a downstream's canonicalwelcome/quickstart.Context: surfaced when a downstream absorbed the samples for the first time via
/update-stack; downstream worked around it by removing the two sample files locally (a content-only drift exception) — a proper upstream fix would let the samples stay ISO.