docs: correct stale claims and tighten the docs site#71
Merged
Conversation
Remove things that no longer hold and fix consistency across the website content (docs/content/*, canonical source for the GitHub Pages site and the in-app docs mirror) plus the README entry point. - Teleport is not the default. The launcher's cluster picker uses the kubeconfig auth provider by default; Teleport is opt-in via the profile. Corrected in the end-to-end walk and the ownership table. - Drop the "cluster ID (required)" form field and the "namespace is derived per your profile" claim. The cluster is the dropdown, every form input is optional, and the agent narrows the namespace at runtime; it isn't bound at preflight. - Remove the "Why it exists" 7-step list from investigations.md; it duplicated overview's "The problem it solves". Point there instead. - Rename "What lives where" to "Separation of concerns" with a lead sentence so the ownership table's purpose is clear. - Drop the "Enable auto mode (coming soon)" placeholder; document the real paths (start screen, watch-driven, or restart). - overview: "Four surfaces" now lists four, with the MCP catalog reframed as the tool layer beneath them; add the Cloud providers integration; fix the "single cluster's namespace" binding claim; sentence-case "Alpha release"; note read-only GCP/AWS context. - README: fix the broken docs-site links (the /docs/<section>/ path segment 404s; the site serves /<section>/) and the stale "Enter the namespace" step. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates Triagent’s documentation (canonical Markdown under docs/content/*) and the repository README to remove stale/incorrect product claims, tighten internal consistency, and fix external links for the published docs site.
Changes:
- Correct docs/README statements around auth provider defaults, investigation form inputs, namespace handling, and “auto mode” enablement paths.
- De-duplicate/reshape documentation structure (e.g., moving MCP discussion into a “tool layer” framing beneath the four operator-facing surfaces).
- Fix broken README links to the GitHub Pages docs site by removing the nonexistent
/docs/route prefix.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| README.md | Fix docs-site links and align the quick-start walkthrough text with current launcher/UI behavior. |
| docs/content/profiles.md | Update the cluster_id input description to reflect provider-backed cluster lists. |
| docs/content/overview.md | Reframe “what’s in the box” as four surfaces + MCP tool layer; add cloud providers integration note; update several stale claims. |
| docs/content/investigations.md | Remove duplicated “why” content; update E2E flow details, form-field guidance, ownership table framing, and auto-mode enablement text. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
5
to
+8
| Triagent is a localhost web app that pairs the Claude reasoning agent with read-only Kubernetes access, an extensible | ||
| MCP catalog (Prometheus, Slack, GitHub, incident.io, your own), a guided playbook walker, and a persistent wiki, all | ||
| bound to a single cluster's namespace per session. You run `triagent start`, it opens a browser, you hand it the | ||
| symptom, and it drives a focused diagnosis you can paste into a ticket when it's done. | ||
| MCP catalog (Prometheus, Slack, GitHub, incident.io, read-only GCP/AWS context, your own), a guided playbook walker, | ||
| and a persistent wiki, all scoped to a single cluster per session. You run `triagent start`, it opens a browser, you | ||
| hand it the symptom, and it drives a focused diagnosis you can paste into a ticket when it's done. |
Step 1 of the end-to-end walkthrough framed "Pick a cluster" as the mandatory entry point, but ValidateInputValues only enforces inputs the profile marks non-optional, and the canonical profile marks all four (cluster, incident URL, Slack channel, notes) optional. Lead with the real rule (at least one starting point) and note the agent infers a cluster via switch_context when none is picked up front. Gate preflight's reachability/RBAC check on a cluster actually being selected. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Comment on lines
+29
to
+32
| - **[Investigations](https://sourcehawk.github.io/triagent/investigations/)**: the live triage view. Hand the assistant a symptom and some context (cluster, Slack thread, incident.io link, notes), watch it work through the diagnosis step by step, and ship the summary as markdown. | ||
| - **[Playbooks](https://sourcehawk.github.io/triagent/playbooks/)**: the step-by-step troubleshooting procedures the assistant follows, defined as YAML. Write and edit them right in the browser, with an AI assistant helping. | ||
| - **[Wiki](https://sourcehawk.github.io/triagent/wiki/)**: the team's lasting knowledge base of failure patterns and prior fixes, which the assistant can search. | ||
| - **[Watches](https://sourcehawk.github.io/triagent/watches/)**: rules that turn Slack messages, GitHub issues, or alerts into proposed investigations on their own. |
Comment on lines
110
to
+114
| 3. Click **+ new investigation** in the sidebar (or navigate to `/investigations/new`) to start a fresh one. Pick a | ||
| cluster from the dropdown. If the provider isn't logged in, you'll be prompted to authenticate (SSO/2FA prompts | ||
| surface in the terminal where you ran `triagent start`, not the browser). | ||
| 4. Fill in the form: | ||
| - **cluster ID** (required when using the cluster_id profile input). The data namespace is derived per your profile. | ||
| 4. Fill in the form. The fields below are individually optional, but the investigation needs at least one starting | ||
| point — the cluster you picked above, or one of these: |
Comment on lines
+63
to
+64
| Four operator-facing surfaces, each with a dedicated section in these docs: **Investigations**, **Watches**, | ||
| **Playbooks**, and **Wiki**. Underneath them sits the **MCP tool catalog** every surface is built on. |
| facts belong in the wiki. | ||
|
|
||
| ## Alpha Release | ||
| ### [The MCP tool catalog](/docs/mcp) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
The docs website (canonical content under
docs/content/*, which also feeds the in-app docs mirror) and the README carried several claims that no longer hold, plus a few internal inconsistencies. This corrects them and does a consistency pass so the site reads as an accurate, OSS-grade reference for both newcomers and experienced operators.Changes
investigations.mdthat duplicatedoverview.md's "The problem it solves"; replaced it with a pointer.…/triagent/docs/<section>/404s (no such route); the site serves…/triagent/<section>/.Testing
internal/profile,internal/server,internal/preflight, frontend components): kubeconfig is the default auth provider,cluster_idis an optional input type absent from the default profile, namespace is passed empty at preflight, and there is no mid-session "Enable auto mode" UI control./<section>/, there is no/docs/path.cd docs/site && npm run build) — all 14 pages generate cleanly.No code changes.
docs/content/*is the canonical source; the gitignoredfrontend/public/docsmirror regenerates at build via the existingsync-docsprebuild hook.