docs: information architecture restructure

[johnx25bd]

Summary

Restructures docs from blockchain-first framing ("geospatial policy engine for Ethereum") to wider "verifiable spatial computation" framing. Blockchain is one integration path alongside agents, APIs, and compliance systems.

• Rewritten entry pages: introduction, quickstart, how-it-works lead with curl/API, not Solidity
• 6 concept pages: geocomputation, geographic-features, result-format, privacy-model + edits to verifiable-computation, location-proofs
• 6 guides: local-development, calling-the-api, blockchain-integration, agent-integration, building-plugins, verifying-location-proofs
• 4 use cases: delivery-verification, parametric-insurance, geofence-compliance, onchain-attestation
• 4 trust model pages: architecture, what-is-verified, what-you-are-trusting, security
• API reference: compute/* and verify/* subdirectories
• New: sdk/types, resources/research, resources/changelog

Known remaining work

• ~9 pre-existing pages have old terminology (faq, playground, schemas, sdk/*, api-reference/overview)
• Original replaced files preserved but not in navigation
• Highest hallucination risk: agent-integration, building-plugins, verifying-location-proofs, privacy-model

Test plan

• Review on Mintlify preview
• Verify navigation links resolve
• Check code examples against actual API/SDK
• Flag fabricated claims or incorrect patterns

[johnx25bd]

Code review

Found 8 issues:

1. api-reference/overview.mdx card links point to old flat paths instead of new compute/ subpaths. Six cards link to /api-reference/distance, /api-reference/contains, etc. but mint.json now routes these to api-reference/compute/distance, api-reference/compute/contains, etc. Users clicking these cards land on orphaned pages with no sidebar context.

mintlify-docs/api-reference/overview.mdx

Lines 146 to 163 in 24edfa8

	<CardGroup cols={2}>
	<Card title="POST /distance" href="/api-reference/distance">
	Distance between two geometries
	</Card>
	<Card title="POST /contains" href="/api-reference/contains">
	Is geometry B inside geometry A?
	</Card>
	<Card title="POST /within" href="/api-reference/within">
	Is point within radius of target?
	</Card>
	<Card title="POST /intersects" href="/api-reference/intersects">
	Do geometries overlap?
	</Card>
	<Card title="POST /area" href="/api-reference/area">
	Area of a polygon
	</Card>
	<Card title="POST /length" href="/api-reference/length">
	Length of a line

2. sdk/verify.mdx links to orphaned /api-reference/verify. The new nav splits this into api-reference/verify/stamp, api-reference/verify/proof, and api-reference/verify/plugins. The monolithic page is no longer in mint.json.

mintlify-docs/sdk/verify.mdx

Lines 489 to 491 in 24edfa8

	<Card title="API Reference: Verify" icon="code" href="/api-reference/verify">
	View the HTTP API documentation

3. how-it-works.mdx links to /concepts/eas-resolvers, which is not in the new navigation. RESTRUCTURE.md says this content moves to guides/blockchain-integration.

mintlify-docs/how-it-works.mdx

Lines 132 to 134 in 24edfa8

	<Note>
	Resolver contracts must be deployed and registered by the developer. Astral does not provide pre-built resolver contracts — you create them to implement your specific business logic. See [EAS Resolvers](/concepts/eas-resolvers) for patterns and examples.
	</Note>

4. use-cases/onchain-attestation.mdx links to /guides/geofenced-token, which is not in the new navigation. The file exists on disk but is orphaned from mint.json.

mintlify-docs/use-cases/onchain-attestation.mdx

Lines 248 to 250 in 24edfa8

	**Geofenced transfers** — restrict token transfers to users within a region (see the [geofenced token guide](/guides/geofenced-token) for the full implementation).

5. API URL inconsistency across pages. The API reference documents /compute/v0/distance but the introduction, quickstart, and guide pages use /compute/distance (missing the v0 segment). Developers following the quickstart will hit a different URL than what the API reference documents.

mintlify-docs/api-reference/compute/distance.mdx

Lines 14 to 16 in 24edfa8

	```
	POST /compute/v0/distance
	```

vs

mintlify-docs/introduction.mdx

Lines 44 to 48 in 24edfa8

	```bash
	# How far is it from point A to point B?
	curl -X POST https://api.astral.global/compute/distance \
	-H "Content-Type: application/json" \
	-d '{

6. PR Add location proof plugin documentation #24 review feedback not addressed in api-reference/overview.mdx. Three changes were requested: (a) add Verify API to table/cards and reorder to Verify -> Compute -> Records, (b) change Records API base URL from /api/v0 to /records/v0, (c) change "across chains" to "across systems" in Records card. None were applied. (See PR #24 comments)

mintlify-docs/api-reference/overview.mdx

Lines 13 to 28 in 24edfa8

	| API | Purpose | Base URL |
	|-----|---------|----------|
	| **Compute API** | Verifiable geospatial operations | `/compute/v0` |
	| **Records API** | Query location attestations | `/api/v0` |
	<CardGroup cols={2}>
	<Card title="Compute API" icon="calculator" href="#compute-api">
	Distance, containment, proximity checks with signed attestations
	</Card>
	<Card title="Records API" icon="database" href="/api-reference/records/overview">
	Query existing location attestations across chains
	</Card>
	</CardGroup>
	---

7. concepts/result-format.mdx "Next" card links backward. The card points to /concepts/location-proofs, but in mint.json ordering, result-format comes after location-proofs. The "Next" link should point to /concepts/privacy-model.

mintlify-docs/concepts/result-format.mdx

Lines 198 to 200 in 24edfa8

	<Card title="Next: Location proofs" icon="map-pin" href="/concepts/location-proofs">
	Learn about verifiable location claims

8. resources/schemas.mdx links to orphaned /resources/security. The security page was moved to trust-model/security but the "Next: Security" card in resources/schemas.mdx still points to the old path, which is not in mint.json.

mintlify-docs/resources/schemas.mdx

Lines 192 to 194 in 24edfa8

	<Card title="Next: Security" icon="shield" href="/resources/security">
	Security considerations

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}