tag-keeper 0.1.0__tar.gz

tag_keeper-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+*.log
+
+# uv が開発用に生成するロックファイル (ライブラリなので固定しない)
+uv.lock

tag_keeper-0.1.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-08
+
+First release. The web UI and messages are in Japanese.
+
+### Added
+
+- **Inventory.** `scan` walks a root read-only into an SQLite catalog kept outside the
+  tree, tracking renames and moves by inode. Mass disappearances are held until a second
+  scan confirms them; a missing or empty root aborts the scan. `hash` computes SHA-256
+  incrementally.
+- **Hygiene report.** `report` lists application data in synced folders, rebuildable
+  artifacts, VM images, installers, temporary files, Office lock files, sync conflict copies
+  (only when the original is next to them; differing copies are marked for review), empty
+  files and folders, and duplicates confirmed by hash.
+- **Tidy-up plans.** `plan` writes candidates to an editable TOML file; `apply` previews,
+  then moves items to a quarantine folder outside the tree or renames and moves them inside
+  it, skipping anything that changed since the plan was written, with snapper pre/post
+  snapshots around the run. Every move is journaled and `undo` puts it back without
+  overwriting anything new. Destinations are checked against OneDrive's naming rules.
+- **Big deletions without stopping the sync client.** With `sync_client = "onedrive"`, a
+  plan that removes a folder above the OneDrive client's `classify_as_big_delete` threshold
+  stops the resident sync, reflects the deletions with one `onedrive --sync` whose threshold
+  is raised just enough (never `--force`), and starts it again. A failed reflection leaves
+  the sync stopped, is journaled, and can be retried or abandoned (`tag-keeper sync`).
+- **Web UI** (`serve`): roots, report, plans (untick to skip), check, apply and undo, with
+  background jobs and a progress panel. Loopback by default; other addresses require HTTP
+  Basic auth, and writes must be same-origin.
+- **File browser** with in-page previews for types that cannot run scripts; paths never
+  leave the root.
+- **Tags** on files and folders, inherited from folders, kept in append-only JSONL logs one
+  per machine, and following moves seen by `scan` or made by plans.
+- **Version history** from btrfs snapshots via btrfs-timeline: versions of a file, a folder
+  at any snapshot, restoring an old version beside the current one. Moves are recorded, so
+  history continues across them.
+- **Inbox suggestions.** Files in folders named like `tmp` or `*未整理*` are listed flat;
+  picking one asks an ollama model (local or cloud) for a `YYYYMMDD_title` name, destination
+  folders among existing ones and tags, usually within seconds. Accepted suggestions run as
+  one plan of renames and moves. Files elsewhere get suggestions on request.
+- **Decision log.** Accepted suggestions, tag accept and reject, and undone plans are
+  appended per machine; the closest past decisions are given to the model as examples.
+
+[0.1.0]: https://github.com/akivajp/tag-keeper/releases/tag/v0.1.0

tag_keeper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akiva Miura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tag_keeper-0.1.0/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.5
+Name: tag-keeper
+Version: 0.1.0
+Summary: Tag, search and tidy your existing file trees from the outside, without moving a file
+Project-URL: Homepage, https://github.com/akivajp/tag-keeper
+Project-URL: Repository, https://github.com/akivajp/tag-keeper
+Project-URL: Issues, https://github.com/akivajp/tag-keeper/issues
+Author-email: Akiva Miura <akiva.miura@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: catalog,cloud-drive,file-management,onedrive,pcloud,self-hosted,tagging
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Bottle
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: System Administrators
+Classifier: Natural Language :: Japanese
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: bottle>=0.12
+Requires-Dist: btrfs-timeline>=0.8.4
+Requires-Dist: rich>=13
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: webtest>=3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tag-keeper
+
+Tag, search and tidy your existing file trees from the outside — without moving a file.
+
+[日本語版 README はこちら](README.ja.md)
+
+> **Status: pre-alpha.** What works today: the inventory (scanning, content hashing, a
+> hygiene report), cleaning up with plans you approve (with undo), a file browser with tags
+> and version history from btrfs snapshots, and name and folder suggestions for your inbox
+> folders from a local model. Search and the rest of tagging come next. See [Roadmap](#roadmap).
+
+## Why
+
+Most document managers take ownership of your files: they ingest them into their own
+storage and lay them out flat. That is the opposite of how a cloud drive is actually
+used. Its folders already mean something — a numbered project folder, a source code
+repository with its own layout, a year/month archive — and that meaning lives in each
+folder, not in one global category tree.
+
+tag-keeper leaves the tree alone. It keeps its own catalog next to the tree, and from
+there it helps you keep the tree clean:
+
+- **It never takes ownership.** No copying, renaming or converting. You keep using your
+  file manager and shell as before.
+- **It follows what you do outside it.** Files you move or rename keep their records.
+- **Changes are proposals.** Anything that would move a file is written down as a plan,
+  shown first, and only runs once you approve it. Nothing is ever deleted: files go to a
+  quarantine folder, and every plan can be undone.
+
+## What it does today
+
+```console
+$ tag-keeper scan ~/CloudSync/OneDrive     # read-only walk; updates the catalog
+$ tag-keeper hash ~/CloudSync/OneDrive     # SHA-256 of files that changed since last time
+$ tag-keeper report ~/CloudSync/OneDrive   # what is probably not worth keeping in the cloud
+```
+
+- **scan** records path, size, mtime and inode of every file and folder. Renames and
+  moves are tracked by inode, so a moved file keeps its row (and its hash).
+  - **Safety valve:** if a large share of files vanishes at once — an unmounted drive, a
+    sync client accident — the deletions are *held*, not recorded. They are recorded only
+    if they are still missing on the next scan (or with `--accept-missing`).
+  - A root that is missing or empty aborts the scan instead of looking like "everything
+    was deleted". Folders that cannot be read are not treated as gone either.
+- **hash** computes SHA-256 only for files that are new or changed, with a progress bar
+  and ETA. A file that changes while being hashed is skipped.
+- **report** lists candidates by category, with sizes and examples:
+  - application data that slipped into a synced folder (game data, caches) — reported
+    once per folder, at the deepest folder that matches, so it never swallows your own
+    documents next to it
+  - rebuildable artifacts (`node_modules`, `__pycache__`, …), VM disk images, installers
+    and disk images, temporary files and Office lock files
+  - sync conflict copies (OneDrive for Linux `-safeBackup-`, pCloud `[conflicted]`,
+    rclone bisync `.conflict1`, device-name suffixes, `(1)` copies) — only when the
+    original sits next to it, since a lone "copy" may be the only version. Copies whose
+    content differs from the original are marked as needing review
+  - empty files and folders
+  - exact duplicates, confirmed by hash (never guessed from size)
+
+The catalog is an SQLite file outside the tree (`~/.local/share/tag-keeper/catalog.db` by
+default). None of these commands writes into the tree.
+
+### Cleaning up with a plan
+
+```console
+$ tag-keeper plan onedrive                  # write the report's candidates to a plan file
+$ $EDITOR ~/.local/share/tag-keeper/plans/<plan-id>.toml   # delete the lines you want to keep
+$ tag-keeper apply <plan file>              # preview only
+$ tag-keeper apply <plan file> --yes        # move them to the quarantine folder
+$ tag-keeper undo <plan-id> --yes           # put everything back
+```
+
+- **plan** writes one line per item, grouped by category. `--category` limits it to some
+  categories (`app-data`, `vm-image`, `conflict`, …). Candidates that need review stay out
+  unless you pass `--include-review`.
+- **apply** previews by default. With `--yes` it moves each item, by rename, to
+  `<quarantine_dir>/<plan-id>/` under its original relative path. Right before each move
+  it checks that the item has not changed since the plan was written (inode, size,
+  modification time, and for folders the file count and total size); changed items are
+  skipped and reported.
+- With `snapper_config` set, a snapper *pre* snapshot is taken before the run and a *post*
+  snapshot after it. If the pre snapshot fails, nothing is moved.
+- Every move is appended to a journal (`~/.local/share/tag-keeper/journal/<plan-id>.jsonl`).
+  **undo** reads the journal and moves items back; it never overwrites something that has
+  appeared at the original path since.
+- The catalog is updated as items move, so the next scan does not mistake a large
+  quarantine for a mass disappearance.
+- Items leave the cloud when the sync client notices they are gone, but they stay on this
+  disk until you empty the quarantine folder yourself.
+
+### Big deletions without stopping your sync client
+
+The [OneDrive client for Linux](https://github.com/abraunegg/onedrive) treats the local
+removal of a folder with many children (`classify_as_big_delete`, 1000 by default) as an
+accident: it refuses to sync and exits. Run under systemd, it keeps exiting on every
+restart, so syncing silently stops. When *you* approve a big deletion, tag-keeper
+coordinates with the client instead (set `sync_client = "onedrive"` on the root):
+
+1. stop the resident sync (`systemctl --user stop onedrive.service`),
+2. quarantine the items,
+3. run one `onedrive --sync` with the threshold raised just above the largest folder in this
+   plan — not `--force`, which would also let unrelated accidents through,
+4. start the resident sync again.
+
+If step 3 fails, the resident sync is left stopped (restarting it would only exit again),
+the failure is journaled, and the web UI and `tag-keeper sync <plan-id> --retry` offer to
+try again. Small plans are left to the running client as usual.
+
+## Web UI
+
+```console
+$ tag-keeper serve                  # http://127.0.0.1:8090/
+```
+
+Everything above can be done in the browser: refresh a root (scan and hash), read the
+report, create a plan, untick what you want to keep, check it, run it and undo it. Long
+operations run in the background, and a panel at the bottom shows each step, a progress
+bar, speed, time remaining and the latest log lines. It works on a phone too.
+
+- Only loopback is served by default. To listen elsewhere (for example on a Tailscale
+  address), give credentials for HTTP Basic auth with `--auth-file` (one line,
+  `user:password`) or `TAG_KEEPER_AUTH`; without them a non-loopback address is refused
+  unless you pass `--allow-no-auth`. Basic auth is not encrypted: use it over a VPN such as
+  Tailscale, or behind TLS.
+- Writes require a same-origin request, and without auth the `Host` header must name the
+  bound address (against DNS rebinding).
+- One job runs at a time. Each job also writes its own log under
+  `~/.local/share/tag-keeper/logs/jobs/`.
+
+### Files, tags and history
+
+- **Browse** a root folder by folder, preview PDFs, images, audio, video and text in the
+  page, and download anything. Only types that cannot run scripts open in the page; HTML
+  and SVG are shown as plain text, everything else downloads. Paths never leave the root,
+  symlinks included.
+- **Tag** files and folders from the browser. A folder's tags are inherited by everything
+  under it. Tags live in append-only JSONL logs, one file per machine
+  (`~/.local/share/tag-keeper/tags/<host>.jsonl`), so they stay readable without the tool
+  and never conflict when synced. When a tagged item is moved — by you or by a plan — the
+  log records the move and the tags follow.
+- **Version history** comes from btrfs snapshots through
+  [btrfs-timeline](https://github.com/akivajp/btrfs-timeline): the versions of a file, a
+  folder as it was at any snapshot (including what has since been deleted), and restoring
+  an old version next to the current file under a dated name (never overwriting).
+  tag-keeper records renames and moves it sees, so a file's history continues across them.
+
+### Inbox suggestions
+
+Folders whose name matches `inbox_patterns` (by default `tmp`, `temp`, `*未整理*`,
+`*inbox*`) are treated as inboxes. The **整理** page lists every file in them flat, without
+the folder hierarchy. Pick a file and a model served by [ollama](https://ollama.com/) reads
+it — text from PDFs and Office files, the image itself for photos and scanned PDFs — and
+suggests, usually within seconds:
+
+- a name, by default `YYYYMMDD_title`, following past decisions and the date style of the
+  destination folder, and keeping a meaningful existing name;
+- up to three destination folders among the folders you already have: candidates are
+  narrowed by character-bigram TF-IDF over each folder's path and file names, then the model
+  picks. Year and month folders are moved to the document's date;
+- tags, preferring the ones you already use; new ones are marked as such.
+
+Clicked files jump the queue and the next two are read ahead. Accepted suggestions go to an
+accept list, which you run as one plan of renames and moves — with snapshots and undo — or
+save to review on the plan page. Files outside the inboxes get a suggestion only when you ask
+for one from the file browser.
+
+**Learning from your decisions.** What you accept (suggested versus final name, folder and
+tags), the suggested tags you add or reject, and plans you undo are appended to a log, one
+JSONL file per machine (`~/.local/share/tag-keeper/decisions/`). Files you move out of an
+inbox yourself count too. When suggesting, the closest past decisions are added to the prompt
+as examples and their folders join the candidates; tags you keep rejecting are avoided. The
+log pairs each suggestion with your decision, so it can be exported as training data.
+
+**Models.** The default is a local model. Any ollama model can be chosen on the page or in
+the config, including ollama's cloud models (`…:cloud`, `…-cloud`) — then the file's content
+is sent to ollama's cloud; the page marks those models with ☁. Suggestions are stored by
+content hash and model, so a file is read once per model.
+
+## Install
+
+Requires Python 3.11+ and Linux. The web UI and messages are in Japanese.
+
+```console
+$ pipx install tag-keeper        # or: uv tool install tag-keeper
+$ tag-keeper --help
+```
+
+Optional tools, each used only by the feature that needs it:
+
+| Tool | Used for |
+|---|---|
+| poppler-utils (`pdftotext`, `pdftoppm`) | reading PDFs for inbox suggestions |
+| [ollama](https://ollama.com/) | inbox suggestions |
+| btrfs and snapper | version history, and snapshots around plans |
+| OneDrive client for Linux | coordinating big deletions with the sync |
+
+From source:
+
+```console
+$ git clone https://github.com/akivajp/tag-keeper.git
+$ cd tag-keeper
+$ uv run tag-keeper --help
+$ uv run --extra dev pytest
+```
+
+## Configuration
+
+Optional. `~/.config/tag-keeper/config.toml`:
+
+```toml
+[[roots]]
+name = "onedrive"
+path = "~/CloudSync/OneDrive"
+exclude = ["*.partial"]              # never scanned (glob on the path relative to the root)
+
+[hygiene]
+allow = ["archive/**"]               # never reported ("I decided to keep these")
+device_names = ["zefat", "hermon"]   # suffixes your sync client adds to conflict copies
+app_data_names = ["MyLauncher"]      # extra folder names to treat as application data
+
+[safety]
+mass_missing_ratio = 0.2             # hold deletions when more than this share vanishes
+mass_missing_min = 100
+
+[plan]
+quarantine_dir = "~/.local/share/tag-keeper/quarantine"  # must be on the root's filesystem
+snapper_config = "home"              # snapper config for pre/post snapshots ("" = none)
+```
+
+Per root, for coordinating with a sync client:
+
+```toml
+[[roots]]
+name = "onedrive"
+path = "~/CloudSync/OneDrive"
+sync_client = "onedrive"             # "" (default) = no coordination
+sync_service = "onedrive.service"    # the systemd --user unit running `onedrive --monitor`
+sync_guard = "auto"                  # "auto": only for big deletions / "always": every run
+```
+
+Tags and inbox suggestions:
+
+```toml
+[tags]
+dir = "~/.local/share/tag-keeper/tags"   # where the per-machine tag logs live
+
+[organize]
+inbox_patterns = ["tmp", "temp", "*未整理*", "*inbox*"]  # case-insensitive globs on folder names
+ollama_url = "http://127.0.0.1:11434"
+model = "gemma3:12b"                     # e.g. "gemma4:31b-cloud" (content is sent to ollama's cloud)
+vision_model = ""                        # model for images when `model` cannot read them
+model_choices = ["gemma4:31b-cloud"]     # extra models offered on the page
+think = ""                               # "true" / "false" for thinking models; "" = model default
+use_images = true
+max_chars = 4000                         # text passed to the model
+candidates = 15                          # destination folders the model chooses from
+```
+
+With roots configured, `tag-keeper scan` (no arguments) scans all of them.
+Every command accepts `--log-file PATH` to keep a timestamped log.
+
+## Roadmap
+
+1. **Inventory and hygiene report**, and tidy-up plans that quarantine what you approve,
+   with snapper snapshots and undo. *(done)*
+2. **Tags and search** — *partly done:* tags inherited from folders in append-only logs, a
+   file browser, version history across moves. *Next:* aliases and parents, typed fields,
+   search by tag, name and content.
+3. **Content extraction** — *partly done:* text from PDF and Office files, images through a
+   local model, for inbox suggestions. *Next:* OCR and transcripts for full-text search.
+4. **Placement and structure** — *partly done:* name and folder suggestions for inbox files.
+   *Next:* directory cards, structure review.
+
+## License
+
+MIT

tag_keeper-0.1.0/README.ja.md

@@ -0,0 +1,243 @@
+# tag-keeper
+
+既存のフォルダ構造を動かさずに、外側からタグ付け・検索・整理を行うツールです。
+
+[English README](README.md)
+
+> **状況: プレアルファ版。** 今動くのは、棚卸し（走査・内容ハッシュ・衛生レポート）、
+> 承認した整理プランによる片付け（取り消し可能）、タグと btrfs スナップショットの版の履歴つきのファイルブラウザ、
+> 手元のモデルによる受け皿のファイルの名前と移動先の提案です。検索とタグの残りはこれから作ります。
+> [ロードマップ](#ロードマップ) を参照してください。
+
+## なぜ作るのか
+
+多くの文書管理ソフトは、ファイルを取り込んで自分の保管場所に一律に並べ直します。
+これは、クラウドドライブの実際の使い方と正反対です。フォルダには既に意味があります
+（番号付きの案件フォルダ、独自の構成を持つソースコードのリポジトリ、年月で分けた保管庫など）。
+その意味はフォルダごとに決まっていて、全体共通のカテゴリでは表せません。
+
+tag-keeper はツリーに手を付けません。ツリーの外に自分の台帳（カタログ）を持ち、そこからツリーをきれいに保つ手助けをします。
+
+- **ファイルを取り込まない。** コピー・改名・変換をしません。ファイラーやシェルはこれまでどおり使えます。
+- **ツールの外での操作に追従する。** 移動・改名したファイルも、記録を引き継ぎます。
+- **変更は提案として出す。** ファイルを動かす操作はプランとして書き出し、先に示して、承認されてから実行します。
+  削除はしません。隔離フォルダへ移すだけで、プランごとに取り消せます。
+
+## 今できること
+
+```console
+$ tag-keeper scan ~/CloudSync/OneDrive     # 読み取り専用で走査し、カタログを更新する
+$ tag-keeper hash ~/CloudSync/OneDrive     # 前回から変わったファイルだけ SHA-256 を計算する
+$ tag-keeper report ~/CloudSync/OneDrive   # クラウドに置く価値が薄そうなものを報告する
+```
+
+- **scan** は、すべてのファイルとフォルダのパス・サイズ・更新日時・inode を記録します。
+  移動・改名は inode で追跡するので、動かしたファイルも行（とハッシュ）を引き継ぎます。
+  - **安全弁:** 一度に多くのファイルが消えたように見えたら（ドライブのマウントが外れた、同期クライアントの事故など）、
+    削除として記録せずに**保留**します。次の走査でも見えなければ記録します（`--accept-missing` で即時に記録）。
+  - ルートが存在しないか空なら、「全部消えた」と扱わずに走査を止めます。読めなかったフォルダの中身も、消えたとは扱いません。
+- **hash** は、新しいファイルと変わったファイルだけ SHA-256 を計算します（進捗バーと残り時間を表示）。
+  計算の途中で変わったファイルは飛ばします。
+- **report** は、候補をカテゴリごとに、容量と例を添えて一覧します。
+  - 同期フォルダに入り込んだアプリのデータ（ゲームのデータ、キャッシュ）。フォルダ単位で1件として報告し、
+    条件に合う最も深いフォルダを選ぶので、隣にある利用者の書類まで巻き込みません
+  - 作り直せる生成物（`node_modules`、`__pycache__` など）、仮想マシンのディスク、インストーラーとディスクイメージ、
+    一時ファイル、Office のロックファイル
+  - 同期の競合コピー（Linux 版 onedrive クライアントの `-safeBackup-`、pCloud の `[conflicted]`、
+    rclone bisync の `.conflict1`、端末名の付いたもの、`(1)` 付きの複製）。同じフォルダに元のファイルがあるものだけです
+    （元が無ければ、それが唯一の版かもしれないため）。元と内容が異なるものには「中身の確認が必要」と付けます
+  - 空のファイルとフォルダ
+  - 内容が同じファイル（ハッシュで確定したものだけ。サイズからの推測では報告しません）
+
+カタログはツリーの外の SQLite ファイルです（既定は `~/.local/share/tag-keeper/catalog.db`）。
+ここまでのコマンドは、ツリーに何も書き込みません。
+
+### 整理プランで片付ける
+
+```console
+$ tag-keeper plan onedrive                  # 報告の候補をプランのファイルに書き出す
+$ $EDITOR ~/.local/share/tag-keeper/plans/<プラン ID>.toml   # 残したいものの行を消す
+$ tag-keeper apply <プランのファイル>        # 確認だけ
+$ tag-keeper apply <プランのファイル> --yes  # 隔離フォルダへ移す
+$ tag-keeper undo <プラン ID> --yes         # すべて元に戻す
+```
+
+- **plan** は、1件を1行にして、カテゴリごとにまとめて書き出します。`--category` でカテゴリを絞れます
+  （`app-data`、`vm-image`、`conflict` など）。中身の確認が要る候補は、`--include-review` を付けたときだけ含めます。
+- **apply** は、既定では確認だけです。`--yes` を付けると、各対象を `<quarantine_dir>/<プラン ID>/` の下へ、
+  元の相対パスのまま改名で移します。移す直前に、プランの作成時から変わっていないか
+  （inode・サイズ・更新日時、フォルダなら配下のファイル数と合計サイズも）を確かめ、変わっていれば飛ばして報告します。
+- `snapper_config` を設定すると、実行の前に snapper の pre スナップショット、後に post スナップショットを撮ります。
+  pre を撮れなければ、何も動かしません。
+- 移した操作は、すべて実行記録（`~/.local/share/tag-keeper/journal/<プラン ID>.jsonl`）に追記します。
+  **undo** はこの記録をもとに元へ戻します。元の場所に新しく別のものができていれば、上書きせずに飛ばします。
+- 移すたびにカタログも更新するので、大量に隔離しても、次の走査で大量消失と誤認しません。
+- 同期クライアントが消えたことに気付けば、クラウドからは消えます。ただし、隔離フォルダを自分で空にするまでは、このディスクに残ります。
+
+### 大量の削除で同期を止めない
+
+[Linux 版 onedrive クライアント](https://github.com/abraunegg/onedrive)は、子の多いフォルダ
+（`classify_as_big_delete`、既定 1000 件）がローカルで消えると事故とみなし、同期をやめて終了します。
+systemd で常駐させていると再起動のたびに同じ理由で終了するので、気付かないうちに同期が止まります。
+利用者が承認した大量の削除では、tag-keeper が同期クライアントと連携します（ルートに `sync_client = "onedrive"` を設定）。
+
+1. 常駐の同期を止める（`systemctl --user stop onedrive.service`）
+2. 隔離する
+3. `onedrive --sync` を1回だけ、しきい値を「このプランで一番大きいフォルダ」より少し上に上げて実行し、削除をクラウドに反映する。
+   `--force` は使いません（関係のない事故まで通してしまうため）
+4. 常駐の同期を再開する
+
+3 が失敗したら、常駐の同期は止めたままにします（再開しても同じ理由で終了を繰り返すため）。
+失敗は実行記録に残り、Web の画面か `tag-keeper sync <プラン ID> --retry` から再試行できます。
+小さなプランでは連携せず、動いている同期クライアントにそのまま任せます。
+
+## Web の画面
+
+```console
+$ tag-keeper serve                  # http://127.0.0.1:8090/
+```
+
+ここまでの操作は、すべてブラウザからできます。ルートを最新にする（走査とハッシュ計算）、レポートを見る、
+プランを作る、残したいもののチェックを外す、確認する、実行する、取り消す。
+時間のかかる処理は裏で動き、画面の下に、段階・進捗バー・速さ・残り時間・直近のログを表示します。スマートフォンでも使えます。
+
+- 既定ではループバックだけで待ち受けます。他のアドレス（Tailscale のアドレスなど）で待ち受けるには、
+  BASIC 認証の資格情報を `--auth-file`（`user:password` の1行）か `TAG_KEEPER_AUTH` で渡してください。
+  渡さなければ、`--allow-no-auth` を付けない限り起動しません。BASIC 認証は暗号化しないので、
+  Tailscale などの VPN 越しか、TLS の後ろで使ってください。
+- 書き込みは同一オリジンからだけ受け付けます。認証なしのときは、Host ヘッダが待ち受けているアドレスであることも確かめます（DNS リバインディング対策）。
+- 同時に動かす処理は1つだけです。処理ごとのログは `~/.local/share/tag-keeper/logs/jobs/` にも残ります。
+
+### ファイル・タグ・版の履歴
+
+- **ファイルブラウザ**: ルートの中をフォルダごとにたどり、PDF・画像・音声・動画・テキストを画面の中でプレビューし、何でもダウンロードできます。
+  画面の中で開くのはスクリプトを実行しない種類だけで、HTML や SVG はテキストとして見せ、それ以外はダウンロードにします。
+  シンボリックリンクを含め、ルートの外には出ません。
+- **タグ**: ファイルブラウザから、ファイルやフォルダにタグを付け外しできます。フォルダのタグは配下に継承されます。
+  タグは端末ごとの追記専用の JSONL（`~/.local/share/tag-keeper/tags/<ホスト名>.jsonl`）に記録するので、
+  ツールが無くても読め、同期しても競合しません。タグの付いたものが（手作業でもプランでも）動いたら、移動を記録してタグを追従させます。
+- **版の履歴**: [btrfs-timeline](https://github.com/akivajp/btrfs-timeline) を使い、btrfs のスナップショットから、
+  ファイルの版の一覧、過去のある時点のフォルダの中身（今は消えたものを含む）を見られます。
+  過去の版は、今のファイルの隣に日時付きの別名で復元します（上書きしません）。
+  tag-keeper が見た移動・改名を記録しているので、移動・改名の前の版もたどれます。
+
+### 受け皿の整理の提案
+
+名前が `inbox_patterns`（既定は `tmp`・`temp`・`*未整理*`・`*inbox*`）に一致するフォルダを受け皿とみなします。
+「整理」の画面に、受け皿の中のファイルをフォルダの階層なしで並べます。ファイルを選ぶと、
+[ollama](https://ollama.com/) のモデルが内容を読み（PDF や Office 文書は文字、写真やスキャンの PDF は画像そのもの）、
+多くは数秒で次を提案します。
+
+- 名前: 既定は `YYYYMMDD_題名`。過去の判断や、移動先のフォルダの日付の付け方に合わせ、意味のある今の名前は尊重します
+- 移動先: 既存のフォルダから最大3つ。各フォルダのパスと中のファイル名の文字の2文字組（TF-IDF）で候補を絞ってから、モデルが選びます。
+  年・月のフォルダは、書類の日付の年・月に置き換えます
+- タグ: 既に使っているタグを優先します。新しいタグには「新規」と付けます
+
+選んだファイルは待ち行列の先頭に割り込み、次の2件は先読みします。採用した提案は採用リストにたまり、
+1つの「移動・改名」のプランとして実行するか（スナップショットと取り消しつき）、プランとして保存して確かめてから実行します。
+受け皿の外のファイルは、ファイルブラウザで頼んだときだけ提案を作ります。
+
+**判断から学ぶ仕組み**: 採用したもの（提案と最終的な名前・移動先・タグ）、提案されたタグを付けた・却下したこと、取り消したプランを、
+端末ごとの JSONL（`~/.local/share/tag-keeper/decisions/`）に追記します。受け皿から手作業で移したものも例に使います。
+提案を作るときは、似た過去の判断を例として指示文に添え、その移動先を候補に入れます。何度も却下したタグは使わせません。
+ログは提案と判断が対になっているので、そのまま学習データとして書き出せます。
+
+**モデル**: 既定は手元のモデルです。画面や設定で ollama のどのモデルも選べ、ollama のクラウドのモデル（`…:cloud`・`…-cloud`）も使えます。
+その場合、ファイルの内容は ollama のクラウドに送られます。画面ではクラウドのモデルに ☁ を付けます。
+提案は内容ハッシュとモデルごとに保存するので、同じファイルを同じモデルで読むのは1回だけです。
+
+## インストール
+
+Python 3.11 以上と Linux が必要です。画面とメッセージは日本語です。
+
+```console
+$ pipx install tag-keeper        # または: uv tool install tag-keeper
+$ tag-keeper --help
+```
+
+次の道具は任意で、それぞれ必要な機能でだけ使います。
+
+| 道具 | 使う機能 |
+|---|---|
+| poppler-utils（`pdftotext`・`pdftoppm`） | 受け皿の整理の提案での PDF の読み取り |
+| [ollama](https://ollama.com/) | 受け皿の整理の提案 |
+| btrfs と snapper | 版の履歴、プランの実行前後のスナップショット |
+| Linux 版 onedrive クライアント | 大量の削除での同期との連携 |
+
+ソースから使う場合:
+
+```console
+$ git clone https://github.com/akivajp/tag-keeper.git
+$ cd tag-keeper
+$ uv run tag-keeper --help
+$ uv run --extra dev pytest
+```
+
+## 設定
+
+任意です。`~/.config/tag-keeper/config.toml`:
+
+```toml
+[[roots]]
+name = "onedrive"
+path = "~/CloudSync/OneDrive"
+exclude = ["*.partial"]              # 走査しない（ルートからの相対パスに対する glob）
+
+[hygiene]
+allow = ["archive/**"]               # 報告しない（「残す」と判断したもの）
+device_names = ["zefat", "hermon"]   # 同期クライアントが競合コピーに付ける端末名
+app_data_names = ["MyLauncher"]      # 既定に加えて、アプリのデータとみなすフォルダ名
+
+[safety]
+mass_missing_ratio = 0.2             # これを超える割合が消えたら、削除の記録を保留する
+mass_missing_min = 100
+
+[plan]
+quarantine_dir = "~/.local/share/tag-keeper/quarantine"  # ルートと同じファイルシステムに置く
+snapper_config = "home"              # 前後のスナップショットを撮る snapper の設定名（"" で撮らない）
+```
+
+同期クライアントとの連携は、ルートごとに設定します。
+
+```toml
+[[roots]]
+name = "onedrive"
+path = "~/CloudSync/OneDrive"
+sync_client = "onedrive"             # ""（既定）なら連携しない
+sync_service = "onedrive.service"    # `onedrive --monitor` を動かしている systemd --user のユニット
+sync_guard = "auto"                  # "auto": 大量削除のときだけ / "always": 実行のたびに
+```
+
+タグと受け皿の整理の提案:
+
+```toml
+[tags]
+dir = "~/.local/share/tag-keeper/tags"   # 端末ごとのタグのログの置き場所
+
+[organize]
+inbox_patterns = ["tmp", "temp", "*未整理*", "*inbox*"]  # フォルダ名に照合する（大文字・小文字を区別しない）
+ollama_url = "http://127.0.0.1:11434"
+model = "gemma3:12b"                     # 例: "gemma4:31b-cloud"（内容が ollama のクラウドに送られる）
+vision_model = ""                        # model が画像を読めないときに、画像を読むモデル
+model_choices = ["gemma4:31b-cloud"]     # 画面で選べるモデルの候補
+think = ""                               # 思考に対応したモデルで "true" / "false"。空ならモデルに任せる
+use_images = true
+max_chars = 4000                         # モデルに渡す本文の上限
+candidates = 15                          # モデルに選ばせる移動先の候補の数
+```
+
+ルートを設定しておけば、`tag-keeper scan`（引数なし）で全ルートを走査します。
+どのコマンドも `--log-file PATH` で日時付きのログを残せます。
+
+## ロードマップ
+
+1. **棚卸しと衛生レポート**、承認したものを隔離する整理プラン（snapper のスナップショットと取り消しつき）（済み）
+2. **タグと検索** — 済み: フォルダから継承するタグ（追記専用ログ）、ファイルブラウザ、移動をまたぐ版の履歴。
+   これから: タグの別名・親子、型付きの属性、タグ・名前・内容による検索
+3. **内容の抽出** — 済み: 受け皿の提案のための PDF・Office 文書の文字と、手元のモデルによる画像の読み取り。
+   これから: 全文検索のための OCR と書き起こし
+4. **配置と構造** — 済み: 受け皿のファイルの名前と移動先の提案。これから: ディレクトリカード、構造の見直し
+
+## ライセンス
+
+MIT