docs: restructure and refresh user-facing documentation#741
Merged
Conversation
Reorganize docs into a clear two-level layout and bring the user-facing references back in line with the code. Structure: - Add docs/README.md and docs/architecture/README.md as navigable indexes. - Collapse docs/internals/ into a single docs/architecture/ folder: promote chat.md and editor-files.md, drop the stale llm-generation.md audit. - Remove implementation-deep-dive.md (redundant with ARCHITECTURE.md). - Split LANGUAGE_SUPPORT.md into a lean user-facing matrix plus architecture/language-support.md for pipeline internals and the add-a-language recipe. Accuracy (verified against source): - CLI_REFERENCE: remove the nonexistent "repowise query" command (it is "repowise search"); correct flags and defaults; add coverage, telemetry, login, and workspace check/metrics. - MCP_TOOLS: document every registered tool (add generate_refactoring_code, list_repos, workspace-only and opt-in tools); fix get_dead_code, get_why, and get_overview signatures; drop the nonexistent "profile" mechanism. - CONFIG: full config.yaml and health-rules.json keys, the complete reasoning set, and previously undocumented environment variables. - WORKSPACES: add the data/DB contract type, correct the edge-kind list and HTTP/gRPC dialects, remove the unimplemented Redis pub/sub claim. - USER_GUIDE: rewrite the dashboard section to the current grouped navigation. - Fix broken links in ARCHITECTURE.md and README.md.
swati510
approved these changes
Jul 10, 2026
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
2 participants
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.
What
Reorganizes
docs/into a clear two-level layout (user-facing at the top, deep references in a singlearchitecture/folder) and brings the user-facing docs back in line with the current code. Every factual change was verified against source.Structure
docs/README.md(grouped by audience) anddocs/architecture/README.md, so the folder is navigable.docs/internals/is gone.chat.mdandeditor-files.mdmoved intoarchitecture/; the stale point-in-timellm-generation.mdaudit was dropped.implementation-deep-dive.mdwas ~80% the same document asARCHITECTURE.md, which is now the single system reference.CODE_HEALTH.md):LANGUAGE_SUPPORT.mdis now a lean user-facing support matrix; the pipeline internals and the add-a-language recipe live in the newarchitecture/language-support.md.Accuracy fixes (verified against source)
repowise querycommand (the real command isrepowise search); corrected flags and defaults across commands; addedcoverage,telemetry,login/logout/whoami, andworkspace check/metrics.generate_refactoring_code,list_repos, the workspace-only tools, and the opt-in tools; fixes theget_dead_code,get_why, andget_overviewsignatures; removes the nonexistent "profile" vocabulary in favor of the realmcp.toolsmechanism. Keeps the "nine flagship tools" framing.config.yamlandhealth-rules.jsonkey tables, the completereasoningvalue set, and the previously missing environment variables (embeddings, telemetry opt-out, server/DB, webhooks).ARCHITECTURE.mdand therepowise queryline in the rootREADME.md.Net: +1,499 / -3,212 lines. Leaner, better organized, and accurate.
The hosted
docs.repowise.dev(frontend) is out of scope here and handled separately.