docs: streamline README, add policy prover to architecture docs - #3718
Merged
Merged
Conversation
drew
requested review from
a team,
derekwaynecarr,
mrunalp and
sjenning
as code owners
September 25, 2026 17:20
drew
changed the title
|
🌿 Preview your docs: https://nvidia-preview-pr-3718.docs.buildwithfern.com/openshell |
pimlock
previously approved these changes
Sep 25, 2026
pimlock
previously approved these changes
Sep 25, 2026
Restructure the README as a short path from overview to quickstart to further reading. Move prerelease install steps into the installation guide and telemetry build flags into a new observability page. Fix broken docs links and outdated runtime and credential descriptions. Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
…guide Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
… step Import the example Anthropic profile, which now allows OpenCode, instead of editing it with sed. Add a step that shows how to review and approve mechanistic policy proposals as the agent needs more access. Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Add an example OpenRouter provider profile scoped to OpenCode and switch the first-agent guide to it, using a free Nemotron model so readers do not need OpenRouter credits. Revert the OpenCode binary added to the example Anthropic profile. Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
drew
force-pushed
the
codex/readme-improvements
branch
from
September 25, 2026 20:26
e38a861 to
1cdd88d
Compare
drew
enabled auto-merge
September 25, 2026 20:47
drew
disabled auto-merge
September 25, 2026 20:53
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 README as a short path from overview to quickstart to further reading (377 → 102 lines). Reference material the README duplicated now lives in the published docs, and two content gaps in the docs are filled so nothing is lost.
Related Issue
No issue required: documentation restructuring with no behavior change.
Changes
README.md: new outline: how it works, quickstart, short policy example, explore-further links, SDK table, community, short telemetry section. Removed the Terminal UI section and screenshot, Key Commands and Protection Layers tables, GPU/BYOC/Helm/prerelease command blocks, and the long Built With Agents/Contributing text (still covered in AGENTS.md and CONTRIBUTING.md). Notice and Disclaimer and License are unchanged.
docs/about/installation.mdx: adds a "Prerelease and Development Builds" section (
OPENSHELL_VERSION=pre/dev, Helm prerelease and dev chart versions), moved from the README.docs/observability/telemetry.mdx (new): what is and isn't collected, runtime opt-out,
defaults-without-telemetrybuilds, and compute-driver Cargo features. Nothing underdocs/covered these before.Accuracy fixes:
/about/run-an-agent(now/about/run-your-first-agent) and drops the broken/tutorials/github-sandboxlink.NetworkPolicyrequirement inline.The
README.md#telemetryanchor used bytelemetry/*.mdis preserved.Policy prover in architecture docs: adds the prover as a gateway component in the system architecture diagram, the component table in
docs/about/architecture.mdx, and the mermaid chart and Core Boundaries table inarchitecture/README.md. Covers both its gateway role (checks proposed policy changes; any finding blocks auto-approval) and the standaloneopenshell-prover checkcommand.Tagline: "autonomous AI agents" becomes "fleets of autonomous AI agents" in the README, docs home and overview pages, and
architecture/README.md. Package metadata is unchanged.Testing
mise run pre-commitpassesChecklist
Reviewer note: the "New in OpenShell 0.1.0" callout is unchanged, but the latest published release is v0.0.116. Consider rewording or removing it until 0.1.0 ships.