steve/kb
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases 18 Wiki Activity
Files
0c124c4ab7630a727b7114dac61b6260d005ba0e
kb/openspec/changes/archive/2026-04-02-fix-search-human-output/specs/go-client/spec.md
T
steve 2d179af557 Fix search human-mode output to match engine API response 
The Go client struct expected a nested document object and top-level
page/section fields, but the engine returns flat results with metadata
in chunk_metadata. This caused empty display for title, type, tags,
page, and section in human output mode.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 16:17:35 +01:00

2.1 KiB
Raw Blame History

MODIFIED Requirements

Requirement: Search command

The client SHALL provide a kb search <query> command that sends the query to the engine and displays results.

Scenario: Human-readable search output

  • WHEN the user runs kb search "how to change oil"
  • THEN the client SHALL POST to /api/v1/search, and display results in a human-readable format showing rank, score, document title, page/section, doc type, tags, and a text snippet
  • THEN the client SHALL parse search results as flat objects with top-level title, doc_type, tags, score, text, chunk_index fields
  • THEN the client SHALL extract page from chunk_metadata when present (PDF documents)
  • THEN the client SHALL extract section_header from chunk_metadata when present (markdown documents)

Scenario: JSON search output

  • WHEN the user runs kb search "query" --format json
  • THEN the client SHALL output the raw JSON response from the engine

Scenario: Search with filters

  • WHEN the user runs kb search "brakes" --tags maintenance --type pdf --top 3
  • THEN the client SHALL include the filters in the API request body

Scenario: Search mode flags

  • WHEN the user runs kb search "error" --fts-only
  • THEN the client SHALL set fts_only: true in the request body

Scenario: PDF result with page number

  • WHEN a search result has chunk_metadata containing {"page": 12}
  • THEN the human output SHALL display "Page 12" in the location line

Scenario: Markdown result with section header

  • WHEN a search result has chunk_metadata containing {"section_header": "Installation > Prerequisites"}
  • THEN the human output SHALL display "Installation > Prerequisites" in the location line

Scenario: Result with both page and section

  • WHEN a search result has chunk_metadata containing both page and section_header
  • THEN the human output SHALL display both separated by " / "

Scenario: Result with no location metadata

  • WHEN a search result has empty chunk_metadata or no page/section keys
  • THEN the human output SHALL omit the location line entirely
Reference in New Issue View Git Blame Copy Permalink