Skip to content

docs: make flux documentation match the code - #126

Merged
Patel230 merged 8 commits into
mainfrom
docs/flux-truth
Sep 29, 2026
Merged

docs: make flux documentation match the code#126
Patel230 merged 8 commits into
mainfrom
docs/flux-truth

Conversation

@Patel230

@Patel230 Patel230 commented Sep 29, 2026

Copy link
Copy Markdown
Contributor

Documentation-only plus one script fix, carried over from a branch that never got a PR. Rebased onto current main.

  • drop the nonexistent flux serve binary from the architecture docs
  • describe runtime as engine-internal, and guard the frozen symbols
  • describe the gRPC transport as the opt-in path it is
  • derive the provider count, table and env example from the registry instead of hardcoding them, so they cannot drift
  • point AGENTS.md and the README tree at files that exist

go build ./... and go test ./... both pass locally (GOWORK=off).

@Patel230
docs(runtime): describe runtime as engine-internal
c89a884 
The runtime package comment called runtime the recommended host entry
point, listed provider/catalog/config/credentials/setup/storage as the
packages hosts import, and claimed the registry holds 16 providers. The
host contract is engine/llm/graph/tools, rho imports none of those
packages directly, and catalog/registry defines 28 providers.

Rewrite the comment to say runtime is engine-internal and not covered by
engine.ContractVersion, and point at the registry instead of restating
its size (F294).
@Patel230
docs: derive provider count, table and env example from the registry
285d9c4 
AGENTS.md claimed "75+ LLM providers" while catalog/registry defines 28.
The README table said it was in registry SortOrder but was not, and
listed STEPFUN_API_KEY although StepFun reads STEP_API_KEY. .env.example
carried the same wrong StepFun variable plus FLUX_API_KEY, KIMI_API_KEY
and MINIMAX_API_KEY, which nothing in flux reads.

- AGENTS.md: state the 28 provider gateways in catalog/registry.
- README: reorder the table to real SortOrder, fix StepFun, add the
  Z.AI and StepFun region options.
- .env.example: list exactly the registry CredentialEnv variables.
- catalog/registry/docs_test.go: fail when any provider count stated in
  README, AGENTS.md, docs or runtime.go, the README table (IDs, order,
  credential variables, fallbacks, regions) or the .env.example block
  drift from registry.All() (F041, F294).
@Patel230
fix(scripts): derive config-flow provider counts from the registry
31b6358 
test-config-flow.sh counted providers with `cd .. && grep flux/catalog/...`,
so any checkout not named "flux" reported 0 providers and failed, and it
printed "all 11 providers have live fetchers" while the registry holds 28.
`grep -c ... || echo 0` also produced "0\n0" on no match.

cd to the repo root once, compare the live-fetcher count to the registry
count instead of a hardcoded 11, and report the real numbers (F294).
@Patel230
docs(grpc): describe the opt-in gRPC transport as it is
6a8981f 
README called the gRPC surface a "dependency-free skeleton ... wired when
generated stubs are available" and the grpc.go package comment said flux
"does not currently import google.golang.org/grpc". In fact go.mod
requires google.golang.org/grpc directly (so it lands in consumers'
go.sum), server_grpc.go (tag grpc) serves flux.v1.ChatService/Chat with a
JSON codec and no protobuf stubs, and EngineChatService already adapts
conversation.Engine. The unit test comment also claimed the tagged test
covers the engine-backed round trip, but it uses a stub service.

- README: rewrite the section and the Quick Start dependency list.
- grpc.go / internal/grpc/README.md: state the real status (tagged JSON
  transport, direct go.mod requirement, internal package, no caller
  starts it) and drop the stale "until stubs are added" comments.
- grpc_engine_test.go: exercise EngineChatService over a store-backed
  conversation.Engine without the build tag: aggregated deltas, saved
  node ID, request fields forwarded, stream error surfaced, nil request
  rejected (F042).
@Patel230
docs(engine): document and guard the frozen engine-internal symbols
1cf3e56 
README and AGENTS.md said hosts depend only on engine/llm/graph/tools
and that credentials, provider and the rest are not shared contracts.
But the facade exposes engine-internal symbols: engine.MapStore,
DefaultStore and SetDefaultStore re-export credentials, Options.
SecretStore is a credentials.Store, OperationsGraphInput/Export alias
operationsgraph, and Options.RateLimitConfig/CacheConfig carry
provider/resilience and provider/cache structs (plus HeaderExtractor
and RateLimitHeaders transitively). Rho's import-path checks cannot see
through these aliases.

Narrowing the exports is not possible without breaking rho: its
production code uses engine.MapStore, DefaultStore, SetDefaultStore,
OperationsGraphInput and BuildOperationsGraph. So document the set as
frozen contract-v2 symbols instead:

- HOST-ENGINE-BOUNDARY.md: new "Frozen engine-internal types" table.
- README, AGENTS.md, engine/doc.go: point at it; replace the
  nonexistent `client` package with `provider`.
- engine/host_surface_test.go: walk the exported surface of the four
  contract packages with go/ast, follow engine-internal symbols through
  struct fields, signatures and exported methods, and fail when the
  reachable set differs from the frozen list or the doc omits one
  (F043).
@Patel230
docs(architecture): drop the nonexistent flux serve binary
92249b2 
docs/ARCHITECTURE.md advertised a Port 8080 badge, "Override: flux serve
<port>" and "Set via FLUX_API_KEY". flux is a library with no cmd/ and
no serve command, nothing reads FLUX_API_KEY, and internal/api's server
takes its key from api.Config.APIKey and its address from
ListenAndServe(addr); nothing in flux starts it.

Other claims in the same doc were also false: the provider-detection
table (openai is 19th, not 2nd, and detection reads the credential
store, not env vars), "blocking responses wrap the stream" (FluxClient.
Chat calls the provider's blocking Chat), sr.Events() (a field, not a
method), Retry-After "on 429 only", and the caching table (the exact
cache is provider/cache, the similarity cache is provider/embeddings).

docs/README.md listed docs/api/openapi.yaml (it is at the repo root),
three guides that do not exist, a Discussions link although Discussions
are disabled, and claimed the OpenAPI spec covers /v1/chat/completions,
/rerank and /ready, which it does not.

Rewrite those sections to match the code and note the OpenAPI gap
(F273).
@Patel230
docs(agents): point AGENTS.md and the README tree at real files
020bb44 
AGENTS.md cited provider/stream.go, provider/resilience/fallback.go,
provider/errors.go and errors/errors.go (none exist), told contributors
to add providers as provider/<name>.go registered in
provider_registry.go, named provider.NewFluxClient and parseSSEStream
(neither exists), said DetectProvider checks env vars in
ANTHROPIC/OPENAI order, pointed "semantic caching" at the exact-match
cache, and described a parent graycode-eco/go.work that does not exist.
The README architecture tree listed errors/, catalog/legacy/ and
internal/version/ (none exist) and omitted the llm, graph and tools
contract packages.

- AGENTS.md: real paths and symbols, the actual add-a-provider flow
  (registry spec, config profile, setup deployment case, live fetcher,
  adapter only when not OpenAI-compatible), the real linter set, and
  the no-go.work/no-replace rule.
- README: rebuild the architecture tree from the current layout.
- docs_paths_test.go: fail when a path cited in AGENTS.md or an entry in
  the README.md / docs/README.md trees does not exist (F272).
@Patel230 @claude
docs: correct five stale file paths in AGENTS.md
c0f69d9 
docs_paths_test.go asserts that every path-like token in AGENTS.md resolves to
a real file. Merging main's prose during the rebase reinstated citations that
had been fixed on this branch:

- provider/stream.go            -> provider/core/stream.go
- provider/resilience/fallback.go -> router/router.go, router/deployment_router.go
- provider/errors.go            -> provider/core/errors.go
- errors/errors.go              -> types/errors.go
- provider/adapters/AnthropicClient -> provider/adapters/anthropic.go

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@Patel230
Patel230 merged commit 1889329 into main Sep 29, 2026
16 checks passed
@Patel230
Patel230 deleted the docs/flux-truth branch September 29, 2026 17:52
Patel230 added a commit that referenced this pull request Oct 2, 2026
@Patel230
docs: make flux documentation match the code (#126)
94527d5 
* docs(runtime): describe runtime as engine-internal

The runtime package comment called runtime the recommended host entry
point, listed provider/catalog/config/credentials/setup/storage as the
packages hosts import, and claimed the registry holds 16 providers. The
host contract is engine/llm/graph/tools, rho imports none of those
packages directly, and catalog/registry defines 28 providers.

Rewrite the comment to say runtime is engine-internal and not covered by
engine.ContractVersion, and point at the registry instead of restating
its size (F294).

* docs: derive provider count, table and env example from the registry

AGENTS.md claimed "75+ LLM providers" while catalog/registry defines 28.
The README table said it was in registry SortOrder but was not, and
listed STEPFUN_API_KEY although StepFun reads STEP_API_KEY. .env.example
carried the same wrong StepFun variable plus FLUX_API_KEY, KIMI_API_KEY
and MINIMAX_API_KEY, which nothing in flux reads.

- AGENTS.md: state the 28 provider gateways in catalog/registry.
- README: reorder the table to real SortOrder, fix StepFun, add the
  Z.AI and StepFun region options.
- .env.example: list exactly the registry CredentialEnv variables.
- catalog/registry/docs_test.go: fail when any provider count stated in
  README, AGENTS.md, docs or runtime.go, the README table (IDs, order,
  credential variables, fallbacks, regions) or the .env.example block
  drift from registry.All() (F041, F294).

* fix(scripts): derive config-flow provider counts from the registry

test-config-flow.sh counted providers with `cd .. && grep flux/catalog/...`,
so any checkout not named "flux" reported 0 providers and failed, and it
printed "all 11 providers have live fetchers" while the registry holds 28.
`grep -c ... || echo 0` also produced "0\n0" on no match.

cd to the repo root once, compare the live-fetcher count to the registry
count instead of a hardcoded 11, and report the real numbers (F294).

* docs(grpc): describe the opt-in gRPC transport as it is

README called the gRPC surface a "dependency-free skeleton ... wired when
generated stubs are available" and the grpc.go package comment said flux
"does not currently import google.golang.org/grpc". In fact go.mod
requires google.golang.org/grpc directly (so it lands in consumers'
go.sum), server_grpc.go (tag grpc) serves flux.v1.ChatService/Chat with a
JSON codec and no protobuf stubs, and EngineChatService already adapts
conversation.Engine. The unit test comment also claimed the tagged test
covers the engine-backed round trip, but it uses a stub service.

- README: rewrite the section and the Quick Start dependency list.
- grpc.go / internal/grpc/README.md: state the real status (tagged JSON
  transport, direct go.mod requirement, internal package, no caller
  starts it) and drop the stale "until stubs are added" comments.
- grpc_engine_test.go: exercise EngineChatService over a store-backed
  conversation.Engine without the build tag: aggregated deltas, saved
  node ID, request fields forwarded, stream error surfaced, nil request
  rejected (F042).

* docs(engine): document and guard the frozen engine-internal symbols

README and AGENTS.md said hosts depend only on engine/llm/graph/tools
and that credentials, provider and the rest are not shared contracts.
But the facade exposes engine-internal symbols: engine.MapStore,
DefaultStore and SetDefaultStore re-export credentials, Options.
SecretStore is a credentials.Store, OperationsGraphInput/Export alias
operationsgraph, and Options.RateLimitConfig/CacheConfig carry
provider/resilience and provider/cache structs (plus HeaderExtractor
and RateLimitHeaders transitively). Rho's import-path checks cannot see
through these aliases.

Narrowing the exports is not possible without breaking rho: its
production code uses engine.MapStore, DefaultStore, SetDefaultStore,
OperationsGraphInput and BuildOperationsGraph. So document the set as
frozen contract-v2 symbols instead:

- HOST-ENGINE-BOUNDARY.md: new "Frozen engine-internal types" table.
- README, AGENTS.md, engine/doc.go: point at it; replace the
  nonexistent `client` package with `provider`.
- engine/host_surface_test.go: walk the exported surface of the four
  contract packages with go/ast, follow engine-internal symbols through
  struct fields, signatures and exported methods, and fail when the
  reachable set differs from the frozen list or the doc omits one
  (F043).

* docs(architecture): drop the nonexistent flux serve binary

docs/ARCHITECTURE.md advertised a Port 8080 badge, "Override: flux serve
<port>" and "Set via FLUX_API_KEY". flux is a library with no cmd/ and
no serve command, nothing reads FLUX_API_KEY, and internal/api's server
takes its key from api.Config.APIKey and its address from
ListenAndServe(addr); nothing in flux starts it.

Other claims in the same doc were also false: the provider-detection
table (openai is 19th, not 2nd, and detection reads the credential
store, not env vars), "blocking responses wrap the stream" (FluxClient.
Chat calls the provider's blocking Chat), sr.Events() (a field, not a
method), Retry-After "on 429 only", and the caching table (the exact
cache is provider/cache, the similarity cache is provider/embeddings).

docs/README.md listed docs/api/openapi.yaml (it is at the repo root),
three guides that do not exist, a Discussions link although Discussions
are disabled, and claimed the OpenAPI spec covers /v1/chat/completions,
/rerank and /ready, which it does not.

Rewrite those sections to match the code and note the OpenAPI gap
(F273).

* docs(agents): point AGENTS.md and the README tree at real files

AGENTS.md cited provider/stream.go, provider/resilience/fallback.go,
provider/errors.go and errors/errors.go (none exist), told contributors
to add providers as provider/<name>.go registered in
provider_registry.go, named provider.NewFluxClient and parseSSEStream
(neither exists), said DetectProvider checks env vars in
ANTHROPIC/OPENAI order, pointed "semantic caching" at the exact-match
cache, and described a parent graycode-eco/go.work that does not exist.
The README architecture tree listed errors/, catalog/legacy/ and
internal/version/ (none exist) and omitted the llm, graph and tools
contract packages.

- AGENTS.md: real paths and symbols, the actual add-a-provider flow
  (registry spec, config profile, setup deployment case, live fetcher,
  adapter only when not OpenAI-compatible), the real linter set, and
  the no-go.work/no-replace rule.
- README: rebuild the architecture tree from the current layout.
- docs_paths_test.go: fail when a path cited in AGENTS.md or an entry in
  the README.md / docs/README.md trees does not exist (F272).

* docs: correct five stale file paths in AGENTS.md

docs_paths_test.go asserts that every path-like token in AGENTS.md resolves to
a real file. Merging main's prose during the rebase reinstated citations that
had been fixed on this branch:

- provider/stream.go            -> provider/core/stream.go
- provider/resilience/fallback.go -> router/router.go, router/deployment_router.go
- provider/errors.go            -> provider/core/errors.go
- errors/errors.go              -> types/errors.go
- provider/adapters/AnthropicClient -> provider/adapters/anthropic.go


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

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Patel230