docs(readme): factual fixes — backend persistence, empty providers (#6196, #6198) by clubanderson · Pull Request #6207 · kubestellar/console

clubanderson · 2026-04-10T19:11:40Z

Summary

Three Copilot review nits across PRs #6194 and #6197. Verified each against source before changing.

#	Correction	Verified against
#6196 / README:78	`add-apt-repository` requires `software-properties-common`, which minimal Ubuntu/WSL images don't ship. Added an explicit `apt-get install -y software-properties-common` line + `-y` flag so the whole snippet runs unattended.	n/a — packaging convention
#6198 / README:102	I claimed the GitHub PAT in the Settings UI is 'Saved by the local kc-agent to its on-disk settings file.' Wrong. `GitHubTokenSection.tsx:57+` POSTs to `/api/github/token`, which is handled by the console backend (`pkg/api/handlers/github_proxy.go` via `api.Post('/github/token', githubProxy.SaveToken)`), NOT by kc-agent. The backend persists to `~/.kc/settings.json`. The 'doesn't work on hosted' reason was also wrong — it's not about `LOCAL_AGENT_HTTP_URL`; the hosted Netlify demo has no writable local backend at all. Fixed both.	`web/src/components/settings/sections/GitHubTokenSection.tsx:57`, `pkg/api/server.go:692-694`
#6198 / README:159	I documented the Settings → API Keys → Manage Keys flow as the recommended path for adding AI keys. It does not work — the agent endpoint that backs this UI returns an empty providers list (`providers := []providerDef{}`), with a source comment saying 'API-key-driven agents are hidden because they cannot execute commands.' So the modal renders zero providers and users can't enter keys through it. Rewrote the AI section to lead with the env-var path (which actually works) and added a note explaining why the modal is currently empty.	`pkg/agent/server_operations.go:284-288`

Note: #6196's other two items (Go 1.24 → 1.25 in Linux example, missing mkdir -p bin) were already fixed in #6197 in a different code path. Verified both are still correct on main.

Closes #6196, closes #6198.

…rs, software-properties-common (#6196, #6198) Three Copilot review nits across two PRs, all verified against source: 1. #6196 / README:78 — sudo add-apt-repository assumes software-properties-common is installed, but minimal Ubuntu/WSL images don't ship with it. Added an explicit apt-get install line for software-properties-common, plus -y to add-apt-repository so the whole snippet runs unattended. 2. #6198 / README:102 — I claimed the GitHub PAT in the Settings UI is 'Saved by the local kc-agent to its on-disk settings file'. Wrong. Verified against web/src/components/settings/sections/GitHubTokenSection.tsx:57+ and pkg/api/server.go:692-694: GitHubTokenSection POSTs to /api/github/token, which is handled by the **console backend** (pkg/api/handlers/github_proxy.go), NOT by kc-agent. The token is persisted to ~/.kc/settings.json by the backend's settings manager. The 'doesn't work on hosted' reason is also wrong — it's not about LOCAL_AGENT_HTTP_URL, it's that the hosted Netlify demo has no writable local backend at all. Fixed both. 3. #6198 / README:159 — I documented the Settings → API Keys → Manage Keys flow as the recommended way to add OpenAI/Claude/ Gemini keys. Verified against pkg/agent/server_operations.go:288: the agent's /settings/keys endpoint literally returns an empty providers list (`providers := []providerDef{}`). The comment in the source explains 'API-key-driven agents are hidden because they cannot execute commands.' So the modal renders zero providers and the documented flow does not work in the current build. Rewrote the AI section to lead with the env-var path (which actually works), and added a note explaining why the Settings UI modal is currently empty so users don't go hunting for a feature that's been intentionally disabled. Note: #6196's other two items (Go 1.24 → 1.25 in the Linux example, and missing `mkdir -p bin`) were already addressed in PR #6197 in a different code path; verified those are still correct on main. Closes #6196, closes #6198. Signed-off-by: Andrew Anderson <[email protected]>

kubestellar-prow · 2026-04-10T19:11:45Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign eeshaansa for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

netlify · 2026-04-10T19:11:46Z

✅ Deploy Preview for kubestellarconsole canceled.

Name	Link
🔨 Latest commit	`0863c17`
🔍 Latest deploy log	https://app.netlify.com/projects/kubestellarconsole/deploys/69d94b6fa10a0c00097aaa49

github-actions · 2026-04-10T19:11:49Z

👋 Hey @clubanderson — thanks for opening this PR!

🤖 This project is developed exclusively using AI coding assistants.

Please do not attempt to code anything for this project manually.
All contributions should be authored using an AI coding tool such as:

Claude Code (Opus 4.5 / 4.6) — recommended

GitHub Copilot

Cursor

Other AI coding assistants

This ensures consistency in code style, architecture patterns, test coverage,
and commit quality across the entire codebase.

This is an automated message.

Copilot

Pull request overview

Documentation-only PR addressing factual correctness in the README around WSL prerequisites, GitHub token persistence, and AI API key configuration behavior.

Changes:

Update WSL/Ubuntu build-from-source snippet to install software-properties-common before using add-apt-repository.
Correct README claims about where the Settings UI GitHub PAT is persisted (console backend → ~/.kc/settings.json).
Rework AI BYOK docs to lead with env-var configuration and explain why the Settings → API Keys modal currently shows no providers.

Copilot · 2026-04-10T19:15:14Z

 | Credential | What it does | Where it lives | When you need it |
 |---|---|---|---|
 | **GitHub OAuth App** (`GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET`) | Sign-in for the **self-hosted** console at `localhost:8080` | `.env` file at the repo root | Only if you self-host the console AND want user sign-in. Skip for the hosted demo. |
-| **GitHub PAT in Settings UI** | Powers nightly E2E status, community activity, leaderboard widgets | Saved by the local `kc-agent` to its on-disk settings file (not browser-only). Only reachable when self-hosting — the hosted Netlify build disables `LOCAL_AGENT_HTTP_URL`, so the Settings page cannot persist a token there. | Optional. Adds GitHub-powered widgets to your **self-hosted** dashboard. |
+| **GitHub PAT in Settings UI** | Powers nightly E2E status, community activity, leaderboard widgets | Persisted by the **console backend** via `POST /api/github/token` (`pkg/api/handlers/github_proxy.go`) to the encrypted local settings file at `~/.kc/settings.json`. Not browser-only and not stored on the kc-agent. Only works when self-hosting — the hosted Netlify demo has no writable local backend, so the Settings page cannot persist a token there. | Optional. Adds GitHub-powered widgets to your **self-hosted** dashboard. |
 | **`FEEDBACK_GITHUB_TOKEN`** | Lets the `/issue` page open GitHub issues for you | `.env` file at the repo root | Optional. Only needed if you want users to file issues from inside the console. Without it, `/issue` returns `503 Issue submission is not available`. |


The README describes the Settings UI PAT and FEEDBACK_GITHUB_TOKEN as separate, “not interchangeable” credentials, but the backend treats them as a single consolidated GitHub PAT (FeedbackGitHubToken) used across GitHub proxy, feedback issue creation, missions, and rewards (sourced from UI-saved settings or the env var). This makes the table/wording misleading (e.g., /issue can work with a token saved via Settings UI as well). Please update the table/intro to reflect the consolidated-token behavior (either merge the rows or clearly state they are two ways to supply the same token).

Copilot · 2026-04-10T19:15:14Z

 |---|---|---|---|
 | **GitHub OAuth App** (`GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET`) | Sign-in for the **self-hosted** console at `localhost:8080` | `.env` file at the repo root | Only if you self-host the console AND want user sign-in. Skip for the hosted demo. |
-| **GitHub PAT in Settings UI** | Powers nightly E2E status, community activity, leaderboard widgets | Saved by the local `kc-agent` to its on-disk settings file (not browser-only). Only reachable when self-hosting — the hosted Netlify build disables `LOCAL_AGENT_HTTP_URL`, so the Settings page cannot persist a token there. | Optional. Adds GitHub-powered widgets to your **self-hosted** dashboard. |
+| **GitHub PAT in Settings UI** | Powers nightly E2E status, community activity, leaderboard widgets | Persisted by the **console backend** via `POST /api/github/token` (`pkg/api/handlers/github_proxy.go`) to the encrypted local settings file at `~/.kc/settings.json`. Not browser-only and not stored on the kc-agent. Only works when self-hosting — the hosted Netlify demo has no writable local backend, so the Settings page cannot persist a token there. | Optional. Adds GitHub-powered widgets to your **self-hosted** dashboard. |


The Settings UI token save endpoint (POST /api/github/token) requires the current user to have the console admin role and returns 403 otherwise. The README row implies any self-hosted user can persist the PAT; please document the admin requirement to avoid confusion when non-admin users try to configure it.

Suggested change

| **GitHub PAT in Settings UI** | Powers nightly E2E status, community activity, leaderboard widgets | Persisted by the **console backend** via `POST /api/github/token` (`pkg/api/handlers/github_proxy.go`) to the encrypted local settings file at `~/.kc/settings.json`. Not browser-only and not stored on the kc-agent. Only works when self-hosting — the hosted Netlify demo has no writable local backend, so the Settings page cannot persist a token there. | Optional. Adds GitHub-powered widgets to your **self-hosted** dashboard. |

| **GitHub PAT in Settings UI** | Powers nightly E2E status, community activity, leaderboard widgets | Persisted by the **console backend** via `POST /api/github/token` (`pkg/api/handlers/github_proxy.go`) to the encrypted local settings file at `~/.kc/settings.json`. Not browser-only and not stored on the kc-agent. Only works when self-hosting — the hosted Netlify demo has no writable local backend, so the Settings page cannot persist a token there. Saving the token requires the current user to have the console `admin` role; non-admin users receive `403 Forbidden`. | Optional. Adds GitHub-powered widgets to your **self-hosted** dashboard if an admin configures it. |

github-actions · 2026-04-10T19:17:05Z

Thank you for your contribution! Your PR has been merged.

Check out what's new:

KubeStellar Console — Live multi-cluster dashboard
Marketplace — Community extensions
Knowledge Base — Troubleshooting and how-tos

Stay connected: Slack #kubestellar-dev | Multi-Cluster Survey

github-actions · 2026-04-10T19:20:26Z

Post-merge build verification passed ✅

Both Go and frontend builds compiled successfully against merge commit 785c472a7fb847b7b54f6a75c34484d5095f6f05.

…, single cache read (#6212, #6220) #6212 — Copilot review on #6207 (README round 4) ================================================== Two factual errors caught against source. 1) The README treated 'GitHub PAT in Settings UI' and 'FEEDBACK_GITHUB_TOKEN' as separate, 'not interchangeable' credentials. Wrong — verified against pkg/api/handlers/github_proxy.go:92 and :238: both write to the single FeedbackGitHubToken field on AllSettings, which is consumed by the github proxy, feedback issue creation, missions, and rewards. They are TWO WAYS TO SUPPLY THE SAME TOKEN, not separate credentials. Merged the table rows into one 'Consolidated GitHub PAT' row and added a 'Setting the consolidated PAT' subsection that explains the env-var path and the Settings UI path are equivalent — pick one. 2) The Settings UI POST /api/github/token endpoint requires the console 'admin' role and returns 403 otherwise. Verified at pkg/api/handlers/github_proxy.go:214: if currentUser.Role != "admin" { return 403 } The README implied any self-hosted user could persist the PAT. Documented the admin requirement explicitly in the new section. #6220 — Copilot review on #6214 (analytics + cache) ===================================================== Two small correctness fixes. 1) web/public/analytics.js:957 — KPI percentages for Human PRs/Issues were computed as `100 - aiPct`. With totalPrs===0, aiPct is forced to 0, so the Human KPI rendered as 100% with the change line '0 of 0 PRs' — extremely confusing. New humanPrPct/humanIssuePct variables that also force to 0 in the empty case, so both KPIs render as 0% / 0% / '0 of 0' when there is no data. 2) web/src/hooks/useMediumBlog.ts:78-82 — readCache() was called THREE times during initial render (one per useState lazy initializer), repeating sessionStorage.getItem + JSON.parse three times and creating a tiny race window if the cache changed between calls. Read once into a captured initialCache variable; all three useStates derive from the same snapshot. Verified: `npm run build` clean. Closes #6212, closes #6220. Signed-off-by: Andrew Anderson <[email protected]>

…, single cache read (#6212, #6220) (#6236) #6212 — Copilot review on #6207 (README round 4) ================================================== Two factual errors caught against source. 1) The README treated 'GitHub PAT in Settings UI' and 'FEEDBACK_GITHUB_TOKEN' as separate, 'not interchangeable' credentials. Wrong — verified against pkg/api/handlers/github_proxy.go:92 and :238: both write to the single FeedbackGitHubToken field on AllSettings, which is consumed by the github proxy, feedback issue creation, missions, and rewards. They are TWO WAYS TO SUPPLY THE SAME TOKEN, not separate credentials. Merged the table rows into one 'Consolidated GitHub PAT' row and added a 'Setting the consolidated PAT' subsection that explains the env-var path and the Settings UI path are equivalent — pick one. 2) The Settings UI POST /api/github/token endpoint requires the console 'admin' role and returns 403 otherwise. Verified at pkg/api/handlers/github_proxy.go:214: if currentUser.Role != "admin" { return 403 } The README implied any self-hosted user could persist the PAT. Documented the admin requirement explicitly in the new section. #6220 — Copilot review on #6214 (analytics + cache) ===================================================== Two small correctness fixes. 1) web/public/analytics.js:957 — KPI percentages for Human PRs/Issues were computed as `100 - aiPct`. With totalPrs===0, aiPct is forced to 0, so the Human KPI rendered as 100% with the change line '0 of 0 PRs' — extremely confusing. New humanPrPct/humanIssuePct variables that also force to 0 in the empty case, so both KPIs render as 0% / 0% / '0 of 0' when there is no data. 2) web/src/hooks/useMediumBlog.ts:78-82 — readCache() was called THREE times during initial render (one per useState lazy initializer), repeating sessionStorage.getItem + JSON.parse three times and creating a tiny race window if the cache changed between calls. Read once into a captured initialCache variable; all three useStates derive from the same snapshot. Verified: `npm run build` clean. Closes #6212, closes #6220. Signed-off-by: Andrew Anderson <[email protected]>

@rishi-jat

…6185 follow-up) @rishi-jat reported (#6185) that the README install instructions had no Windows path. That was fixed in #6187/#6193/#6194/#6197/#6207, but the README is only one surface — the in-app modals that show up when users first try to set up kc-agent had no Windows option either. This PR adds parity between the README and both in-app modals. AgentSetupDialog.tsx (the welcome modal that auto-shows when no agent is connected and the user hasn't dismissed it): - New windowsBuildCommand constant: `apt-get install software-properties-common` -> longsleep PPA -> `golang-1.25` -> git clone -> `mkdir -p bin` -> `go build`. Single line so users can paste it once into their WSL shell. - New Windows (WSL2) collapsible section parallel to the existing Linux one. Same Eye/click pattern, same Copy button + 'Copied' feedback (UI_FEEDBACK_TIMEOUT_MS), shares the existing toast timer cleanup pattern via copiedWindowsTimerRef. - Linux build command also updated: bumped to include 'mkdir -p bin' so a fresh clone doesn't fail (#6196 caught this for the README). InClusterAgentDialog.tsx (the in-cluster connect dialog): - Same WINDOWS_WSL_INSTALL_CMD constant + new Windows (WSL2) collapsible section parallel to the build-from-source one. New COPY_KEY_WSL=102 in the existing key range. - Linux build-from-source command updated similarly: 'mkdir -p bin' added, label changed from 'Go 1.24+' to 'Go 1.25+' to match go.mod. Both Windows sections include: - The one-time PowerShell prerequisite (`wsl --install -d Ubuntu`) described inline so users don't have to leave the modal - A note that http://localhost:8080 just works in the Windows browser because WSL2 forwards localhost - A pointer back to the README's step-by-step version This closes the in-app gap rishi-jat originally reported. The README + in-app modals are now consistent for the four supported install paths: macOS Homebrew, Linux build-from-source, Windows WSL2 build, in-cluster deploy. Verified: `npm run build` clean. Refs #6185. Signed-off-by: Andrew Anderson <[email protected]>

@rishi-jat

…6185 follow-up) (#6238) * feat(setup): add Windows (WSL2) section to in-app agent setup modals (#6185 follow-up) @rishi-jat reported (#6185) that the README install instructions had no Windows path. That was fixed in #6187/#6193/#6194/#6197/#6207, but the README is only one surface — the in-app modals that show up when users first try to set up kc-agent had no Windows option either. This PR adds parity between the README and both in-app modals. AgentSetupDialog.tsx (the welcome modal that auto-shows when no agent is connected and the user hasn't dismissed it): - New windowsBuildCommand constant: `apt-get install software-properties-common` -> longsleep PPA -> `golang-1.25` -> git clone -> `mkdir -p bin` -> `go build`. Single line so users can paste it once into their WSL shell. - New Windows (WSL2) collapsible section parallel to the existing Linux one. Same Eye/click pattern, same Copy button + 'Copied' feedback (UI_FEEDBACK_TIMEOUT_MS), shares the existing toast timer cleanup pattern via copiedWindowsTimerRef. - Linux build command also updated: bumped to include 'mkdir -p bin' so a fresh clone doesn't fail (#6196 caught this for the README). InClusterAgentDialog.tsx (the in-cluster connect dialog): - Same WINDOWS_WSL_INSTALL_CMD constant + new Windows (WSL2) collapsible section parallel to the build-from-source one. New COPY_KEY_WSL=102 in the existing key range. - Linux build-from-source command updated similarly: 'mkdir -p bin' added, label changed from 'Go 1.24+' to 'Go 1.25+' to match go.mod. Both Windows sections include: - The one-time PowerShell prerequisite (`wsl --install -d Ubuntu`) described inline so users don't have to leave the modal - A note that http://localhost:8080 just works in the Windows browser because WSL2 forwards localhost - A pointer back to the README's step-by-step version This closes the in-app gap rishi-jat originally reported. The README + in-app modals are now consistent for the four supported install paths: macOS Homebrew, Linux build-from-source, Windows WSL2 build, in-cluster deploy. Verified: `npm run build` clean. Refs #6185. Signed-off-by: Andrew Anderson <[email protected]> * test(ui-ux): bump EXPECTED_RAW_HEX_COUNT 282→284 for #6185 ref Signed-off-by: Andrew Anderson <[email protected]> --------- Signed-off-by: Andrew Anderson <[email protected]>

Copilot AI review requested due to automatic review settings April 10, 2026 19:11

kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Apr 10, 2026

clubanderson added the ai-generated Pull request generated by AI label Apr 10, 2026

kubestellar-prow Bot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Apr 10, 2026

Copilot started reviewing on behalf of clubanderson April 10, 2026 19:12 View session

Copilot AI reviewed Apr 10, 2026

View reviewed changes

clubanderson merged commit 785c472 into main Apr 10, 2026
38 of 44 checks passed

kubestellar-prow Bot deleted the fix/6196-6198-readme-corrections-round2 branch April 10, 2026 19:16

github-actions Bot mentioned this pull request Apr 10, 2026

[Copilot Review] 2 comment(s) on merged PR #6207 #6212

Closed

clubanderson mentioned this pull request Apr 10, 2026

fix: consolidated PAT row, admin role, KPI 0%-when-zero, single cache read (#6212, #6220) #6236

Merged

1 task

clubanderson mentioned this pull request Apr 10, 2026

feat(setup): add Windows (WSL2) section to in-app agent setup modals (#6185 follow-up) #6238

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(readme): factual fixes — backend persistence, empty providers (#6196, #6198)#6207

docs(readme): factual fixes — backend persistence, empty providers (#6196, #6198)#6207
clubanderson merged 1 commit intomainfrom
fix/6196-6198-readme-corrections-round2

clubanderson commented Apr 10, 2026

Uh oh!

kubestellar-prow Bot commented Apr 10, 2026

Uh oh!

netlify Bot commented Apr 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 10, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Uh oh!

github-actions Bot commented Apr 10, 2026

Uh oh!

github-actions Bot commented Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

clubanderson commented Apr 10, 2026

Summary

Uh oh!

kubestellar-prow Bot commented Apr 10, 2026

Uh oh!

netlify Bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for kubestellarconsole canceled.

Uh oh!

github-actions Bot commented Apr 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Apr 10, 2026

Uh oh!

github-actions Bot commented Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

netlify Bot commented Apr 10, 2026 •

edited

Loading