Skip to content

docs(docker): fix claims and redraw diagrams - #407

Merged
catinspace-au merged 4 commits into
mainfrom
docs/suite-review
Nov 16, 2026
Merged

catinspace-au merged 4 commits into
mainfrom
docs/suite-review

Conversation

@catinspace-au

Copy link
Copy Markdown
Contributor

Fix incorrect claims in README.md and docs/. Redraw the diagrams. Shorten config comments to pointers.

Claim totals for README.md and docs/: 2461 claims, 916 PASS, 24 FAIL fixed, 1521 UNCHECKABLE. No FAILs are open. Main corrections:

  • architecture.md put the fetcher and transforms on the loader's gRPC port. No profile runs either on gRPC.
  • CONTRIBUTING.md said CI starts no stack. Two CI jobs start one and count demo rows.
  • The VRL kill test runs on Kafka, not direct gRPC.
  • The troubleshooting diagram checked the topic. Its text checks the subscription.
  • auth-profile.md implied the profile was live. It opens with the profile's status: off by default, with no e2e sign-in.

Restore:

Diagrams: 9 failing diagram_check before, 10 passing on Mermaid 12.3.0 after. Screenshot checks cover light and dark.

developing.md was 4,439 words. Move its test suites to testing.md and checks.md. Move live console mode to live-console.md.

Config comment lines, before and after:

  • Makefile 268 to 176
  • ci.yml 128 to 64
  • service_profiles.yaml 41 to 12
  • ruff.toml 26 to 11
  • docker-compose.yml 72 to 62
  • droast.toml 16 to 10
  • .gitignore 15 to 13

Each file loads to the same data. make -pnq help prints the same database.

make check: 2412 tests passed. ruff is clean. check-docs passed over 21 documents.

Prose check flags heading density in README.md and common-failures.md. Their headings mark sections. CONTRIBUTING.md has prose-check hits in the template and DCO text.

catinspace-au and others added 4 commits November 16, 2026 12:08
Correct claims in README.md and docs/. The PR has the ledger counts.

- architecture.md corrects claims that transforms push to the loader on gRPC and that the fetcher and transforms dial port 6000. No profile runs either on gRPC. Only the receiver dials port 6000.
- The troubleshooting diagram checks the subscription, matching the text. The DLQ paragraphs move from the one-shot heading to the DLQ.
- CONTRIBUTING.md corrects its claim that CI starts no stack. The image and published-compose jobs start one and count each demo source's rows.
- auth-profile.md opens with its status: off by default, wiring checked, no e2e sign-in.
- Fix two link labels pointing to the wrong page. Restore the readiness heading in observability.md.
- Restore the stack manifest and signer variables dropped from README to configuration.md. Add the make help pointer to developing.md. Add the not-a-HEALTHCHECK note to self-test.md.

All ten diagrams are redrawn to the diagrams standard and pass diagram_check on Mermaid 12.3.0. Split the 1392 px wide troubleshooting diagram into two.

developing.md was 4,439 words. Move the test suites to testing.md and checks.md. Move live console mode to live-console.md. Replace copies of operating.md and known-issues.md content with links.

Config comments are cut to pointers and short reasons in the Makefile, ci.yml, docker-compose.yml, service_profiles.yaml, ruff.toml, droast.toml and .gitignore. Each file parses to the same data as before. The footprint key defaults move to profiles.md.

Signed-off-by: Derek <derek@hyperi.io>
- The kill tests cover the VRL transform on Kafka, not on direct gRPC.
- The e2e suite runs no collector unless a test sets `otel: true`.
- `make proof` falls back from the pinned tag to the default branch.
- The source test reads the admin login from `env/engine.env`.
- ruff, pytest, uv and Envoy need a network on a first check.
- A live-mode apply prunes deleted sources and updates the collector.
- The diagram descriptions name the `dfe.otel_*` tables and the targets that read profile.mk.

Cut or replace uses of 'refuses', 'requires', 'carries', 'already', 'also', 'too', 'gains' and 'prove'. The ledger lists the uses kept.

Split the semicolons in four config comments. Shorten three comment blocks in ci.yml. The data each config file holds is unchanged.

Signed-off-by: Derek <derek@hyperi.io>
The e2e suite puts the stack it found back on a pass, a failure or a SIGTERM. A SIGKILL or a host failure skips that, so testing.md says to start the stack again by hand.

Signed-off-by: Derek <derek@hyperi.io>
@catinspace-au
catinspace-au merged commit c68f2e5 into main Nov 16, 2026
16 checks passed
@catinspace-au
catinspace-au deleted the docs/suite-review branch November 16, 2026 01:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant