[self-care:documentation-discoverability] Agent documentation routing defects

Open Beginner friendly
  • Is something wrong?
#20,667 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
javascript
Domain
documentation

Research direction

Start with docs/deployment.md, docs/configuration.md and docs/dashboard-data-ingestion.md, then trace how llms.txt routes through resources.json to documentation pages. Add a bounded, authoritative section for hosted Redis and make it reachable from that route; rerun the discoverability audit to confirm task 8 succeeds without a fallback search.

Written by the indexing model from the issue text.

Description

self-care self-care:documentation-discoverability

Routing succeeded for 9 of 10 tasks (90%). Task 8 (configure hosted Redis) fails: no routed document covers it, and a bounded repository search was needed.

Action: Fix the listed authoritative routing defects and rerun this audit.

Metrics
  • Routing success: 9/10 (90%)
  • Document hops: average 1.5, maximum 2
  • Fallback searches: 1
  • Dead ends: 1
  • Missing documents: 1
  • Contradictions: 0
  • Obsolete references: 0
Task results
Per-task table
# Task First doc Next doc Hops Unambiguous Answered Fallback Dead end Missing Contradiction Obsolete
1 Campaign execution authority resources.json authority-envelopes 2 true true false false none false none
2 Add a new campaign create-cao-campaign skill none 1 true true false false none false none
3 Change dashboard canonical data model resources.json dashboard-data-model 2 true true false false none false none
4 Implement a Dashboard Language query resources.json dashboard-language 2 true true false false none false none
5 Activity workflow-metadata collection resources.json activity 2 true true false false none false none
6 Worker authority constraints resources.json orchestrators-and-workers 2 true true false false none false none
7 Debug a failed CAO deployment debug-cao skill none 1 true true false false none false none
8 Configure hosted Redis resources.json deployment 2 false false true true hosted Redis configuration page or section false none
9 Add a CAO CLI command cao-cli skill none 1 true true false false none false none
10 Set up CAO via setup-cao setup-cao skill none 1 true true false false none false none
Required remediation
  • Task 8: llms.txt, resources.json and llms-small.txt give no route to hosted Redis guidance. llms-small.txt mentions Redis only to say it is not required for the local dashboard. Source files exist in docs/configuration.md and docs/dashboard-data-ingestion.md.
  • Add a bounded Redis section to docs/deployment.md, or to the authoritative configuration page. It must be reachable from llms.txt through resources.json, with a resource entry or a link from the deployment page. Alternatively, add the Redis topic to the description of an existing routed resource.
Evidence
Retrieval and validation

  • Public URL: https://githubnext.github.io/gh-cao/llms.txt (retrieval status: available)

  • SHA-256 digests:

    • llms.txt: 296aa723791831f8ec71a3e6c2fd938ab074ce05e731db2c857ced2a7db69f84
    • resources.json: 3d1d9d7fc269b8906b8e76001ae622d705cd2ec5700362f688f62728dc8c46e5
    • resource.json: f205fc73ebb4ff14620a21a626a04b6e46659a09b19fb6a3691db170fa754c81
    • catalog-resource.json: b8ebd3eabfa5c5fda79dddb604e229a3cc92ea6da9a705ca1b58b0964db1742d

  • resources.json: 62 resources, sorted by id, all URLs under https://githubnext.github.io/gh-cao/.

  • resource.json: has source, provenance (commit d4bf131), freshness and sha256 integrity. It exposes only read-only cao pages, cao_catalog and cao_overview bindings.

  • catalog-resource.json: has executable read-only cao_catalog bindings for both pages and queries.

  • Fallback for task 8: one repository search for "redis" under docs/ and README.md matched docs/configuration.md, docs/control-policy-specification.md, docs/dashboard-data-ingestion.md and docs/dashboard.md. Only the match list was recorded and no file was opened. This counts as a discoverability failure.

  • Limitation: sampled per-page index.json fetches from the public site were not completed in this run. Task routing was judged from llms.txt, resources.json and llms-small.txt.

Control Plane

cao: githubnext/gh-cao, correlation: 43168974790-3862

Generated by SelfCare / Documentation Discoverability · copilot · auto (Claude Sonnet 5.5) · ~28 AIC · ⌖ ~2 AIC · ⊞ 15.5K · ◷

  • expires on Nov 26, 2026, 6:45 AM UTC
Dominant language
JavaScript
Stars
19
Forks
4
Avg merge
4h
Merged PRs (30d)
708

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from githubnext/gh-cao

All issues in githubnext/gh-cao

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.