docs: revive PR #66 PostGIS updates + demote --fast flag with idempotency warning

[pyramation]

Summary

Two documentation fixes in one PR:

1. Revive lost PostGIS skill updates (from #66)

PR #66 added PostGIS documentation to skills/constructive-graphql/references/search-postgis.md, but the repo was subsequently restructured (skills/ → .agents/skills/), leaving the PR in conflict with its changes orphaned. This reapplies those changes to the new path. Additions include:

• withinDistance (ST_DWithin) compound input operator with GraphQL + SDK examples
• orderingEquals operator (was missing)
• Type-specific fields table (Point, LineString, Polygon, Multi*, Collection)
• Measurement fields (area, length, perimeter)
• Transformation fields (centroid, bbox, numPoints)
• Aggregate functions (ST_Extent, ST_Union, ST_Collect, ST_ConvexHull)
• Updated "When to Use" recommendations and cross-references

2. Demote --fast flag in pgpm CLI reference

pgpm deploy --fast --no-tx was listed as a standard deployment option, which led agents to use it as their default approach. In reality, --fast is not idempotent — it skips dependency tracking and will attempt to re-deploy shared deps (e.g. pgpm-verify), breaking deployments. Moved it out of the standard examples into a prominent warning block.

Review & Testing Checklist for Human

• Verify withinDistance input shape matches the actual WithinDistanceInput GraphQL type — doc claims { point: GeoJSON, distance: Float }. Check against within-distance-operator.ts in the constructive repo.
• Verify measurement field availability — doc claims area/perimeter on Polygon, length on LineString. Confirm against measurement-fields.ts.
• Check cross-reference relative paths — ../../pgpm/SKILL.md, ../../pgpm/references/docker.md, and ./codegen-orm-patterns.md should resolve correctly from .agents/skills/constructive-graphql/references/.
• Confirm --fast flag warning accurately describes the non-idempotent behavior and shared-dependency issue.

Notes

• PR docs: update PostGIS skill with withinDistance, measurements, transformations, aggregates #66 can be closed after this merges — its changes are fully incorporated here.
• The aggregate functions section is intentionally brief since aggregates depend on the Graphile aggregates system being enabled.
• Geography Point fields use longitude/latitude instead of x/y — documented but worth double-checking against the inflection plugin.

Link to Devin session: https://app.devin.ai/sessions/b317d028d4674dda91aad43460fee844
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