Skip to content

Restructure the README to the portfolio standard - #79

Merged
AdamXweb merged 1 commit into
mainfrom
docs/readme-standard
Aug 10, 2026
Merged

Restructure the README to the portfolio standard#79
AdamXweb merged 1 commit into
mainfrom
docs/readme-standard

Conversation

@adamXbot

@adamXbot adamXbot commented Aug 9, 2026

Copy link
Copy Markdown
Collaborator

Brings README.md into the shared portfolio structure: hero, badge row, fenced disclosure block, then overview / what it does / get it / docs / contributing / licence.

Wrong facts removed

  • Mangled one-liner. The description read "Self-hostable mantis key service" — apparently a find/replace that ate the word "canary". Restored to "Self-hostable canary key service", which is what the docs source calls it.
  • Stale version numbers in prose. The beta warning claimed "CLI v0.1.6, full server v0.1.1, edge v0.1.3 at time of writing". Actual versions on main are CLI 0.2.0 and edge 0.1.4 — two of the three were wrong. Prose version numbers are now gone entirely; the release badge carries the version so it cannot drift again.
  • The "80+ notification channel" claim on the Uptime Kuma bullet was an assertion about Kuma, not about this repo, and is not verifiable here. Rewritten to say only what Mantis does (a per-key status URL that flips on hit).
  • The "9-file honey-directory .zip" count could not be confirmed from the source, so the count was dropped. The .zip artefact itself is real and stays.

Links

  • Eight links to privacykey/mantis-docs — that repo has been renamed to privacykey/docs-mantis. They resolved only through GitHub's rename redirect, which is not a guarantee. All eight repointed at the real name.
  • No live docs site. docs.json in the docs repo defines no domain, and neither docs.privacykey.org nor mantis.privacykey.org resolves. The README now says plainly that the rendered site is not live yet and links the Markdown on GitHub, rather than implying a docs host exists.
  • Every remaining relative path and URL across all four files was checked: all resolve, nothing 404s.

Badges

Replaced the ad-hoc row with the four standard badges. Each was verified to render a real value rather than "no status" / "not found":

Badge Renders
status status: Active
release release: cli-v0.2.0
licence licence: MIT
ci ci: passing

ci.yml does run on main (on: push: branches: [main]) and has green runs there, so the CI badge is genuine. The decorative Homebrew and Cloudflare Workers badges were dropped — the brew install line is in "Get it" and the edge worker has its own paragraph.

The status badge currently resolves, but note it reads from the privacykey/.github hub; if the status-hub PR is still in flight it may briefly render "resource not found". The path is correct.

Kept deliberately

The HTTPS-only warning is preserved as its own block immediately below the disclosure. It makes a different claim to the pre-1.0 notice and is deliberately not merged into it.

Size

README.md 9702 → 6625 bytes. Nothing was deleted; the long-form material moved:

  • CONTRIBUTING.md (new) — run from source, the full CI job matrix, the three test tiers, benchmarks, versioning. Records that pnpm is the only supported package manager and that CI reads the pinned version from packageManager.
  • docs/GETTING-STARTED.md (new) — both quickstarts, bootstrap admin key, the one-command Fly.io launch, edge caveats, component index.
  • docs/FLEET-PROVISIONING.md (new) — idempotent external_id minting and enrollment-scoped API keys.

Rewrites README.md to the shared section order (hero, badges, disclosure,
overview, what it does, get it, docs, contributing, licence) and moves the
long-form material into files of its own rather than deleting it.

Corrections:

- The one-line description read "Self-hostable mantis key service", which
  looks like a bad find/replace. Restored to "Self-hostable canary key
  service", matching the description in the docs source.
- The beta warning pinned component versions in prose: "CLI v0.1.6, full
  server v0.1.1, edge v0.1.3". CLI is 0.2.0 and the edge worker is 0.1.4, so
  two of the three were wrong. Version numbers now come from the release
  badge instead of prose, so they cannot go stale again.
- All eight documentation links pointed at privacykey/mantis-docs, a repo
  that has been renamed to privacykey/docs-mantis. They only resolved via
  GitHub's rename redirect. Repointed at the real name.
- "License" -> "Licence" for the portfolio's British spelling.

Badges: replaced the ad-hoc row with the four standard badges (status,
release, licence, CI). All four were verified to render a real value. The
decorative Homebrew and Cloudflare Workers badges were dropped; the brew
install path is in "Get it" and the edge worker has its own section.

The HTTPS-only warning is kept as its own block below the disclosure. It
makes a different claim to the pre-1.0 notice and must not be merged into it.

Moved out (README 9702 -> 6625 bytes):

- Run-from-source setup, the CI job matrix, test tiers and benchmarks ->
  CONTRIBUTING.md (new)
- Both quickstarts, the Fly.io launch script, and the component index ->
  docs/GETTING-STARTED.md (new)
- Fleet / MDM provisioning -> docs/FLEET-PROVISIONING.md (new)

Every relative path and every URL in the four files was checked; all resolve.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@AdamXweb
AdamXweb merged commit 7497097 into main Aug 10, 2026
8 checks passed
@AdamXweb
AdamXweb deleted the docs/readme-standard branch August 10, 2026 13:35
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.

2 participants