Skip to content

README as an open-source front page; reference moved to docs/; Apache-2.0 LICENSE (158) - #159

Merged
jerryfane merged 2 commits into
mainfrom
docs/readme-front-page
Nov 16, 2026
Merged

jerryfane merged 2 commits into
mainfrom
docs/readme-front-page

Conversation

@jerryfane

Copy link
Copy Markdown
Contributor

Closes 158. Owner request via Jarvis 492667 (brief at /root/fleet-tools/state/keyring-seat/readme-brief-20261116.md); license per owner decision, Jarvis 492673.

Change

  • README.md: one-line pitch, badges (release, CI, license, Go), why, mermaid diagram, feature list linking each area, 5-minute quick start, security model (what it protects against / what it does not), docs table, license.
  • docs/: configuration, proxy, relay, dashboard, projects, oauth, google-gcloud, consent-links, apple, signing, egress-proxy, instance-mode. Every former section moved, headings demoted one level, relative links fixed; checked line by line that every non-blank former line is in docs/ except the edits listed below.
  • Brought up to date with main (these sections no longer matched the code): OAuth services are editable in the dashboard; owner-only provider said description; placeholder client IDs refused; Show value flags invisible characters and quotes; edit form has project and forward_role; .p8 can be uploaded in the dashboard (the APNs note said the dashboard could not take it).
  • Public hygiene: private names replaced with neutral examples (role, services, key names, a project name), in docs/ and deploy/cloudflare/README.md; two links to a private repo removed. No hostnames, tailnet IPs, account names or tokens. Only RFC 5737 and CGNAT example addresses remain.
  • docs/images/dashboard-keys.png: real dashboard of a demo instance with fake keys and neutral names (script: /root/fleet-tools/state/keyring-seat/readme-shot/demo.sh).
  • LICENSE (standard Apache-2.0 text from GitHub's API) and NOTICE (Copyright 2026 Jerry Fanelli).

deploy/mac/README.md is unchanged in place (the release tarball and keyring upgrade package it by that path).

Evidence

  • Quick start run end to end against main: set, new-token, check (rules ok: 1 services, 1 roles), serve, relay; the call through the relay reached the upstream with the key added, a path outside the grant got 403, /_relay/health ok, the audit line had no key.
  • Local link check: every relative link in README.md and docs/ resolves.
  • Docs only; no code changed.

…-2.0 LICENSE (158)

Owner request 2026-11-16 (Jarvis 492667) and license decision (492673).
- README: pitch, badges, why, mermaid diagram, feature list, a 5-minute
  quick start (run end to end on main before writing it), an honest
  security model, a docs table and the license.
- docs/: every former README section moved, one file per area, with
  headings adjusted and relative links fixed; nothing dropped.
- Updated to main: OAuth services are editable; the provider's
  error_description; placeholder client IDs refused; Show value flags
  invisible characters; forward_role and project on the edit form; the
  dashboard can upload a .p8.
- Private fleet names replaced by neutral examples (README, docs,
  deploy/cloudflare/README.md); two links to a private repo dropped.
- docs/images/dashboard-keys.png from a demo instance with fake keys.
- LICENSE (Apache-2.0, standard text) and NOTICE.
@jerryfane

Copy link
Copy Markdown
Contributor Author

Head eeead6d fixes the P3: deploy/mac/README.md lines 200 and 250 now link to docs/apple.md (#apple-ads-signing-not-an-api-proxy, #app-store-connect-signing), both anchors exist there. Repo-wide search found no other links to removed README anchors.

@jerryfane

Copy link
Copy Markdown
Contributor Author

Reviewer: adspower-fleet-review
Runtime: omp
Job: local-review-review-router-18e86c94eee4fa73-1

Decision: approved
Summary: Reviewed the complete documentation-only diff at 1f64210. One nonblocking broken-link finding; no introduced production or design defects found. No prior PR #159 verdicts were recorded. CLI smoke passed. One unchanged instance test failed during fixture setup. Sandbox C-header permissions prevented race checks; native macOS execution was unavailable, with no exact-head CI evidence supplied.
Severity: P3

Findings

  • Update deployment backlinks after moving Apple setup (P3)
    • description: deploy/mac/README.md:200,250 still link to the removed README Apple signing anchors. Both links resolved before this change but no longer reach the service configuration required by the installation instructions. Point them directly to ../../docs/apple.md with the existing Apple Ads and App Store Connect anchors.
    • evidence: Executed anchor comparison: both targets exist in the base README, are absent from the head README, and exist in docs/apple.md.
    • file: docs/apple.md
    • line: 3

Tests Run

  • CGO_ENABLED=0 go vet ./... -> passed
  • CGO_ENABLED=0 go build ./... -> passed
  • GOOS=darwin GOARCH=arm64 go build ./... -> passed
  • CGO_ENABLED=0 go test ./... -count=1 -> failed: TestWorkspaceAccountHydrationCachesByBinding at internal/instance/workspace_test.go:642; fixture PUT /consent returned 400: consent API cannot use the admin address. All other tested packages passed.
  • go vet ./...; go build ./...; go test -race ./... -count=1 -> blocked during compilation: /usr/include/stdc-predef.h: Permission denied
  • CGO_ENABLED=0 go build -o "$review_tmp/keyring" ./cmd/keyring; KEYRING_REVIEW_BIN="$review_tmp/keyring" python3 - <<'PY' (inline isolated CLI smoke) -> passed: documented set/new-token/check/serve/relay flow, allowed request 200, denied path 403, invalid token 401, credential injection/redaction, secret-free audit, stopped-keyring 502. Used fake credentials and a loopback upstream.
  • python3 - <<'PY' (inline Markdown link checks) -> 38 changed-document local links passed; separately confirmed two deployment backlinks lost their README targets.

Raw runtime output was retained in local Gitmoot state and is not posted here.

@jerryfane

Copy link
Copy Markdown
Contributor Author

Reviewer: adspower-fleet-review
Runtime: omp
Job: local-review-review-router-18e86cf2d4d35d3f-1

Decision: approved
Summary: Reviewed only the delta from 1f64210 to eeead6d. Both deployment backlinks are fixed. No new correctness or design defects found. Documentation-only changes; no production build or platform checks required.

Findings

Tests Run

  • git diff --check 1f64210 eeead6d -> passed.
  • python3 - <<'PY' (focused documentation navigation assertions) -> passed: exact head and changed-file scope verified; both repaired links and all three reciprocal Apple documentation links resolve.

Raw runtime output was retained in local Gitmoot state and is not posted here.

@jerryfane
jerryfane merged commit f23fa93 into main Nov 16, 2026
2 checks passed
@jerryfane
jerryfane deleted the docs/readme-front-page branch November 16, 2026 04:59
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