Skip to content

docs(console): correct docs and redraw all ten Mermaid diagrams - #743

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

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

Conversation

@catinspace-au

Copy link
Copy Markdown
Contributor

docs/, the README and CONTRIBUTING match this repo's code and dfe-engine, dfe-hyperdx, dfe-infra and hyperi-ci.

Fix 17 FAIL claims out of 547 claims. Claim status: 265 PASS, 228 UNCHECKABLE and 37 false FAILs. Most UNCHECKABLE claims are backticked names the tool cannot locate. The false FAILs concern sibling-repo paths, paths relative to a directory, the image name and a yarn setting.

  • LOG_LEVEL runs TRACE to CRITICAL, not DEBUG to ERROR.
  • create-schema-form.md: every row goes to uploadedSchemaColumns. Submit is blocked if any row is invalid.
  • With a dev engine on another port, login does not spin. Every browser call to the engine fails CORS. The OIDC option goes missing. Pages cannot load data.
  • The Flow card's lag comes from /lag, not /flow.
  • build-and-deploy.md explains where the chart is published and what make build does. An empty NEXT_PUBLIC_API_URL sends the browser to the console's origin.
  • Session renewal sets the dfe_token cookie again.

Restore:

  • the advice to clean a file before upload
  • the rule that the console never reaches past the engine API
  • the Linux docker job in the macOS smoke workflow

Replace the 10 diagrams rejected by the checker. All 10 pass the diagram checker on Mermaid 12.3.0 and hyperi-ci's mermaid-parse. architecture.md opens with an L3 diagram of the console. The rest are L4.
Convert Three diagrams to sequence diagrams. Convert one to a state diagram.

Trim config comments without changing values:

  • .yarnrc.yml, with its CVE exception moved to CONTRIBUTING
  • Dockerfile, removing a comment about a cache order the file does not have
  • both workflows, .dockerignore, both .gitignore files
  • osv-scanner.toml's threat model path comment

Corrections cover every page under docs/, the README and CONTRIBUTING. They reflect the code, dfe-engine, dfe-hyperdx, dfe-infra and hyperi-ci.

- Correct the documented LOG_LEVEL range from DEBUG to ERROR to TRACE to CRITICAL.
- build-and-deploy.md explains the chart destination and `make build`. It says an empty NEXT_PUBLIC_API_URL sends the browser to the console's origin for the engine.
- authentication.md says renewal sets the dfe_token cookie again.
- The Flow card docs cover a source fed by a pipeline.
- Redraw all ten Mermaid diagrams to the diagram standard. The L3 console diagram goes at the top of architecture.md. The rest are L4. Three become sequence diagrams and one a state diagram.
- Cut config comments to pointers and short reasons.
- Move the yarn age gate's CVE exception to CONTRIBUTING.
- Remove the Dockerfile comment describing a cache order the file does not have.

Signed-off-by: Derek <derek@hyperi.io>
The 'engine URL is not configured' message shows when INTERNAL_API_URL and NEXT_PUBLIC_API_URL are both unset. The server code reads either one.

The image has NEXT_PUBLIC_API_URL baked empty. INTERNAL_API_URL decides whether the message shows in the image.

Signed-off-by: Derek <derek@hyperi.io>
# Conflicts:
#	CONTRIBUTING.md
#	docs/local-development.md
@catinspace-au
catinspace-au merged commit b6aa62e into main Nov 16, 2026
20 checks passed
@catinspace-au
catinspace-au deleted the docs/suite-review branch November 16, 2026 03:15
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