Update docs with better mental model, maybe fix CI#152
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Expands the project documentation with a clearer “mental model” for DxMessaging (Fixes #151) and attempts to stabilize CI formatting/renormalization behavior by adjusting git add --renormalize patterns.
Changes:
- Add a new “Mental Model” concepts page and a new Concepts index, then link to them from existing docs entry points.
- Update getting-started navigation paths/timings to include the Mental Model as the first step for newcomers.
- Adjust renormalize guidance and GitHub Actions workflows to exclude
yamlfrom extension loops to avoid dotfile/glob pathspec failures.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| docs/index.md | Adds a top-level quick link to the new Mental Model page. |
| docs/getting-started/visual-guide.md | Adds Mental Model to the “Ready to dive deeper?” list. |
| docs/getting-started/quick-start.md | Updates “Next Steps” to include Mental Model first. |
| docs/getting-started/overview.md | Adds Mental Model to the “Start Here” list. |
| docs/getting-started/index.md | Adds Mental Model to recommended learning paths and updates the time estimate. |
| docs/getting-started/getting-started.md | Adds Mental Model to the next-steps list. |
| docs/concepts/mental-model.md | Introduces a detailed conceptual guide (message categories, tokens/lifecycle, patterns, pitfalls). |
| docs/concepts/index.md | Adds a Concepts landing page organizing the conceptual documentation. |
| .llm/skills/index.md | Updates the generated skills index entry metadata for the renormalize skill doc. |
| .llm/skills/github-actions/git-renormalize-patterns.md | Updates renormalize guidance and adds notes about dotfile/glob behavior. |
| .llm/context.md | Adds project-level guidance about dotfile-only extensions in renormalize loops. |
| .github/workflows/prettier-autofix.yml | Removes yaml from renormalize extension loops with an explanatory comment. |
| .github/workflows/format-on-demand.yml | Removes yaml from renormalize extension loops with an explanatory comment. |
|
|
||
| - **Ordered lists**: Use lazy numbering (`1.`, `1.`, `1.`) not sequential (`1.`, `2.`, `3.`). This matches Prettier behavior and markdownlint MD029 configuration. | ||
| - **Fenced code blocks**: Use triple backticks (```), not indented blocks. | ||
| - **Nested fences**: When showing code blocks inside code blocks (e.g., documenting markdown), the outer fence must have MORE backticks than inner fences. Use ``for outer when inner uses` ```. |
There was a problem hiding this comment.
The inline-code example for nested fences is malformed/confusing: Use ``for outer when inner uses ````. This doesn’t clearly show the intended backtick sequences and will likely render incorrectly. Consider rewriting this sentence to explicitly show the outer/inner fence backtick counts (e.g., outer uses four backticks when inner uses three) in a way that renders unambiguously.
Suggested change
| - **Nested fences**: When showing code blocks inside code blocks (e.g., documenting markdown), the outer fence must have MORE backticks than inner fences. Use ``for outer when inner uses` ```. | |
| - **Nested fences**: When showing code blocks inside code blocks (e.g., documenting markdown), the outer fence must have MORE backticks than inner fences. For example, if the inner fence uses three backticks (```), write the outer fence with four backticks. |
Comment on lines
+261
to
+262
| if (typeof module !== 'undefined' && module.exports) { | ||
| module.exports = { |
There was a problem hiding this comment.
In this new export block, string literals use single quotes (e.g., typeof module !== 'undefined') while the rest of the file consistently uses double quotes. Please switch these to double quotes to keep quoting consistent within the file.
Comment on lines
+586
to
+587
| if (typeof module !== 'undefined' && module.exports) { | ||
| module.exports = { |
There was a problem hiding this comment.
In this new export block, string literals use single quotes (e.g., typeof module !== 'undefined') while the surrounding code in this file uses double quotes. Consider switching to double quotes for consistency.
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.
Description
Related Issue
Fixes #151
Type of Change
Checklist