Skip to content

docs: condense README - #37

Merged
HackedRico merged 1 commit into
mitre:mainfrom
HackedRico:doc/concise-readme
Aug 31, 2026
Merged

docs: condense README#37
HackedRico merged 1 commit into
mitre:mainfrom
HackedRico:doc/concise-readme

Conversation

@HackedRico

Copy link
Copy Markdown
Collaborator

Description

Cuts the README from 380 to 137 lines. Documentation only, no behaviour changes.

Structural edits:

  • Merged the "Recent Changes" gallery, "Features" and "Workflow Guide" into a single three-row workflows table. The three sections restated each other.
  • Reduced four screenshots to one, and removed the <p align="center"> and <br> padding around it.
  • Folded "Development" into "Quick start" and "API Surface" into "Architecture". Both were two or three lines of unique content wrapped in their own headings.
  • Turned "Troubleshooting" into a symptom/fix table.
  • Rewrote "Installation" as one required command block plus one optional block, instead of five numbered steps with prose interleaved.

Content removed:

  • The "Project Structure" tree, 27 lines duplicating a directory listing.
  • The "Known limits" section. Flagging this one for a maintainer call, since it is the only substantive removal rather than a restructure: it documented the 0.83 precision / 0.89 F1 pipeline score, the absent detections plugin, coarse platform matching, unchecked fusion identity, and the un-scoped run_operation. Happy to restore it if you would rather keep those caveats published.

Everything else survives intact: the what-to-run vs where-to-run framing, the pipeline diagram, both env vars, the Caldera connection exceptions, and the three conf/local.yml overlay gotchas.

The three now-unreferenced screenshots are still in docs/images/ rather than deleted, in case you want one swapped back in.

Type of change

Documentation only. None of the template categories apply, so all four are deleted per the template instructions.

How Has This Been Tested?

No code changed, so no test run applies. Verification was limited to the document itself:

  • Every relative link and image path resolves: docs/images/mcp-main-screen.png, PLUGIN_MCP.md, and the #caldera-connection anchor used by the troubleshooting table.
  • Heading hierarchy checked for orphaned subsections after the merges.

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have made corresponding changes to the documentation
  • I have added tests that prove my fix is effective or that my feature works (not applicable, documentation only)

Cut the README from 380 to 137 lines. Fold Workflow Guide, Recent
Changes, Development and API Surface into their neighbouring sections,
keep a single screenshot, and turn Troubleshooting into a table.

Drop the Project Structure tree and the Known limits section.
@HackedRico
HackedRico merged commit 02d0f92 into mitre:main Aug 31, 2026
3 checks passed
@HackedRico
HackedRico deleted the doc/concise-readme branch August 31, 2026 16:47
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