Directory structure and ownership

Bounded candidate reference — 2026-10-20: 0.2.0-rc.1 is committed locally through 84f415b3098af5653577b2c65eea31fca21df79c, unpublished and not production-approved; stable PHP >=8.5.11 <8.6.0 is required. This is documentation, not adoption: this knowledge base retains its installed 0.1.0-rc.1 dependency and PHP 8.2.11 local profile. Dated PHP 8.2 evidence is historical; earlier dirty-source reports retain their original test provenance, not retroactive clean-commit proof. Candidate examples are illustrative: API signatures were reviewed, but candidate code was not executed by this editorial update. See current checkpoint, open criteria and adoption boundary.

The repository intentionally contains both framework source and a complete application scaffold. Directories remain present even before a consuming application needs code, using README files or ignored placeholders rather than application-specific implementations.

CleanFramework/
├── AGENTS.md
├── VERSION                   local pre-release candidate identifier
├── backups/                  instructions/example manifests only
├── bin/                      framework CLI and verification
├── compatibility/
│   └── prosperous-pairs-legacy/
│       ├── app/Core/         preserved original Application and Container
│       ├── app/Services/     all 50 preserved original services
│       └── original-framework-manifest.json
├── config/                   neutral framework defaults
├── docs/                     architecture, standards, scope, verification
├── resources/assets/         package-level source asset placeholders
├── src/                      framework runtime
│   ├── Administration/ Application/ Asset/ AssistedAction/ Audit/ Cache/
│   ├── Config/ Console/
│   ├── Container/ Database/ Error/ Feature/ Http/ Idempotency/ Integration/
│   ├── Lock/ Logging/ Mail/ Media/ Migration/ Module/ Observability/ Outbox/ Privacy/
│   └── Queue/ Revision/ Routing/ Scheduler/ Security/ Storage/ Support/ Validation/ View/
├── temp/                     disposable local work, ignored
├── tests/                    runner plus Unit/Integration/Http/Security/Fixtures
├── examples/
│   └── reading-list/         unrelated portability application and tests
└── skeleton/
    ├── AGENTS.md
    ├── app/
    │   ├── Controllers/      example controller
    │   ├── Core/             application composition extension point
    │   ├── Domain/           application rules
    │   ├── Repositories/     application persistence
    │   ├── Services/         neutral application-service example
    │   ├── Security/         application identity/policy
    │   ├── Providers/        external adapters
    │   ├── Middleware/       application HTTP middleware
    │   └── Plugins/          retained original empty extension location
    ├── backups/              example manifest/instructions, no real backups
    ├── bin/                  application CLI
    ├── config/               app/schema, modules.json and trusted module-bootstrap.php
    │   └── environments/     independent DEV/TEST/STAGE/PROD overlays
    ├── database/
    │   ├── migrations/       neutral example migration
    │   └── seeders/          development-only seed guidance
    ├── public/
    │   ├── app.php           sole public PHP entry point
    │   ├── .htaccess
    │   ├── assets/{css,js,images,fonts}/
    │   └── cache/media/      ignored public image derivatives
    ├── resources/
    │   ├── routes.php
    │   ├── assets/{css,js,images}/
    │   └── views/{admin,layouts,pages,partials,errors}/
    ├── storage/
    │   ├── cache/ logs/ sessions/ uploads/ backups/
    │   ├── assets/ asset-locks/ rate-limits/
    │   └── README.md
    ├── temp/                 application-local disposable files
    └── tests/{Unit,Integration,Http,Security,Fixtures}/

public/ is the only valid web document root. storage/, backups/, temp/, configuration, source, migrations, and vendor dependencies must never be exposed through an alias. Placeholder directories communicate intended ownership; they do not imply an unimplemented module is supported.

src/Integration/ contains separate Http/, Provider/, OAuth/, Webhook/, and Ai/ boundaries. The first four provide neutral Phase 6 mechanics; real provider adapters and account configuration remain in a consuming application's app/Providers/ directory.

src/Queue/, src/Outbox/, and src/Scheduler/ provide the Phase 5 state machines, stores, and execution boundaries. src/Lock/ and src/Idempotency/ provide coordination contracts and local/database adapters where implemented; included local adapters do not imply multi-host safety. src/Privacy/ supplies classification and retention mechanics, while the application owns retention periods, legal holds, and object policy.

docs/INDEX.md is the reading map; docs/APPLICATION_WALKTHROUGH.md connects the existing portability application's files; docs/API_GUIDE.md points to behavioral API contracts; and docs/TROUBLESHOOTING.md describes safe local diagnostics. These are guides, not additional runtime packages.

src/Media/, src/Revision/, and src/Observability/ contain Phase 7 neutral contracts and local adapters. src/Administration/ contains declarations and presentation data only. The corresponding skeleton admin view is opt-in and has no default route or controller.

src/Integration/Ai/ contains Phase 8 typed structured-generation policy in addition to the preserved concise provider port/circuit. src/AssistedAction/ contains non-executing proposal records, optimistic local stores, registered handler policy, approval/step-up enforcement, and explicit outcomes. Prompts, action definitions/handlers, provider adapters, and live routes belong to a consuming application.

The optional compatibility/prosperous-pairs-legacy package preserves the original framework surface and historical namespaces. Reusable neutralized mechanics live under top-level src/; new applications use those APIs and do not load the bridge. Every skeleton/app/ directory is an extension point for application-specific composition, use cases, and policies.

examples/reading-list/ is a complete but deliberately small second application. Unlike skeleton/, it exists to prove framework portability and ownership boundaries, not to be copied as generic boilerplate. It has an independent namespace, Composer manifest, environment configuration, public front controller, native PHP views, and test runner and does not load the optional compatibility package.

Editorial provenance

Source: docs/DIRECTORY_STRUCTURE.md. Source SHA-256: 7d7f094421fbd92543a5ab5eaac09c14af94e15952f21c36aebe8c64d045e468.

Framework candidate reference; editorial checkpoint 2026-10-20. See candidate status and adoption boundary.