Skip to content

Docs: user-guide/ as packaged guide and website source, essential README - #28

Merged
iacoware merged 13 commits into
mainfrom
iacoware/review-docs-and-website
Oct 28, 2026
Merged

iacoware merged 13 commits into
mainfrom
iacoware/review-docs-and-website

Conversation

@iacoware

@iacoware iacoware commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Spec #22: docs/user-guide/ becomes the single docs source, shipped in the package and read by the website; the README shrinks to the essentials.

 README.md                     # 237 → 52 lines: intro, install, `all` preset, entryFiles warning, absolute site links, agent pointer
+CONTRIBUTING.md               # Development section, no site page
-RULES.md
+docs/user-guide/              # shipped; rest of docs/ stays maintainer-only
+├── README.md                 # guide index + website landing
+├── installation.md
+├── configuration.md
+├── shared-settings.md        # one source: README options + RULES.md Shared settings
+├── alongside-effect-tsgo.md
+├── default-configuration.md
+├── common-limits.md
+├── versioning.md
+├── troubleshooting.md
+├── rules.md                  # Rules overview (route rules-overview), orders rule pages
+└── rules/<rule>.md           # 31 files, frontmatter title + group; examples `// ❌ no` / `// ✅ yes`
 website content module
-  readmeMdSource   (split README at headings)
-  rulesMdSource    (split RULES.md at headings)
+  userGuideSource  (one file = one page; frontmatter title/order/group)
   rule template check, link rewrite (.md → route), link/heading resolution

Evidence

  • Before: site built from README.md + RULES.md heading splits; tarball ships 1056-line RULES.md.
    After:
    • pnpm format && pnpm build-and-pack: passes, pack:check + smoke test ok; tarball has docs/user-guide/ (31 rule files), no other docs/ file, no RULES.md
    • cd website && pnpm test: 56/56 pass (frontmatter errors, ❌/✅ example markers, link rewrite, missing file/heading, rule template, real-guide alignment, README absolute links)
    • rule-files.test.ts: rule files == registered rules (fails when one is missing)
    • cd website && pnpm build: 42 pages

Merge Danger

Door: two-way

Old RULES.md#<rule> anchors and old site routes (e.g. configuration/#configuration-options) break; no redirects (out of scope per #22). Released 0.1.0 CHANGELOG entry relinked to docs/user-guide/rules.md.

Blast Radius: docs

Website pages/routes and npm package contents (docs/user-guide/ added, RULES.md removed). No rule logic or messages changed.

Closes #22
Closes #23
Closes #24
Closes #25
Closes #26
Closes #27

🤖 Generated with Claude Code

https://claude.ai/code/session_019G1WFgfM39Sk5PVy3KS6sh

…matter, with relative .md links rewritten to routes; Versioning moves from the README to user-guide/versioning.md, which ships in the package

The build fails, naming the file, on a guide file without valid frontmatter, and, naming the link, on a link to a missing guide file or heading. The README links to the Versioning page with an absolute URL, checked by an alignment test.
…ute URLs; Configuration, Default configuration, Alongside @effect/tsgo and the Rules overview move to user-guide/, whose README.md is the guide index and the website landing; Development moves to CONTRIBUTING.md

The website no longer reads the README: its README source and tests are gone, replaced by guide-file tests for the landing (scope above the name, tagline, actions), the rules overview route and links to RULES.md. A README test checks that every link is an absolute URL to an existing site page or repository file. A quoted frontmatter value is read without its quotes, so the landing title can start with `@`. The project instructions describe the README role and the website sources; the website workflow runs on user-guide/ changes.
…oses both opening sections and every link to them points to the new pages

user-guide/shared-settings.md merges the Configuration options of the Configuration page with the RULES.md Shared settings reference, so entryFiles, testFiles and discriminants and their defaults are described in one place; the Configuration page keeps a short pointer. The RULES.md source makes no reference pages and the reference page kind is gone; an alignment test checks that RULES.md has only the rules index and the groups of its rules. The catalog style guide describes the Shared settings page.
…ignored in extends or rejected in overrides, warnings on a non-CLI layout and silence on aliases, each with symptom, cause and fix linking to Shared settings or Common limits; the README and the guide index link to it

An alignment test checks that the guide index links to every guide page.
…s group in frontmatter, ordered on the website by the links of user-guide/rules.md; RULES.md is removed

Each rule file follows the catalog template without heading and back link; the anti-slop rules end with an Origin note on their source and license. The website builds rule pages from the rule files: the build fails, naming the file, when the template is broken, the group is missing or the rules index does not link the file. The RULES.md source, its tests and alignment tests are gone; alignment tests check that every real rule file is a page in the group and order of the rules index. The root test checks that the rule files equal the registered rules. RULES.md leaves files, pack:check and the website workflow; guide links to it point to the rule files and the rules index topics take the group names. The style guide, the project instructions and CONTRIBUTING.md describe adding a rule file and its rules index entry.
…6-rule-files

* iacoware/review-docs-and-website:
  Troubleshooting becomes a user-guide page: settings errors, settings ignored in extends or rejected in overrides, warnings on a non-CLI layout and silence on aliases, each with symptom, cause and fix linking to Shared settings or Common limits; the README and the guide index link to it
@iacoware
iacoware marked this pull request as ready for review October 28, 2026 15:24
…th ✅; the rule template requires both emoji
…ebsite source, workflow paths, links to repository files and every reference follow
@iacoware
iacoware merged commit 28959df into main Oct 28, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant