# Nested perch layout

A Self's perch directory contains a `nested/` folder housing the perches of its Psyche and any active working perches. Only Selves (and ready agents) live at the top level of `$SPT_HOME/owlery/`. The earlier layout was flat — every perch (Self, Psyche, working) lived side-by-side under `owlery/`.

We moved to nested through Phase 25 and 25.4 because flat treated structurally-dependent perches (a Psyche cannot exist without its Self; a working perch cannot exist without its parent Self) as peers of independent agents. That made cleanup, doctor diagnostics, and ownership reasoning all harder than they needed to be. Nested makes the parent → child relationship explicit on disk and lets a single recursive walk of a Self's directory enumerate everything that belongs to it.

The cost is non-trivial: address resolution now goes through `perch_path::resolve_*` with a `ParentHint` enum, callers that historically composed paths inline had to be migrated, and code must continue to read both layouts during the migration window. We accepted that cost as the price of an explicit ownership tree.