[Docs] The README never says this is an unreleased alpha #582

New issue

Closed

opened 2026-07-22 16:16:33 +00:00 by brenno · 1 comment

brenno commented

2026-07-22 16:16:33 +00:00

Owner

Found in the pre-publication first-impression review.

Evidence: grep -ni "alpha|beta|0\.1\.0|experimental|not.*production|pre-release|unreleased" README.md → no matches. The only hint is inside a table at README.md:128: "(nothing is released yet)". Meanwhile docs/README.md:9-16 carries a proper banner — "Status: unreleased. No release has ever been tagged… every user runs whatever commit they built from" — and pubspec.yaml:4 says version: 0.2.0+1, a third number beside the 0.1.0 this launch is called.

Why this must be fixed before publication: the README promises 24 feature areas including sealed pentest reports, CVSS 4.0, AI drafting, git storage and a privacy scanner, with no maturity qualifier anywhere. A critic reads that as a product claim, checks the tag list, finds nothing, and the first public comment becomes "this oversells what it is" — the exact opposite of the honesty the rest of the documentation genuinely earns. The candour already exists one directory down; it is simply missing from the one file everyone reads.

Proposal: move the docs/README.md:9-16 status banner, or a two-line version of it, directly under the H1 and above the description: unreleased, no tag has ever been cut, you build from source, the file format is the stable part and the app is not.

Related to #520 (release engineering) but must not wait for it — this is only about how the README frames the project on day one.

Found in the pre-publication first-impression review. **Evidence:** `grep -ni "alpha|beta|0\.1\.0|experimental|not.*production|pre-release|unreleased" README.md` → no matches. The only hint is inside a table at `README.md:128`: "(nothing is released yet)". Meanwhile `docs/README.md:9-16` carries a proper banner — "**Status:** unreleased. No release has ever been tagged… every user runs whatever commit they built from" — and `pubspec.yaml:4` says `version: 0.2.0+1`, a third number beside the 0.1.0 this launch is called. **Why this must be fixed before publication:** the README promises 24 feature areas including sealed pentest reports, CVSS 4.0, AI drafting, git storage and a privacy scanner, with no maturity qualifier anywhere. A critic reads that as a product claim, checks the tag list, finds nothing, and the first public comment becomes "this oversells what it is" — the exact opposite of the honesty the rest of the documentation genuinely earns. The candour already exists one directory down; it is simply missing from the one file everyone reads. **Proposal:** move the `docs/README.md:9-16` status banner, or a two-line version of it, directly under the H1 and above the description: unreleased, no tag has ever been cut, you build from source, the file format is the stable part and the app is not. Related to #520 (release engineering) but must not wait for it — this is only about how the README frames the project on day one.

brenno added the

docs

label

2026-07-22 16:16:33 +00:00

brenno referenced this issue from a commit

2026-07-22 17:07:09 +00:00

docs(readme): een voorpagina die in tien seconden te lezen is (#582 #590 #591 #611 #619 #620 #621 #635)

brenno referenced this issue from a commit

2026-07-22 17:12:52 +00:00

docs(readme): een voorpagina die in tien seconden te lezen is (#582 #590 #591 #611 #619 #620 #621 #635)

brenno referenced this issue

2026-07-22 17:14:10 +00:00