Skip to content

docs: restructure and polish safety and policy section#189

Merged
miyoungc merged 4 commits intomainfrom
miyoungc/polish-safety-privacy-doc
Mar 10, 2026
Merged

docs: restructure and polish safety and policy section#189
miyoungc merged 4 commits intomainfrom
miyoungc/polish-safety-privacy-doc

Conversation

@miyoungc
Copy link
Collaborator

@miyoungc miyoungc commented Mar 10, 2026

Reorganize the Safety and Privacy documentation section: remove the redundant security-model page, extract default policy content into its own page, polish the policies page, and add a Sphinx extension that auto-generates policy reference tables from YAML.

Part of #187

Changes

Documentation structure

  • Delete security-model.md — content was already covered by safety-and-privacy/index.md; keeping both created redundancy.
  • Add default-policies.md — new page documenting the built-in default policy, agent compatibility table (Claude Code / OpenCode / Codex), and what the default policy allows.
  • Add reference/default-policy.md — new reference page that uses the policy-table directive to render the full default policy from YAML.
  • Update toctree in index.md to replace security-model with default-policies.

Sphinx extension (docs/_ext/policy_table.py)

  • Custom directive (policy-table) that reads the sandbox policy YAML (dev-sandbox-policy.yaml) and auto-generates:
    • A Filesystem, Landlock, and Process summary table.
    • One subsection per network_policies block with endpoint tables (host, port, TLS, access/rules) and allowed binary lists.
  • Human-readable titles and descriptions for each known policy block (e.g., "Anthropic API and Telemetry", "Git Clone and Fetch", "Python Package Installation").
  • Registers the YAML as a Sphinx dependency so tables rebuild when the policy file changes.
  • Update docs/conf.py — register the _ext directory on sys.path and add policy_table to extensions.

Content polish (policies.md)

  • Move "Default Policy" section (agent compatibility table and related guidance) to the new default-policies.md page.
  • Rename "How do I edit it" → Hot-Reload Policy Updates.
  • Rename "If something is blocked" → Debug Denied Requests.
  • Tighten GitHub repo access example intro.
  • Remove bold formatting from numbered workflow steps.
  • Update Next Steps links.

Cross-reference fixes (5 files)

  • Update all security-model references → index or default-policies across overview.md, run-claude.md, run-opencode.md, providers.md, and index.md.
  • Fix duplicate link in run-claude.md where two Next Steps items both pointed to policies.md.

Test plan

  • mise run docs:serve builds without warnings or broken references
  • All cross-page links in the Safety and Privacy section resolve correctly
  • policy-table directive renders tables from the YAML in reference/default-policy.md

@miyoungc miyoungc added this to the gtc milestone Mar 10, 2026
@miyoungc miyoungc requested a review from kirit93 March 10, 2026 01:24
@miyoungc miyoungc self-assigned this Mar 10, 2026
@miyoungc miyoungc added the area:docs Documentation and examples label Mar 10, 2026
@miyoungc miyoungc changed the title docs: restructure safety and policy section docs: restructure and polish safety and policy section Mar 10, 2026
@miyoungc miyoungc merged commit c91c313 into main Mar 10, 2026
12 checks passed
@miyoungc miyoungc deleted the miyoungc/polish-safety-privacy-doc branch March 10, 2026 04:26
drew pushed a commit that referenced this pull request Mar 16, 2026
* restructure safty and policy section

* put the table autogeneration back

* enhance generate policy ref doc

* typo
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:docs Documentation and examples

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant