Simplify All Documentation and Deduplicate Agent Skills - #121
Merged
Conversation
Rewrite every doc page, AGENTS.md, CONTRIBUTING.md, README.md, and the project skills in plain language: shorter sentences, no em-dashes, no filler, and each rule stated once. Fix privacy.md and architecture.md, which still said Claude access is strictly read-only after guarded Claude Code token renewal shipped. Remove the eleven un-prefixed duplicate skill folders under .agents/skills and keep the macos-* set. Claude-Session: https://claude.ai/code/session_014qB9EhTjgafts2Y6V31wyf
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
There was a problem hiding this comment.
🟡 Changes recommended
.agents/README.md claims a .claude symlink exists, but no .claude entry is present in the repo checkout, so the documentation is currently inaccurate.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR rewrites Runway’s documentation for clearer, more skimmable prose, corrects outdated Claude credential/renewal descriptions, and deduplicates the vendored macOS agent-skill bundle by removing the older unprefixed copies.
Changes:
- Rewrite and streamline markdown docs across
docs/plus repo policy files (README-like docs, CONTRIBUTING, security/trademark, PR template) without intended behavior changes. - Update privacy/refreshing/provider docs to reflect guarded Claude Code token renewal and current credential handling.
- Remove the duplicate unprefixed macOS skill set under
.agents/skills/*and keep themacos-*versions; update remaining skill docs and references.
File summaries
| File | Description |
|---|---|
| TRADEMARK.md | Simplifies trademark policy wording. |
| SECURITY.md | Simplifies vulnerability reporting instructions and scope wording. |
| docs/updates.md | Rewords update mechanism and appcast/domain notes for clarity. |
| docs/research/grok-remaining-resets.md | Plain-language rewrite of Grok reset-token research notes. |
| docs/research/codex-reset-credit-claim.md | Plain-language rewrite of Codex reset-credit protocol notes. |
| docs/releasing.md | Reorganizes and clarifies release setup and workflows. |
| docs/refreshing.md | Clarifies refresh/caching behavior and keychain UI guarantees. |
| docs/README.md | Rewords documentation index/section blurbs. |
| docs/proxy.md | Clarifies proxy configuration and behavior details. |
| docs/providers/zai.md | Simplifies Z.ai provider docs and troubleshooting phrasing. |
| docs/providers/sakana.md | Simplifies Sakana provider docs and troubleshooting phrasing. |
| docs/providers/openrouter.md | Simplifies OpenRouter provider docs and troubleshooting phrasing. |
| docs/providers/opencode.md | Simplifies OpenCode provider docs and troubleshooting phrasing. |
| docs/providers/muse.md | Simplifies Muse provider docs and troubleshooting phrasing. |
| docs/providers/kimi.md | Simplifies Kimi provider docs and troubleshooting phrasing. |
| docs/providers/grok.md | Simplifies Grok provider docs and troubleshooting phrasing. |
| docs/providers/devin.md | Simplifies Devin provider docs and troubleshooting phrasing. |
| docs/providers/cursor.md | Simplifies Cursor provider docs and troubleshooting phrasing. |
| docs/providers/antigravity.md | Simplifies Antigravity provider docs and troubleshooting phrasing. |
| docs/provider-enablement.md | Clarifies first-run and new-provider enablement rules. |
| docs/privacy.md | Updates credential-handling statements, including guarded Claude renewal. |
| docs/pricing.md | Simplifies pricing-layering and resolution explanation. |
| docs/performance.md | Rewords benchmarks/methodology for readability. |
| docs/menu-bar.md | Simplifies menu-bar behavior documentation. |
| docs/memory-explorer.md | Simplifies memory explorer behavior documentation. |
| docs/logging.md | Clarifies logging behavior, redaction, and rotation in plainer language. |
| docs/local-http-api.md | Simplifies API docs while retaining contract details. |
| docs/icloud-sync.md | Simplifies iCloud sync behavior and setup explanation. |
| docs/cli.md | Simplifies CLI behavior and limitations explanation. |
| docs/adding-a-provider.md | Simplifies provider authoring guide; preserves core contract points. |
| CONTRIBUTING.md | Simplifies contribution rules/workflow and acceptance criteria. |
| AGENTS.md | Reorders/condenses engineering conventions and PR/release guidance. |
| .github/PULL_REQUEST_TEMPLATE.md | Simplifies PR template wording and guidance comments. |
| .agents/skills/window-management/SKILL.md | Removes duplicate unprefixed skill (keeps macos-window-management). |
| .agents/skills/view-refactor/SKILL.md | Removes duplicate unprefixed skill (keeps macos-view-refactor). |
| .agents/skills/test-triage/SKILL.md | Removes duplicate unprefixed skill (keeps macos-test-triage). |
| .agents/skills/telemetry/SKILL.md | Removes duplicate unprefixed skill (keeps macos-telemetry). |
| .agents/skills/swiftui-patterns/SKILL.md | Removes duplicate unprefixed skill (keeps macos-swiftui-patterns). |
| .agents/skills/swiftui-patterns/references/windowing.md | Removes duplicate unprefixed reference content. |
| .agents/skills/swiftui-patterns/references/split-inspectors.md | Removes duplicate unprefixed reference content. |
| .agents/skills/swiftui-patterns/references/settings.md | Removes duplicate unprefixed reference content. |
| .agents/skills/swiftui-patterns/references/menu-bar-extra.md | Removes duplicate unprefixed reference content. |
| .agents/skills/swiftui-patterns/references/components-index.md | Removes duplicate unprefixed reference content. |
| .agents/skills/swiftui-patterns/references/commands-menus.md | Removes duplicate unprefixed reference content. |
| .agents/skills/swiftpm-macos/SKILL.md | Removes duplicate unprefixed skill (keeps macos-swiftpm). |
| .agents/skills/signing-entitlements/SKILL.md | Removes duplicate unprefixed skill (keeps macos-signing-entitlements). |
| .agents/skills/pricing-update/SKILL.md | Rewrites pricing-update skill text for clarity without procedural intent changes. |
| .agents/skills/packaging-notarization/SKILL.md | Removes duplicate unprefixed skill (keeps macos-packaging-notarization). |
| .agents/skills/liquid-glass/SKILL.md | Removes duplicate unprefixed skill (keeps macos-liquid-glass). |
| .agents/skills/build-run-debug/SKILL.md | Removes duplicate unprefixed skill (keeps macos-build-run-debug). |
| .agents/skills/build-run-debug/references/build-script.md | Removes duplicate unprefixed reference content. |
| .agents/skills/build-and-run-macos-app/SKILL.md | Updates cross-reference to the macos-build-run-debug reference path. |
| .agents/skills/appkit-interop/SKILL.md | Removes duplicate unprefixed skill (keeps macos-appkit-interop). |
| .agents/skills/appkit-interop/references/window-panels.md | Removes duplicate unprefixed reference content. |
| .agents/skills/appkit-interop/references/responder-menus.md | Removes duplicate unprefixed reference content. |
| .agents/skills/appkit-interop/references/representables.md | Removes duplicate unprefixed reference content. |
| .agents/skills/appkit-interop/references/drag-drop-pasteboard.md | Removes duplicate unprefixed reference content. |
| .agents/README.md | Rewrites agent-skill bundle README to match the deduped layout. |
Review details
- Files reviewed: 68/68 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The credential ownership section said Runway has no Keychain write path. ClaudeCredentialWriteBack is that path, used only by guarded Claude Code renewal, which the next paragraph already described. Claude-Session: https://claude.ai/code/session_01NSawiwVuDgrYSPoqhe9jkL
There was a problem hiding this comment.
🟢 Approval recommended
The changes are documentation/skill-bundle cleanups with only minor wording consistency nits identified.
Review details
Suppressed comments (4)
Previously missed (2) — in code that hasn't changed since the last review.
docs/logging.md:44
- Grammar/wording: “(500 byte)” should be “(500-byte)” (or “500 bytes”).
docs/performance.md:14 - This page mixes the terms “popover” and “popup”. Elsewhere in the docs (and in macOS terminology for a status item) the UI is consistently called a “popover”, so using “popup” here is inconsistent and may confuse readers.
This issue also appears in the following locations of the same file:
- line 34
- line 45
docs/performance.md:34
- Use “popover” consistently (this page already mentions a “popover render path” above).
docs/performance.md:45 - Use “popover” consistently with the rest of the docs.
- Files reviewed: 68/68 changed files
- Comments generated: 0 new
- Review effort level: Lite
Carry the Muse, Kimi, Codex, and OpenCode doc updates from main into the rewritten pages. Claude-Session: https://claude.ai/code/session_01NSawiwVuDgrYSPoqhe9jkL
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
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.
TL;DR
Rewrite all documentation in plain language, fix two pages that described outdated Claude credential behavior, and remove the duplicate copy of the vendored macOS agent skills.
What was happening
$0.00, "most PRs are closed by design").docs/privacy.mdanddocs/architecture.mdstill said Claude access is strictly read-only and Runway never refreshes a Claude token. That has been wrong since guarded Claude Code renewal shipped in Keychain: durable approvals, silent reads, and guarded token renewal #99, and contradicteddocs/providers/claude.md..agents/skillsheld two copies of the OpenAI macOS skill bundle: an older un-prefixed set and the newermacos-*set.What this changes
docs/, plus README, AGENTS.md, CONTRIBUTING.md, SECURITY.md, TRADEMARK.md, and the PR template, is rewritten for plain, skimmable prose. Behavior and facts are unchanged. About 1,775 lines removed and 968 added.@AGENTS.md..agents/README.mdis rewritten, and the one stale cross-reference inbuild-and-run-macos-appnow points atmacos-build-run-debug. Therelease-swiftandpricing-updateskills are rewritten in the same style with no procedural changes.Heads-up
CHANGELOG.mdand the vendoredmacos-*skill bodies are untouched on purpose.Tests
SecurityCLIUsageTestsscans.agents/skillsforsecurityCLI calls. The remaining files contain none.https://claude.ai/code/session_014qB9EhTjgafts2Y6V31wyf