# Repository Guidance

## Purpose

This repository is the product layer around `@push.rocks/smartstorage`.

Its job is to turn the storage engine into a usable product:

- a Docker image that starts cleanly and predictably
- a management UI and ops API
- product-facing config, auth, and persistence behavior
- tests, docs, and release hygiene

## Dependency Ownership

We control the dependencies used here, especially `@push.rocks/smartstorage` and the `@design.estate/*` UI stack.

- Do not keep product code full of workarounds for missing dependency capabilities.
- If a missing capability clearly belongs in a dependency, improve the dependency.
- If dependency work is not being done in this repo right now, write a focused implementation prompt into `./prompts/*.md`.

## Boundary

This repo should own:

- Docker and runtime packaging
- CLI, env var, and startup UX
- admin auth flow and management APIs
- product metadata persistence and migrations
- acceptance tests and docs

`@push.rocks/smartstorage` should own:

- storage-engine stats and health surfaces
- bucket and object metadata summaries that should be cheap at runtime
- cluster and drive introspection
- runtime auth/credential APIs when the engine must react to changes

## Planning Docs

- Put current repo improvement work in `readme.plan.md`.
- Keep durable findings in `readme.hints.md`.
- Put dependency implementation prompts in `prompts/*.md`.