diff --git a/README.md b/README.md index a9a025b..7fda7ac 100755 --- a/README.md +++ b/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) @@ -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.

- Fictional Docker host documentation beside its related notes in Obsidian's local graph + Real Obsidian iPhone dashboard showing open Markdown and CSV-backed tasks from two fictional projects, with completed tasks below

-Obsidian demo with fictional notes. Cross-project links shown are demo-only; Folderwise currently validates links within each repository. +- **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. +
+Browse your knowledge on the desktop, too

- Folderwise iBridge setup notification on macOS confirming that sync is scheduled every five minutes + Fictional Docker host documentation beside its related notes in Obsidian's local graph

-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). +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). +
## 🔄 Keep it current diff --git a/docs/assets/PROVENANCE.md b/docs/assets/PROVENANCE.md index 021ba52..6b881e5 100644 --- a/docs/assets/PROVENANCE.md +++ b/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. diff --git a/docs/assets/ibridge-iphone-dashboard.png b/docs/assets/ibridge-iphone-dashboard.png new file mode 100644 index 0000000..34b0d21 Binary files /dev/null and b/docs/assets/ibridge-iphone-dashboard.png differ diff --git a/docs/assets/ibridge-macos-error.png b/docs/assets/ibridge-macos-error.png new file mode 100644 index 0000000..a2f43f5 Binary files /dev/null and b/docs/assets/ibridge-macos-error.png differ diff --git a/docs/assets/ibridge-task-cycle.png b/docs/assets/ibridge-task-cycle.png new file mode 100644 index 0000000..ace383d Binary files /dev/null and b/docs/assets/ibridge-task-cycle.png differ diff --git a/docs/assets/ibridge-task-rename.png b/docs/assets/ibridge-task-rename.png new file mode 100644 index 0000000..a4aa8bb Binary files /dev/null and b/docs/assets/ibridge-task-rename.png differ diff --git a/docs/assets/ibridge-workflow.svg b/docs/assets/ibridge-workflow.svg new file mode 100644 index 0000000..20b1560 --- /dev/null +++ b/docs/assets/ibridge-workflow.svg @@ -0,0 +1,37 @@ + + Folderwise's optional iCloud bridge + Authoritative Mac project repositories stay outside iCloud. Selected copies go to a separate iCloud vault used by Obsidian on iPhone. Supported phone edits return to Mac for validation and local Git commits. The Mac must be available; the default schedule is five minutes plus iCloud delivery time. + + + + + Your files. A separate phone vault. + + Mac project repositories + Authoritative Markdown + CSV records + Independent Git histories · outside iCloud + Validated local commits · no pushes + + Selected copies + Supported edits + Validate on Mac + + + + + + + Separate iCloud vault + Selected exported documents + Generated task views across projects + + iCloud + delivery + + Obsidian on iPhone + Read · complete · reopen + Task renames + selected note edits: opt-in + Mac available for imports and commits + 5-minute default schedule + iCloud delivery delay + + diff --git a/docs/guide.md b/docs/guide.md index c97fa19..f398feb 100644 --- a/docs/guide.md +++ b/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/.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/.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. diff --git a/docs/ibridge-testing.md b/docs/ibridge-testing.md index 3e5a065..9142fd5 100644 --- a/docs/ibridge-testing.md +++ b/docs/ibridge-testing.md @@ -136,6 +136,12 @@ A successful notification request is **not** proof that a banner was visible. Sc - If no banner appears, end the capture or sharing session, or check Focus and the app's notification permissions, then try again. See [the notification visibility guide](obsidian.md#a-notification-appears-only-in-notification-center). - **Never silently change a global privacy setting** (for example allowing notifications while the display is shared or mirrored). Doing so can expose other apps' private messages. If you choose it for a test, do it consciously, say so in the report, and restore it. +## Reading the real-device examples + +The [illustrated completion and reopening sequence](obsidian.md#complete-and-reopen-from-iphone) uses four separate iPhone Mirroring captures from an owner-run acceptance test with fictional Markdown and CSV projects. It shows a CSV task ticked **before sync**, its source backlog returned after completion, a different CSV task unticked **before sync**, and its row returned after reopening. These are real-device captures, not screenshots generated by the automated self-test. The [returned rename view](obsidian.md#rename-tasks-from-iphone-opt-in) demonstrates task wording, not selected-note text editing. + +Use those images to recognize expected phone states. To establish a completed round trip, also record the scheduled run, authoritative source diff, adapter validation, local commit and clean working tree using the checklist above. A checkbox on screen alone proves neither a Mac import nor a Git commit. The [actual error banner](obsidian.md#conflicts-and-recovery) proves visible notification presentation; it is distinct from setup success and does not establish recovery by itself. [Asset provenance](assets/PROVENANCE.md) records the source capture filenames and transformations. + ## What CI cannot test CI mocks the iCloud transport with plain file copies between the Mac source and the vault and assumes the real transport always works. The `ibridge_status` section then judges every outcome by `_folderwise-sync-status.md`. These stay manual: diff --git a/docs/obsidian.md b/docs/obsidian.md index 7da31db..108deea 100644 --- a/docs/obsidian.md +++ b/docs/obsidian.md @@ -4,6 +4,25 @@ The optional **folderwise-ibridge** keeps your project repositories on your Mac The bridge is deliberately simple: checking means complete; unchecking means incomplete. It does **not** interpret a task, confirm evidence, or establish that the described action happened. Task changes do not advance `last_verified`. Project adapters must implement this same boolean behavior without fabricating evidence. A project can additionally accept task **renames** from the phone; see [Rename tasks from iPhone](#rename-tasks-from-iphone-opt-in). Selected notes can accept **text edits** too; see [Edit notes from iPhone](#edit-notes-from-iphone-opt-in). +## From Mac files to your phone + +Folderwise is a Markdown-and-Git knowledge framework, not a standalone iPhone app. **Obsidian** provides the phone interface; the optional bridge connects selected exports to your local repositories. Folderwise provides no hosted sync service. + +

+ Mac repositories outside iCloud export selected copies to a separate iCloud vault used by Obsidian on iPhone; supported edits return for Mac validation and local Git commits +

+ +The Mac must be available for imports and local commits. Scheduled sync defaults to **five minutes**, with additional iCloud delivery delay; this is not instant or real-time sync. Selected-note edits also wait for their quiet period. Imports require a clean project working tree, validation and conflict checks. Local commits do not imply GitHub pushes. + +| On iPhone | What is supported | +| --- | --- | +| Read documents | Selected tracked files exported into the separate vault | +| Complete or reopen a task | Checkbox toggles in generated task views or supported handwritten source checkboxes; CSV tasks need a configured adapter | +| Rename a task | Per-project `folderwise-ibridgerename: true`; edit the generated task view and preserve its source link; adapter tasks must permit title edits | +| Edit selected copied notes | Bridge `--text-edits on` **and** project `folderwise-ibridgeedit` patterns; protected regions, quiet period and conflict rules still apply | + +Generated task views have stricter rules than opted-in copied notes: they are task projections, not free-form documents. The screenshots below illustrate task operations, **not selected-note text editing**. + ## Layout and prerequisites Use one vault for all project folders. Your source parent remains outside iCloud, for example `~/folderwise/`, with independent project repositories underneath. Create a **separate** vault in Obsidian under `iCloud Drive/Obsidian/Folderwise`. Do not move the source repositories, put Git history in the vault, or synchronize that vault with a second cloud service. @@ -48,6 +67,16 @@ Configuration, ownership records, baselines, temporary clones, export journal an In Obsidian on Mac and iPhone, install and enable the community **Tasks** plugin (`obsidian-tasks-plugin`). Open the exported root `Tasks.md` in reading mode. It includes open and completed tasks across all enabled projects, grouped by project. Every result links to its source document. Undated and nested tasks are included; no tag is required. Tasks inside fenced code examples, front matter and generated blocks are excluded from generic Markdown scanning. +### Complete and reopen from iPhone + +Tick a task in `Tasks.md` to complete it. Untick it in **Completed tasks** to reopen it, including an adapter-backed row hidden by the project's normal backlog. Let iCloud deliver the edit and the Mac run the next scheduled import; then check the returned source note and **Recent imports** in `_folderwise-sync-status.md`. + +

+ Four separate iPhone capture excerpts: a CSV task completed before sync, an empty returned source backlog, a different completed CSV task reopened before sync, and that reopened row in the returned source backlog +

+ +*Real-device acceptance captures with fictional data and a configured CSV adapter. These show two different demo tasks: one completed and another reopened. Panels 1 and 3 are phone state before sync; panels 2 and 4 are returned source views after sync. Screenshots support the visual sequence; verify local commits separately with the [acceptance checklist](ibridge-testing.md#2-complete-tasks-from-the-dashboard). They do not independently establish Git history or selected-note editing.* + ### Generated task folder and naming `TASK_DIR` is the tool’s internal constant for **`_Folderwise Tasks`**, a bridge-managed folder at the root of the **iCloud vault**. It is not a folder in your authoritative Mac project repositories. The bridge builds one task-view file per enabled project, combining its supported handwritten Markdown checkboxes and tasks supplied by its configured CSV adapter. @@ -89,6 +118,12 @@ Renaming is off by default. To allow it for a project, add this to its `.docs.ya folderwise-ibridgerename: true ``` +

+ Returned Obsidian task view with title edits enabled and the control task renamed on iPhone, retaining its source link +

+ +*Authentic returned task-view excerpt with fictional data. This shows the renamed title on the phone; the [rename acceptance test](ibridge-testing.md#5-opt-in-rename-test) verifies the source, local commit and status entry separately.* + The value must be a boolean. After the next sync the project's generated view says that title edits are imported. Then, on iPhone: 1. Open `_Folderwise Tasks/.md` and edit the task text, or use the Tasks plugin's edit dialog on `Tasks.md` and change the description. Keep the checkbox and keep the `([source](…))` link at the end of the line. A due date, tag or other text the dialog adds after the link is rejected. @@ -317,6 +352,14 @@ Use the same `--config /absolute/path/config.json` argument as your installed br Phone imports are evaluated against the last accepted baseline, not modification timestamps. A rejected edit to a **generated task view** is saved to the bridge state's `rejected/` folder (private to your user, outside iCloud, kept 30 days), the view is restored, the edit is listed in the status report, and other projects keep syncing. A pending edit that conflicts with a Mac-side change (for example a toggle or rename of a task that was renamed on the Mac) is handled the same way. Unsupported or conflicting edits to a **copied source note**, and failures such as a dirty project or a failed hook, pause that project (below) so nothing is overwritten; the error names the file and line. +

+ Actual Folderwise iBridge error banner saying the bridge needs attention and directing the user to the vault sync status report +

+ +*Actual attention banner from the fictional acceptance test, distinct from the setup-success notification above. The banner directs you to `_folderwise-sync-status.md`; it does not by itself prove the rejected text was saved or the source stayed unchanged.* + +For a rejected generated-view edit, read **Phone edits not applied**, inspect the restored view and use the private Mac recovery copy if you need the rejected wording. For a paused copied note, inspect **Paused projects** and preserve the pending text before resolving it. Do not treat either kind of notification as proof of a successful import. + **One project's problem pauses only that project.** A dirty source tree, a failed hook or adapter, an unsupported edit to a copied note, an unsafe link, or a changed vault file pauses the project it belongs to: its imports and exports wait, its vault copies and pending phone edits stay exactly as they are, and the status report says `Paused projects: `. Other projects keep importing, exporting and committing. The attention alert fires once per distinct problem. Problems that belong to no project (the dashboard, the status report, an interrupted export journal) still freeze every export. Fix the cause and the next sync resumes the project; no state needs to be erased. To get an unwanted phone edit out of the way without hand-restoring bytes, list and resolve it: