fix(init): align agent templates with csp output and auto-cache

[amondnet]

Summary

The agent instructions that csp init writes, and the copies the csp plugin ships, had drifted from csp's actual behavior and from upstream semble's current template. This PR brings them back in line.

• Result key. The templates told agents to pass filePath from a prior search result. CLI/MCP output is the snake_case wire dict (utils::format_results), so the key is file_path. camelCase filePath is left unchanged in the library and SDK docs, where it is correct.
• Caching guidance. The templates told agents to pre-index with csp index -o and said the index is not automatically updated. csp auto-caches under $HOME/.csp/index/ and invalidates by content hash (ADR-0002). Following that advice pinned agents to a stale --index copy. The block is replaced with upstream's wording: "Results are cached automatically on first run and invalidated when files change."
• Snippet length. The first example now uses --max-snippet-lines 10, as upstream does (#198).
• Workflow. The workflow now follows upstream's steps, including "Navigate directly to the returned file and line. Do not re-search or grep for the same content."

Upstream's multi-repo paragraph is intentionally not included. csp does not support multi-repo search yet; that is tracked in #114.

Files

• crates/csp/src/bin/csp/agents/*.md: all 10 templates. Bodies remain byte-identical and each file keeps its own frontmatter.
• plugins/csp/agents/csp-search.md, plugins/csp/skills/csp-search/SKILL.md
• README.md, README.ko.md (kept in sync), docs/src/content/docs/agents-md.mdx
• crates/csp/src/bin/csp/main.rs: new test agent_templates_match_cli_output_and_auto_cache. It asserts that every Agent template contains file_path and contains neither filePath nor the stale "not automatically updated" wording.

The README reference sections that document the csp index command and the --index flag are unchanged. Only the advice that agents must pre-index was removed.

Related issue

Closes #111

Checklist

• PR title follows Conventional Commits
• Tests added or updated, and the suite passes (cargo test --workspace: 336 lib + 27 CLI tests pass)
• Lint/format pass. cargo fmt and clippy -D warnings pass. bun run lint was not run locally.
• Documentation updated if behavior changed
• No breaking change

---

Summary by cubic

Aligns the csp init agent templates and plugin copies with csp's actual CLI output and its auto-caching behavior, fixing the two incorrect instructions from #111.

• Templates now tell agents to pass file_path and start_line from search results instead of the nonexistent filePath/line.
• Removed the csp index -o pre-indexing step; templates now state results are cached automatically, with git URL indexes keyed by URL and --ref requiring csp clear index to refresh.
• First search example uses --max-snippet-lines 10, and the workflow directs agents to navigate straight to the returned file_path at start_line instead of re-searching.
• Applied to all 10 agent templates, the plugin agent and skill files, both READMEs, and the docs page.
• Added a test asserting every bundled template references file_path and start_line and omits filePath and the stale "not automatically updated" wording.

^{Written for commit e141657. Summary will update on new commits.}

[gemini-code-assist]

Code Review

This pull request removes manual indexing instructions and references to the --index option across multiple README files, agent templates, and documentation, replacing them with details on automatic caching and indexing. It also standardizes the parameter name from filePath to file_path and adds a Rust test to verify that agent templates align with these updates. Feedback on the changes suggests translating the newly added English inline comments in the Korean README (README.ko.md) to Korean to maintain language consistency.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 0 complexity · 0 duplication

Metric	Results
Complexity	0
Duplication	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[codspeed]

Merging this PR will not alter performance

✅ 5 untouched benchmarks

---

_{Comparing amondnet/111-fix-agent-templates (e141657) with main (97b3fe9)}

[codecov]

Codecov Report

❌ Patch coverage is 83.33333% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
crates/csp/src/bin/csp/main.rs	83.33%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

cubic analysis

All reported issues were addressed across 16 files

Linked issue analysis

Linked issue: pleaseai/code-search#111: csp init / plugin agent templates: wrong filePath key, stale "index not auto-updated" guidance, missing --max-snippet-lines

Status	Acceptance criteria	Notes
✅	Use file_path across templates and plugin copies	The templates and both plugin copies use file_path, and the new test checks every bundled Agent template.
✅	Describe automatic caching without requiring pre-indexing	The updated guidance describes automatic caching and removes the instruction to run csp index -o first.
✅	Use --max-snippet-lines 10 in the examples	The first search example in the updated templates, plugin copies, and documentation uses --max-snippet-lines 10.
✅	Update both READMEs together	README.md and README.ko.md both replace the old indexing advice with automatic-cache guidance.
✅	Test that bundled templates contain no filePath	The new test iterates over every Agent template and fails if it contains filePath.

Architecture diagram

sequenceDiagram
    participant U as dev/LLM Agent
    participant CLI as csp CLI
    participant AC as Auto-Cache
    participant IDX as Index Store
    participant SR as Search Results

    Note over U,SR: csp search - runtime flow

    U->>CLI: csp search "query" ./my-project --max-snippet-lines 10
    CLI->>AC: check/query cache (auto-cached)
    alt Cache miss (first run or files changed)
        AC->>IDX: Build index incrementally
        IDX-->>AC: Index ready
        AC->>AC: Store by content hash
    end
    AC-->>CLI: Cached results
    CLI->>SR: Format results (snake_case keys)
    SR-->>U: {file_path, line, snippet...}

    Note over U,CLI: csp find-related - follows up on file_path + line

    U->>CLI: csp find-related src/auth.ts 42 ./my-project
    CLI->>SR: Resolve related chunks (uses existing auto-cache)
    SR-->>U: Related code locations

    Note over U,CLI: Agent workflow (per templates)

    U->>CLI: Navigate directly to file_path:line
    U->>CLI: (Occasionally) grep for exhaustive literal matches

Loading

<sub>Reply with feedback, questions, or to request a fix.

Turn on auto-fix | Re-trigger cubic</sub>

[greptile-apps]

Confidence Score: 5/5

[Low impact] The PR appears safe to merge, with no new actionable issues found.

Summary

Updates agent templates and documentation to match the CLI’s result fields and cache behavior.

• Search agents now follow csp’s returned file and line.

No new actionable issues found. All three earlier concerns remain fixed; their threads were unnumbered, so they have no previousFindings entries.

_{Reviews (3) · Last reviewed commit: "test(init): assert agent templates refer..." · Reviewed by Greptile}

[amondnet]

/gemini review

[gemini-code-assist]

Code Review

This pull request updates the documentation and agent templates across multiple files to reflect that indexing is now automatic and cached, replacing manual indexing commands. It also renames the line parameter to start_line for the find-related command and adds a unit test to verify these template changes. The feedback suggests enhancing the new unit test by asserting that the templates correctly contain start_line to ensure test integrity and prevent future drift.

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

[amondnet]

/gemini review

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
83.3% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[gemini-code-assist]

Code Review

This pull request updates documentation and agent templates across multiple markdown files to reflect the transition from manual indexing to automatic caching, standardizing references to 'file_path' and 'start_line'. It also adds a unit test in 'main.rs' to verify these template updates. The reviewer suggested extending this unit test to also validate sibling plugin templates when they exist in the local workspace, preventing future template drift and improving test coverage.