Repository navigation
Docs: user-guide/ as packaged guide and website source, essential README - #28
Merged
Merged
Conversation
…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
…g; site pages follow the parsed kind
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
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.
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.Evidence
After:
pnpm format && pnpm build-and-pack: passes,pack:check+ smoke test ok; tarball hasdocs/user-guide/(31 rule files), no otherdocs/file, no RULES.mdcd 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 pagesMerge 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 todocs/user-guide/rules.md.Blast Radius: docs
Website pages/routes and npm package contents (
docs/user-guide/added,RULES.mdremoved). 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