Conversation
The repository had solid CLI docs and maintainer notes, but no public-facing site that framed the project for first-time users. This adds a VitePress-based GitHub Pages surface with a landing page, workflow guide, architecture guide, and a deploy workflow that follows the protected-branch path. Constraint: GitHub Pages should deploy from Actions without changing branch protection Constraint: Public docs should not expose maintainer-only handoff notes as site pages Rejected: Keep everything inside README only | too dense for first-time discovery Rejected: Use Jekyll or a heavier docs framework | worse fit for this Node repo and v1 scope Confidence: high Scope-risk: moderate Reversibility: clean Directive: Keep the public site focused on user-facing explanation and workflows; do not publish internal validation artifacts without a deliberate docs decision Tested: npm run build; npm test; npm run docs:build Not-tested: Live GitHub Pages deployment after merge to main
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ef3f4b58c2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| group: pages | ||
| cancel-in-progress: true |
There was a problem hiding this comment.
Using a single concurrency.group: pages with cancel-in-progress: true means every PR build and every main push deployment share the same lock, so a new PR run can cancel an in-flight production deploy from push to main. Because this workflow is triggered by both pull_request and push, the current setting can intermittently prevent docs updates from reaching GitHub Pages when activity overlaps.
Useful? React with 👍 / 👎.
| - name: Checkout | ||
| uses: actions/checkout@v5 |
There was a problem hiding this comment.
The workflow uses default checkout depth, but docs config enables lastUpdated, which depends on git history to compute per-page timestamps. With shallow checkout, VitePress can only see truncated history and will produce inaccurate "last updated" metadata for pages not changed in the latest commit; add fetch-depth: 0 to the checkout step so timestamps reflect actual file history.
Useful? React with 👍 / 👎.
1 participant
Summary
Testing
Notes
srcExcludemain