# Documentation Index

This directory contains all project documentation.

## Guides

### [Installation](./guide/installation.md)

Install shelfbox with Homebrew, a pre-built binary, or a source build.

Covers:

* Platform requirements
* Windows setup
* Advanced installer options
* Building from source
* Uninstalling and optional local-data cleanup

### [Common Workflows](./guide/workflows.md)

Task-oriented guides for first-time and common operations.

Examples:

* Start managing a local file
* Keep a `.env` file out of Git
* Move the store to a new location
* Recover after a repository move
* Recover after a reclone
* Keep multiple clones of the same repository separate
* Use linked Git worktrees
* Migrate an already-tracked file to local-only management
* Shelve or restore all eligible files below a directory
* Audit the store and clean explicitly orphaned data
* Repair broken materializations
* Rebuild a lost local index

Use this document when you know what you want to achieve but do not yet know which command to use.

---

## Command Reference

### [Item Commands](./reference/item-commands.md)

Reference for:

* `item add`
* `item restore`
* `item repair`
* `item sync`
* `item materialize`
* `item relink`
* `item move`
* `item list`
* `item status`
* `item info`

### [Repo Commands](./reference/repo-commands.md)

Reference for:

* `repo list`
* `repo status`
* `repo reclaim`
* `repo repair`
* `repo sync`
* `repo materialize`
* `repo gc`

### [Store Commands](./reference/store-commands.md)

Reference for:

* `store info`
* `store verify`
* `store rebuild-index`
* `store migrate-manifests`
* `store gc`

### [Config Commands](./reference/config-commands.md)

Reference for:

* `config list`
* `config get`
* `config set`
* `config explain`
* `config path`

Use the reference documents when you already know the command and need exact behavior, flags, outputs, or error conditions.

---

## Architecture

### [Architecture Overview](./architecture/architecture-overview.md)

High-level system architecture.

Covers:

* Workspace structure
* Crate responsibilities
* Request lifecycle
* Major subsystems

### [Module Map](./architecture/module-map.md)

Current crate and module boundaries after the API facade refactor.

Covers:

* CLI command module layout
* Public `shelfbox-core` API surface
* Private context, ops, storage, adapter, and policy modules
* Dependency direction rules

### [Data Model](./architecture/data-model.md)

Persistent data structures and storage layout.

Covers:

* `meta.json`
* `index.json`
* `manifest.json`
* Store directory structure

### [Design Decisions](./architecture/design-decisions.md)

Important design decisions and their rationale.

Examples:

* Ownership model choices
* Store layout decisions
* Repair policy
* Repository identity strategy
* Concurrency and locking

Use the architecture documents when modifying implementation or evaluating design changes.

---

## Specifications

### [Copy Mode](./spec/copy-mode.md)

Normative public copy-materialization policy, including explicit sync and
durable-recovery rules.

Defines:

* Safety and canonical-data invariants
* Materialization facts and operation behavior
* Durable recovery requirements
* Compatibility and release gates

### [Ownership Model](./spec/ownership-model.md)

Formal ownership state machine specification.

Defines:

* Ownership states
* State transitions
* Command authority rules
* Ownership invariants
* Reclaimability rules

This is the authoritative source for ownership semantics.

### [Failure Matrix](./spec/failure-matrix.md)

Operational failure and recovery specification.

Defines:

* Failure modes
* Detection methods
* Recovery procedures
* Recoverability guarantees
* Recovery invariants

Use this document when evaluating recovery behavior or failure handling.

---

## Reading Guide

| Goal                           | Document                  |
| ------------------------------ | ------------------------- |
| Install shelfbox               | [`guide/installation.md`](./guide/installation.md) |
| Start managing a local file    | [`guide/workflows.md`](./guide/workflows.md#start-managing-a-local-file) |
| Solve a practical problem      | [`guide/workflows.md`](./guide/workflows.md) |
| Understand a command           | [`reference/*`](#command-reference) |
| Modify implementation          | [`architecture/*`](#architecture) |
| Implement or review copy mode  | [`spec/copy-mode.md`](./spec/copy-mode.md) |
| Understand ownership behavior  | [`spec/ownership-model.md`](./spec/ownership-model.md) |
| Understand recovery guarantees | [`spec/failure-matrix.md`](./spec/failure-matrix.md) |