Core Laravel Package

Getting Started

This is the first assessment for saucebase-dev/core, so treat the following as a starting orientation rather than a deeply verified guide — the package's public surface is still thin in documentation terms, and v1.14.0 is a small, additive release.

Install and bootstrap

1. composer require saucebase-dev/core
2. Publish the package assets and run the installer:

   php artisan vendor:publish --tag=saucebase-core
   php artisan saucebase:install   # or the equivalent setup command exposed by the package
   

3. Clear caches after publishing config: php artisan config:clear && php artisan optimize:clear.

Where to look first

• config/saucebase.php (or similarly named published config) — this is where module discovery, enabled/disabled state, and path conventions live.
• The package's own src/ service provider — it reveals the registration order and any boot-time hooks you may need to extend.
• With v1.14.0, also look at the Boost integration: the release ships Laravel Boost with core, which means module guidelines and skills are available to AI coding agents without a separate install step.

First use case

Ask your AI agent (Claude, Copilot, Cursor, etc. — anything speaking MCP) to scaffold or modify a module after Boost is wired up. Because v1.14.0 bundles Boost, the agent should already receive the module guidelines and skills that describe the package's conventions. That is the fastest way to see what the package expects structurally: let the agent read the guidelines, then diff its output against a hand-written module.

If you're not using an AI agent, the first use case is simply generating a module and confirming it registers, routes, and migrates correctly.

Implementation Patterns

Module-as-unit-of-work

Structure day-to-day work around modules rather than the global app. Each module should own its routes, migrations, config, and (optionally) its own service provider. Register modules through the core's discovery/config mechanism instead of hand-editing config/app.php — this keeps composer dump-autoload churn out of your module workflow.

Boost-driven development loop (new in v1.14.0)

The bundled Boost integration changes the inner loop meaningfully:

• Guidelines act as a persistent style/architecture contract. Keep them in the repo and review changes to them in PRs the same way you review code — an agent that ingests stale or wrong guidelines will confidently produce wrong modules.
• Skills are the reusable procedures (scaffold a module, add a migration, wire a route). Prefer invoking a skill over free-form prompting; it produces more consistent output across team members.
• Because Boost now ships with core, pinning saucebase-dev/core effectively pins your agent's behaviour too. Bump deliberately.

Integration tips

• Service providers: keep module providers thin. Register bindings in register(), side effects (routes, views, migrations, commands) in boot(), and let the core handle ordering.
• Config: prefer module-local config files merged by the provider over adding keys to the root config. It keeps modules independently removable.
• Testing: write one smoke test per module asserting the provider registers and routes resolve. Most integration breakage in modular Laravel setups is silent non-registration, not logic bugs.
• CI: run php artisan optimize:clear before test suites. Cached config and cached module manifests are the number one source of "works locally, fails in CI" in this class of package.

Gotchas and Tips

Boost only helps agents that are actually connected

v1.14.0 ships Boost with core, but that doesn't mean your editor is using it. Verify the MCP server is registered and the agent can list tools before you trust its output. A silent fallback to unguided generation looks identical to a working setup until you read the generated code.

Guidelines drift is a real risk

Because guidelines and skills now travel with the package, they can conflict with project-specific conventions you've already established. If your team has its own rules, layer them explicitly rather than assuming the package guidelines win. When output looks off after an upgrade, check whether a guideline changed before debugging your own code.

Caching

Clear config, route, and view caches after any module add/remove. If the package caches module discovery, that cache also needs busting — look for a dedicated artisan command or a cache key in the config.

Autoloading

New modules typically need composer dump-autoload unless the package registers a PSR-4 fallback. Missing this produces confusing "class not found" errors that look like a registration bug.

Debugging non-registering modules

Add a temporary dd() or Log::info() in the core's module loader to see what it discovered. Comparing "what the loader found" against "what you expect it to find" resolves most issues in one pass.

Extension points

Prefer the package's published config and provider hooks over editing vendor files. If a hook doesn't exist for what you need, that's a signal to open an upstream issue rather than to monkey-patch — modular cores tend to change their internals between minor versions.

Version pinning

Given the tight coupling between core and the Boost-bundled agent tooling, pin saucebase-dev/core to a minor range you've tested (~1.14.0 rather than ^1.0) and upgrade in its own PR so any change in agent behaviour is isolated from feature work.