Investigate (and migrate) whether HIERO_LEDGER_READ token will allow a migration of activity by permission holders from config.yaml to github api

[exploreriii]

🧑‍🔬 Advanced Issue — the most complex work in this project: architectural, multi-module, or core-logic changes where the solution itself may need discovering.
Time: ~30+ hours · Prerequisites: a proven track record here (≥1 completed intermediate issue; demonstrated CI/CD proficiency substitutes for workflow-focused issues).
The bar is production-ready: safe, maintainable, architecturally sound.

The task

Problem:
Reading permission holders in a given repository is gated by permissions, requires read permissions.

When we want to track who has permissions in a repo and their activity rates, such as in table:
https://hiero-hackers.github.io/analytics/#tab=Governance&widget=gonedark

We rely on approximating who is a role holder by looking at the config.yaml file from governance https://github.com/hiero-ledger/governance/blob/main/config.yaml and mapping their permissions, then tracking their activity based on these approximated permissions.

If instead we can confirm permissions directly from the github api, we can use our existing activity trackers to plug in to that data, making the solution much more accurate and also lightweight

Impact / what done looks like:
Confirm and migrate from approximating permissions from config.yaml to fetching from github directly with use of this token

Known unknowns and risks:
We do not know if the token will enable this, nor the codebase that needs to be updated

How to work on this

1. Claim it: comment /assign — yes, even at this level; unassigned PRs are closed automatically.
2. Propose your design as a comment before building. Cover the approach, the alternatives you rejected, and the system-wide impact. For large changes, say how you'll split the work into reviewable PRs. (@coderabbitai plan can sketch a starting point, but the design is yours.)

What tends to bite experienced contributors in this repo:

• The dependency DAG in docs/architecture.md is deliberately strict (zero violations today) — a solution that needs a new cross-layer import needs a design conversation first, not an exception.
• The output-contract test pins every CSV, chart, and dashboard artifact the pipelines produce. Changing the output surface means changing the contract on purpose, and downstream dashboard consumers exist.
• Ingestion has deliberate two-layer staleness semantics (TTL cache vs. the durable incremental dataset store with reuse/refresh windows) — read the module docstrings before touching fetch paths; naive "fixes" here reintroduce bugs we've already removed.

🤖 AI: tools are welcome; verified work is required — see the AI policy. Fully automated bot PRs are closed.

Before opening your PR:

• The PR includes a short design/impact note: approach, alternatives considered, affected modules, compatibility impact
• Correctness, safety, and performance are evaluated, not assumed — and the evaluation is visible in the note or the tests
• Testing is comprehensive, including deliberate output-contract updates where the output surface changes
• I reviewed my own diff as if it were someone else's

Review expectations: advanced PRs get probing questions and may take longer than a day — that's the level working as intended. Stuck or want a design sounding board? Comment here — see getting help.

[coderabbitai]

Coding Plan

Summary

• Confirm the HIERO_LEDGER_READ token against GET /repos/{owner}/{repo}/collaborators first. The ticket's core unknown is whether the token grants this access.
• Add a new data_sources collaborator-permissions resource that reuses the existing REST, cache, snapshot, and offline patterns. Produce the same {repo(bare): {user: role}} structure that role_coverage already consumes.
• Wire the API source into pipelines/role_coverage.py as the primary source. Add a graceful fallback to the existing config.yaml approximation, so the output contract, forks, and offline CI stay intact.
• Document the deliberate security-posture change. Keep test coverage for both the API and fallback paths.

Design Choices

Design Choice 1: Which GitHub API surface fetches collaborator permissions

Options Considered:

1. REST GET /repos/{owner}/{repo}/collaborators?affiliation=all — returns role_name (pull/triage/push/maintain/admin) and permissions, includes team-based org members and outside collaborators, follows the existing github_rest.py pattern.
2. GraphQL Repository.collaborators — requires push access, returns less direct role mapping, and needs a new GraphQL query.

Chosen Option: 1

Rationale: REST returns the effective role_name directly, matches the existing github_rest.py call style, and needs only Metadata: Read plus the caller's effective repository role.

Design Choice 2: Full replacement of config.yaml path or primary source with fallback

Options Considered:

1. Full replacement — remove the config.yaml role derivation and depend only on the API.
2. Hybrid — use API-derived permissions when the token is present and authorized, and fall back to the config.yaml approximation otherwise.

Chosen Option: 2

Rationale: The hybrid preserves the documented "public read" posture for contributors and forks, keeps offline CI working, keeps ungoverned/extra orgs functional, and matches the existing optional-secret-with-fallback pattern used for ANALYTICS_PAT.

Design Choice 3: Token environment variable name

Options Considered:

1. HIERO_LEDGER_READ — the exact name in the ticket.
2. A generic name such as GITHUB_PERMISSIONS_TOKEN.

Chosen Option: 1

Rationale: Use HIERO_LEDGER_READ to match the ticket and the CI secret that will be provisioned, and document its required scope in SECURITY.md and CONTRIBUTING.md.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Feasibility validation and role-mapping foundation

This phase confirms the token works against the collaborators endpoint and prepares the shared role-mapping vocabulary. Group these tasks together because they establish the facts and the domain primitive that the new data source depends on.

Task 1: Add the permissions token to configuration

Introduce the new token as an optional, separately named credential.

• Update src/hiero_analytics/config/github.py to read a new HIERO_LEDGER_READ environment variable, alongside the existing GITHUB_TOKEN.
• Keep the token optional. Do not fail startup when it is unset.
• Expose a small helper that reports whether an elevated permissions token is configured, so upper layers can select the source.
• Do not add elevated-scope requirements to the default GITHUB_TOKEN.

Task 2: Validate token access to the collaborators endpoint

Confirm the unknown from the ticket before building the migration.

• Add a small, self-contained validation entry point (a CLI subcommand or a script under an existing scripts location) that calls GET /repos/{owner}/{repo}/collaborators?affiliation=all for a sample of hiero-ledger repos using HIERO_LEDGER_READ.
• Report the HTTP status, whether role_name is present, and whether team-based org members appear.
• Detect and log the "Must have push access to view repository collaborators" and 403 cases explicitly, because these define whether the migration is viable.
• Record the findings in the PR design note. Do not couple this validation code to the pipeline.

Task 3: Add role_name mapping to the domain vocabulary

Provide a single mapping from GitHub API roles to the existing role vocabulary.

• Extend src/hiero_analytics/domain/roles.py with a mapping from role_name values (pull, triage, push, maintain, admin) to the existing roles.
• Map pull→None (not counted), triage→triage, push→committer, maintain→maintainer, admin→maintainer, to stay consistent with the current permission_to_role output.
• Reuse ROLE_PRIORITY and the existing role names. Do not introduce new role names.

🤖 Prompt for AI agents

Implement Phase 1: validate that the `HIERO_LEDGER_READ` token can read
collaborator permissions, and build the domain role-mapping foundation for later
phases.

- In `src/hiero_analytics/config/github.py`, add a new optional environment
variable `HIERO_LEDGER_READ` next to the existing `GITHUB_TOKEN`. Do not fail
startup if it is unset. Add a small helper function that reports whether an
elevated permissions token is configured, for use by upper layers to select the
data source. Do not add elevated-scope requirements to `GITHUB_TOKEN`.
- Add a self-contained validation entry point (CLI subcommand or script under an
existing scripts location) that calls `GET
/repos/{owner}/{repo}/collaborators?affiliation=all` for a sample of
`hiero-ledger` repos, using `HIERO_LEDGER_READ` for authorization. Have it
report HTTP status, presence of `role_name`, and whether team-based org members
appear. Explicitly detect and log the "Must have push access to view repository
collaborators" message and `403` responses. Keep this validation code decoupled
from the pipeline. Record findings in the PR design note.
- Extend `src/hiero_analytics/domain/roles.py` with a mapping from GitHub
`role_name` values to existing roles: `pull`→`None` (not counted),
`triage`→`triage`, `push`→`committer`, `maintain`→`maintainer`,
`admin`→`maintainer`. Reuse `ROLE_PRIORITY` and existing role names; do not
introduce new role names.

Phase 2: New collaborator-permissions data source

This phase adds the data source that fetches collaborator permissions and produces the same {repo: {user: role}} structure that downstream code already consumes. Group these tasks together because they form one new resource inside data_sources.

Task 1: Add a collaborator-permission record model

Define the record shape and hydration for API responses.

• Add a CollaboratorPermissionRecord to src/hiero_analytics/data_sources/models.py with fields for repo, login, and role_name.
• Add a hydrator that builds the record from the REST JSON node.
• Keep the model free of analysis or pipeline imports, per the layering rules.

Task 2: Fetch collaborator permissions per repo

Add the REST fetch that fans out across the org's repos.

• Add a new resource module under src/hiero_analytics/data_sources/github_ingest/ (for example collaborators.py) that enumerates repos via the existing repo enumeration (fetch_org_repos_graphql/RepositoryRecord).
• For each repo, call GET /repos/{owner}/{repo}/collaborators?affiliation=all through GitHubClient, following the github_rest.py pattern for authenticated REST calls, but using HIERO_LEDGER_READ for authorization.
• Reuse the shared parallel fan-out and retry helpers (_common.py fetch_all_with_retry / fetch_org_resource_parallel) and the TTL cache (cache.py) for per-repo parallelism, because collaborator permissions are a per-repo snapshot with no reliable "since" timestamp.
• Handle per-repo 403/"Must have push access" responses defensively. Skip the repo and record the reason rather than failing the whole run.

Task 3: Build the API-derived role lookup with offline snapshot support

Produce the {repo: {user: role}} structure and persist it for offline runs.

• Add a builder that converts CollaboratorPermissionRecord values into {repo(bare): {user: role}}, using the Task 1.3 mapping, is_bot_login exclusion, and username normalization (trim + lowercase), matching the existing build_repo_role_lookup semantics.
• Take each user's highest role per repo. The endpoint already returns the effective role, so no team-merge logic is needed here.
• Persist an aggregate JSON snapshot per org (following the governance_config.py snapshot approach and dataset_path), and read the snapshot when offline_mode_enabled() is true.
• Note in code comments that the config-only BLANKET_TEAMS idiom does not apply to API data, because the API already reports effective org-wide grants.

🤖 Prompt for AI agents

Implement Phase 2: add a new `data_sources` resource that fetches collaborator
permissions from the GitHub REST API and produces the same `{repo: {user:
role}}` structure as the existing config-based lookup.

- In `src/hiero_analytics/data_sources/models.py`, add a
`CollaboratorPermissionRecord` with fields for repo, login, and `role_name`,
plus a hydrator that builds the record from the REST JSON node. Keep this model
free of analysis or pipeline imports, per the layering rules.
- Add a new resource module under
`src/hiero_analytics/data_sources/github_ingest/` (for example
`collaborators.py`). Enumerate repos via the existing repo enumeration
(`fetch_org_repos_graphql`/`RepositoryRecord`). For each repo, call `GET
/repos/{owner}/{repo}/collaborators?affiliation=all` through `GitHubClient`,
following the `github_rest.py` pattern for authenticated REST calls, but
authorize using `HIERO_LEDGER_READ`. Reuse the shared parallel fan-out and retry
helpers (`_common.py` `fetch_all_with_retry` / `fetch_org_resource_parallel`)
and the TTL cache (`cache.py`) for per-repo parallelism, since collaborator
permissions form a per-repo snapshot with no reliable "since" timestamp. Handle
per-repo `403`/"Must have push access" responses defensively: skip the repo and
record the reason instead of failing the whole run.
- Add a builder that converts `CollaboratorPermissionRecord` values into
`{repo(bare): {user: role}}`, using the Phase 1 role_name mapping,
`is_bot_login` exclusion, and username normalization (trim + lowercase),
matching the existing `build_repo_role_lookup` semantics. Take each user's
highest role per repo; no team-merge logic is needed since the endpoint returns
the effective role. Persist an aggregate JSON snapshot per org, following the
`governance_config.py` snapshot approach and `dataset_path`, and read that
snapshot when `offline_mode_enabled()` is true. Add a code comment noting that
the config-only `BLANKET_TEAMS` idiom does not apply to API data, because the
API already reports effective org-wide grants.

Phase 3: Pipeline integration with fallback and graceful degradation

This phase wires the new source into the role_coverage pipeline as the primary source, with a fallback to the existing config.yaml path. Group these tasks together because they change source selection without changing the output surface.

Task 1: Select the permission source in the role_coverage pipeline

Choose the API source when authorized, otherwise fall back.

• Update src/hiero_analytics/pipelines/role_coverage.py to select the API-derived lookup when HIERO_LEDGER_READ is configured and the org is governed, and to fall back to fetch_governance_config + build_repo_role_lookup otherwise.
• Keep the resulting roles_by_repo keyed by bare repo name, so the existing bare_repo() join with activity records is unchanged.
• Keep all downstream CSV writes (role_coverage_all*.csv, role_coverage_globally_quiet*.csv, team tables) unchanged in name, columns, and period variants.

Task 2: Degrade gracefully when the token or data is unavailable

Ensure forks, contributors, and offline CI keep working.

• When HIERO_LEDGER_READ is unset or the API returns insufficient-access errors for the org, log a clear message and use the config.yaml fallback.
• When offline_mode_enabled() is true, read the API snapshot from Task 2.3 if present, and otherwise fall back to the governance snapshot, reusing the OfflineDatasetMissingError skip-cleanly pattern where appropriate.
• Keep extra/ungoverned orgs (for example hiero-hackers) resolving to no governance data, preserving current per-org semantics.

🤖 Prompt for AI agents

Implement Phase 3: integrate the new API-derived collaborator permission lookup
into the `role_coverage` pipeline as the primary source, with fallback to the
existing `config.yaml`-based lookup, keeping the output surface unchanged.

- Update `src/hiero_analytics/pipelines/role_coverage.py` to select the
API-derived lookup when `HIERO_LEDGER_READ` is configured and the org is
governed. Fall back to `fetch_governance_config` + `build_repo_role_lookup`
otherwise. Keep the resulting `roles_by_repo` keyed by bare repo name so the
existing `bare_repo()` join with activity records stays unchanged. Keep all
downstream CSV writes (`role_coverage_all*.csv`,
`role_coverage_globally_quiet*.csv`, team tables) unchanged in name, columns,
and period variants.
- Add graceful degradation: when `HIERO_LEDGER_READ` is unset, or the API
returns insufficient-access errors for the org, log a clear message and use the
`config.yaml` fallback. When `offline_mode_enabled()` is true, read the API
snapshot from Phase 2 if present, otherwise fall back to the governance
snapshot, reusing the `OfflineDatasetMissingError` skip-cleanly pattern where
appropriate. Keep extra/ungoverned orgs (for example `hiero-hackers`) resolving
to no governance data, preserving current per-org semantics.

Phase 4: Tests, output contract, and documentation

This phase verifies behavior and records the deliberate scope change. Group these tasks together because they cover correctness and the documented security/architecture posture.

Task 1: Add and update tests

Cover the new source, mapping, and fallback selection.

• Add unit tests for the role_name mapping in domain/roles.py.
• Add tests for the collaborator fetch record hydration and the API-derived lookup builder, including bot exclusion, username normalization, highest-role-per-repo, and the 403/"push access" skip path. Add fixtures for representative collaborator JSON.
• Add pipeline tests in tests/pipelines/test_role_coverage.py that assert the same top-level CSVs are produced under both the API path and the fallback path.
• Keep tests/data_sources/test_governance_config.py valid, because build_repo_role_lookup and the config path remain for fallback.

Task 2: Preserve and confirm the output contract

Confirm no unintended output-surface changes.

• Confirm tests/contracts/test_output_contract.py still passes, because file names and column sets are unchanged.
• If the source selection introduces any new persisted artifact (for example the API snapshot), confirm it is not emitted at the org output level, so it does not trigger the "orphan output" check. Update the contract deliberately only if a new user-visible output is added.

Task 3: Update documentation and CI

Record the new token, its scope, and the design decision.

• Update SECURITY.md to describe HIERO_LEDGER_READ as an optional read-scoped credential that reads collaborator permissions, and note that it exceeds the public-read default.
• Update CONTRIBUTING.md to state that HIERO_LEDGER_READ is optional and that the config.yaml fallback runs without it.
• Update src/hiero_analytics/config/README.md and src/hiero_analytics/data_sources/README.md to document the new token and the collaborator-permissions source.
• Add a "fetched resource requiring a permission-scoped token" note to the "Where things commonly go" table in docs/architecture.md.
• Update .github/workflows/update-analytics.yml to pass the optional HIERO_LEDGER_READ secret with graceful fallback, matching the existing ANALYTICS_PAT pattern.

🤖 Prompt for AI agents

Implement Phase 4: add test coverage for the new source and fallback logic,
confirm the output contract stays intact, and document the new token and design
decision.

- Add unit tests for the `role_name` mapping in `domain/roles.py`.
- Add tests for the collaborator fetch record hydration and the API-derived
lookup builder, covering bot exclusion, username normalization,
highest-role-per-repo selection, and the `403`/"push access" skip path. Add
fixtures for representative collaborator JSON.
- Add pipeline tests in `tests/pipelines/test_role_coverage.py` that assert the
same top-level CSVs are produced under both the API path and the fallback path.
- Keep `tests/data_sources/test_governance_config.py` valid, since
`build_repo_role_lookup` and the config path remain for fallback.
- Confirm `tests/contracts/test_output_contract.py` still passes, since file
names and column sets are unchanged. If source selection introduces a new
persisted artifact (for example the API snapshot), confirm it is not emitted at
the org output level, so it does not trigger the "orphan output" check. Update
the contract deliberately only if a new user-visible output is added.
- Update `SECURITY.md` to describe `HIERO_LEDGER_READ` as an optional
read-scoped credential that reads collaborator permissions, noting it exceeds
the public-read default.
- Update `CONTRIBUTING.md` to state that `HIERO_LEDGER_READ` is optional and
that the `config.yaml` fallback runs without it.
- Update `src/hiero_analytics/config/README.md` and
`src/hiero_analytics/data_sources/README.md` to document the new token and the
collaborator-permissions source.
- Add a "fetched resource requiring a permission-scoped token" note to the
"Where things commonly go" table in `docs/architecture.md`.
- Update `.github/workflows/update-analytics.yml` to pass the optional
`HIERO_LEDGER_READ` secret with graceful fallback, matching the existing
`ANALYTICS_PAT` pattern.

Research

The project is a layered analytics pipeline. data_sources fetches and caches GitHub data. domain holds the role vocabulary (domain/roles.py). analysis transforms data. pipelines orchestrate runs. dashboard_spec and export render widgets.

Today, the pipeline does not read permission holders from GitHub. Instead, data_sources/governance_config.py fetches the governance config.yaml, and build_repo_role_lookup maps team-to-permission grants to a {repo: {user: role}} structure. pipelines/role_coverage.py joins that lookup with activity data and writes role_coverage_globally_quiet*.csv, which drives the gonedark widget.

The dependency graph is strict and acyclic (data_sources may import only config and domain). The output-contract test pins CSV file names and column sets. Fetching actual collaborator permissions is a new capability that must fit into the existing REST fetch, cache, and offline-snapshot patterns.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: validate that the `HIERO_LEDGER_READ` token can read
collaborator permissions, and build the domain role-mapping foundation for later
phases.

- In `src/hiero_analytics/config/github.py`, add a new optional environment
variable `HIERO_LEDGER_READ` next to the existing `GITHUB_TOKEN`. Do not fail
startup if it is unset. Add a small helper function that reports whether an
elevated permissions token is configured, for use by upper layers to select the
data source. Do not add elevated-scope requirements to `GITHUB_TOKEN`.
- Add a self-contained validation entry point (CLI subcommand or script under an
existing scripts location) that calls `GET
/repos/{owner}/{repo}/collaborators?affiliation=all` for a sample of
`hiero-ledger` repos, using `HIERO_LEDGER_READ` for authorization. Have it
report HTTP status, presence of `role_name`, and whether team-based org members
appear. Explicitly detect and log the "Must have push access to view repository
collaborators" message and `403` responses. Keep this validation code decoupled
from the pipeline. Record findings in the PR design note.
- Extend `src/hiero_analytics/domain/roles.py` with a mapping from GitHub
`role_name` values to existing roles: `pull`→`None` (not counted),
`triage`→`triage`, `push`→`committer`, `maintain`→`maintainer`,
`admin`→`maintainer`. Reuse `ROLE_PRIORITY` and existing role names; do not
introduce new role names.
===============================================================================

Task: 2

Implement Phase 2: add a new `data_sources` resource that fetches collaborator
permissions from the GitHub REST API and produces the same `{repo: {user:
role}}` structure as the existing config-based lookup.

- In `src/hiero_analytics/data_sources/models.py`, add a
`CollaboratorPermissionRecord` with fields for repo, login, and `role_name`,
plus a hydrator that builds the record from the REST JSON node. Keep this model
free of analysis or pipeline imports, per the layering rules.
- Add a new resource module under
`src/hiero_analytics/data_sources/github_ingest/` (for example
`collaborators.py`). Enumerate repos via the existing repo enumeration
(`fetch_org_repos_graphql`/`RepositoryRecord`). For each repo, call `GET
/repos/{owner}/{repo}/collaborators?affiliation=all` through `GitHubClient`,
following the `github_rest.py` pattern for authenticated REST calls, but
authorize using `HIERO_LEDGER_READ`. Reuse the shared parallel fan-out and retry
helpers (`_common.py` `fetch_all_with_retry` / `fetch_org_resource_parallel`)
and the TTL cache (`cache.py`) for per-repo parallelism, since collaborator
permissions form a per-repo snapshot with no reliable "since" timestamp. Handle
per-repo `403`/"Must have push access" responses defensively: skip the repo and
record the reason instead of failing the whole run.
- Add a builder that converts `CollaboratorPermissionRecord` values into
`{repo(bare): {user: role}}`, using the Phase 1 role_name mapping,
`is_bot_login` exclusion, and username normalization (trim + lowercase),
matching the existing `build_repo_role_lookup` semantics. Take each user's
highest role per repo; no team-merge logic is needed since the endpoint returns
the effective role. Persist an aggregate JSON snapshot per org, following the
`governance_config.py` snapshot approach and `dataset_path`, and read that
snapshot when `offline_mode_enabled()` is true. Add a code comment noting that
the config-only `BLANKET_TEAMS` idiom does not apply to API data, because the
API already reports effective org-wide grants.
===============================================================================

Task: 3

Implement Phase 3: integrate the new API-derived collaborator permission lookup
into the `role_coverage` pipeline as the primary source, with fallback to the
existing `config.yaml`-based lookup, keeping the output surface unchanged.

- Update `src/hiero_analytics/pipelines/role_coverage.py` to select the
API-derived lookup when `HIERO_LEDGER_READ` is configured and the org is
governed. Fall back to `fetch_governance_config` + `build_repo_role_lookup`
otherwise. Keep the resulting `roles_by_repo` keyed by bare repo name so the
existing `bare_repo()` join with activity records stays unchanged. Keep all
downstream CSV writes (`role_coverage_all*.csv`,
`role_coverage_globally_quiet*.csv`, team tables) unchanged in name, columns,
and period variants.
- Add graceful degradation: when `HIERO_LEDGER_READ` is unset, or the API
returns insufficient-access errors for the org, log a clear message and use the
`config.yaml` fallback. When `offline_mode_enabled()` is true, read the API
snapshot from Phase 2 if present, otherwise fall back to the governance
snapshot, reusing the `OfflineDatasetMissingError` skip-cleanly pattern where
appropriate. Keep extra/ungoverned orgs (for example `hiero-hackers`) resolving
to no governance data, preserving current per-org semantics.
===============================================================================

Task: 4

Implement Phase 4: add test coverage for the new source and fallback logic,
confirm the output contract stays intact, and document the new token and design
decision.

- Add unit tests for the `role_name` mapping in `domain/roles.py`.
- Add tests for the collaborator fetch record hydration and the API-derived
lookup builder, covering bot exclusion, username normalization,
highest-role-per-repo selection, and the `403`/"push access" skip path. Add
fixtures for representative collaborator JSON.
- Add pipeline tests in `tests/pipelines/test_role_coverage.py` that assert the
same top-level CSVs are produced under both the API path and the fallback path.
- Keep `tests/data_sources/test_governance_config.py` valid, since
`build_repo_role_lookup` and the config path remain for fallback.
- Confirm `tests/contracts/test_output_contract.py` still passes, since file
names and column sets are unchanged. If source selection introduces a new
persisted artifact (for example the API snapshot), confirm it is not emitted at
the org output level, so it does not trigger the "orphan output" check. Update
the contract deliberately only if a new user-visible output is added.
- Update `SECURITY.md` to describe `HIERO_LEDGER_READ` as an optional
read-scoped credential that reads collaborator permissions, noting it exceeds
the public-read default.
- Update `CONTRIBUTING.md` to state that `HIERO_LEDGER_READ` is optional and
that the `config.yaml` fallback runs without it.
- Update `src/hiero_analytics/config/README.md` and
`src/hiero_analytics/data_sources/README.md` to document the new token and the
collaborator-permissions source.
- Add a "fetched resource requiring a permission-scoped token" note to the
"Where things commonly go" table in `docs/architecture.md`.
- Update `.github/workflows/update-analytics.yml` to pass the optional
`HIERO_LEDGER_READ` secret with graceful fallback, matching the existing
`ANALYTICS_PAT` pattern.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[exploreriii]

Closing as currently out of scope