fix(docs): update Gray Swan API links and onboarding instructions in security README#12809
Conversation
all-hands-bot
left a comment
There was a problem hiding this comment.
Documentation update looks good overall. I found a few issues with the onboarding flow clarity that should be addressed.
| 2. Create a Gray Swan API key. | ||
| 3. If you just want to use Cygnal's default protections, you can move to the next section. | ||
| 4. If you want **even more** custom protection, you can create your own policy [here](https://platform.grayswan.ai/policies). Policies are composed of rules, which require a short title, e.g. "Git Operations", and then the rule itself, e.g. "The agent should never push code directly to the main branch". | ||
| 1. Existing Gray Swan customers should already have access to the platform. |
There was a problem hiding this comment.
🟠 Important: Step 1 mentions existing customers "should already have access to the platform" but doesn't tell them how to find or create their API key. The old version had "Create a Gray Swan API key" as step 2, which was clearer.
Suggestion: Add guidance like "Existing Gray Swan customers should already have access to the platform and can create or retrieve their API key from [platform link]."
| 4. If you want **even more** custom protection, you can create your own policy [here](https://platform.grayswan.ai/policies). Policies are composed of rules, which require a short title, e.g. "Git Operations", and then the rule itself, e.g. "The agent should never push code directly to the main branch". | ||
| 1. Existing Gray Swan customers should already have access to the platform. | ||
| 2. New users should [request a demo](https://hubs.ly/Q03-sX2z0) to get onboarded and receive API credentials. | ||
| 3. During onboarding, Gray Swan can also provide custom policy recommendations and integration support. |
There was a problem hiding this comment.
🟡 Suggestion: Step 3 is informational context about the onboarding process rather than an actionable step. This breaks the flow of the numbered list where other steps are user actions.
Consider rephrasing as a note under step 2: "New users should request a demo to get onboarded and receive API credentials. (Gray Swan can provide custom policy recommendations and integration support during onboarding.)"
| 1. Existing Gray Swan customers should already have access to the platform. | ||
| 2. New users should [request a demo](https://hubs.ly/Q03-sX2z0) to get onboarded and receive API credentials. | ||
| 3. During onboarding, Gray Swan can also provide custom policy recommendations and integration support. | ||
| 4. If you just want to use Cygnal's default protections, you can move to the next section. | ||
| 5. If you want **even more** custom protection, you can create your own policy [here](https://platform.grayswan.ai/policies). Policies are composed of rules, which require a short title, e.g. "Git Operations", and then the rule itself, e.g. "The agent should never push code directly to the main branch". |
There was a problem hiding this comment.
🟡 Suggestion: The overall flow mixes "getting access" (steps 1-3) with "configuration options" (steps 4-5). Consider restructuring for clarity:
For existing Gray Swan customers:
- Log into the platform and retrieve your API key
For new users:
- Request a demo to get onboarded and receive API credentials
- Gray Swan can provide custom policy recommendations during onboarding
Configuration:
- If using default protections, proceed to the next section
- For custom protection, create a policy here...
Summary of PR
Updates
openhands/security/README.mdin the Gray Swan section to reflect the new API key onboarding flow:Demo Screenshots/Videos
Change Type
Checklist
Fixes
Resolves #(issue)
Release Notes