This repository was archived by the owner on Aug 10, 2026. It is now read-only.
docs: adopt the Krateo Documentation Standard - #51
Merged
Conversation
Replace the single drifted README with the invariant bundle (README +
docs/{index,overview,usage,configuration,api,examples,release,log}.md +
docs/llms.txt + examples/sample-resource/), every claim re-derived from
current source:
- the old README's env table diverged from main.go (workers 1 vs 5,
resync 1m vs 3m, max-error-retry-interval 30s vs 90s) and omitted the
hard-required REST_CONTROLLER_SERVICEACCOUNT_NAME/_NAMESPACE pair plus
the whole snowplow/authn and OTel surface; configuration.md now carries
the full verified flag/env table
- dead-org purge: krateoplatformops links (oasgen-provider README,
doc.crds.dev) and the krateoplatformops org in the usage example are gone
- api.md documents the executed RestDefinition surface (verbs, fieldMapping,
async A/B, RESTAction delegation, compareScope), the Configuration auth
contract, status/conditions/events and the self-provisioned secretRef RBAC
- runnable example mirrors the integration testdata (mock CRUD API via
ConfigMap-hosted OAS + bearer-auth Sample CR)
- wire the shared lint-docs conformance check into PR CI
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LJsLqtryCgWwEt8FnPE1se
- api.md: drift rewrites the Ready condition REASON (Resource is not up-to-date due to ...), not the message (restResources.go:399-401; condition.Unavailable() carries no message) - release.md: since the #50 migration release-tag.yaml's build job no longer needs test — the jobs start in parallel, so the suite runs on every tag but does not currently gate the image push - log.md: successCodes/tolerateCodes/notFoundCodes, static headers/queries and the async Model A engine first shipped in 0.10.0 (KOG M5/WS-B, 2026-07-10/11), not <=0.9.x - examples/sample-resource/README.md: the mockserver authenticates the bearer token 'test' (mockserver authenticate()), it does not accept any bearer token Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJsLqtryCgWwEt8FnPE1se
…ionFailed event, dead-org comment Re-verified the whole bundle against source: api.md claimed the Model B async operation handle is parked in status — it lives in the krateo.io/async-operation-* annotations (async_requeue.go), now documented, along with the AsyncOperationFailed Warning event the events list omitted; release-tag.yaml's stale braghettos/ chart-repo comment corrected (the script itself already derives the org from GITHUB_REPOSITORY). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJsLqtryCgWwEt8FnPE1se
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
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.
Converts rest-dynamic-controller to the Krateo Documentation Standard at pilot depth (reference: the merged snowplow pilot).
What's here
README.md+docs/{index,overview,usage,configuration,api,examples,release,log}.md+docs/llms.txt(pinned0.20.0) + one runnable example (examples/sample-resource/), all with OKF frontmatter.REST_CONTROLLER_WORKERSdocumented default1, actual5(main.go:72)REST_CONTROLLER_RESYNC_INTERVALdocumented1m, actual3m(main.go:75)REST_CONTROLLER_MAX_ERROR_RETRY_INTERVALdocumented30s, actual90s(main.go:90)REST_CONTROLLER_SERVICEACCOUNT_NAME/_NAMESPACEpair (main.go:130hard-fails without them) and the entire snowplow/authn (URL_SNOWPLOW,URL_AUTHN, token path) and OTel surface —docs/configuration.mdnow carries the full verified tablegithub.com/krateoplatformops/oasgen-providerlinks, thedoc.crds.dev/...krateoplatformops...reference andorg: krateoplatformopsin the usage example are goneserversoverride ininternal/tools/client/restclient.go) and preserved indocs/overview.mddocs/api.mddocuments the contract RDC actually executes: the RestDefinition verb surface (fieldMapping/resolvers/transforms, pagination, notFoundCodes/notFoundBody, async Models A/B, RESTAction delegation refs, the threecompareScopemodes), the<Kind>Configurationauth contract (basic/bearer/apiKey, whitespace-trimmed Secrets), status/conditions/events, and the self-provisioned per-CR secretRef RBAC.RestDefinition+ bearer-authSampleCR) with honest preconditions (the bundled mockserver implements the API); manifests are YAML-validated.lint-docsconformance check is wired intorelease-pullrequest.yaml; the extracted linter passes locally with 0 errors / 0 warnings.🤖 Generated with Claude Code
https://claude.ai/code/session_01LJsLqtryCgWwEt8FnPE1se