Make README a quick start and split detailed documentation

[bcomnes]

Summary

Closes #299.

This documentation change is independent of the watch stack and based on master.

• Replace the 3,000-line README with an introduction, minimal successful build, core source-to-output model, and documentation links.
• Move detailed reference material into twelve topic pages plus a documentation index under docs/.
• Add a shared docs layout using parentLayout with path-based breadcrumbs above and below documentation pages, following the breadcrum.net convention.
• Preserve moved README bookmarks with a collapsed compatibility index, documentation-site redirects, and anchors usable by both GitHub and the generated site.
• Update migration/reference links, point excluded example/source links to GitHub, and fix introductory/editorial wording.
• Preserve the merged parentLayout, dataDeps, separate data parameter, and migration documentation throughout the split.
• Use one sentence per line for moved repository prose.

Validation

• Full npm test passed outside the restricted runner.
• Five breadcrumb unit tests cover the docs index, topic pages, loose migration pages, nested paths, relative links under a deployment prefix, and HTML escaping.
• npm run build:domstack passed with all new documentation pages included.
• An ad hoc generated-site check passed all 425 local links/anchors across 23 pages and verified paired breadcrumbs on all 15 documentation pages.
• Chromium checks passed for legacy README bookmarks and hash-change navigation, breadcrumb navigation, and mobile/desktop table-of-contents transitions.
• The README's minimal source fixture builds successfully to public/index.html with the documented content and default layout.

Notes

The example reference uses docs/example-projects/ because the documentation build intentionally excludes directories named examples. The existing migration guides remain separate documents with updated moved-reference links and the shared breadcrumb layout.

[coveralls]

Coverage Report for CI Build 34392019473

Coverage decreased (-2.3%) to 94.12%

Details

• Coverage decreased (-2.3%) from the base build.
• Patch coverage: 6 uncovered changes across 2 files (349 of 355 lines covered, 98.31%).
• 1 coverage regression across 1 file.

Uncovered Changes

File	Changed	Covered	%
lib/build-esbuild/index.js	38	34	89.47%
bin.js	28	26	92.86%
Total (6 files)	355	349	98.31%

Coverage Regressions

1 previously-covered line in 1 file lost coverage.

File	Lines Losing Coverage	Coverage
lib/build-esbuild/index.js	1	92.67%

---

Coverage Stats

Relevant Lines:	9027
Covered Lines:	8656
Line Coverage:	95.89%
Relevant Branches:	2350
Covered Branches:	2052
Branch Coverage:	87.32%
Branches in Coverage %:	Yes
Coverage Strength:	292.11 hits per line

---

💛 - Coveralls

[bcomnes]

For the sub-pages, can you adopt a docs breadcrumb convention similar to the docs in https://github.com/hifiwi-fi/breadcrum.net/tree/master/packages/web/client/layouts/docs

[bcomnes]

Implemented in 04ddfa0, following the shared-layout convention from breadcrum.net.

All topic pages, the docs index, and both migration guides now select layout: docs and receive path-derived breadcrumbs above and below their content.
The breadcrumbs use slash separators, retain a Home link, and mark the current page with aria-current="page".
Relative parent links work for both directory pages and standalone migration guides, including deployments under a URL prefix.
The existing responsive table of contents is preserved, with no new dependencies.

Validation passed: full npm test, five breadcrumb unit tests, the documentation build, all 414 local links/anchors across 23 generated pages, and Chromium checks for breadcrumb navigation, mobile/desktop layout transitions, and legacy bookmarks.

[bcomnes]

This needs to be rebased and all the changes factored in.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​fragtml@​0.0.10
	npm/​@​domstack/​sync@​0.0.6 ⏵ 0.0.8	+1		+1	+3
	npm/​mermaid@​11.17.2

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: npm robust-predicates is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: package.json → npm/mermaid@11.17.2 → npm/robust-predicates@3.0.3 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/robust-predicates@3.0.3. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report