docs: Refresh docs against current code

[sentry-junior]

Docs refresh for the whole repo, no audience filter. Only docs changed. No source files were touched.

Corrected against code

• docs/setup.md told you to set "path": "sentry-options/" in repos.json. copy_schemas (clients/rust/src/schema_fetch.rs) expects {namespace}/schema.json directly under that path, so the value as written copies no schemas. Every entry in the automator's real repos.json uses sentry-options/schemas.
• docs/setup.md pinned sentry-options 1.1.1 and the workflow and hook to SHA 0b115be, which is 82 commits behind main and older than 1.2.0. The same page tells you to use Options::builder(), which shipped in 1.2.0 and 1.2.1 (CHANGELOG.md). The pins now use 1.2.17, the current release on crates.io and PyPI, and the 1.2.17 tag commit.
• docs/setup.md, Rust section: manual refresh pointed at sentry_options.refresh, which is the Python name. In Rust, refresh() is only a method on an Options instance (clients/rust/src/lib.rs). The global store from .init() does not expose it. docs/architecture.md now documents .build() and this limitation.
• docs/options.md: the Rust test snippets called .get() on the Result that options("seer") returns, which does not compile. I fixed them and compiled them against the crate.
• docs/options.md, deleting a feature flag: the definition step only covered sentry's manager.add. It now names the schema.json entry for other services. The fallback behavior is now split by layer: the client returns False for a flag with no value (FeatureChecker::try_has).
• examples/README.md:
  • The deployment was named sentry-options-test, but kubectl logs targeted sentry-options-example.
  • The sample output was missing string-option, which examples/python/main.py prints.
  • "Watches for ConfigMap changes" and "within ~5 seconds" now describe refresh-on-read plus the kubelet sync delay.
  • I removed a personal sandbox project, a registry path, and a private-repo path, because this repo is public.

Restructured

• AGENTS.md now has the build, lint, and test commands from .github/workflows/main.yml and pyproject.toml. It also lists the invariants (maturin-only Python build, schema evolution rules, craft-generated changelog) and links both example READMEs.
• README.md: cut filler, linked the setup guide from the quickstart, and added where to get help and the license.
• docs/options.md: added the missing "Diffing effective values" entry to the table of contents.

Could not verify

• "our slack agent @jr will clean these up daily" (docs/options.md, deleting an option).
• What sentry and getsentry do when a flag registration is removed while checks remain ("reports the error to Sentry"). That code lives outside this repo.

Code looks wrong, not the doc

• The Rust global store has no public refresh(). As a result, Options::builder().with_refresh_threshold(None).init() freezes values for the life of the process. Python has sentry_options.refresh() for the same mode.
• The sentry_options/__init__.py module docstring says the library "watches for file changes". It actually refreshes on read. I reported this instead of editing it, because this pass does not change source.
• No CI job runs the root tests/gen_stubs_test.py. It passes locally.
• In Cargo.toml, the [workspace.dependencies] sentry-options version is still 1.2.11. scripts/bump-version.sh does not update it.

Not covered

• CHANGELOG.md is a dated record that craft generates, so I left it alone.
• I did not review rustdoc or docstring comments beyond the items above.
• The repo skills in .claude/skills defer to the docs. I checked them and they did not need changes.

via @joshuarli.

--

View Junior Session [Sentry]