docs: consolidate and update documentation for M1.1–M1.3 and CE3#10
Open
flyingrobots wants to merge 12 commits intomainfrom
Open
docs: consolidate and update documentation for M1.1–M1.3 and CE3#10flyingrobots wants to merge 12 commits intomainfrom
flyingrobots wants to merge 12 commits intomainfrom
Conversation
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. WalkthroughThis PR consolidates and expands documentation, adds a doc-drift validation script, and bumps the package version to 1.1.4; several long guides were replaced with redirect notes to centralized docs, and QUICK_REFERENCE.md was substantially expanded with CLI, HTTP API, state machine and architecture content. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Fix all issues with AI agents
In `@docs/GETTING_STARTED.md`:
- Line 3: Update the validation line that currently reads "Validated against
v1.1.3 on 2026-02-14." to reference the bumped release (v1.1.4) so it reads
"Validated against v1.1.4 on 2026-02-14."; locate and edit the literal string
"Validated against v1.1.3 on 2026-02-14." in GETTING_STARTED.md (or
alternatively add a brief explanatory note if you intentionally validated
against 1.1.3 rather than changing the version).
In `@QUICK_REFERENCE.md`:
- Line 3: Update the version string that currently reads "Validated against
v1.1.3 on 2026-02-14." to "Validated against v1.1.4 on 2026-02-14." so the
QUICK_REFERENCE.md entry matches the 1.1.4 release; locate the literal text
"Validated against v1.1.3 on 2026-02-14." and replace only the version portion
to v1.1.4 to keep the date unchanged.
In `@scripts/check-doc-drift.sh`:
- Line 33: The current extraction regex in scripts/check-doc-drift.sh (variable
api_paths, using SERVER_FILE) only matches lowercase letters and hyphens; update
the grep pattern to allow digits, underscores and deeper path segments (e.g.,
change "/api/cms/[a-z-]+" to something like "/api/cms/[A-Za-z0-9_/-]+" or more
robustly "/api/cms/[^']+" ) so grep captures paths such as /api/cms/content-v2
and /api/cms/some_thing; keep the surrounding sed transformations the same (they
already strip "pathname === '" and trailing quotes).
- Around line 55-59: The variable root_gs_links is populated but never used; add
a follow-up check that tests if root_gs_links is non-empty and then reports the
finding and increments the errors counter (or exits) so the script fails drift
detection. Concretely, after the grep that sets root_gs_links, add a conditional
like [[ -n "$root_gs_links" ]] (or test -n) to call the existing error-reporting
path (e.g., echo a descriptive message mentioning GETTING_STARTED.md and
append/increment the errors variable used elsewhere) so stale links cause the
script to mark an error.
- Around line 22-29: The current loop uses a plain substring grep (grep -q
"$cmd") which causes false positives (e.g., "log" matching "changelog"); update
the check in the for loop that iterates over cli_commands to perform a precise
match against QUICK_REF — for example use word-boundary or anchored/regex
matching (grep -q -E "\\b$cmd\\b" "$QUICK_REF") or, if docs wrap commands in
backticks, match the backtick-delimited form (grep -q "\`$cmd\`" "$QUICK_REF")
so that the grep against QUICK_REF accurately verifies presence of the exact CLI
command name referenced by CLI_FILE and still increments errors when missing.
- Line 22: The current extraction for cli_commands uses a grep regex that only
matches letters and hyphens, so update the pattern used in the cli_commands
assignment (the grep -oE "case '([a-z-]+)'" invocation) to allow digits and
underscores as well (e.g. use [a-z0-9_-]+) so command names like export-v2 or
name_with_underscore are captured; keep the surrounding sed substitutions the
same.
added 3 commits
February 14, 2026 21:27
…heck - Broaden CLI command regex to [a-z0-9_-]+ for future-proofing - Use backtick-delimited matching for CLI commands to avoid substring false positives - Broaden API path regex to [a-z0-9_/-]+ for endpoints with digits/underscores - Wire up root_gs_links check that was computed but never evaluated
Owner
Author
|
@coderabbitai review please 🥕 |
|
Given your request for the highest standards and pedantic scrutiny, I'll examine:
Initiating full review now... ✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Fix all issues with AI agents
In `@docs/GETTING_STARTED.md`:
- Around line 169-192: Update the Step 7 migration bullets to separate the
concepts: keep the "Idempotent" bullet as-is (already-applied migrations are
skipped), change the "No dry-run mode" bullet to explicitly state that the tool
does not provide a preview/dry-run that shows pending migrations without
applying them (e.g., there is no command that simulates changes), and move the
sentence "Migrations are no-ops until structural changes exist between versions"
into the idempotency bullet or rephrase it to explain that when no structural
changes exist, no migrations will be applied; reference the commands shown (node
bin/git-cms.js layout-version and node bin/git-cms.js migrate) so readers
understand which actions are affected.
In `@QUICK_REFERENCE.md`:
- Line 104: The table entry for the route `GET /api/cms/show-version` currently
uses the format marker `<40-hex>` which assumes SHA-1; change that marker to a
format-agnostic identifier like `<commit-sha>` or `<oid>` in the
QUICK_REFERENCE.md table row for `GET /api/cms/show-version` so it matches the
SHA-256 discussion in docs/GETTING_STARTED.md and avoids implying a fixed 40-hex
length.
- Around line 137-145: Clarify the "Draft ref only → `draft`" rule so it states
that a draft-only ref yields `draft` only when there is no Status trailer or
when the trailer explicitly says `Status: draft`; otherwise a draft-only ref
with `Status: unpublished` or `Status: reverted` produces `unpublished` or
`reverted` respectively (update the text around the existing phrases "Draft ref
only → `draft`", "Status: unpublished", and "Status: reverted" to reflect this
conditional behavior).
- Around line 36-51: The CLI docs incorrectly state that the `revert` command
returns an article to the draft state; update the table in QUICK_REFERENCE.md so
the `revert` row (command `revert`, usage `git cms revert <slug>`) accurately
describes that it sets the article state to `reverted` (as performed by the
`revertArticle()` function) and updates the status trailer to `reverted`, rather
than saying it returns to `draft`; keep wording concise and consistent with the
state machine and tests.
- Around line 110-135: Update the ASCII state diagram in QUICK_REFERENCE.md to
match ContentStatePolicy.js: add an explicit arrow from DRAFT to REVERTED
labeled "revert" (showing DRAFT → REVERTED), and correct the separate reverted
block so the outgoing edge reads the actual action used to leave REVERTED (e.g.,
"restore" or "draft" transition) and points REVERTED → DRAFT; ensure the diagram
labels match the policy transitions for DRAFT, PUBLISHED, UNPUBLISHED, and
REVERTED as defined in ContentStatePolicy.js.
In `@scripts/check-doc-drift.sh`:
- Around line 56-63: The grep currently only matches links like
[text](GETTING_STARTED.md) in files directly under docs/; update the pattern
used for root_gs_links to allow an optional "../" prefix (so it matches both
GETTING_STARTED.md and ../GETTING_STARTED.md) and change the searched files from
"$ROOT"/docs/*.md to a recursive glob (e.g., "$ROOT"/docs/**/*.md) so files in
subdirectories like docs/operations/ are checked; adjust the grep invocation
that sets root_gs_links accordingly (refer to the root_gs_links variable and the
regex '\[.*\](GETTING_STARTED.md)' in the script).
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In `@QUICK_REFERENCE.md`:
- Around line 91-107: The HTTP API docs use a nonstandard `{ slug, sha? }`
notation for the POST /api/cms/publish body; replace the `sha?` with an
explicit, canonical form such as `sha (optional)` and add a parenthetical note
that omitting sha uses optimistic concurrency (or that the server accepts a
missing sha) so readers understand that `sha` is optional; update the table cell
for the POST /api/cms/publish entry and any matching references to `sha` to use
this explicit notation.
In `@scripts/check-doc-drift.sh`:
- Around line 36-41: The API endpoint check in scripts/check-doc-drift.sh uses
bare grep -q "$ep" which allows substring false-positives; update the loop that
iterates over api_paths to match the backticked path as documented in
QUICK_REFERENCE.md by changing the grep check to look for a literal
backtick-wrapped endpoint (use grep -q "\`$ep\`" or otherwise escape the
backticks) so that the test for $ep against $QUICK_REF only succeeds when the
exact `/api/...` path is documented; update the check inside the for loop that
currently references QUICK_REF and $ep.
- Around line 43-54: The deleted-file check uses the non-recursive glob
"$ROOT"/docs/*.md (see the offenders assignment) so references in docs
subdirectories are missed; update the offenders command to search docs
recursively — either replace the docs glob with a recursive grep invocation like
grep -r --include='*.md' "$file" "$ROOT" "$ROOT/docs" (so all subdirs under docs
are scanned) or enable shell globstar and use "$ROOT"/docs/**/*.md; keep the
rest of the filtering (grep -v ... ) and error handling the same.
added 2 commits
February 14, 2026 21:45
- Fix revert command description: sets state to 'reverted', not 'draft'
- Fix state machine diagram: add draft→reverted, fix reverted block semantics
- Clarify state derivation rule for draft-only refs
- Replace <40-hex> with <oid> for hash-format-agnostic docs
- Replace nonstandard { slug, sha? } with explicit optional notation
- Fix migration walkthrough: clarify no-dry-run vs idempotency
- Fix API endpoint substring matching in check-doc-drift.sh
- Fix deleted-file search to recurse into docs subdirectories
- Fix root GS links regex to handle relative path prefixes
Owner
Author
|
@coderabbitai review please 🥕 |
|
I will meticulously examine: Documentation Completeness & Accuracy:
Script Validation:
Consolidation Quality:
Metadata Precision:
Cross-File Consistency:
Executing thorough, unforgiving review now... ⚔️ ✅ Actions performedReview triggered.
|
Removed 'git config --global' from .github/workflows/ci.yml to ensure that local development environments (using tools like 'act') do not accidentally have their global git configuration modified by CI scripts. Now uses local repo configuration instead. Also updated CHANGELOG.md to reflect this security fix.
Using local 'git config' failed in CI environments where actions/checkout downloads a ZIP instead of cloning (e.g. containers without git). Switched to using 'git config --global' but redirected to a workspace-local file via GIT_CONFIG_GLOBAL to maintain host isolation while satisfying git's requirement for a configuration target.
- Refined QUICK_REFERENCE.md state machine diagram and derivation rules - Updated QUICK_REFERENCE.md HTTP API table with canonical optional notation - Clarified 'revert' command behavior in QUICK_REFERENCE.md - Updated GETTING_STARTED.md migration section with better bullet separation - Hardened check-doc-drift.sh recursive search and regex precision - Updated documentation validation banners to v1.1.5 - Updated CHANGELOG.md with v1.1.5 improvements
1. Redirected GIT_CONFIG_GLOBAL to /tmp and added 'touch' to ensure writeability and prevent lock file errors. 2. Moved 'Install Git' to the top of the e2e-test job to ensure 'actions/checkout' creates a proper .git directory.
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
1 participant
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
GETTING_STARTED.mdandREPO_WALKTHROUGH.mdreplaced with redirect stubs (content consolidated intodocs/GETTING_STARTED.mdandQUICK_REFERENCE.md)docs/GETTING_STARTED.mdupdated with version history browsing (CE3), migration workflows (M1.3), and unpublish/revert examplesREADME.mdupdated with missing CLI commands and choose-your-path navigation blockROADMAP.mdmilestone statuses updated (M1.1, M1.2, M1.3, CE2, CE3 → complete)scripts/check-doc-drift.shandnpm run check:docsfor automated doc drift detectionTest plan
npm run test:local— 77 tests passnpm run check:docs— all CLI commands and HTTP endpoints documented, no stale references