contextia search

contextia search performs a free-text search across Contextia artifacts. It matches against titles, IDs, descriptions, and body content, returning ranked results. This is a deterministic text search — no embeddings or semantic similarity.

Synopsis

contextia search <query> [OPTIONS]

Arguments

Argument	Description
query	Search string to match against artifacts

Options

Option	Short	Description
--type <type>	-t	Filter by type: spec, norm, decision, all (default: all)
--field <field>		Search only in: title, id, description, all (default: all)
--limit <n>	-l	Maximum number of results (default: 10)
--format <fmt>	-f	Output format: human, json, context
--json	-j	Shorthand for --format json
--help	-h	Show help and exit

Ranking

Results are ranked by a weighted scoring system:

1. Exact ID match — highest priority (e.g., searching “AUTH-001” matches SPEC-AUTH-001)
2. Title match — weighted higher than body matches
3. Body content match — full-text match within the Markdown body

Results with multiple matching fields score higher than single-field matches.

Examples

Search for authentication-related specs:

$ contextia search "authentication"
  Score  ID             Type  Title
  0.95   SPEC-AUTH-001  spec  Authentication Flow
  0.72   DEC-002        dec   OAuth 2.0 with PKCE over API keys
  0.45   NORM-SEC-001   norm  No secrets in source code

Search only in spec titles:

$ contextia search "database" --type spec --field title
  Score  ID             Type  Title
  0.91   SPEC-DB-003    spec  Database Migration Strategy
  0.68   SPEC-DB-004    spec  Database Connection Pooling

Search by partial ID:

$ contextia search "AUTH" --field id
  Score  ID             Type  Title
  1.00   SPEC-AUTH-001  spec  Authentication Flow
  1.00   SPEC-AUTH-002  spec  Authorization Rules
  1.00   DEC-AUTH-005   dec   JWT over session cookies
  1.00   NORM-AUTH-001  norm  All endpoints require auth

JSON output for scripting:

$ contextia search "api" --type spec --json --limit 2
[
  {
    "score": 0.88,
    "id": "SPEC-API-002",
    "type": "spec",
    "title": "REST API Conventions",
    "path": ".contextia/system/specs/SPEC-API-002.md"
  },
  {
    "score": 0.65,
    "id": "SPEC-API-005",
    "type": "spec",
    "title": "API Rate Limiting",
    "path": ".contextia/system/specs/SPEC-API-005.md"
  }
]

Context format for LLM consumption:

$ contextia search "error handling" --format context
[SPEC-ERR-001] Error Handling Strategy (0.92)
[NORM-ERR-001] All errors return structured JSON (0.78)
[DEC-ERR-002] Custom exception hierarchy over generic exceptions (0.54)

Limit results:

$ contextia search "test" --limit 3
  Score  ID             Type  Title
  0.90   NORM-TEST-001  norm  Every module has unit tests
  0.82   SPEC-TEST-002  spec  Integration Test Framework
  0.71   DEC-TEST-001   dec   pytest over unittest

Behavior

• The search index is built from .contextia/.cache/. If the cache is stale or missing, it is rebuilt automatically before searching.
• Searching is case-insensitive.
• An empty query returns all artifacts (equivalent to contextia list).
• The command writes status messages (e.g., “Rebuilding index…”) to stderr, and results to stdout.