sbx: restructure governance docs and add API reference#25162
Draft
dvdksn wants to merge 9 commits into
Draft
Conversation
Splits the existing security/governance and security/policy pages into a new governance section with concepts, local, organization, monitoring, and API reference sub-pages, and adds a custom api-reference Hugo layout that renders the colocated OpenAPI 3 spec directly from the spec file. The layout reads the spec via transform.Unmarshal, resolves $ref nodes through a small returning partial, and overrides baseof's main block to take the full content width. The built-in right-rail TOC is replaced with a sticky endpoint navigator that groups operations by tag with method-colored pills. Each operation card shows method/path, summary, description, parameters, request body, and responses. Responses use native <details> elements so the list of status codes stays scannable; 2xx defaults to open. JSON examples are wrapped in the site's syntax-light/dark utility so Chroma classes pick up the theme. Each operation also exposes a copy-as-cURL button that assembles a ready-to-paste command from the spec's path and query parameter examples, the bearer-auth scheme (with $TOKEN as a literal placeholder), and the request body's default JSON example. A companion api-reference.markdown.md template renders the same spec as a clean markdown document so the page's "Copy Markdown" / "View Markdown" actions and the .md alternate link return real content instead of just the page title. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
This PR restructures sandbox governance docs into a clean multi-page hierarchy and adds an OpenAPI-rendered API reference page. The redirect aliases on local.md and org.md correctly cover the old security/policy and security/governance URLs. Two issues found in the newly added content.
Relocates the OpenAPI reference page bundle out of the product manual tree and into the canonical /reference/api/ section. The old URL keeps working via a Hugo alias on the new page. Under /ai/sandboxes/governance the sidebar still shows an "API reference" entry: a non-rendered stub page (build.render: never) with sidebar.goto pointing at the new location, so the link in the governance sidebar cross-references the reference section directly without bouncing through a placeholder page. The duplicate static/manuals/ai/sandboxes/governance/api.yaml is dropped now that the page resource is the single source of the spec. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The sidebar stub at content/manuals/ai/sandboxes/governance/api.md has build.render: never, so relative (api.md) links from sibling files resolved to an empty href once the bundle moved to the reference section. Updates org.md, local.md, concepts.md, and _index.md to link directly at the new URL. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Picks up upstream style fixes (drops "currently", removes meta "Note:" prefix) and overrides the doc-URL line that upstream regressed to the pre-restructure /security/governance/ path. Will be fixed upstream so the next re-vendor stays clean. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Re-vendors the OpenAPI spec from upstream, which now exposes UpdateRule with application/merge-patch+json (RFC 7396) instead of application/json. The layout, the curl-command builder, and the markdown template all previously hardcoded index .content "application/json", which would have silently dropped the new content. They now iterate the content map and pick the first declared media type, surface it as a small "Content type:" label, and use the same value in the generated curl Content-Type header. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Adds content/manuals/ai/sandboxes/governance/using-the-api.md as a task-oriented companion to the reference. The page sits between Monitoring and the AI Governance reference link in the sidebar (weight 28). Authentication is fully written out — a portable JWT exchange snippet that keeps the credential out of shell history and out of the process env. The walkthrough and recipe sections are TODO scaffolds for follow-up content authoring. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replaces the bespoke prerequisites bullet with the same paid- subscription callout that ai/sandboxes/governance/_index.md and org.md use, drops "Docker Hub" in favor of "Docker" in prose, and switches the access-requirement wording to "owner role in the organization". Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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
2 participants
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
Restructures the Docker AI Governance documentation under
/ai/sandboxes/governance/and adds the supporting API reference.Preview links:
Information architecture
The existing
security/governanceandsecurity/policypages are merged into a new top-levelgovernancesection so local-policy and org-policy sit side by side instead of being split across unrelated parents:/ai/sandboxes/governance/— section landing; explains local + org as layered enforcement/ai/sandboxes/governance/concepts/— resource model, rule syntax, evaluation, precedence/ai/sandboxes/governance/local/—sbx policyCLI for individual machines/ai/sandboxes/governance/org/— Admin Console flow (wassecurity/governance.md)/ai/sandboxes/governance/monitoring/—sbx policy ls/sbx policy log/ai/sandboxes/governance/using-the-api/— programmatic management (scaffold; see below)API reference
/reference/api/ai-governance/renders the Governance OpenAPI spec vendored atcontent/reference/api/ai-governance/api.yamlfromdocker/governor-services. Operations, schemas, examples, and status codes are fully driven by the spec — future updates land via re-vendor, not in-repo edits. Anything wrong in the rendered reference should be fixed upstream and re-vendored here.API usage guide (scaffold)
/ai/sandboxes/governance/using-the-api/is a task-oriented companion to the reference. The Authentication section is complete (JWT exchange against Docker Hub login, with a portable, shell-history-safe snippet). The walkthrough and recipe sections are TODO scaffolds for the governance team to fill in — a create-policy / add-rule / verify / update flow, plus common patterns like scoping, syncing from version control, and delegation.Review focus
/ai/sandboxes/governance/landing — does the local + org framing match how the product is positioned?/reference/api/ai-governance/— does the rendered spec match the source of truth, and is anything important missing?using-the-api/TODOs — what should the walkthrough demonstrate, and which common patterns deserve their own subsection?Generated by Claude Code