Folderwise 0.2.0

Folderwise 0.2.0 — your knowledge folders, now in your pocket 📱

Folderwise 0.2.0 adds an optional Obsidian + iCloud bridge: read your projects on an iPhone, tick tasks off, and have your Mac turn those edits into ordinary, reviewable local Git commits. The Mac stays the owner of your Git history; the phone never pushes anything. Nothing changes for existing projects unless you opt in.

This release was validated on a real iPhone (iOS 27, Obsidian 1.14.5, Dataview 0.5.68) through the real scheduled macOS job, using fictional data: 88 acceptance checks, 85 passed, 3 blocked by physical/environment limits (listed below), 0 failed. Early rows ran on Tasks 7.21.0 and earlier pre-release revisions of this code; Tasks 8.6.0 is the version the final rows and the supported feature set target. The reproducible acceptance record lists what ran where.

✨ Highlights

• 📱 Check things off from your iPhone. Set up an Obsidian vault with icloud_bridge.py; a scheduled macOS LaunchAgent exports generated task views, picks up your edits, and commits them locally with Bridge: provenance trailers (no task text in commit messages).
• ✅ Real Obsidian Tasks support (emoji and Dataview formats): due, start and scheduled dates, priorities, in-progress / cancelled / custom statuses, automatic created, done and cancelled dates, recurrence (including completed-first ordering), 🏁 on-completion delete or keep, task IDs and dependencies. Tags, links, Unicode and block IDs survive every round trip.
• 🌳 Subtasks that behave. Nested, tab-indented, numbered, quoted and callout tasks; repeated child titles; fenced examples are never exported as tasks.
• ✏️ Opt-in task renames from the phone, with every unsafe shape rejected as a unit: swapped or duplicate titles, links or images inside titles, a leading =, titles over 200 characters, text after the source link, a removed link, reordering.
• 📝 Opt-in edits to copied notes. Create, reparent or delete child tasks and toggle recurring tasks inside notes you list with folderwise-ibridgeedit; protected regions and managed stamps stay untouched.
• 🧾 CSV task adapters. Back phone tasks with a CSV through a small adapter. Capabilities are enforced per adapter: a boolean-only adapter rejects due dates and recurrence by name, a rich adapter supports fields, statuses, recurrence and delete.
• 🛡️ Safe by design. A bad edit is contained instead of lost or applied: the phone text is saved to state/rejected/, the view is restored, the reason appears in the status report, and you get one notification. One project's problem pauses only that project.
• 🔍 See before it happens. plan previews what a phone edit would do; resolve recovers a pending edit; doctor and status explain the state; _folderwise-sync-status.md is the report of record.
• 🤝 Mac and phone can work at once. Different fields merge; the same field changed on both sides keeps the Mac value and reports the conflict; nothing is silently overwritten.
• 🔁 Recovers from interruptions. Lost state, an interrupted export, a lost journal or a replay after a published commit rebuild without duplicate commits or duplicate recurrence successors. A brief iCloud file lock is retried quietly instead of raising an alert.
• ⏱️ Quiet period. By default the bridge waits for 120 seconds of unchanged phone text across two five-minute runs, so half-typed titles are never committed.
• 🔔 Notification modes off, errors (default) and imports, plus notify-test.
• 📦 Minimal pull-only framework checkouts (framework_checkout.py) for installing just the framework beside your own repositories.
• 🚀 Quick Start for the iPhone bridge. A five-minute path at the top of the Obsidian guide: prerequisites, setup, first scheduled commit, and the four settings that matter.
• 📚 A reproducible test record. The 0.2.0 acceptance record has the fictional fixtures, the full 88-row matrix with results, the blocked rows and how to finish them, and lessons for re-running it after a refactor. README and guides refreshed to match.

🔧 Under the hood

• Fixed staged validation and isolated bridge project failures (#16).
• Clearer previews and damaged source-link diagnostics (#19).
• Four defects found during the real-device run were fixed before release, including quiet handling of transient iCloud locks.
• Self-tests cover the bridge, rich adapters, Tasks 8.6 fixtures, renames, isolation, copied notes, transient locks, status reporting and setup. CI enforces coverage on every change.

⚠️ Known limitations

Not verified on a physical device in this release:

• Offline edit then reconnect (needs a physical airplane-mode toggle).
• A fresh vault's Tasks plugin load on the phone (the existing-vault upgrade path passed; the bridge export for a fresh vault was healthy).
• A visible native notification banner (the notification is requested once per run with an issue; macOS decides whether a banner shows, and screen mirroring can suppress it).

Also good to know:

• The iPhone bridge needs macOS (for the LaunchAgent). The core framework remains Linux and macOS; native Windows is not supported (use WSL).
• If a rejection restores your view, wait until the restored view reaches the phone (or reopen the dashboard) before editing again, otherwise the phone can save the rejected text back.
• Rejection reasons for swapped and duplicate titles share one general message.

🧭 Compatibility notes

• Python 3.10 or later, Git with a configured author identity, and uv. Linux and macOS (CI: Python 3.10 and 3.15 on Linux, 3.15 on macOS).
• The Obsidian bridge is opt-in: no existing project, vault or setting changes unless you run the bridge setup. It reads and writes only the projects you enroll and never pushes.
• Obsidian Tasks 8.x is the validated plugin version; run doctor to see a version warning if your vault differs.

⬆️ Upgrade notes

• Clone installs: git pull --ff-only.
• Archive installs: follow Upgrading an archive install; nothing is overwritten without a backup.
• Your independent knowledge projects are never modified by an upgrade. If you already use the bridge from an earlier build, rerun icloud_bridge.py doctor after upgrading, then let the next scheduled run regenerate the views.

📥 Install

Download folderwise-0.2.0.zip or folderwise-0.2.0.tar.gz together with SHA256SUMS, verify, extract, and run the self-test as described in docs/framework-checkout.md ("Install from a release archive"). Cloning the repository is recommended if you want Git-based upgrades.

shasum -a 256 -c SHA256SUMS --ignore-missing

Source commit: 9c0b9aa345c8 (full SHA 9c0b9aa345c898f0dd62849875ab9b293a9cd802). Every file in the archives is a tracked file at that commit; RELEASE-INFO.json records the version and commit.

What's Changed

• README: emoji headings, What's new, tools overview by @TheLinuxGuy in #7
• Add opt-in minimal pull-only framework checkouts by @TheLinuxGuy in #8
• Add opt-in Obsidian vault setup and iCloud task bridge by @TheLinuxGuy in #9
• Polish Folderwise iBridge notifications and generated vault files by @TheLinuxGuy in #10
• iBridge: opt-in task renames from iPhone, safer rejected edits, clearer status by @TheLinuxGuy in #11
• iBridge: per-project pausing, plan preview of phone edits, resolve command, imports notifications by @TheLinuxGuy in #12
• Document iCloud bridge test cases; keep them in step with the self-tests by @TheLinuxGuy in #13
• Fix staged validation and isolate bridge project failures by @TheLinuxGuy in #16
• iBridge: opt-in phone text edits to copied notes, and a status-report test matrix by @TheLinuxGuy in #14
• docs: showcase the optional iPhone bridge workflow by @TheLinuxGuy in #18
• Clarify bridge previews and damaged source-link diagnostics by @TheLinuxGuy in #19
• Support Obsidian Tasks metadata and subtasks in iPhone sync by @TheLinuxGuy in #17
• Update copyright holder in LICENSE file by @TheLinuxGuy in #20
• docs: iPhone/Obsidian Quick Start, 0.2.0 README, reproducible acceptance suite by @TheLinuxGuy in #22

Full Changelog: v0.1.0...v0.2.0

Folderwise 0.1.0

🗂️ Folderwise 0.1.0 — first release

Human-readable knowledge, AI-assisted upkeep. Markdown and Git underneath.

Folderwise is a Markdown-and-Git framework for knowledge that people read and AI agents help maintain: home network inventories, runbooks, decisions, plans, household records. One topic, one folder, one Git history, with shared tools that keep metadata, links, indexes and review dates consistent.

✨ What's in 0.1.0

• 🧰 The toolkit: create projects and docs, stamp every edit with a Change Log, lint front matter and links, render CSV-backed tables, move or rename docs without breaking links, list what changed and what is overdue for review, and health-check a project (new_project, docs_new, docs_stamp, docs_lint, docs_index, docs_recent, docs_stale, docs_mv, render_tables, docs_doctor, sync_rules).
• 🪝 A pre-commit hook in every project that lints what you stage and fails closed if the tools or uv are missing.
• 🛡️ A framework guard: the public repository is an allowlist, so your own knowledge projects, caches and credentials are never added to it.
• 🤖 Agent-ready projects: shared rules in each project's AGENTS.md, plus a ready-made setup prompt for Claude Code or Codex.
• 🗃️ Obsidian-friendly: plain Markdown that works with an optional Obsidian vault.
• ✅ Tested: 417-check self-test, 90% production line coverage, clean-machine install checks, and both archives extracted and tested before this release was created.

💻 Compatibility

• 🐧 Linux and 🍎 macOS. CI runs the full suite on Linux with Python 3.10 and 3.15, and on macOS with Python 3.15.
• 🐍 Python 3.10 or later and uv. Git with a configured author identity.
• 🪟 Native Windows is not supported or tested: the Git hooks are POSIX sh scripts. Use WSL.
• 🔒 Nothing is uploaded and there is no sync service. Your knowledge projects stay in their own local Git repositories.

🔄 Upgrade notes

This is the first release, so there is nothing to migrate.

• 🌱 Clone installs (recommended): git pull --ff-only, then run the self-test.
• 📦 Archive installs: extract the next release into a separate folder, run its self-test, preview the differences, and copy only the framework files with backups. Never extract over your install. Steps: Upgrading an archive install.
• 🛑 No step in the upgrade path touches your independent knowledge projects.

📥 Install

Recommended: clone (upgrades with Git):

git clone https://github.com/TheLinuxGuy/folderwise.git ~/folderwise

Or from this release's archive (no Git history):

1. Download folderwise-0.1.0.zip or folderwise-0.1.0.tar.gz and SHA256SUMS into the same folder.
2. Verify the download:

shasum -a 256 -c SHA256SUMS --ignore-missing

On Linux, use sha256sum -c --ignore-missing SHA256SUMS.

3. Extract as ~/folderwise (the folder must not already exist) and run the self-test:

mkdir ~/folderwise && tar -xzf folderwise-0.1.0.tar.gz -C ~/folderwise --strip-components=1
cd ~/folderwise && uv run _tools/selftest.py

For the zip: unzip -q folderwise-0.1.0.zip && mv folderwise-0.1.0 ~/folderwise. Full instructions: Install from a release archive. Then create your first project with uv run _tools/new_project.py (see the README).

🔐 About this release

• Built from commit bc879279361a (full SHA bc879279361a6bcb3a4261e3f0eea12d96f74fda). RELEASE-INFO.json inside each archive records the version and commit.
• Archives contain only approved tracked files: tools, project template, public guides, license, and the root files that keep your projects out of the framework repository. No CI configuration, caches or credentials.
• This release is immutable: its tag and assets cannot be changed after publishing. A fix will ship as a new version.

What's Changed

• Add CI, coverage gate, Codecov, install checks and draft release packaging by @TheLinuxGuy in #1
• Release workflow: retry and explain draft verification by @TheLinuxGuy in #6

New Contributors

• @TheLinuxGuy made their first contribution in #1

Full Changelog: https://github.com/TheLinuxGuy/folderwise/commits/v0.1.0