docs: clarify README and agent skill

[lzehrung]

Summary

• rewrite the README around a clearer agent value proposition, concrete repository questions, first-use workflows, real output shapes, and honest tradeoffs
• restructure the bundled Codegraph skill into a task-to-command decision guide with explicit root, output, live-read, MCP freshness, lifecycle, and installation rules
• add a concise vectorless-search guide covering the retrieval model, ranking signals, search modes, graph context, strengths, and limits
• connect the search guide from the README, agent workflows, and architecture documentation
• correct stale onboarding claims and a broken CLI documentation anchor found during review

Review findings addressed

• replace snapshot-specific explore counts and ordering with a durable abbreviated output shape
• stop promising health signals from the small orient budget, which skips health analysis by default
• add the missing Why not just grep or an LSP? table-of-contents entry
• clarify that Codegraph gives agents a reusable repository map and bounded navigable evidence, not merely another search result list

Verification

• npm run check - 178 test files passed; 2,178 tests passed; 1 skipped
• npx vitest run tests/package-metadata.test.ts - 37 tests passed
• changed-document link and anchor validation - 56 internal links checked, 0 missing
• review-and-correct verification - all findings resolved, no new regressions

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (1 file)

• README.md

Previous Review Summaries (3 snapshots, latest commit 4ef96d2)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 4ef96d2)

Status: No Issues Found | Recommendation: Merge

Files Reviewed (2 files)

• README.md
• docs/search.md

Previous review (commit dd7a8f3)

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
docs/search.md	89	Duplicated paragraph — nearly identical to line 85

Files Reviewed (5 files)

• README.md
• docs/agent-workflows.md
• docs/how-it-works.md
• docs/search.md — 1 issue
• tests/package-metadata.test.ts

Fix these issues in Kilo Cloud

Previous review (commit a5528a0)

Status: No Issues Found | Recommendation: Merge

Files Reviewed (2 files)

• README.md
• codegraph-skill/codegraph/SKILL.md

---

_{Reviewed by kimi-k2.6-20260420 · Input: 56.2K · Output: 3.9K · Cached: 109.1K}

[Copilot]

Pull request overview

Documentation-focused update that rewrites the README and bundled agent skill to emphasize concrete repository questions, first-use workflows, stable output shapes, and explicit tradeoffs/freshness rules.

Changes:

• Restructures README.md into question-driven workflows with abbreviated durable output examples and updated onboarding guidance.
• Reworks codegraph-skill/codegraph/SKILL.md into a task-to-command decision guide, including explicit --root boundary rules and MCP freshness/lifecycle guidance.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
README.md	Rewrites the top-level README around concrete questions, first-run workflows, durable output shapes, and updated agent setup guidance.
codegraph-skill/codegraph/SKILL.md	Restructures the bundled skill into a decision guide with explicit project-boundary, output-consumer, sensitive-file, and MCP freshness rules.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.