Development

Use this page when working in the Capell 1.x host repo or wiring Capell into a Laravel app. Product concepts live in How Capell works; package-authoring rules live in Packages.

Who’s this for? Contributors working inside this monorepo. Local setup, commands, and tests — not needed to install or use Capell (start here).

Repository Shape

Local 1.x work normally uses two sibling repos:

capell/
    capell-4/
    capell-packages-4/

The host repo owns Core, Admin, Frontend, Installer, and Marketplace. Add-on package behavior belongs in ../capell-packages-4 unless the host repo owns the contract or extension point.

When more than one person or agent session works in this repo at once, use a git worktree and set it up with bash scripts/init-worktree.sh — a fresh worktree has no vendor/, and symlinking one by hand silently makes tests run against the primary checkout.

Use Composer path repositories for local package development. Keep matching 1.x branches in both repos when a change spans host and add-on packages.

Daily Commands

Full suites and preflights join the host release verification gate. The guide explains waiting, release-child ownership and the focused single-file exception.

Command	Use
`composer prepare`	Run Testbench package discovery.
`composer test:fast`	Run the sharded fast Pest command while developing.
`composer test`	Run the full Pest test suite.
`composer lint`	Run changed-file Pint formatting.
`composer analyze`	Run the fast PHPStan configuration.
`composer preflight`	Run the standard static, contract, formatting, analysis, and test gates.
`composer preflight:all`	Run Composer path and contract checks, doc guards, Rector, Pint, Prettier, ESLint, PHPStan, security audit, and Pest.
`composer serve`	Build and serve the Testbench workbench.

Start narrow while developing:

vendor/bin/pest packages/admin/tests --configuration=phpunit.xml
vendor/bin/pest packages/frontend/tests/Unit/Security/PublicHtmlSafetyInspectorTest.php --configuration=phpunit.xml

Use the command index for a short grouped reference and artisan commands when you need install option details.

Capell Artisan Commands

Check the installed app first:

php artisan list capell

Common host commands:

Command	Use
`capell:install`	Install Capell packages, default data, admin access, and selected optional packages.
`capell:upgrade`	Run host package upgrade flow and migrations.
`capell:doctor`	Run host diagnostic checks.
`capell:extension-audit`	Validate extension contracts and manifests.
`capell:package:lint`	Lint package manifests, versions, assets, and shared extension contracts.
`capell:extensions:repair-composer-drift`	Repair Composer-actionable extension drift outside dashboard requests.
`capell:package-cache` / `capell:package-cache:clear`	Warm or clear package discovery cache.
`capell:make`, `capell:make-action`, `capell:make-data`, `capell:make-extender`, `capell:make:extension`, `capell:make:theme`, `capell:make-schema`, `capell:make-blueprint`	Generate host/app/package scaffolding.
`capell:admin-install`, `capell:admin-setup`, `capell:admin-upgrade`	Admin package install/setup/upgrade surfaces.
`capell:admin-cache-widgets`, `capell:admin-clear-widgets-cache`, `capell:admin-cache-configurators`, `capell:admin-clear-configurators-cache`	Warm or clear Admin registries.
`capell:frontend-install`, `capell:frontend-after-install`, `capell:frontend-upgrade`	Frontend package lifecycle commands.

Optional-package commands such as capell:static-site, capell:xml-sitemap, and capell:frontend-tailwind-assets only exist when their package is installed.

Development Routes

Need	Read
Apply repository coding conventions	Coding standards
Make queued work survive failures	Queued work reliability
Decide host vs package vs app ownership	Host, package, or app code
Pick an install path	Install matrix
Configure local repo work	Local development
Work with the 1.x monorepo branch	Monorepo 1.x branch
Run Capell in containers	Container development
Install or repair admin setup	Admin install setup
Seed content safely	Seeding content
Understand page revisions and rollback	Page event history
Add settings migrations	Settings migrations
Work with public page API output	Public page API
Understand CI and Pest shards	CI and test shards
Measure Blade view test coverage	Blade view coverage
Look up config keys and env vars	Configuration reference
Create package authoring surfaces	Package authoring
Follow package provider conventions	Package provider conventions
Diagnose environment or registry state	Diagnostics
Decide where docs belong	Docs ownership rules
Avoid unsafe extension/package patterns	Do not do this
Capture useful docs screenshots	Screenshot state guide

Configuration

Host config lives in:

File	Covers
`packages/core/config/capell.php`	Package discovery, cache flags, media backend, install tooling, roles, workspace preview/prune, release windows.
`packages/admin/config/capell-admin.php`	Admin settings, update notices, cache refresh, security headers, preview containers.
`packages/frontend/config/capell-frontend.php`	Asset build tool, home route registration, fallback site behavior, model-event registration, debug logging, HTML rendering.
`packages/installer/config/capell-installer.php`	Reinstall guard, Composer/PHP binaries, default install package selection.
`packages/marketplace/config/capell-marketplace.php`	Marketplace enablement, API/web URLs, identity, webhook URL/secret, catalogue paging.

After changing config in an app:

php artisan optimize:clear

Seeding Content

Use Actions and models directly from seeders. Avoid building seeders around admin forms.

Create sites with CreateSiteAction.
Create pages with CreatePageAction or page factories in tests.
Use PageUrl records for language/site-aware URLs.
Seed translations explicitly.
Use package seeders for optional package data.

For repeatable demos, keep demo content in the package that owns the feature.

Settings Migrations

Settings migrations go in database/settings/, are registered by install/setup commands, and must be guarded with existence checks. Do not assume a settings table exists during early install or test bootstrap.

Developer Tools

Use maker commands for boring scaffolding, then write the real work by hand.

Reach for capell:make-* to stamp out the file and wiring.
Write domain behavior as explicit Actions, and structured boundaries as Data objects.

Diagnostics should report state without mutating it. If a diagnostic can fix something, make the repair an explicit Action and call it from a separate command or admin action.