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