Workspace

---
name: workspace
description: >
  Use this skill when initializing, checking, or refreshing a Retriever workspace.
  It defines the .retriever directory layout, bootstrap flow, runtime refresh rules,
  the pinned dependency contract for the current runtime, and the current workspace
  maintenance command surface.
metadata:
  version: "1.1.17"
---

# Retriever Workspace

Use this skill for any task that needs to bootstrap or maintain a workspace-local Retriever installation.

## Load order

1. Read [workspace.md](workspace.md) first.
2. Read [requirements.lock.md](requirements.lock.md) when dependency installation or verification is involved.
3. Read [../tool-template/tool-template.md](../tool-template/tool-template.md) when using or refreshing the canonical `tools.py` bundle.
4. Read [../schema/schema.md](../schema/schema.md) when initializing or migrating the database schema.

## Core rules

- The workspace root is the user-selected folder, not `.retriever/`.
- All persistent Retriever state lives under `.retriever/` inside that root.
- Database paths stored in SQLite must be relative, never absolute.
- Treat `skills/tool-template/tools.py` as the canonical command entrypoint.
- Use `workspace status`, `workspace init`, and `workspace update`; old direct `doctor`, `bootstrap`, and `upgrade-workspace` command names are implementation/history details, not the user-facing surface.
- The tool's own dispatcher refreshes runtime metadata for stale workspaces before running any non-exempt command; see [workspace.md](workspace.md) for the full contract.
- Treat `runtime.json` as the local state record for the canonical tool version, schema version, and checksum.
- Treat canonical template checksum drift as an upgrade signal even if the plugin version string is unchanged.
- On reinstall, the next non-exempt command will refresh runtime metadata automatically; there is no separate reindex step needed purely because the canonical template changed.
- If environment checks fail, stop and report the issue clearly instead of partially bootstrapping.

## Current outcome

With the current `1.1.17` / schema `26` tool surface, Claude should be able to:

- verify the runtime with `workspace status`
- create the `.retriever/` directory structure
- use the canonical `tools.py` bundle directly
- initialize or migrate schema `26`
- write a stable `runtime.json`
- ingest supported documents through the bounded V2 `ingest` facade
- verify the required PST backend is present before calling the runtime ready
- populate built-in metadata for email, chat-like, PST, MBOX, Slack, and production documents during ingest
- ingest supported PST container sources through the same regular `ingest` surface
- materialize one-level EML/MSG attachment families with stable `control_number` values during ingest
- search indexed documents with structured filters

Do not improvise the runtime contract beyond the referenced files.