Add replica tree views and storage-backed replica handling

[brendan-m-murphy]

Summary

• Add replica tree view support and wire replica operations through storage-backed structures
• Update catalog, storage, and replica modules to reflect the new view-tree behavior
• Refresh API and architecture docs to describe the replica workflow and storage model
• Extend tests across CLI, hooks, replicas, storage, writers, and add flows

Testing

• Updated and expanded automated test coverage for replica, storage, CLI, hook, and writer paths
• Not run (not requested)

[Copilot]

Pull request overview

Introduces a UUID-backed primary storage layout for managed artifacts, with the existing template-derived path becoming a symlink "replica" by default. Adds a new replica module that can plan and apply generated symlink views over current catalog state, and threads a new primary_location parameter through add_file/plan_artifact_storage and StoragePlan.

Changes:

• New ogcat.replicas module with ReplicaViewPlan/ReplicaPlanItem/ReplicaState and Catalog.plan_view() for dry-run/apply of symlink views.
• add_file() and plan_artifact_storage() now default to primary_location="uuid" (storing under files/objects/<aa>/<uuid><suffix>) and create a template symlink replica via a new record post-processor; StoragePlan carries artifact_uuid/primary_location.
• Tests updated across add/storage/CLI/hooks/writers and a new tests/test_replicas.py; README, architecture, locators-and-storage, and API docs refreshed.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/ogcat/catalog.py	Adds UUID primary placement, template-symlink-replica post-processor, plan_view(), and helper functions.
src/ogcat/replicas.py	New module defining replica plan/apply data structures and symlink renderer.
src/ogcat/storage.py	Extends StoragePlan and plan_storage() with artifact_uuid/primary_location.
src/ogcat/init.py	Re-exports new replica types.
tests/test_add.py	Updates expectations to UUID primary + template replica; adds primary_location="template" test.
tests/test_storage.py	Splits UUID-default vs template-primary cases; adds explicit-locator override test.
tests/test_replicas.py	New test suite covering plan/apply, collisions, unsupported locators, missing targets, regeneration.
tests/test_cli.py	Adjusts assertions to UUID primary paths.
tests/test_writers.py	Adds primary_location="template" to existing zarr-naming test.
README.md	Documents UUID-primary default and plan_view.
docs/concepts/locators-and-storage.md	Explains UUID primary, template replica, and view planning.
docs/architecture.md	Notes UUID-backed primary and replica/view derivation.
docs/api/replicas.rst, docs/api/index.rst	Adds API reference page for replicas.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 27 out of 27 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 27 out of 27 changed files in this pull request and generated no new comments.