🐛 Preserve Android document tree parents

[vinceglb]

Summary

On Android, navigating from Documents/Notes/Drafts back to its parent could return Documents, losing the selected tree grant and causing list() to throw Uri is not a directory.

Resolve external-storage parents from document IDs while preserving the original tree URI. Stop at the selected root, and exclude that root from child metadata lookup so nested selected directories can be listed correctly. Return null for content URIs whose parent cannot be reliably determined.

Updates the PlatformFile guide and API documentation. Adds regression coverage for nested navigation, tree boundaries, encoded names, storage-volume roots, and unsupported content URIs. The sample already handles a null parent.

Related to #655.

Validation

• ./gradlew :filekit-core:testAndroidHostTest --tests '*PlatformFileParentAndroidTest*' --max-workers=1 — 11 passed, including API 23 coverage.
• ./gradlew :filekit-core:testAndroidHostTest --tests '*PlatformFileAndroidTest*' --max-workers=1 — 23 passed.
• Repository ktlint command with ktlint-compose-0.4.28-all.jar — passed.
• git diff --check — passed.

The tests use Robolectric with a provider that models a grant to one selected tree. Real-device verification remains outstanding; broader multiplatform checks are left to CI. CI results are pending at PR creation.

Manual verification

On an Android test installation without an existing broader Documents grant:

1. Create Documents/Notes/Drafts/note.txt.
2. Select Documents/Notes using FileKit.openDirectoryPicker().
3. Enter Drafts, call parent(), and list the result. It should return Notes and list Drafts without throwing.
4. Call parent() on the selected root; it should return null.
5. Repeat after selecting Documents: navigating up from Drafts should return Notes, then Documents.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-15T08:00:15.267157Z	e217824	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.