Start a new application

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.

For the current unpublished 0.2.0-rc.1 / stable PHP >=8.5.11 <8.6.0 candidate, start with the release-matched first-application recipe. It provides safe source copying, exact offline setup, route/controller/view files, CLI/DB prerequisites and the independent-human evidence boundary.

This is the scaffold checklist. For a complete, runnable explanation of the configuration/repository/service/controller/route/view wiring, follow APPLICATION_WALKTHROUGH.md. Read the documentation index, API guide, and troubleshooting guide as needed.

• Copy skeleton/ to a new directory. Exclude its generated vendor/ and composer.lock if copying after this extraction's smoke test.
• In the new composer.json, set the clean/framework path repository URL to /Users/dan/Documents/CleanFramework Project/CleanFramework (or the framework's actual location).
• On an approved supported runtime, run `COMPOSER_DISABLE_NETWORK=1 composer install --no-plugins --no-scripts --no-interaction`. Stop if a dependency requires a download; obtain separate setup authority rather than bypassing the offline restriction. Do not use the unchanged PHP8.2 host for this candidate.
• Copy .env.example to .env, keep APP_ENV=DEV, and enter only local credentials.
• Read and retain the copied AGENTS.md; it defines application ownership, security, comments, testing, and coding conventions.
• Add application code under the existing Controllers, Domain, Repositories, Services, Security, Providers, and Middleware directories without moving it into the framework namespace. The included HomePageService is a neutral example, not a hidden legacy dependency.
• Add routes in resources/routes.php and explicit factories in bootstrap.php. The included HomePageService shows how application use cases are injected without moving them into the framework package.
• Add native PHP views under the existing layouts/pages/partials/errors structure and escape output.
• Add application migrations under database/migrations; inspect the plan before applying them. Even status/plan/verify query the ledger and require an explicitly approved disposable DB; they are not part of the DB-free boot.
• Organize tests under Unit, Integration, Http, Security, and Fixtures; then run tests and the local server. The skeleton supplies an extension structure, not a prebuilt account system, queue daemon or queue command registration.
• Before STAGE/PROD, provision independent secrets, a public-only Apache DocumentRoot, private writable directories, HTTPS, logs, backups, and isolated Apache/MySQL verification.

Example first route:

use Clean\Framework\Http\Response;

// Add inside resources/routes.php's registration closure, where $router exists.
$router->get('/status', static fn (): Response => Response::json([
    'success' => true,
    'status' => 'ok',
]));

Do not copy domain code, schemas, views, credentials, or provider adapters from an unrelated application. The portability boundary depends on application code remaining outside Clean\\Framework\\.

Do not install clean/framework-prosperous-pairs-legacy in a new application. That separately versioned package exists only when an existing application's characterization tests prove that it still needs one or more original classes during a controlled migration. File preservation alone does not satisfy the legacy schema, configuration, controller, or provider dependencies. The compatibility and migration guide explains its opt-in identity and preservation boundaries; it is not a required dependency or a recommended shortcut for a new application.

Before building a generic helper inside app/Services, review the focused framework modules under src/ (cache, mail, storage, validation, feature, audit, outbox, and integration contracts). Put mechanics shared across applications in the framework only after they are neutral and tested; keep workflow, schema, provider, copy, role, and policy decisions in the application.

Editorial provenance

Source: docs/NEW_APPLICATION.md. Source SHA-256: 5b0208e3f8c18efc1024b232d512d435fa85ed55d9898272ee3ed22efc52ec7f.

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