docs+test(readme): combined unifiedSearch + nearbyPlaces ORM example backed by a real integration test

[pyramation]

Summary

Started as docs-only; grew a small test + two dependency/CLI fixes in service of making the docs' claim provable.

Docs (both READMEs, kept in sync):

• Expanded the PostGIS spatial bullet to distinguish scalar filters shipping today (bboxIntersects2D, isNull, GIST indexes) from the new cross-table layer.
• Added a Cross-table spatial relations (@spatialRelation) bullet listing the 5 blueprint-declared virtual relations (memory.nearbyPlaces, memory.nearbyContacts, trip.nearbyVenues, event.nearbyVenues, memory.nearbyMemories) with their default radii, linking to packages/provision/src/schemas/spatial-relations.ts.
• Added a second ORM example that composes unifiedSearch with nearbyPlaces in one where: clause and selects searchScore + locationGeo { geojson, srid }, plus a one-liner explaining what the server compiles that into (a unified_search(...) CTE joined against an EXISTS (… ST_DWithin …) subquery — no GeoJSON over the wire).
• Retargeted the "proven by tests" note at the new combined test instead of splitting citations across two files.

New test — the proof behind the combined example:

• packages/agentic-db/__tests__/unified-spatial-combined.test.ts — uses the @constructive-io/graphql-test harness (which bundles ConstructivePreset → UnifiedSearchPreset), seeds 3 memories + 2 market-category places at known coordinates, runs the exact memory.findMany({ where: { unifiedSearch, nearbyPlaces } }) shape from the README through the generated SDK, asserts only the positive-match memory is returned and searchScore is non-null.

Dev-dep bump (test harness only):

• packages/agentic-db/package.json — graphile-settings 4.18.5 → 4.21.0 so the test-harness runtime schema matches production. The old pin transitively resolved graphile-search@1.5.6, which registered the composite filter as fullTextSearch; 1.7.0 renamed it to unifiedSearch (the name already exposed by the regenerated SDK schema in chore: regenerate SDK/CLI/schemas end-to-end with spatial-relations blueprint #27). Without this bump, the new test fails with Field 'unifiedSearch' is not defined by type 'MemoryFilter' — the symptom that surfaced the mismatch.

CLI fix uncovered by the bump:

• sdk/cli/src/commands/search.ts — hand-authored CLI that still hardcoded fullTextSearch in its HYBRID_CONDITION. Worked against the old harness, broke against the new one (cli-e2e-tests surfaced GraphQLError: Field "fullTextSearch" is not defined by type "ContactFilter" and similar across 12 filter types). Renamed to unifiedSearch to match the current SDK/schema. Pure one-word find-and-replace in 3 places.

Related work (context, not part of this PR): constructive-db #840/#843/#844/#863/#865, constructive #993/#997/#1001, agentic-db #24/#26/#27.

Review & Testing Checklist for Human

• CLI field rename is a silent behavior change for anyone running an older server. fullTextSearch was the filter name on servers built against graphile-search@<1.7.0; unifiedSearch is the name on newer servers. The CLI now only talks to the new name. Confirm there are no production-deployed agentic-db servers still on the old plugin version that the CLI is expected to hit.
• graphile-settings bump is scoped to packages/agentic-db/devDependencies and doesn't leak into any shipped package. Spot-check the pnpm lockfile diff for that (there are some expected incidental graphile-upload-plugin snapshot additions because peer resolution re-keyed, but no first-party package gained a new runtime dep).
• New test passed locally (pnpm exec jest --testPathPatterns=unified-spatial-combined, 14s) and in CI (orm-tests, cli-e2e-tests, rag-tests all green on 81466ea). Still worth eyeballing the assertions in unified-spatial-combined.test.ts to confirm they'd actually fail if the composition stopped working — specifically that the negative-match seed rows (NYC memory, Tokyo place) would not slip through.
• Confirm it's intentional that the root README and packages/agentic-db/README.md stay identical — this PR keeps them in sync; if they're meant to diverge (e.g., package README trimmed to schema-only), say the word and I'll split them.

Notes

• 8/8 CI green on the latest commit. The cli-e2e-tests failure on the interim commit (2e60830) was the CLI/schema mismatch described above; fixed in 81466ea.
• The radii cited in the docs (5 km / 2 km / 1 km / 500 m / 1 km) are pulled from the blueprint file referenced above and are schema defaults, not hard-coded on the query — each filter still takes a distance at query time.
• No behavioral impact on the shipped agentic-db pgpm package itself (no schema/blueprint change); only the CLI client and test-harness dep moved.

Link to Devin session: https://app.devin.ai/sessions/c5eeee65a3c546c4ac6753bb05fa03e0
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring