agent-folder-workspace 0.1.2__tar.gz → 0.1.4__tar.gz

{agent_folder_workspace-0.1.2 → agent_folder_workspace-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-folder-workspace
-Version: 0.1.2
+Version: 0.1.4
 Summary: Offline, lazy, agent-oriented exploration of heterogeneous folders
 Author-email: Dark Light <darklight@noreply.com>
 License-Expression: Apache-2.0
@@ -37,7 +37,7 @@ hierarchies for agents. It discovers file metadata first and opens document
 bodies only when a caller expands or reads a node. The default parser path is
 local Python code: Microsoft Office and LibreOffice are not required.
 
-> **Project status:** `0.1.2` is an alpha contract. Read-only exploration and
+> **Project status:** `0.1.4` is an alpha contract. Read-only exploration and
 > byte access are implemented; editing, rendering, OCR, and complete semantic
 > coverage of every supported container are not.
 
@@ -91,7 +91,7 @@ adapters, and caching:
 4. Parser workers block Python socket/DNS entry points before importing risky
    adapters and enforce one deadline across startup, queueing, IPC, and parsing.
 5. `SizedLru` retains bounded decoded pages in memory. `ContentIndex` stores an
-   optional per-workspace SQLite search index in the application cache.
+   optional SQLite search index in each workspace's owned local cache.
 6. `WorkspaceManager` gives one FastMCP process a bounded registry of active and
    explicitly addressed workspace roots.
 7. The Python API, Typer CLI, and FastMCP stdio server share the same workspace
@@ -175,9 +175,15 @@ The server exposes exactly these tools:
 - `probe_backends`
 
 `open_workspace(path)` accepts an explicit absolute directory, returns an opaque,
-process-lifetime `workspace_id`, and makes that workspace active. Existing tools
-accept an optional `workspace_id`; omission uses the active workspace. Opening
-the same canonical root again reuses its ID. `list_workspaces`,
+process-lifetime `workspace_id`, and makes that workspace active. The compatible
+extended form `open_workspace(path, cache_directory=None)` accepts an optional
+absolute cache directory for that document basis. Without it, MCP checks for and
+reuses an existing owned cache at
+`path/.agent-folder-workspace-cache`; a foreign directory with that name is
+rejected. The selected path is returned as `workspace_info.cache_directory`.
+Existing tools accept an optional `workspace_id`; omission uses the active
+workspace. Opening the same canonical root again reuses its ID; attempting to
+reopen it with a different cache returns an input error. `list_workspaces`,
 `activate_workspace`, and `close_workspace` manage the registry. One process
 holds at most eight workspaces and never evicts one silently.
 
@@ -221,7 +227,7 @@ folderws doctor --probe-office --json --timeout-seconds 10
 # Build the complete semantic content index
 folderws index --root DIR
 
-# Remove only the selected application cache tree
+# Remove the current document directory's owned cache, or an explicit cache
 folderws clear-cache [--cache-dir PATH]
 
 # Materialize the bundled, managed OpenCode skill and plugin
@@ -236,9 +242,10 @@ two ownership-marked resources atomically and always refuses foreign files,
 symbolic links, and Windows reparse points. The compatibility `--force` flag
 never bypasses ownership checks.
 
-`clear-cache` removes only a non-link directory containing the package's cache
-ownership marker; an arbitrary directory supplied through `--cache-dir` is
-refused.
+Without `--cache-dir`, `clear-cache` selects
+`./.agent-folder-workspace-cache`. It removes only a non-link directory
+containing the package's cache ownership marker; an arbitrary directory
+supplied through `--cache-dir` is refused.
 
 ## Lazy loading and cache
 
@@ -270,13 +277,16 @@ Decoded `ContentPageV1` values use a byte-sized in-memory LRU capped by
 best-effort basis. `index_content()` performs a full supported semantic walk
 without retaining all decoded bodies in RAM.
 
-The persistent index is an application-owned SQLite database below the
-platform cache directory, separated by a hash of the workspace root. It uses
-FTS5 when available and a plain-table fallback otherwise. `max_disk_cache_bytes`
-is checked after read-through chunks and completed files; least-recently-used
-indexed files are evicted and SQLite WAL/database pages are compacted. Embedded
-and alternative views enforce the same application-cache budget at their own
-materialization boundaries.
+The persistent index is an application-owned SQLite database below
+`WORKSPACE_ROOT/.agent-folder-workspace-cache`, separated by a hash of the
+workspace root. Existing owned caches are reused, while the cache subtree is
+excluded from document discovery. `WorkspaceConfig.cache_directory` and MCP's
+optional `cache_directory` argument can select another cache root explicitly.
+The index uses FTS5 when available and a plain-table fallback otherwise.
+`max_disk_cache_bytes` is checked after read-through chunks and completed
+files; least-recently-used indexed files are evicted and SQLite WAL/database
+pages are compacted. Embedded and alternative views enforce the same cache
+budget at their own materialization boundaries.
 Read-through index failures do not make an otherwise successful content read
 fail. Embedded mounting, by contrast, requires a writable bounded cache. Use
 `folderws clear-cache` to remove an explicitly selected cache tree safely.
@@ -308,8 +318,8 @@ successfully discovered file has been indexed. The affected directory node is
 Optional conversion is performed by a timeout-bounded child Python process.
 The result is verified as OOXML and mounted through the normal OOXML adapter.
 Its cache key includes the backend, adapter version, and SHA-256 of the source,
-and both conversion scratch and the retained result stay below the
-`platformdirs` per-workspace application cache rather than `%TEMP%` or `/tmp`.
+and both conversion scratch and the retained result stay below the selected
+workspace cache rather than `%TEMP%` or `/tmp`.
 Microsoft automation disables macros, UI, events, external-link updates, and
 recent-file writes where the application API exposes those controls.
 LibreOffice uses a disposable cache-local profile, headless/safe-mode flags,
@@ -324,6 +334,9 @@ documents and does not execute document macros. Important controls include:
 - roots that are symbolic links or reparse points are rejected;
 - external roots are opened only by an explicit `open_workspace` call, are
   bounded to eight per process, and receive process-lifetime opaque IDs;
+- workspace caches default to an owned `.agent-folder-workspace-cache` below
+  the selected root, are excluded from source discovery, and can be overridden
+  only with an explicit absolute MCP path;
 - child links are not followed by default, and resolved sources must remain
   under the selected root;
 - SQLite files are opened with `mode=ro` and `PRAGMA query_only=ON`;
@@ -410,7 +423,7 @@ The detailed coverage and per-format caveats are in
   rendering. A hard parent timeout cannot guarantee cleanup of a vendor process
   that is itself stuck below COM or LibreOffice process control.
 - The stated 100,000-node and warm p95 performance figures are design targets,
-  not certified guarantees in `0.1.2`; CI covers correctness across Windows,
+  not certified guarantees in `0.1.4`; CI covers correctness across Windows,
   Linux, and macOS but does not emulate a specific Windows-x64 SSD workload.
 
 ## Development

{agent_folder_workspace-0.1.2 → agent_folder_workspace-0.1.4}/README.md

@@ -5,7 +5,7 @@ hierarchies for agents. It discovers file metadata first and opens document
 bodies only when a caller expands or reads a node. The default parser path is
 local Python code: Microsoft Office and LibreOffice are not required.
 
-> **Project status:** `0.1.2` is an alpha contract. Read-only exploration and
+> **Project status:** `0.1.4` is an alpha contract. Read-only exploration and
 > byte access are implemented; editing, rendering, OCR, and complete semantic
 > coverage of every supported container are not.
 
@@ -59,7 +59,7 @@ adapters, and caching:
 4. Parser workers block Python socket/DNS entry points before importing risky
    adapters and enforce one deadline across startup, queueing, IPC, and parsing.
 5. `SizedLru` retains bounded decoded pages in memory. `ContentIndex` stores an
-   optional per-workspace SQLite search index in the application cache.
+   optional SQLite search index in each workspace's owned local cache.
 6. `WorkspaceManager` gives one FastMCP process a bounded registry of active and
    explicitly addressed workspace roots.
 7. The Python API, Typer CLI, and FastMCP stdio server share the same workspace
@@ -143,9 +143,15 @@ The server exposes exactly these tools:
 - `probe_backends`
 
 `open_workspace(path)` accepts an explicit absolute directory, returns an opaque,
-process-lifetime `workspace_id`, and makes that workspace active. Existing tools
-accept an optional `workspace_id`; omission uses the active workspace. Opening
-the same canonical root again reuses its ID. `list_workspaces`,
+process-lifetime `workspace_id`, and makes that workspace active. The compatible
+extended form `open_workspace(path, cache_directory=None)` accepts an optional
+absolute cache directory for that document basis. Without it, MCP checks for and
+reuses an existing owned cache at
+`path/.agent-folder-workspace-cache`; a foreign directory with that name is
+rejected. The selected path is returned as `workspace_info.cache_directory`.
+Existing tools accept an optional `workspace_id`; omission uses the active
+workspace. Opening the same canonical root again reuses its ID; attempting to
+reopen it with a different cache returns an input error. `list_workspaces`,
 `activate_workspace`, and `close_workspace` manage the registry. One process
 holds at most eight workspaces and never evicts one silently.
 
@@ -189,7 +195,7 @@ folderws doctor --probe-office --json --timeout-seconds 10
 # Build the complete semantic content index
 folderws index --root DIR
 
-# Remove only the selected application cache tree
+# Remove the current document directory's owned cache, or an explicit cache
 folderws clear-cache [--cache-dir PATH]
 
 # Materialize the bundled, managed OpenCode skill and plugin
@@ -204,9 +210,10 @@ two ownership-marked resources atomically and always refuses foreign files,
 symbolic links, and Windows reparse points. The compatibility `--force` flag
 never bypasses ownership checks.
 
-`clear-cache` removes only a non-link directory containing the package's cache
-ownership marker; an arbitrary directory supplied through `--cache-dir` is
-refused.
+Without `--cache-dir`, `clear-cache` selects
+`./.agent-folder-workspace-cache`. It removes only a non-link directory
+containing the package's cache ownership marker; an arbitrary directory
+supplied through `--cache-dir` is refused.
 
 ## Lazy loading and cache
 
@@ -238,13 +245,16 @@ Decoded `ContentPageV1` values use a byte-sized in-memory LRU capped by
 best-effort basis. `index_content()` performs a full supported semantic walk
 without retaining all decoded bodies in RAM.
 
-The persistent index is an application-owned SQLite database below the
-platform cache directory, separated by a hash of the workspace root. It uses
-FTS5 when available and a plain-table fallback otherwise. `max_disk_cache_bytes`
-is checked after read-through chunks and completed files; least-recently-used
-indexed files are evicted and SQLite WAL/database pages are compacted. Embedded
-and alternative views enforce the same application-cache budget at their own
-materialization boundaries.
+The persistent index is an application-owned SQLite database below
+`WORKSPACE_ROOT/.agent-folder-workspace-cache`, separated by a hash of the
+workspace root. Existing owned caches are reused, while the cache subtree is
+excluded from document discovery. `WorkspaceConfig.cache_directory` and MCP's
+optional `cache_directory` argument can select another cache root explicitly.
+The index uses FTS5 when available and a plain-table fallback otherwise.
+`max_disk_cache_bytes` is checked after read-through chunks and completed
+files; least-recently-used indexed files are evicted and SQLite WAL/database
+pages are compacted. Embedded and alternative views enforce the same cache
+budget at their own materialization boundaries.
 Read-through index failures do not make an otherwise successful content read
 fail. Embedded mounting, by contrast, requires a writable bounded cache. Use
 `folderws clear-cache` to remove an explicitly selected cache tree safely.
@@ -276,8 +286,8 @@ successfully discovered file has been indexed. The affected directory node is
 Optional conversion is performed by a timeout-bounded child Python process.
 The result is verified as OOXML and mounted through the normal OOXML adapter.
 Its cache key includes the backend, adapter version, and SHA-256 of the source,
-and both conversion scratch and the retained result stay below the
-`platformdirs` per-workspace application cache rather than `%TEMP%` or `/tmp`.
+and both conversion scratch and the retained result stay below the selected
+workspace cache rather than `%TEMP%` or `/tmp`.
 Microsoft automation disables macros, UI, events, external-link updates, and
 recent-file writes where the application API exposes those controls.
 LibreOffice uses a disposable cache-local profile, headless/safe-mode flags,
@@ -292,6 +302,9 @@ documents and does not execute document macros. Important controls include:
 - roots that are symbolic links or reparse points are rejected;
 - external roots are opened only by an explicit `open_workspace` call, are
   bounded to eight per process, and receive process-lifetime opaque IDs;
+- workspace caches default to an owned `.agent-folder-workspace-cache` below
+  the selected root, are excluded from source discovery, and can be overridden
+  only with an explicit absolute MCP path;
 - child links are not followed by default, and resolved sources must remain
   under the selected root;
 - SQLite files are opened with `mode=ro` and `PRAGMA query_only=ON`;
@@ -378,7 +391,7 @@ The detailed coverage and per-format caveats are in
   rendering. A hard parent timeout cannot guarantee cleanup of a vendor process
   that is itself stuck below COM or LibreOffice process control.
 - The stated 100,000-node and warm p95 performance figures are design targets,
-  not certified guarantees in `0.1.2`; CI covers correctness across Windows,
+  not certified guarantees in `0.1.4`; CI covers correctness across Windows,
   Linux, and macOS but does not emulate a specific Windows-x64 SSD workload.
 
 ## Development

{agent_folder_workspace-0.1.2 → agent_folder_workspace-0.1.4}/docs/architecture.md

@@ -18,7 +18,7 @@ flowchart LR
     Workspace --> Index["ContentIndex SQLite cache"]
     Registry --> Files["Selected local root"]
     Adapters --> Files
-    Index --> Cache["Platform application cache"]
+    Index --> Cache["Workspace-local owned cache"]
     CLI["folderws doctor --probe-office --json"] --> Probe["Isolated backend probe worker"]
     Probe --> Apps["Office COM or LibreOffice"]
 ```
@@ -143,9 +143,13 @@ offset, limit, and representation. It estimates serialized page bytes and
 evicts least-recently-used values until `max_content_cache_bytes` is respected.
 The cache disappears with the workspace process or refresh.
 
-`ContentIndex` is created on first content-index/search use beneath the
-platform-specific `agent-folder-workspace` cache directory. Each root gets a
-directory named with a truncated SHA-256 of the normalized absolute root. The
+`ContentIndex` is created on first content-index/search use beneath
+`WORKSPACE_ROOT/.agent-folder-workspace-cache` by default. Each root gets a
+directory named with a truncated SHA-256 of the normalized absolute root. An
+existing owned cache is reused; a same-named directory without the ownership
+marker is rejected, and `NodeRegistry` excludes the cache subtree from source
+discovery. An explicit `WorkspaceConfig.cache_directory` or MCP
+`open_workspace(..., cache_directory=...)` selects another cache root. The
 index records relative path, modification time, size, completion, content byte
 count, and last access. Synchronization removes entries whose source metadata
 changed.
@@ -159,7 +163,7 @@ filesystem inventory. If any directory scan failed, the unknown denominator
 forces `coverage=0` and `complete=false`; the partial directory node contains a
 `directory_scan_failed` diagnostic.
 
-After every read-through chunk and completed file, the physical application
+After every read-through chunk and completed file, the physical workspace
 cache size is checked. Least-recently-used indexed files are evicted and the
 SQLite WAL/database is checkpointed and compacted. Embedded and optional
 alternative materializers separately check the same total cache root before
@@ -181,7 +185,7 @@ replaces a hash-derived target. The target is accepted only below a cache path
 whose relevant components are not symbolic links.
 
 `max_embedded_depth` and `max_embedded_files` bound recursive mounts per
-workspace. `max_disk_cache_bytes` accounts for the application cache before a
+workspace. `max_disk_cache_bytes` accounts for the selected cache before a
 new materialization and evicts inactive derived files by modification time;
 materializations in active use are protected. The target retains only the
 embedded suffix, while node metadata records nested adapter path, depth, and
@@ -200,6 +204,11 @@ workspace ID and otherwise route to the active root. Its capability dispatcher
 resolves workspace methods at call time so reduced injected implementations
 return a structured `capability_unavailable` error.
 
+`open_workspace` also accepts an optional absolute `cache_directory`. Omission
+uses and validates the fixed workspace-local cache; an explicit path belongs
+only to the new workspace. Reopening a live root with a conflicting cache is
+rejected rather than migrating active indexes or materialized nodes.
+
 MCP tool boundaries translate public workspace errors to stable error codes and
 sanitize unexpected failures behind a correlation ID. This leaves the stdio
 transport usable for a later request. Risky PDF and container semantics remain

{agent_folder_workspace-0.1.2 → agent_folder_workspace-0.1.4}/docs/formats.md

@@ -67,6 +67,12 @@ package/attachment roles, and mounted semantic content is not included in the
 outer format's default full-index branches. Cached copies can outlive a
 workspace instance until eviction or `folderws clear-cache`.
 
+By default, indexes and derived copies live below
+`WORKSPACE_ROOT/.agent-folder-workspace-cache`. The owned directory is excluded
+from the document inventory, so split or converted artifacts do not reappear
+as source files. `WorkspaceConfig.cache_directory` or MCP's optional absolute
+`cache_directory` can select a different cache for one document basis.
+
 ## Resource controls
 
 Defaults from `WorkspaceConfig` that have active enforcement paths include:

agent_folder_workspace-0.1.4/docs/superpowers/plans/2026-07-24-workspace-local-cache.md

@@ -0,0 +1,300 @@
+# Workspace-Local Cache Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Store split and derived document data in an owned cache beside each document basis by default and let MCP choose an absolute cache path per newly opened workspace.
+
+**Architecture:** Resolve every real `FolderWorkspace` to one explicit cache root during open, defaulting to `WORKSPACE_ROOT/.agent-folder-workspace-cache`, and exclude that root from the source inventory. Extend `open_workspace` with one backward-compatible optional cache argument; validate and pass it through `WorkspaceManager`, while reporting the selected cache in `WorkspaceInfoV1`.
+
+**Tech Stack:** Python 3.11-3.14, Pydantic v2, FastMCP, pytest, Ruff, strict Mypy, Hatchling/build, Twine.
+
+---
+
+### Task 1: Cache path resolution and source-inventory exclusion
+
+**Files:**
+- Modify: `src/agent_folder_workspace/cache.py`
+- Modify: `src/agent_folder_workspace/workspace.py`
+- Modify: `src/agent_folder_workspace/registry.py`
+- Modify: `src/agent_folder_workspace/installer.py`
+- Modify: `src/agent_folder_workspace/cli.py`
+- Modify: `tests/test_search_cache.py`
+- Modify: `tests/test_mcp_cli_installer.py`
+
+- [ ] **Step 1: Write failing default, reuse, collision, and exclusion tests**
+
+Add tests that open a real workspace and assert:
+
+```python
+expected = root / ".agent-folder-workspace-cache"
+assert workspace.config.cache_directory == expected
+assert workspace.workspace_info().cache_directory == str(expected)
+```
+
+Create an owned `expected` directory with `.agent-folder-workspace-cache-v1`, verify it is reused,
+and create an unowned collision to verify `FolderWorkspace.open` raises `InputValidationError`.
+After indexing, refresh and assert `.agent-folder-workspace-cache` is absent from the root node's
+children. Add a CLI test proving `clear-cache` defaults to the selected root's local cache.
+
+- [ ] **Step 2: Run the focused tests and verify RED**
+
+Run:
+
+```console
+.venv/bin/python -m pytest tests/test_search_cache.py tests/test_mcp_cli_installer.py -q
+```
+
+Expected: failures because the current default uses `platformdirs`, `WorkspaceInfoV1` has no cache
+field, and the registry inventories a cache nested below the workspace.
+
+- [ ] **Step 3: Implement deterministic local cache resolution**
+
+In `cache.py`, add:
+
+```python
+DEFAULT_CACHE_DIRECTORY_NAME = ".agent-folder-workspace-cache"
+
+
+def default_cache_directory(workspace_root: Path) -> Path:
+    return workspace_root / DEFAULT_CACHE_DIRECTORY_NAME
+
+
+def validate_cache_directory(cache_root: Path, workspace_root: Path) -> Path:
+    ...
+```
+
+The validator returns a normalized absolute path, rejects link/reparse components, rejects a cache
+that equals or contains the workspace root, and requires the regular ownership marker when the
+target already exists. Missing targets remain lazy.
+
+Resolve `WorkspaceConfig.cache_directory` in `FolderWorkspace.open` before constructing the
+workspace. In `NodeRegistry`, normalize the configured cache path once and skip the exact matching
+entry during scans. Make `installer.default_cache_dir(root=Path("."))` return the same fixed local
+path and let `clear-cache` accept that resolved default through the CLI.
+
+- [ ] **Step 4: Run focused tests and verify GREEN**
+
+Run:
+
+```console
+.venv/bin/python -m pytest tests/test_search_cache.py tests/test_mcp_cli_installer.py -q
+```
+
+Expected: all selected tests pass.
+
+- [ ] **Step 5: Commit the cache slice**
+
+Stage the listed source and test files and commit through the repository commit policy with title
+`Store document caches beside sources`.
+
+### Task 2: Per-workspace MCP cache selection
+
+**Files:**
+- Modify: `src/agent_folder_workspace/models.py`
+- Modify: `src/agent_folder_workspace/workspace_manager.py`
+- Modify: `src/agent_folder_workspace/mcp_server.py`
+- Modify: `src/agent_folder_workspace/__init__.py`
+- Modify: `src/agent_folder_workspace/schemas/WorkspaceInfoV1.schema.json`
+- Modify: `src/agent_folder_workspace/schemas/WorkspaceHandleV1.schema.json`
+- Modify: `src/agent_folder_workspace/schemas/WorkspaceListV1.schema.json`
+- Modify: `tests/test_workspace_manager.py`
+- Modify: `tests/test_mcp_cli_installer.py`
+- Modify: `tests/test_contracts.py`
+
+- [ ] **Step 1: Write failing manager and MCP contract tests**
+
+Extend the fake factory to accept an optional `WorkspaceConfig` and record it. Prove:
+
+```python
+opened = manager.open_workspace(documents, cache_directory=cache)
+assert factory.configs[-1].cache_directory == cache
+```
+
+Add failures for relative cache paths and for reopening one root with a different cache. Assert the
+active workspace remains unchanged after failure. Inspect the FastMCP schema and assert
+`cache_directory` is optional on `open_workspace`, then call it and verify the returned
+`workspace_info.cache_directory`.
+
+- [ ] **Step 2: Run manager and MCP tests and verify RED**
+
+Run:
+
+```console
+.venv/bin/python -m pytest tests/test_workspace_manager.py tests/test_mcp_cli_installer.py -q
+```
+
+Expected: failures because `open_workspace` does not accept or route `cache_directory`.
+
+- [ ] **Step 3: Implement the optional cache argument**
+
+Change the manager method to:
+
+```python
+def open_workspace(
+    self,
+    path: str | Path,
+    cache_directory: str | Path | None = None,
+) -> WorkspaceHandleV1:
+    ...
+```
+
+Require an explicit cache to be absolute. When present, call the factory with
+`WorkspaceConfig(cache_directory=requested_cache)`; otherwise retain the single-argument factory
+call for compatibility. Compare the selected cache when the root is already open and reject
+conflicts with `InputValidationError`.
+
+Change the FastMCP handler to:
+
+```python
+@server.tool(name="open_workspace")
+def open_workspace(path: str, cache_directory: str | None = None) -> object:
+    return _call_safely(
+        lambda: workspace_manager.open_workspace(path, cache_directory=cache_directory)
+    )
+```
+
+Add `cache_directory: str | None = None` to `WorkspaceInfoV1` and populate it for real workspaces.
+Regenerate JSON schemas with `scripts/generate_json_schemas.py`.
+
+- [ ] **Step 4: Run focused tests and schema checks**
+
+Run:
+
+```console
+.venv/bin/python -m pytest tests/test_workspace_manager.py tests/test_mcp_cli_installer.py tests/test_contracts.py -q
+.venv/bin/python scripts/generate_json_schemas.py --check
+```
+
+Expected: all selected tests pass and all committed schemas are current.
+
+- [ ] **Step 5: Commit the MCP slice**
+
+Stage the listed source, schema, and test files and commit through the repository commit policy
+with title `Select cache paths per MCP workspace`.
+
+### Task 3: Documentation, version, and package assertions
+
+**Files:**
+- Modify: `README.md`
+- Modify: `docs/architecture.md`
+- Modify: `docs/formats.md`
+- Modify: `docs/windows.md`
+- Modify: `src/agent_folder_workspace/opencode/skill/SKILL.md`
+- Modify: `pyproject.toml`
+- Modify: `src/agent_folder_workspace/__init__.py`
+- Modify: `scripts/check_wheel.py`
+- Modify: `tests/test_distribution.py`
+
+- [ ] **Step 1: Write failing distribution assertions for version 0.1.3 and cache docs**
+
+Update distribution tests to require version `0.1.3` and the terms:
+
+```python
+for term in (
+    ".agent-folder-workspace-cache",
+    "cache_directory",
+    "existing owned cache",
+):
+    assert term in metadata.get_payload()
+```
+
+Update `scripts/check_wheel.py` to expect `0.1.3` and all currently exported schemas.
+
+- [ ] **Step 2: Run the focused distribution tests and verify RED**
+
+Run:
+
+```console
+.venv/bin/python -m pytest tests/test_distribution.py -q
+```
+
+Expected: failures because metadata, version, and documentation still describe `0.1.2` and the
+platform cache.
+
+- [ ] **Step 3: Update user and architecture documentation**
+
+Document the local default, ownership-based reuse, scanner exclusion, optional absolute MCP cache
+path, conflict behavior, and `clear-cache` default. Update the bundled OpenCode skill to pass
+`cache_directory` only when the user explicitly supplies or approves it.
+
+Set both package versions to `0.1.3`:
+
+```toml
+version = "0.1.3"
+```
+
+```python
+__version__ = "0.1.3"
+```
+
+- [ ] **Step 4: Run the focused distribution tests and verify GREEN**
+
+Run:
+
+```console
+.venv/bin/python -m pytest tests/test_distribution.py -q
+```
+
+Expected: all distribution tests pass.
+
+- [ ] **Step 5: Commit the release slice**
+
+Stage the documentation, version, script, and test files and commit through the repository commit
+policy with title `Prepare agent folder workspace 0.1.3`.
+
+### Task 4: Full verification and PyPI-only release
+
+**Files:**
+- Verify: entire repository
+- Build: temporary clean output outside tracked `dist/`
+
+- [ ] **Step 1: Run all quality gates**
+
+Run:
+
+```console
+.venv/bin/python -m pytest -q
+.venv/bin/ruff format --check .
+.venv/bin/ruff check --no-cache .
+.venv/bin/mypy src
+.venv/bin/python scripts/generate_json_schemas.py --check
+.venv/bin/python scripts/check_wheel.py --reproducible --install-smoke
+git diff --check
+```
+
+Expected: every command exits zero.
+
+- [ ] **Step 2: Build and inspect clean release artifacts**
+
+Build wheel and sdist into a new temporary directory:
+
+```console
+SOURCE_DATE_EPOCH=315532800 .venv/bin/python -m build --no-isolation --outdir <temporary>
+.venv/bin/python -m twine check <temporary>/*
+.venv/bin/python scripts/check_wheel.py <temporary> --install-smoke
+```
+
+Expected: one `0.1.3` wheel and one `0.1.3` sdist, valid metadata, successful isolated import and
+CLI/MCP smoke checks.
+
+- [ ] **Step 3: Commit any deterministic generated correction and tag**
+
+Require a clean worktree, create annotated tag `v0.1.3`, and verify the tag points at the release
+commit. Do not create any GitHub release or publish to another registry.
+
+- [ ] **Step 4: Upload only to production PyPI**
+
+Use the environment's configured production PyPI credentials:
+
+```console
+.venv/bin/python -m twine upload --repository-url https://upload.pypi.org/legacy/ <temporary>/*
+```
+
+Expected: PyPI accepts both `agent_folder_workspace-0.1.3` artifacts.
+
+- [ ] **Step 5: Verify the public release**
+
+Query PyPI's JSON endpoint and download the published wheel into a fresh temporary directory.
+Verify version `0.1.3`, SHA-256 against the locally uploaded wheel, package import,
+`agent_folder_workspace.__version__`, MCP tool schema, and the local-cache behavior. Confirm no
+TestPyPI or other publication was performed.