16 real questions, grouped by situation. Every command is copy-pasteable and matches the CLI reference exactly — nothing here is aspirational. Output shapes are excerpts of the real thing; your numbers and file paths will differ.
ctx-optimize query "refund flow"
Refund flow [section] README.md L3-L6 ProcessRefund [function] pay.go L3-L3query
Store.Merge, who's depending on it?"ctx-optimize card "Store.Merge"
Store.Merge [method] internal/store/store.go L200-L273 sig: func (s *Store) Merge(b *schema.Batch) (nodesAdded, edgesAdded int, err error) doc: Merge upserts a validated batch into the graph... called by (12): cmdAdd, cmdSync, cmdMerge, ... calls (6): Batch.Validate, writeNDJSON, ...card
ctx-optimize hubs --top 10
# or browse the generated map:
open ~/ctxoptimize/<repo>/wiki/
add command reach the store's merge logic?"ctx-optimize path "cmdAdd" "Store.Merge"
ctx-optimize explain "PaymentService"
card or change-plan.validateRefund — what do I need to know before I touch it?"ctx-optimize change-plan validateRefund
callers (1): pay.go::ProcessRefund blast radius (depth 2, 2 shown): ... tests to run: pay_test.go::TestProcessRefund confidence: 4 EXTRACTED, 1 INFERRED
plan.ctx-optimize affected PaymentService --depth 2
change-plan adds.ctx-optimize verify "pay.go:L1-L5"; echo $? # 0 — node exists, file exists, range in bounds, no drift vs gather-time HEAD ctx-optimize verify "pay.go:L900-L950"; echo $? # 1 — out of bounds, refused
file:line still holds — exit 0 only when every claim in the citation checks out. Use it before a human acts on an agent's answer.ctx-optimize status # fresh: ✗ STALE — store at 8a5057b, repo now at 03d0f49; run: ctx-optimize add . ctx-optimize fresh; echo $? # 0 fresh / 1 stale / 2 unknown (no git HEAD)
fresh into a pre-commit hook or CI step so nothing answers from a stale snapshot.ctx-optimize up
ctx-optimize adapters help postgres # the setup card: value format, credential params export BILLING_DB_URL='postgres://reader:$PG_PASS@db.internal:5432/billing' ctx-optimize add BILLING_DB_URL # dial, capture the logical shape, merge, record
up under a 24h TTL.ctx-optimize capture BILLING_DB_URL
# {"producer":"source:BILLING_DB_URL", "nodes":[...], ...} — printed, nothing written
ctx-optimize query "prod namespace service ingress"
cat > .ctxoptimize/adapters/tickets.sh <<'EOF'
#!/bin/sh
echo '{"producer":"tickets","nodes":[{"id":"t:1","label":"TCK-1 checkout bug","kind":"ticket","file_type":"external","source":"tickets"}]}'
EOF
ctx-optimize add . # "adapter tickets: 1 nodes, 0 edges"
ctx-optimize query "TCK-1"
--json door (my-exporter | ctx-optimize add --json -) for one-off feeds.cd services/billing ctx-optimize query "dev dependency"
services/billing's own store — not ranked against every other module's noise — including dep: nodes for anything it imports, federated across whatever build tool declared it. A miss escalates repo-wide automatically and labels which module actually answered.ctx-optimize merge api worker --into everything
cd my-repo && ctx-optimize up
ctx-optimize remote push # runs the script YOUR team declared in .ctxoptimize/config.json # teammate, on a fresh clone: ctx-optimize up # pulls the prebuilt store instead of gathering locally
push/pull run the commands your team declares (a private git repo, S3, anything). init scaffolds a ready-to-arm git lane as inert samples.Read Concepts for the graph model these recipes query, and Use cases for the narrative version of onboarding, refactoring safely, and sharing a store across a team. Every verb here is documented in full on the CLI reference.