Skip to content

docs(elastic): fix docs to match the code - #186

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

Incorrect claims in the README, CONTRIBUTING and docs/ are fixed or cut.

  • Of 129 documented claims, 62 PASS, 59 FAIL are fixed and 8 are UNCHECKABLE.
  • hyperi-ai docs claims reports 35 FAIL rows, all false alarms: Elastic processor names, dfe-engine identifiers and env names composed at runtime.
  • Fix the 9 diagrams that failed the checker. All 9 pass on Mermaid 12.3.0.
  • configuration.md restores documentation lost in the README rewrite in docs(readme): explain the service and getting started #172:
    • The lossy_payloads_total, parse_errors_total and send_backpressure_total counters.
    • The metrics-manifest subcommand.
    • /scaling/pressure.
  • The parity docs cover tests/compare-policy.yaml and the known limits. The parity corpus and its test are absent from this repo.
  • parsers.md documents dfe-parse layers 2 and 3 as built but unused.
  • schema-generation.md marks the work as partly built outside this repo, with the rest still a design (Import schemas from a live ES/OpenSearch server, and generate meta schemas for all beats #16).
  • The dfe-parsers crate section is cut.
  • Config comments in 15 files across manifests, workflows and policy files are cut to a pointer or a one-line reason. Parsed values are unchanged.
  • src/envelope.rs changes doc comments only.
  • Fix 18 of 19 doc findings. Keep Device Vendor, a CEF header field name.

Wrong claims in README.md, CONTRIBUTING.md and docs/ are fixed or cut. The nine Mermaid diagrams follow the diagrams standard. All nine failed the checker before and pass it after the changes.

- The architecture page drew a TransformChain the service never runs. It shows the four steps, the crate graph, one batch as a sequence, and what a failed processor does.
- Pages describing the parity corpus test, its baseline and its fixture format are cut to what this repository holds: compare-policy.yaml and the known limits.
- Docs mark layers 2 and 3 of dfe-parse, the dfe-parsers crate and schema generation as built but unused, or as designs. The dfe-parsers section is cut.
- configuration.md documents the bad-input counters, the metrics-manifest subcommand and /scaling/pressure.
- Config comments are cut to a pointer or a one-line reason in 15 files. Every parsed value is identical before and after.
- src/envelope.rs: doc comments only. Envelope detection runs for each event in a batch.
The docs describe the compare policy without corpus or scoring details.

- compat.md covers compare-policy.yaml and two known limits. The scoring diagram and scoring process description are removed.
- Remove corpus mentions and detector benchmark figures from parity.md, testing.md, configuration.md, parsers.md, schema-generation.md and CONTRIBUTING.md.
- testing.md no longer calls `Exact` the default match mode. MatchMode has no default.
- src/envelope.rs doc comments say auto detection runs per event. docs/config-schema.{json,yaml} and docs/deployment-contract.json are regenerated with `generate-artefacts`.
CONTRIBUTING.md drops the DCO section removed on main. Its pull request steps drop sign-off. Cargo.toml keeps main's psl >=2.1.248 under the branch's shorter comment. .prose-exemptions.yaml goes, because the DCO text it covered is gone.
Main's #187 sends an event over sink.max_message_bytes to the DLQ. The architecture page keeps the branch's layout. Its one-record paragraph names serialise_events_with_oversize and the DLQ. The configuration page uses main's DLQ wording and the branch's word choices.
@catinspace-au
catinspace-au merged commit 16af68b into main Nov 16, 2026
26 checks passed
@catinspace-au
catinspace-au deleted the docs/suite-review branch November 16, 2026 05:05
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