| 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
- Read workspace.md first.
- Read requirements.lock.md when dependency installation or verification is involved.
- Read ../tool-template/tool-template.md when using or refreshing the canonical
tools.py bundle.
- Read ../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 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.
