docs: align README and docs with linting-and-guardrails positioning#408
Merged
Conversation
Deploying archgate-cli with
|
| Latest commit: |
d9700cd
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://33961e20.archgate-cli.pages.dev |
| Branch Preview URL: | https://docs-positioning-update.archgate-cli.pages.dev |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThis PR replaces "governance" wording with "guardrails" and updates marketing/site strings to emphasize "enterprise-grade linting and guardrails for AI work" across README, site config, homepage, getting-started guides, plugin docs, consolidated LLM context, CI callouts, and shim README files. ChangesGuardrails Messaging Rebranding
🎯 1 (Trivial) | ⏱️ ~5 minutes
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/astro.config.mjs (1)
1-1:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winNote: Pipeline formatting check failed.
The pipeline reports oxfmt formatting issues for this file. Run
oxfmt --write .to apply fixes before merging.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/astro.config.mjs` at line 1, The file docs/astro.config.mjs failed the oxfmt check; run the formatter to fix formatting (run `oxfmt --write .` as instructed) and commit the updated docs/astro.config.mjs (the import line referencing "`@astrojs/starlight`" will be reformatted). After applying the formatter, re-run the pipeline or CI to ensure the oxfmt check passes.Source: Pipeline failures
docs/src/content/docs/guides/vscode-plugin.mdx (1)
44-44:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winComplete the rebranding: update "governance directory" to align with guardrails messaging.
This line still refers to the
.archgate/directory using "governance" terminology, which is inconsistent with the rebranding effort applied throughout this PR. The description, intro (line 6), and workflow section (line 109) all correctly use "guardrails" terminology.📝 Suggested fix
-1. Creates the `.archgate/` governance directory (ADRs, lint rules) +1. Creates the `.archgate/` directory with ADRs and lint rulesor
-1. Creates the `.archgate/` governance directory (ADRs, lint rules) +1. Creates the `.archgate/` guardrails directory (ADRs, lint rules)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/src/content/docs/guides/vscode-plugin.mdx` at line 44, Replace the phrase "governance directory (ADRs, lint rules)" and any direct reference to ".archgate/" in this line with the rebranded "guardrails directory (ADRs, lint rules)" (or otherwise align the wording to use "guardrails") so the description matches the rest of the doc; search for the string ".archgate/" and the term "governance directory" in the VS Code plugin doc and update this occurrence to use "guardrails" terminology.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/astro.config.mjs`:
- Around line 17-18: The structured data JSON-LD still uses the old phrase
"automated code governance" while the page-level description (the description
field) was updated to "Enterprise-grade linting and guardrails for AI work.";
update the JSON-LD blocks for WebSite and SoftwareApplication to use the same
messaging. Locate the JSON-LD objects named WebSite and SoftwareApplication in
this file and replace their description values (the properties currently
containing "automated code governance") with the new phrase "Enterprise-grade
linting and guardrails for AI work." so search-indexed metadata matches the page
description.
In `@docs/public/llms-full.txt`:
- Line 95: The generated docs/public/llms-full.txt is stale; regenerate it by
running the generation script and commit the updated file: run `bun run
docs/scripts/generate-llms-full.ts` (or the equivalent docs generator command in
your environment) to produce a fresh docs/public/llms-full.txt, verify the
output, stage and recommit the updated file so CI validation passes.
---
Outside diff comments:
In `@docs/astro.config.mjs`:
- Line 1: The file docs/astro.config.mjs failed the oxfmt check; run the
formatter to fix formatting (run `oxfmt --write .` as instructed) and commit the
updated docs/astro.config.mjs (the import line referencing "`@astrojs/starlight`"
will be reformatted). After applying the formatter, re-run the pipeline or CI to
ensure the oxfmt check passes.
In `@docs/src/content/docs/guides/vscode-plugin.mdx`:
- Line 44: Replace the phrase "governance directory (ADRs, lint rules)" and any
direct reference to ".archgate/" in this line with the rebranded "guardrails
directory (ADRs, lint rules)" (or otherwise align the wording to use
"guardrails") so the description matches the rest of the doc; search for the
string ".archgate/" and the term "governance directory" in the VS Code plugin
doc and update this occurrence to use "guardrails" terminology.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 3b87b433-c1cf-4201-8a6d-3d9b527096af
📒 Files selected for processing (12)
README.mddocs/astro.config.mjsdocs/public/llms-full.txtdocs/src/content/docs/getting-started/installation.mdxdocs/src/content/docs/getting-started/quick-start.mdxdocs/src/content/docs/guides/ci-integration.mdxdocs/src/content/docs/guides/claude-code-plugin.mdxdocs/src/content/docs/guides/copilot-cli-plugin.mdxdocs/src/content/docs/guides/cursor-integration.mdxdocs/src/content/docs/guides/opencode-integration.mdxdocs/src/content/docs/guides/vscode-plugin.mdxdocs/src/content/docs/index.mdx
Update all user-facing documentation to lead with "linting and guardrails" instead of "governance" or "ADRs as executable rules": - README tagline and opening paragraph - Docs site meta description, hero tagline, and card titles - JSON-LD structured data descriptions - OG image alt text and meta keywords - Editor plugin guide intros (Claude Code, Cursor, VS Code, Copilot, OpenCode) - Getting-started and CI integration pages ADRs and governance remain in explanatory body content. Only headline and intro language was updated. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
rhuanbarreto
force-pushed
the
docs/positioning-update
branch
from
26cf4b3 to
56fa1ff
Compare
Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/public/llms-full.txt (1)
3-13:⚠️ Potential issue | 🟠 Major | ⚡ Quick winRegenerate
docs/public/llms-full.txt; it still contains pre-rebrand lead copy.This generated file still starts with old “governance” positioning (Lines 3, 11-13), which is inconsistent with the PR’s guardrails-first objective and indicates the artifact is stale/partially regenerated.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/public/llms-full.txt` around lines 3 - 13, The top of docs/public/llms-full.txt still uses pre-rebrand “governance” lead copy; regenerate and replace the lead paragraph and any lines mentioning “governance” with the PR’s guardrails-first messaging so the file reflects the new positioning. Rerun the docs generator or the script that produces llms-full.txt, update the opening sentence (the first paragraph describing Archgate and ADRs) and the bullets that reference “AI governance”/“governance” to use “guardrails-first” language and guardrail-focused phrasing, then save the regenerated file so the content is consistent with the guardrails-first objective.Source: Pipeline failures
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@docs/public/llms-full.txt`:
- Around line 3-13: The top of docs/public/llms-full.txt still uses pre-rebrand
“governance” lead copy; regenerate and replace the lead paragraph and any lines
mentioning “governance” with the PR’s guardrails-first messaging so the file
reflects the new positioning. Rerun the docs generator or the script that
produces llms-full.txt, update the opening sentence (the first paragraph
describing Archgate and ADRs) and the bullets that reference “AI
governance”/“governance” to use “guardrails-first” language and
guardrail-focused phrasing, then save the regenerated file so the content is
consistent with the guardrails-first objective.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 12e2332a-7bd9-427d-8094-b181751ab9ac
📒 Files selected for processing (12)
README.mddocs/astro.config.mjsdocs/public/llms-full.txtdocs/src/content/docs/getting-started/installation.mdxdocs/src/content/docs/getting-started/quick-start.mdxdocs/src/content/docs/guides/ci-integration.mdxdocs/src/content/docs/guides/claude-code-plugin.mdxdocs/src/content/docs/guides/copilot-cli-plugin.mdxdocs/src/content/docs/guides/cursor-integration.mdxdocs/src/content/docs/guides/opencode-integration.mdxdocs/src/content/docs/guides/vscode-plugin.mdxdocs/src/content/docs/index.mdx
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
shims/go/README.md (1)
47-47:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUpdate Quick start comment to match rebranding.
The Quick start section comment still says "Initialize governance in your project," but the PR rebrand replaces "governance" with "linting and guardrails" throughout user-facing text. Consider updating to "Initialize linting and guardrails in your project" or similar phrasing to maintain consistency with the new positioning.
📝 Suggested fix
-# 1. Initialize governance in your project +# 1. Initialize linting and guardrails in your project🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@shims/go/README.md` at line 47, Update the Quick start heading text to use the rebranded phrasing: replace the heading string "# 1. Initialize governance in your project" in shims/go/README.md with something like "# 1. Initialize linting and guardrails in your project" (or equivalent wording) so the user-facing text matches the new "linting and guardrails" positioning.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@shims/go/README.md`:
- Line 47: Update the Quick start heading text to use the rebranded phrasing:
replace the heading string "# 1. Initialize governance in your project" in
shims/go/README.md with something like "# 1. Initialize linting and guardrails
in your project" (or equivalent wording) so the user-facing text matches the new
"linting and guardrails" positioning.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: abe68d37-e4f3-43fe-9ebd-0f70e378b09e
📒 Files selected for processing (5)
shims/go/README.mdshims/maven/README.mdshims/nuget/Archgate.Tool/README.mdshims/pypi/README.mdshims/rubygem/README.md
Apply the same linting-and-guardrails positioning to all translated docs pages: update descriptions, intros, card titles, and table entries from "governance/styring" to "guardrails" in both pt-BR and Norwegian. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/src/content/docs/pt-br/index.mdx`:
- Line 3: Standardize the terminology by replacing the English loanword
"enterprise" with the Portuguese term "empresarial" so both occurrences are
consistent; update the phrase "Linting e guardrails de nível enterprise" to
"Linting e guardrails de nível empresarial" and ensure the other instance
currently using "empresarial" stays unchanged, verifying no other occurrences in
the same file differ.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 5f4245e9-866d-4f6b-9b13-10775728d1fc
📒 Files selected for processing (10)
docs/src/content/docs/nb/guides/copilot-cli-plugin.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/nb/guides/opencode-integration.mdxdocs/src/content/docs/nb/guides/vscode-plugin.mdxdocs/src/content/docs/nb/index.mdxdocs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/guides/opencode-integration.mdxdocs/src/content/docs/pt-br/guides/vscode-plugin.mdxdocs/src/content/docs/pt-br/index.mdx
Update getting-started and guide pages in pt-BR and Norwegian to match the English positioning changes: installation, quick-start, ci-integration, and claude-code-plugin pages now lead with guardrails instead of governance. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Contributor
Code Coverage
Full HTML report available in workflow artifacts. Per-directory breakdown
|
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/public/llms-full.txt (1)
1-1:⚠️ Potential issue | 🟠 Major | ⚡ Quick winRegenerate and recommit this generated file to unblock CI.
The current pipeline still fails with
git diff --exit-code docs/public/llms-full.txt, which means this artifact is not in sync with source docs. Re-runbun run docs/scripts/generate-llms-full.tsand commit the regenerated output.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/public/llms-full.txt` at line 1, Regenerate the out-of-sync artifact by running the docs generation script and recommit the result: run the generator (bun run docs/scripts/generate-llms-full.ts), verify docs/public/llms-full.txt is updated (no changes reported by git diff --exit-code), and commit/push the regenerated docs/public/llms-full.txt so the CI check passes.Source: Pipeline failures
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@docs/public/llms-full.txt`:
- Line 1: Regenerate the out-of-sync artifact by running the docs generation
script and recommit the result: run the generator (bun run
docs/scripts/generate-llms-full.ts), verify docs/public/llms-full.txt is updated
(no changes reported by git diff --exit-code), and commit/push the regenerated
docs/public/llms-full.txt so the CI check passes.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: c0ed509d-38b2-4705-bd79-6cc06ea92bd0
📒 Files selected for processing (9)
docs/public/llms-full.txtdocs/src/content/docs/nb/getting-started/installation.mdxdocs/src/content/docs/nb/getting-started/quick-start.mdxdocs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/nb/guides/claude-code-plugin.mdxdocs/src/content/docs/pt-br/getting-started/installation.mdxdocs/src/content/docs/pt-br/getting-started/quick-start.mdxdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/pt-br/guides/claude-code-plugin.mdx
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/public/llms-full.txt (1)
1-1:⚠️ Potential issue | 🟠 Major | ⚡ Quick winRegenerate and recommit
docs/public/llms-full.txtto unblock CI.Validation is still failing because the generated artifact is stale. Re-run the generator and commit the refreshed output.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/public/llms-full.txt` at line 1, The generated artifact docs/public/llms-full.txt is stale; re-run the repository's documentation generator that produces llms-full.txt to regenerate the file, verify the updated output, stage and recommit the refreshed docs/public/llms-full.txt, and push the commit so CI picks up the updated artifact.Source: Pipeline failures
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@docs/public/llms-full.txt`:
- Line 1: The generated artifact docs/public/llms-full.txt is stale; re-run the
repository's documentation generator that produces llms-full.txt to regenerate
the file, verify the updated output, stage and recommit the refreshed
docs/public/llms-full.txt, and push the commit so CI picks up the updated
artifact.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: ef5df1af-63b4-4b84-a585-6b5f108c7c60
📒 Files selected for processing (9)
docs/public/llms-full.txtdocs/src/content/docs/nb/getting-started/installation.mdxdocs/src/content/docs/nb/getting-started/quick-start.mdxdocs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/nb/guides/claude-code-plugin.mdxdocs/src/content/docs/pt-br/getting-started/installation.mdxdocs/src/content/docs/pt-br/getting-started/quick-start.mdxdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/pt-br/guides/claude-code-plugin.mdx
Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
This was referenced Jun 11, 2026
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
Aligns all user-facing documentation with the new positioning adopted 2026-06-09: lead with linting and guardrails, not "governance" or "ADRs".
index.mdx) -- updated hero tagline, meta description, card title ("AI Agent Integration" instead of "AI-Aware Governance"), and editor-plugin section languageastro.config.mjs) -- updated global site descriptionADRs and governance remain in all explanatory and body-level content (How it Works sections, rule descriptions, domain docs, etc.) -- only the lead/headline language was updated.
Test plan
cd docs && bun run build).mdxfilesSummary by CodeRabbit