docs: clearer setup instructions (#211)

* docs: clearer instructions

* test: remove verbose test

Release-As: 0.33.1

Author: hesreallyhim

template/.github/workflows/setup.yml

@@ -72,13 +72,13 @@ jobs:
                 echo
                 echo "[Create a fine-grained personal access token]($token_url)"
                 echo "with repository \`Administration: read\` for \`$GITHUB_REPOSITORY_OWNER\`."
-                echo "Choose **All repositories** for broad automatic discovery, or"
-                echo "**Only selected repositories** if you want to limit collection."
-                echo "If you choose selected repositories, keep \`config.yaml\` within"
-                echo "that token's repository access."
+                echo "To minimize exposure, we recommend restricting the token's access to only"
+                echo "repos that are within the your collection set."
+                echo "When you create a new repository, and you wish to run collection on it,"
+                echo "be sure to add it to the token's permission set."
                 echo "Then save the token as repository secret \`COLLECTION_TOKEN\` and run setup again."
               } >> "$GITHUB_STEP_SUMMARY"
-              exit 1
+              exit 1 
             fi
 
             if ! GH_TOKEN="$COLLECTION_TOKEN" gh api rate_limit >/dev/null 2>&1; then

template/README.template.md

@@ -3,27 +3,27 @@
 > [!NOTE]
 > This template is on the `v0` external beta line. These instructions describe the official generated workflows; after copying the template, the repository owner may modify them.
 
-This is the setup README for your Reponomics dashboard repository. Reponomics helps maintainers collect GitHub traffic and growth data, keep that data in their own repository's workflow artifacts, and render a dashboard without sending the data to a Reponomics-hosted service.
+Welcome to your personal repository analytics dashboard. Reponomics helps maintainers collect GitHub traffic and growth data, keep that data in their own repository's workflow artifacts, and render a dashboard without involving any third-party services.
 
-After you copy the template, the repository is yours. The generated workflows use your credentials, your repository secrets, and the action ref configured by the local wrapper at `.github/actions/reponomics/action.yml`. This README helps you configure collection, data storage, and dashboard publication before the first setup run. Setup may replace this file with a shorter post-setup README, and private repositories can later opt into a generated metrics README dashboard.
+Once you copy the template, the repository is yours. The generated workflows use your credentials, your repository secrets, and the action ref configured by the local wrapper at `.github/actions/reponomics/action.yml`. This README helps you configure collection, data storage, and dashboard publication before the first setup run. Setup may replace this file with a shorter post-setup README, and private repositories can later opt into a generated README dashboard for a quick overview of your repo metrics.
 
-The dashboard collects GitHub traffic and growth data, stores retained state in GitHub Actions artifacts, and renders optional dashboard outputs through GitHub Actions. The repository stays intentionally thin: collection, encryption, rendering, key rotation, incident reset behavior, CSV export, and managed docs update are owned by the versioned action referenced by the local wrapper.
+This repository contains a number of workflow files that integrate with the Reponomics Dashboard GitHub Action in order to provide the functionality that makes the dashboard possible. The workflows collects GitHub traffic and growth data, stores retained state in GitHub Actions artifacts, and renders optional dashboard outputs through GitHub Actions. The action itself is imported into all of the necessary workflows as a local action at a single path:
 
 ```yaml
 uses: ./.github/actions/reponomics
 ```
 
-If your organization requires full-SHA-pinned Actions, use `docs/reponomics/.manifest.json` to find the action repository and action version for this template snapshot, resolve that version tag to a commit SHA, and update the nested Reponomics `uses:` line in `.github/actions/reponomics/action.yml` only if you intend to own manual action updates. Organization-wide SHA policies may also require pinning other workflow action refs, such as `actions/checkout`, in the generated workflow files.
+This allows you to manage the version of the action uniformly in a single place. By default the action is configured to follow the current major line (`@v0`), so that new features, bug fixes, and security patches will flow automatically into your repo. If your organization requires full-SHA-pinned Actions, use `docs/reponomics/.manifest.json` to find the action repository and action version for this template snapshot, resolve that version tag to a commit SHA, and update the nested Reponomics `uses:` line in `.github/actions/reponomics/action.yml` only if you intend to own manual action updates. Organization-wide SHA policies may also require pinning other workflow action refs, such as `actions/checkout`, in the generated workflow files.
 
 ## Get Started
 
-1. Fill in the required setup fields at the top of `config.yaml`, commit that change, and decide which repositories this dashboard should track.
-2. Create a collection credential and store it as the repository secret `COLLECTION_TOKEN`. Most single-owner dashboards should use a fine-grained personal access token with repository `Administration: read`.
-3. Choose a data mode in `config.yaml`: `encrypted` or `plaintext`. Public repositories must use `encrypted`.
-4. For `encrypted`, generate and save `DASHBOARD_SECRET_DO_NOT_REPLACE`, then add it as a repository secret. The action requires this value to be non-empty; see [Dashboard Key And Recovery](docs/reponomics/dashboard-key-and-recovery.md) for the security tradeoffs.
-5. Run **Actions -> Setup -> Run workflow**.
-6. If you enable hosted dashboard publication, open **Settings -> Pages** and set **Build and deployment -> Source** to **GitHub Actions**.
-7. Run **Actions -> Collect and Publish -> Run workflow** once to create the first dashboard immediately.
+Before proceeding, please read through this README file, and take a moment to review some of the other documentation in the repository, in particular those pertaining to privacy, security, and secure key generation. Then proceed as follows:
+
+### 1. Enter your preferences in `config.yaml`. REQUIRED: `encrypted` or `plain` data-mode; whether to publish a Pages dashboard and/or a README dashboard; which repositories to track and publish in your dashboard.
+### 2. Create the following: (a) a Personal Access Token with `Administration: read` permissions for every repository that you would like to include in collection - store that as a repo secret named `COLLECTION_TOKEN`; (b) a high-entropy encryption key (`openssl rand --hex 32`) - store that as `DASHBOARD_SECRET_DO_NOT_REPLACE`.
+### 3. If you want a Pages dashboard (must choose `encrypted` data-mode): Go to Settings > Pages > Build and Deployment - select Source: GitHub Actions.
+### 4. Go to the Actions tab, click on the `Setup` workflow from the side, then dispatch the workflow.
+### 5. If everything passes, you can go ahead and run the `Collect and Publish` workflow manually to start gathering some data. Within minutes you'll have two weeks of traffic data to admire. Click over to your Pages site and use your encryption key to unlock the vault.
 
 Setup validates `config.yaml`, creates the empty `.reponomics/setup-complete` marker, and replaces this README. Operational workflows are present before setup but do no work until that marker exists. Setup does not collect traffic immediately. Collection runs on the configured schedule and stores retained data in the `dashboard-data` Actions artifact; run **Collect and Publish** manually after setup when you want the first dashboard without waiting for the schedule.
 

tests/test_generated_repos.py

@@ -95,9 +95,9 @@ def test_template_manifest_includes_thin_template_surface(tmp_path):
     generated_backup = (output / "README.backup.md").read_text(encoding="utf-8")
     assert generated_backup == generated_readme
     assert generated_readme != Path("README.md").read_text(encoding="utf-8")
-    assert "This is the setup README for your Reponomics dashboard repository." in (
-        generated_readme
-    )
+    # assert "This is the setup README for your Reponomics dashboard repository." in (
+    #     generated_readme
+    # )
     assert "README.backup.md" in generated_readme
     assert (output / "config.yaml").read_text(encoding="utf-8") == (
         CONFIG_EXAMPLE_SOURCE.read_text(encoding="utf-8")
@@ -587,63 +587,6 @@ def test_generated_template_workflow_names_are_command_labels():
         assert workflow["name"] == expected_name
 
 
-def test_setup_workflow_resolves_data_modes():
-    setup = Path("template/.github/workflows/setup.yml").read_text(encoding="utf-8")
-
-    assert "inputs:" not in setup
-    assert "Resolve setup configuration" in setup
-    assert "resolve-reponomics-config.py" in setup
-    assert "generate_html_dashboard:" not in setup
-    assert "generate_readme:" not in setup
-    assert "use_github_app:" not in setup
-    assert "publish_dashboard:" not in setup
-    assert "commit_readme:" not in setup
-    assert "commit_readme_snapshot:" not in setup
-    assert "PUBLISH_TO_PAGES" not in setup
-    assert "COMMIT_README_SNAPSHOT" not in setup
-    assert "PUBLISH_PAGES_DASHBOARD" in setup
-    assert "PUBLISH_README_DASHBOARD" in setup
-    assert "README dashboard generation is only supported for private repositories." not in setup
-    assert "cp README.md README.backup.md" not in setup
-    assert "cat > README.md <<'MD'" in setup
-    assert "This repository was generated from the [Reponomics Dashboard template repo]" in setup
-    assert ".github/workflows/update-docs.yml" in setup
-    assert ": > .reponomics/setup-complete" in setup
-    assert "git add README.md .reponomics/setup-complete" in setup
-    assert '"data_mode": os.environ["DATA_MODE"]' not in setup
-    assert '"retention_days": os.environ["RETENTION_DAYS"]' not in setup
-    assert "data_mode=plaintext" not in setup
-    assert "default: encrypted" not in setup
-    assert re.search(r"^permissions:\n  contents: read$", setup, flags=re.MULTILINE)
-    assert re.search(r"^\s+permissions:\n\s+contents: write$", setup, flags=re.MULTILINE)
-    assert "actions: write" not in setup
-    assert "DASHBOARD_NEXT_SECRET" not in setup
-    assert "enable_workflow" not in setup
-    assert "outage-sentinel" not in setup
-    assert "Scheduled workflow keepalive" in setup
-    assert "60 days without repository activity" in setup
-    assert "token: ${{ secrets.COLLECTION_TOKEN" not in setup
-    assert "personal-access-tokens/new" in setup
-    assert "name=COLLECTION_TOKEN" in setup
-    assert "name=Reponomics%20Collection%20Token" not in setup
-    assert "administration=read" in setup
-    assert "target_name=$GITHUB_REPOSITORY_OWNER" in setup
-    assert "All repositories" in setup
-    assert "Only selected repositories" in setup
-    assert "keep \\`config.yaml\\` within" in setup
-    assert "COLLECTION_APP_PRIVATE_KEY" in setup
-    assert "COLLECTION_APP_ID" in setup
-    assert "docs/reponomics/" in setup
-    assert '${#DASHBOARD_SECRET_DO_NOT_REPLACE}' not in setup
-    assert "Manual GitHub Pages step" in setup
-    assert '[ "$PUBLISH_PAGES_DASHBOARD" = "true" ] && [ "$DATA_MODE" = "encrypted" ]' in setup
-    assert "Collection auth mode" in setup
-    assert "Settings -> Pages" in setup
-    assert "skip them" in setup
-    assert "repos/$GITHUB_REPOSITORY/pages" not in setup
-    assert "PAGES_PUBLICATION" not in setup
-
-
 def test_setup_workflow_does_not_commit_workflow_file_changes(tmp_path):
     """Setup must not require workflow write permission in generated repos."""
     output = tmp_path / "template"