[danoszz]

Penthera is now described as an open R&D project with a usable tool, the overlapping plan docs are merged, every user-facing page names the question it answers, and a one-page voice guide sets the tone. Docs and metadata only: no version bump, no tag, and no code changes beyond retargeting one test.

Positioning (approved wording, verbatim)

• One-liner: README hero and docs/index.md.
• Paragraph: README "What Penthera is" (this replaces "The problem") and docs/index.md.
• Short version (117 chars): package.json, .claude-plugin/plugin.json, marketplace.json (both descriptions), and action.yml (the name "Penthera: Cyber Security Agent" is unchanged).
• SKILL.md description: opens with the positioning and keeps every trigger phrase; 1017 chars, under the 1024 limit.
• GitHub repo description: set to the short version with gh repo edit on 2026-10-20, with the maintainer's go.

The README has a new "How it is measured" section built as method → evidence → tool. The benchmark numbers now carry their Wilson 95% intervals (precision 0.86, 0.67 to 0.95; recall 0.90, 0.71 to 0.97) and say plainly that the sample is 22 findings in labs we wrote ourselves.

README size

13,928 → 13,807 bytes (about 13.5 KB). The approved paragraph replaces "The problem". To make room, "What it is today", "Research and methodology", "Use cases" and "Privacy" became "How it is measured" and a five-row Start here table, and the privacy link moved into the trust list. PR #63 adds about 200 bytes to the dashboard rows, which still leaves the README under 14 KB. The dashboard table and the "See it all" row are untouched, so #63 should rebase cleanly.

Merged, archived and removed pages

Before	After
ROADMAP.md (shipped lists, v1.3/1.4 tables, next, later)	ROADMAP.md: what ships next, starting with the 1.8.0 freeze, each item tied to a user question; history compressed to one table
docs/plan.md	Milestones → ROADMAP "Shipped"; "what perfect means" → Quality gates in vision-2.0.md; working rhythm → CONTRIBUTING. File archived as docs/archive/plan-to-2.0.md
docs/release-plan.md (v1.2 to v1.4)	Archived as docs/archive/release-plan.md, with a one-line note
docs/research/socket-positioning-notes.md	Archived; the voice guide replaces it as docs guidance
docs/vision-2.0.md "the plan to become the best"	"Penthera 2.0: research plan": goals, gaps, experiments E1 to E6, quality gates, and milestones per phase rather than per version (1.8.0 is frozen)
docs/index.md (flag tables, three overlapping plan links)	Start here from starter → pro, a "verify it" path, by situation, and project pages
(none)	docs/voice.md, docs/archive/README.md

tests/cli-smoke.test.js read the v1.5.0 row of docs/plan.md. It now reads the same row in ROADMAP.md, with the same assertions.

Inventory: before and after

Each user-facing page now opens with > **Starter.**, > **Pro.** or > **Project page.** and the question it answers.

Page	Audience	Question it answers	Change
README.md	All	What is it, and how do I start?	Positioning, "How it is measured", Start here
docs/index.md	Starter → pro	Where do I start, and where next?	Rewritten
docs/commands/init.md, scan.md	Starter	Is my app safe to ship?	Intention line; scan.md: the no-args penthera runs the init wizard (it did not say so before), and reports/ is gitignored by init, not by default
docs/commands/deps.md, install.md	Starter	Is this package safe to add?	Intention line, US spelling; fixed a "table above" that pointed to another page
docs/commands/agents.md, use-cases/ai-coding-teams.md	Starter	Is this MCP server or skill safe?	Intention line
docs/commands/skill.md	Starter	Can my coding agent run it for me?	Intention line
docs/use-cases/solo-founder.md	Starter	Is my app safe to ship?	Limits with accuracy numbers and intervals
docs/dashboard.md	Starter	Can I see it all in one place?	Not touched (PR #63)
docs/commands/action.md, hook.md	Pro	How do I put it in CI?	Intention line
docs/commands/fix.md, docs/local-loop.md	Pro	How do I run the fix loop?	Plainer opener; internal jargon ("W1", "W6") removed
docs/rule-packs.md, owasp-wstg-coverage.md	Pro	How do I tune the rules? / Which OWASP tests are covered?	WSTG map re-synced with lib/owasp-wstg.js (it was last edited in June)
docs/evidence.md, compliance-nis2.md, compliance-cra.md, use-cases/eu-sme-compliance.md	Pro	What do I give my auditor?	NIS2: removed hype and a claim of Belgian support (only nl.json exists)
docs/use-cases/open-source-maintainers.md, agencies.md	Pro	How do I check every PR and release? / A repeatable handover	Wording
docs/privacy.md	Pro	What does it send over the network?	Added deps --online and --fix-model; fixed a broken anchor
docs/compare/*	Pro	How does it compare, and how do I run both?	Snyk page: "no API calls" corrected (Retire.js and recon can reach the network without --offline)
docs/METHODOLOGY.md, bench/README.md	Pro	How does it decide? How accurate is it?	Intervals in the abstract; network exceptions made complete
docs/MANIFESTO.md, genai.md	Project	Why was it built this way? How much did AI write?	R&D framing; links now say "research plan"
docs/vision-2.0.md	Project	How do you know it works, and what's next?	See above
ROADMAP.md	Project	What ships next, and when?	See above
CONTRIBUTING.md	Project	How do I contribute, and how does it ship?	Release cadence and freeze; fixed a broken README anchor; no em dashes
docs/voice.md	Project	How should this sound?	New
SECURITY.md	All	How do I report a vulnerability in Penthera?	Supported versions said 1.2.x and now say 1.7.x; two broken anchors fixed
docs/funding/*	Project	How can I support it? Is it sound to fund?	Partner brief: agents was "in review", the CRA helper "on the roadmap" and the compare pages "not yet written"; all three corrected. Removed the stale "Proposed edits in this PR" section
docs/research/plan-1.8.md	Research	Phase A plan	One dated note: 1.8.0 is frozen, so Phase A lands in 1.9 or later
docs/research/prereg/*	Research	Pre-registrations	Not touched (registered documents)
docs/references.md	Research	Sources	Not touched (generated by scripts/build-references.mjs)
skills/penthera/SKILL.md	Agent	When to use the skill	Description; two links into docs/ now point to GitHub, because docs no longer ship in the npm package (#65)

Release cadence and freeze (CONTRIBUTING)

• At most one minor release every 2 to 4 weeks.
• Every minor goes through an X.Y.0-rc.N on npm's next tag first.
• Patches are for fixes only.
• A feature freeze before each minor.
• Current freeze: 1.8.0 = main + feat(ui): redesign penthera ui: Simple mode, setup, 1-bit System look #63.

Gap: publish.yml does not yet pass --tag next for -rc tags, and npm 11 refuses to publish a prerelease without an explicit tag. CONTRIBUTING says this. The workflow change is left for a separate PR.

For the maintainer to check

• Moving research milestones off version numbers: with 1.8.0 frozen, Bench/E1 (feat(bench): Penthera Bench v1 tooling for E1, plus draft pre-registrations E2 to E5 #61) lands in 1.9 or later. vision-2.0.md and plan-1.8.md now say so.
• The approved paragraph says "every check is tested in public, pre-registered experiments". E1 is registered but has not run yet. The README's "How it is measured" section states the current status next to it.
• Found but not fixed:
  • In lib/owasp-wstg.js, a few WSTG names look mislabelled (for example ATHZ-05 named "OAuth Weaknesses"). Fixing that is a code change.
  • In solo-founder.md, the sample output in a code fence does not add up to its own summary line. Commands and code fences were left alone for the docs-as-tests session.

Checks

• npm test: 50 files passed, 902 tests passed, 21 skipped.
• npm run audit:internal: PASS on every gate (tests 913 passed, benchmark unchanged at 0.864 / 0.905, packaging 643 kB, docs links 296 checked and 0 broken). The regenerated audit/REPORT.md is not committed; it belongs to the release commit.
• An extra anchor check (all relative links and #anchors across tracked .md files): no broken links.

🤖 Generated with Claude Code

[github-actions]

Dependency capability diff

Compared against 81f40e21cf8d2148b561e98bea9d1f9dea1cba1f: 0 added · 0 changed · 0 removed.

No package gained capabilities, and no new package can reach shell, network or install-time code.

_{penthera deps v1.7.0: offline static analysis, no telemetry. Capabilities are what code can do, not a verdict.}

Checked by Penthera, open-source security for the apps and AI systems you ship · https://github.com/danoszz/penthera

_{Updated for commit e8e830d · workflow run. This comment is edited in place on every push.}