docs: showcase the optional iPhone bridge workflow

README.md

@@ -9,7 +9,7 @@
 [![Coverage](https://codecov.io/gh/TheLinuxGuy/folderwise/graph/badge.svg)](https://codecov.io/gh/TheLinuxGuy/folderwise)
 [![Latest release](https://img.shields.io/github/v/release/TheLinuxGuy/folderwise?display_name=tag&sort=semver)](https://github.com/TheLinuxGuy/folderwise/releases/latest)
 
-[Overview](#-a-place-for-what-you-know) · [What's new](#-whats-new) · [Get started](#-getting-started) · [See it in Obsidian](#-see-it-in-obsidian) · [Documentation](docs/guide.md)
+[Overview](#-a-place-for-what-you-know) · [What's new](#-whats-new) · [Get started](#-getting-started) · [iPhone workflow](#-your-projects-on-iphone) · [Documentation](docs/guide.md)
 
 </div>
 
@@ -92,32 +92,37 @@ Folderwise includes metadata and link validation, CSV-to-Markdown tables, genera
 | 🔎 `docs_index.py` / `docs_recent.py` / `docs_stale.py` | what exists, what changed lately, what is due for re-verification |
 | 🔀 `docs_mv.py` | moves or renames docs and headings and keeps every link valid |
 | 📊 `render_tables.py` | renders CSV files into Markdown tables |
-| ☁️ `icloud_bridge.py` | mirror projects into iCloud, complete or rename tasks across projects on iPhone, and commit changes on Mac |
+| ☁️ `icloud_bridge.py` | export selected files to iCloud; complete/reopen tasks in Obsidian on iPhone; validate and commit locally on Mac |
 | 🩺 `docs_doctor.py` / `sync_rules.py` | health-check projects; push the template's shared rules into them |
 
 Every tool, flag and setting is documented in the [full guide](docs/guide.md).
 
-## 🔮 See it in Obsidian
+## 📱 Your projects on iPhone
+
+**Read your documents and manage tasks across projects in Obsidian on iPhone.** The optional iCloud bridge exports selected files to a separate vault while your authoritative Markdown-and-Git repositories stay on your Mac. Folderwise is a knowledge framework; Obsidian provides the phone app.
 
 <p align="center">
-  <img src="docs/assets/obsidian-local-graph.png" alt="Fictional Docker host documentation beside its related notes in Obsidian's local graph" width="800">
+  <img src="docs/assets/ibridge-iphone-dashboard.png" alt="Real Obsidian iPhone dashboard showing open Markdown and CSV-backed tasks from two fictional projects, with completed tasks below" width="400">
 </p>
 
-<sub>Obsidian demo with fictional notes. Cross-project links shown are demo-only; Folderwise currently validates links within each repository.</sub>
+- **Complete and reopen tasks** from one dashboard. CSV-backed tasks need a configured project adapter.
+- **Rename tasks** with per-project opt-in, or **edit selected notes** with both the bridge text-edit switch and project path-pattern opt-in. Generated task views accept only supported task edits.
+- **Keep a local history.** An available Mac validates imports against clean working trees and conflict rules, updates source files, and commits locally. Local commits do not push to GitHub.
 
+Scheduled sync defaults to **five minutes, plus iCloud delivery delay**. Folderwise provides no hosted sync service.
 
-Browse your docs in Obsidian and manage every project’s tasks from one iPhone dashboard. Check off a task on your phone (or, once a project opts in, rename it or edit selected notes); your Mac updates the source files and commits the change while keeping your repositories outside iCloud. [Set up Obsidian + iCloud →](docs/obsidian.md) · [Bridge test cases and iPhone acceptance checklist](docs/ibridge-testing.md)
+**[Set up Obsidian + iCloud →](docs/obsidian.md)** · [See the task round trip](docs/obsidian.md#complete-and-reopen-from-iphone) · [Acceptance checklist](docs/ibridge-testing.md)
 
-**🔔 Mac alerts when sync needs attention.** Receive setup confirmations and alerts for detected sync issues. Open your vault’s [_folderwise-sync-status.md](docs/obsidian.md#bridge-status-report) for details.
+<details>
+<summary>Browse your knowledge on the desktop, too</summary>
 
 <p align="center">
-  <img src="docs/assets/ibridge-macos-notification.png" alt="Folderwise iBridge setup notification on macOS confirming that sync is scheduled every five minutes" width="364">
+  <img src="docs/assets/obsidian-local-graph.png" alt="Fictional Docker host documentation beside its related notes in Obsidian's local graph" width="800">
 </p>
 
-<sub>Actual Mac setup confirmation. Sync issue alerts use the same Folderwise name and logo. [Notification settings and visibility](docs/obsidian.md#a-notification-appears-only-in-notification-center).</sub>
+Obsidian demo with fictional notes. Cross-project links shown are demo-only; Folderwise currently validates links within each repository. [Understand the repository layout](docs/framework-checkout.md).
 
-> [!NOTE]
-> Your topic folders are separate repositories, ignored by the framework's Git checkout. The optional bridge copies selected project files into your own iCloud vault; Folderwise provides no hosted sync service. [Understand the layout](docs/framework-checkout.md).
+</details>
 
 ## 🔄 Keep it current
 

docs/assets/PROVENANCE.md

@@ -9,3 +9,31 @@ The three SVG badges contain static, factual project metadata. They do not claim
 The notification icon in `_tools/ibridge_assets/folderwise.icns` derives from `folderwise-logo.png`. Transparent pixels below alpha 13 were trimmed, the artwork fitted within a 900-pixel square on a transparent 1024-pixel canvas, then resized for macOS standard/Retina icon sizes. The original artwork is unchanged.
 
 `ibridge-macos-notification.png` is the project owner’s real macOS setup-success notification from the fictional bridge test. It was cropped from `SCR-20261025-prno.png` to remove surrounding desktop space; the logo, message, colors, and notification UI were not altered. It shows setup confirmation, not an error alert.
+
+## iPhone workflow assets (2026-10-25)
+
+Owner-supplied, real-device acceptance captures from the fictional bridge test identified as `20261025-201506-iphone-acceptance`. The source JPEGs are unedited iPhone Mirroring window captures; the Mac error banner is a separate owner capture. Originals remain outside this repository, with their original bytes and permissions. No raw evidence folders, logs or private absolute paths are included.
+
+**Interfaces and evidence:** Obsidian, its Tasks plugin, iPhone Mirroring and macOS provide the pictured interfaces. Folderwise is not a standalone iPhone app. `lab-notes` and `trip-notes`, task wording and records are fictional test data; a displayed `sensitivity: private` is a fixture value. Screenshots establish visible phone or banner state at particular moments. Returned-state labels follow the owner's capture descriptions; they do not independently prove an import or a local Git commit. No image demonstrates selected-note text editing.
+
+**Review and transformations:** Source contact-sheet review covered all 13 phone captures, both Mac banner versions and all existing repository raster assets. Selected images contain fictional task data and device status, with no personal names, addresses, credentials or private filesystem paths observed. No redaction was needed. Screen text, checkboxes, cursor artefacts, errors and source links were not changed. No UI was reconstructed or generated, and no different moments were spliced into a single screen. Crops are separately framed and labelled. Raster output uses lossless, optimized RGB PNG; original screenshot pixels are pasted at native scale, with display resizing left to the reader. Compositions use cream, teal and charcoal derived from the established branding, Arial typography, and external labels drawn with Pillow. No new generative artwork was used.
+
+| Asset | Kind and sources | Transformation and purpose |
+| --- | --- | --- |
+| `ibridge-iphone-dashboard.png` | Derivative composition; `01-dashboard-baseline-open-top.jpg` plus existing `folderwise-logo.png` | 560 × 1360. Full 490 × 1075 capture pasted at (35, 190); original logo's transparent padding trimmed and logo resized to fit 64 × 64. New background, heading and footer outside the capture. Chosen for its clear All projects heading and open tasks from both demo projects. Baseline state, before testing; not proof of an import. |
+| `ibridge-task-cycle.png` | Derivative sequence; captures `04-csv-complete-tapped-on-iphone-before-sync.jpg`, `07-csv-source-backlog-empty-after-completion.jpg`, `09-reopen-md-and-csv-tapped-before-sync.jpg`, `10-csv-source-backlog-reopened-row-returned.jpg` | 560 × 1555. Four labelled excerpts, in that order. Crop boxes (left, top, right, bottom; right/bottom excluded): (30, 810, 465, 958), (30, 680, 465, 920), (30, 385, 465, 535), (30, 715, 465, 970). Native-size excerpts on black cards with external labels. Chosen to compare before-sync dashboard actions with returned source backlog states. **Two different CSV demo tasks**, one completed and another reopened; not a single task's entire lifecycle. |
+| `ibridge-task-rename.png` | Derivative composition; `13-rename-returned-on-iphone.jpg` | 560 × 620. Crop (22, 190, 465, 580), pasted at (58, 135) without resizing; cream background and external labels. Shows the generated view's opt-in instructions, renamed control task and retained source link. Returned phone state; commit evidence is separate. |
+| `ibridge-macos-error.png` | Authentic capture derivative; `01-folderwise-error-banner.trimmed.png`, itself cropped by the owner from `01-folderwise-error-banner.original.png` | 360 × 93. Lossless PNG optimization of the owner's existing crop, without changing pixels or notification wording. Actual needs-attention banner, not setup success. Used in recovery guidance, not as evidence that recovery completed. |
+| `ibridge-workflow.svg` | Code-native illustration, no screenshot | 560 × 960. Authored SVG typography, cards and arrows explain selected exports, supported imports, separate vault, Obsidian interface and Mac-local commits. A conceptual workflow, not a capture or a hosted service. Opt-in details and validation constraints are explained in the surrounding documentation. |
+
+### Selection notes
+
+- `01` was preferred to `02-dashboard-baseline-both-projects.jpg`: both show the two projects, but `01` retains a clear dashboard title without the scrolling header overlap.
+- `03-md-complete-tapped-on-iphone-before-sync.jpg`, `05-dashboard-after-background-sync-completed.jpg`, `06-md-source-note-returned-from-mac.jpg` and `08-completed-view-before-reopen.jpg` provide useful supporting state but would duplicate the chosen CSV sequence. The returned Markdown source (`06`) shows task completion, not free-form note editing.
+- `11-dashboard-after-reopen-sync.jpg` has a rendering glitch and is excluded from promotional use.
+- `12-rejected-edit-restored-view-on-iphone.jpg` is supporting recovery state; it is omitted to avoid another near-identical task-view image. The actual error banner plus written recovery steps supplies the useful troubleshooting context.
+- The existing hero and logo remain the brand assets. The desktop graph remains available in the README's expandable desktop example. The existing setup-success notification, Login Items screenshot and macOS background-activity notice remain in their relevant setup sections; none is relabelled as an error.
+
+### Existing assets retained
+
+`obsidian-login-items.png` and `obsidian-background-activity-notice.png` are existing authentic macOS interface captures documenting helper registration and the system's own background-activity notice. They are unchanged in this work. As with `ibridge-macos-notification.png`, neither establishes a successful phone import. The original branding, desktop demo and badge provenance above continues to apply.

docs/guide.md

@@ -428,6 +428,10 @@ The root `.gitignore` ignores every root entry unless explicitly allowed. The pu
 
 ## Optional Obsidian and iCloud bridge
 
+Read selected project documents in **Obsidian on iPhone** and complete or reopen tasks across projects. Folderwise remains a Markdown-and-Git framework: repositories stay outside iCloud, and a separate vault holds exported copies. Task renaming is a per-project opt-in; selected-note editing needs both the bridge text-edit switch and project path patterns. CSV-backed tasks need an adapter with the relevant capabilities. Generated task views accept supported task edits, not arbitrary document edits.
+
+An available Mac validates imports against clean-working-tree and conflict rules and creates **local Git commits**, never automatic GitHub pushes. The five-minute default schedule has additional iCloud delivery delay; note edits also have a quiet period. Folderwise provides no hosted sync service. [See the workflow and real iPhone examples](obsidian.md#from-mac-files-to-your-phone), then follow the setup below.
+
 A fresh Folderwise installation creates no Obsidian vault and leaves bridge sync off. Run `icloud_bridge.py setup` to initialize a local parent vault and a separate iCloud vault with reviewed defaults, enroll existing unconfigured projects, set the default for future `new_project.py` projects, perform the first sync and enable the Mac schedule. The default interval is five minutes. See [the full setup, defaults, uninstall and recovery guide](obsidian.md).
 
 ```sh
@@ -469,7 +473,7 @@ Each sync validates project configurations once and reuses that snapshot for inv
 
 Setup enrollment and phone task imports share the same disposable-clone transaction: copy the project's hooks and Git identity, apply the requested edit, validate and commit, then fast-forward the live repository only if its worktree and HEAD are unchanged. A failed operation removes its disposable clone and preserves pending phone edits for retry.
 
-The bridge also generates `Tasks.md` and `_Folderwise Tasks/<project-folder-name>.md` in the iCloud vault: one combined task view per enabled project, refreshed after imports on each sync. These are interactive views; Mac project files and adapter-managed records remain authoritative. Checkbox toggles are supported everywhere; title edits only for projects with `folderwise-ibridgerename: true`. See [generated task folder ownership, naming, and lifecycle](obsidian.md#generated-task-folder-and-naming).
+The bridge also generates `Tasks.md` and `_Folderwise Tasks/<project-folder-name>.md` in the iCloud vault: one combined task view per enabled project, refreshed after imports on each sync. These are interactive views; Mac project files and adapter-managed records remain authoritative. Checkbox toggles are supported in mapped task views and supported handwritten source checkboxes; title edits only for projects with `folderwise-ibridgerename: true`. See [generated task folder ownership, naming, and lifecycle](obsidian.md#generated-task-folder-and-naming).
 
 Bridge-local JSON configuration is separate from `.docs.yaml`: `version` is 1; `enabled` records installed integration state; `source` and `vault` are separate absolute directories; `mode` is full/lean; `interval_minutes` defaults to 5; `text_edits` (boolean, default false) and `edit_settle_seconds` (default 120) control phone note edits; `notifications` is errors (default), imports (errors plus a counts-only note when phone edits are applied) or off; `max_image_bytes` and `max_images_total_bytes` are null for unlimited (zero means zero bytes). `adapters` maps project names to local argv arrays implementing list/apply/validate. `launchagents_dir` is an optional override for isolated scheduling tests. Configure limits with `--max-image-bytes` and `--max-images-total-bytes`, clear both with `--unlimited-images`, and inspect omissions/estimated export size in root-vault `_folderwise-sync-status.md`. These are file-size estimates, not actual iCloud account usage or billing.