fileworkbench/README.md

# Fileworkbench — Android MVP source release 0.2.3

**Open files, not accounts.** A read-only, local-processing Android file browser and viewer, with a
Kotlin Multiplatform document core that can be reused by a later native iOS shell.

> **Source release, not a verified APK.** Host checks pass: 112 core/JVM and 16 listing checks. The complete project includes the SAF-D1 diagnostics
> and the earlier PDF and cursor-result corrections. The user's continuing folder failure is
> **not diagnosed or claimed fixed**. See `docs/VALIDATION.md` for executed host checks and
> Android-build limitations. No APK, JDK, Android SDK or iOS application is bundled.

## 0.2.3 — complete diagnostic project, Gradle 8.14.5 / JVM 17

No patch application is required. Extract this archive to a fresh directory and open the
contained `fileworkbench` project. Do not copy old build scripts, `.idea`, `.gradle`, or
`gradle/gradle-daemon-jvm.properties` over this release. Preserve your original checkout separately.

- Gradle **8.14.5** is pinned in the wrapper, bootstrap downloads and official SHA-256 checksums.
- Gradle daemon criteria, Java/Kotlin toolchains and JVM bytecode targets use **17**. Install a
  JDK 17 locally and select it as the IDE Gradle JVM / `JAVA_HOME`; no absolute JDK path is shipped.
- Root plugin requests and catalog IDs remain distinct: the Kotlin JVM plugin is requested once
  at the root with `apply false`, then applied in its subproject.
- App version is **0.2.3 / code 5**. The Locations footer shows
  **Fileworkbench 0.2.3 · Browser diagnostics SAF-D1**.
- A genuinely null directory-query cursor reports `[SAF-D1/NULL_CURSOR]`, the provider authority,
  Android API and retained-read-grant status. No document URI/path or file content is included.
  This is evidence for the next diagnosis, not an automatic repair or broader storage grant.

See `docs/RELEASE-0.2.3.md` for the integrated changes and `docs/BUILD.md` for fresh-project setup.

## What is in this release

- Native **Browse / Recent** screens; saved folder locations, nested navigation, breadcrumbs, filename
  search, folders-first sorting, size/date/type details, hidden-file toggle and opt-in provider thumbnails.
- Android **files-app category** and separate `GET_CONTENT` picker with MIME filters, single/multiple
  selection, confirmation, and temporary read-only copied results. It does not replace the system picker.
- Android system document/folder picker and `Open with` / single-file `Share` intent handling.
- Private bounded read-only snapshots, recent files, retained read grants where the provider permits
  them, explicit share-original / save-copy / preview-text export, details and cache/history cleanup.
- Native PDF page navigation and zoom, with a separate isolated PDF-rendering service and a bounded
  raw-pixel IPC transport. Raster image view with downsampling and zoom.
- Text/source, basic Markdown, CSV/TSV tables, and ZIP index views.
- **Reading previews** for DOCX, XLSX, PPTX, ODT, ODS and ODP: text, sheet values, simple document
  tables and slide sections. Search works on supported extracted text and archive names.
- Common Kotlin parsers, policy, models, search and export; JVM ZIP adapter; Apple framework targets.
- Unit/integration test sources, a local offline core test runner, Android smoke-test sources,
  a build/CI configuration, debug fixture DocumentsProvider, format matrix, threat model and implementation roadmap.

**Office reading previews are not original-layout rendering.** Images, charts, page geometry,
advanced formatting and other content can be absent. The UI and text exports state this explicitly.
No LibreOfficeKit, Collabora or third-party Office rendering binary is bundled. Legacy/macro-enabled
Office, Office editing, PDF search/forms, and full-fidelity Office viewing are not implemented.

## Use the browser

Choose **Browse → Add folder** once, grant access in Android's UI, and browse that folder inside
Fileworkbench. Tap a file to preview; Back / Files returns to the same browser location. **More →
Open in another app** hands off a read-only copy. Use **Open file** for single items elsewhere.

This uses folder-scoped access, **not unrestricted storage access**. Android 11+ does not permit
bookmarking the storage root or Downloads root through this mechanism; individual Downloads files
remain available through the system picker. There is no rename/delete/move feature in this release.

Read [`docs/BROWSER.md`](docs/BROWSER.md) for registration semantics, picker security, storage
restrictions, limits and the shared iOS-facing API. The browser's Android test plan is in
[`docs/BROWSER_ACCEPTANCE.md`](docs/BROWSER_ACCEPTANCE.md).

## Open the project

Gradle is pinned to **8.14.5**. Use an installed **JDK 17** for both your IDE Gradle JVM and terminal.

Use JDK 17 and an Android Studio version supporting AGP 8.11.1. Install Android SDK platform 36
and Build Tools 35.0.0. The Android app is configured for Android 8.0/API 26 and newer.

The source ZIP deliberately does not contain a downloaded Gradle wrapper JAR. The included
launchers fetch the **official Gradle 8.14.5 wrapper** on first use and require its pinned SHA-256.
The Gradle distribution is separately checksum-pinned. This is build-time networking only.

```sh
chmod +x gradlew scripts/*.sh
./gradlew --version
./gradlew :core:jvmTest :platform-jvm:test :androidApp:assembleDebug
```

On Windows use `gradlew.bat`; its bootstrap uses PowerShell. Before importing into Android Studio,
run `./gradlew --version` once (Windows: `gradlew.bat --version`) to materialize the wrapper JAR.
Then open this root directory in Android Studio and select the `androidApp` run configuration.

After a **successful** Android build, the debug APK is expected at:
`androidApp/build/outputs/apk/debug/androidApp-debug.apk`.

```sh
adb install -r androidApp/build/outputs/apk/debug/androidApp-debug.apk
```

This installs a development build, not a production-signed distribution. Full setup and troubleshooting:
[`docs/BUILD.md`](docs/BUILD.md).

## Modules

```text
androidApp/       Compose browser/viewer, SAF, file picker, copies, grants, PDF service, images
core/             commonMain: document core + browser models/filter/sort/MIME/selection budgets
platform-jvm/     bounded java.util.zip adapter, local-file preview orchestration
                      (shared by Android and JVM tests, NOT by iOS)
ios/              Apple integration plan; native framework targets live in core/build.gradle.kts
scripts/          verified Gradle bootstrap, offline tests, structural checks, Android build checks
docs/             architecture, build instructions, feature matrix, security, roadmap, validation
examples/         small ordinary text/CSV/source examples
```

## Privacy defaults

There are no network, broad-storage or account permissions in the main manifest. The app never
uploads documents or edits originals. It uses user-selected provider URIs, not all-files access.
A selected external storage provider may itself use the network. Sharing/exporting/copying selected
text are deliberate user actions outside the app's local-only boundary.

Snapshots, saved folder names/URIs, and recent filenames/URIs are stored privately in the app sandbox; there is no additional
application-level encryption. Backup/transfer exclusions are configured. Cached data is not
promised to be securely erased from flash storage. This MVP is not security-audited.

## Verification commands

```sh
# With Gradle + Android SDK:
./scripts/verify-android.sh
# With a connected device/emulator:
./gradlew :androidApp:connectedDebugAndroidTest
# Without Android SDK or network, using an installed Kotlin compiler + Python 3:
./scripts/test-core.sh
python3 scripts/check-project.py
python3 scripts/test-folder-listing.py
./scripts/check-kotlin-syntax.sh
```

The offline runner uses the same test method bodies as the Gradle unit tests, stripping only
runner annotations. It is not a substitute for an Android build or runtime test.

## iOS path

On a compatible Mac/Xcode installation:

```sh
./gradlew -PenableIos=true :core:assembleFileworkbenchCoreReleaseXCFramework
```

This builds only the reusable framework. An Apple file-access/ZIP adapter and native UI still need
implementation. Read [`ios/README.md`](ios/README.md) before starting an iOS port.

## Start here for continued development

[`docs/ROADMAP.md`](docs/ROADMAP.md) defines the next slices and acceptance gates.
[`docs/CODEX_HANDOFF.md`](docs/CODEX_HANDOFF.md) is a continuation brief for an implementation agent.
Do not represent an interface, an unexecuted test, or a configured build target as completed runtime
functionality. The immediate next gate is the first real Android build and device test.

Working name: **Fileworkbench**. Provisional application ID: `dev.fileworkbench.android`.
New source is MIT-licensed; review distribution/licensing before adding third-party native engines.