docs: add CoSAI persona mapping and expand install-path documentation#60
Conversation
Add a dedicated Choosing an Install Path page that compares every supported install route, a CoSAI Personas page that explains who is responsible for implementing each route, and cross-link the existing Getting Started page so persona ownership is consistent across the documentation. - docs/install-paths.md: new route comparison (rule files, Agent Skills, plugin marketplace, remote instructions, org-managed dashboards, MCP), project vs user scope guidance, audience-based recommendations, and a Responsible CoSAI Personas Per Install Route mapping. - docs/personas.md: new page summarizing the eight CoSAI personas in the context of CodeGuard deployment, with detail for the personas that directly implement install routes. - docs/getting-started.md: add a Responsible CoSAI personas callout and persona notes on Build from Source and the automated update workflow. - docs/images/codeguard-install-flowchart.svg: supporting flowchart. - mkdocs.yml: register the new CoSAI Personas page in the nav. Made-with: Cursor
There was a problem hiding this comment.
Pull request overview
Adds new documentation to help readers choose among CodeGuard install routes and understand CoSAI persona ownership across individual, team, and org deployments.
Changes:
- Add a new “Choosing an Install Path” page covering supported delivery mechanisms, scope guidance, and a per-route persona mapping.
- Add a new “CoSAI Personas” page summarizing persona responsibilities in the context of CodeGuard.
- Update Getting Started and MkDocs navigation to link and surface the new pages (and include a new install-route flowchart SVG).
Reviewed changes
Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Adds new docs pages to the site navigation in the intended order. |
| docs/install-paths.md | New install-route comparison/decision guide with scope guidance and persona mapping. |
| docs/personas.md | New persona overview page with links back to install-route mapping. |
| docs/getting-started.md | Adds links/callouts pointing to the new install-path and persona docs, plus the flowchart image. |
| docs/images/codeguard-install-flowchart.svg | New visual flowchart illustrating install routes per tool. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
santosomar
left a comment
There was a problem hiding this comment.
Thanks for adding this, Aaron! This persona mapping is exactly the kind of cross-project linkage we need between Project CodeGuard and the rest of the CoSAI ecosystem. A few alignment notes to make sure docs/personas.md stays in lockstep with the canonical persona model in secure-ai-tooling:
The authoritative persona definitions live in the CoSAI RM repo secure-ai-tooling/risk-map/tables/personas-full.md. The persona titles you reference in getting-started.md (Application Developer, Agentic Platform and Framework Providers, AI System Governance, AI Platform Provider) already match verbatim, this is great!
Eventually, we coud strengthen alignment inside personas.md to use the Risk Map persona IDs (e.g., personaApplicationDeveloper, personaAgenticProvider, personaGovernance, personaPlatformProvider) alongside the human-readable titles. This gives us machine-linkable anchors if/when CodeGuard rules are cross-referenced from the Risk Map or the Shared Responsibility Model.
One thing to change is to avoid the deprecated personas. personaModelCreator and personaModelConsumer are explicitly marked Deprecated in the Risk Map — if they appear anywhere in CodeGuard docs, please replace with the modern successors (Model Provider, Application Developer, or AI System Users depending on context).
This is a good suggestion. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
|
@davidlabianca PTAL ;-) |
davidlabianca
left a comment
There was a problem hiding this comment.
lgtm - nice integration of the CoSAI-RM personas...
Summary
Expands the CodeGuard documentation to cover every supported install route
and adds CoSAI persona mappings so readers know who is responsible for
implementing and operating each route across individual, team, and
organization deployments.
What's included
Documentation
docs/install-paths.md(new)Agent Skills, plugin marketplace, remote instructions/installer,
org-managed vendor dashboards, and self-hosted MCP.
Cursor Team Rules, GitHub Copilot organization custom instructions,
and Claude Code managed settings.
team/repository, and organization-wide deployments.
route to its primary and supporting personas.
docs/personas.md(new)CodeGuard deployment.
install paths (Application Developer, AI System Governance, Agentic
Platform and Framework Providers, AI Platform Provider, AI System
Users).
Data Provider, AI Model Serving) and cross-links back to the
install-path mapping.
docs/getting-started.md(updated)CoSAI personas and linking to the personas page and per-route
mapping.
Option 2: Build from SourceandKeeping Rules Updated (Automated)for consistency with the otherdocs.
docs/images/codeguard-install-flowchart.svg(new)install-path page.
mkdocs.yml(updated)install-path page and the Claude Code plugin page.
Test plan
uv run python src/validate_unified_rules.py sources/uv run python src/convert_to_ide_formats.pyuv run mkdocs serveto confirm the new pages render and navigationis correct.
install-path page and the getting-started page.
Out of scope for this PR
docs/install-route-test-plan.mdand thetests/install-routes/evaluation kit are being prepared as a separate follow-up PR so the
test plan ships alongside the fixtures, prompts, and results template
it relies on.
Made with Cursor