feat(search): add local result filters

[altaywtf]

Summary

• Add exact state, fin-status, and tag filters to local archive search
• Expose the new filters through fincrawl describe search and CLI flags
• Update agent-facing search docs and synthetic tests

Verification

• ./scripts/verify
• ./scripts/release-check
• go run ./cmd/fincrawl describe search --json
• Markdown local link check
• Private-store smoke with FINCRAWL_SOURCE=/Users/altay/projects/uinaf/fincrawl using redacted aggregate output

Data Boundary

• Synthetic tests only; no tenant credentials, identifiers, transcript data, generated snapshots, logs, reports, screenshots, or transcript-derived examples added.

Complexity

• Neutral: search keeps the existing FTS/LIKE paths and adds parameterized exact filters.

---

Summary by cubic

Add exact result filters to local archive search to narrow results by state, Fin status, and tag. Exposes new CLI flags and updates docs and tests.

• New Features
  • Added search flags: --state, --fin-status, and --tag.
  • Updated describe schema and examples to show the new flags.
  • Implemented SearchOptions and SearchWithOptions; filters applied to both FTS and LIKE paths.
  • Added synthetic tests for filtered queries and CLI projection.
  • Updated README, architecture docs, skills references, and roadmap with examples.

^{Written for commit bf79799. Summary will update on new commits. Review in cubic}

[cubic-dev-ai]

No issues found across 10 files

_{Re-trigger cubic}

[Copilot]

Pull request overview

Adds exact, local-only result filters to fincrawl search (state / Fin status / tag) and exposes them consistently across the CLI schema, docs, and synthetic tests.

Changes:

• Introduces store.SearchWithOptions / SearchOptions and applies optional exact filters in both the FTS and LIKE search paths.
• Adds --state, --fin-status, and --tag flags to fincrawl search, and updates describe search schema output.
• Updates agent-facing docs/examples and expands synthetic tests to cover the new filters.

Reviewed changes

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

Show a summary per file

File	Description
skills/fincrawl/SKILL.md	Adds CLI examples demonstrating --state and --fin-status filtering.
skills/fincrawl/references/reads.md	Documents and exemplifies the new exact filters for agent/operator usage.
README.md	Updates common-flow examples to include filtered search usage.
internal/store/search.go	Implements filterable search via SearchOptions and shared SQL filter construction for FTS/LIKE.
internal/store/fixture_test.go	Adds store-level tests validating filtered searches against the synthetic fixture DB.
internal/cli/cli.go	Wires new search flags into CLI parsing and store search invocation.
internal/cli/cli_test.go	Adds CLI-level test coverage for filtered search behavior and schema output.
internal/cli/agent_dx.go	Extends machine-readable describe search schema to include new flags and examples.
docs/roadmap.md	Notes the addition of search filters as a delivered capability.
docs/architecture.md	Updates architecture command examples to include filter flags.

---

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