Thank you for you detailed comments! I'll comment on those related to Catalyst core.

Perl has well-established ways to set up inheritance. Messing with the caller's @ISA from your module's import() method is not a clean way to do it, and the documentation doesn't mention it being done at all. It does the same for the dispatcher class.

There is nothing that stops you from setting up the application class manually, but by doing that you'll probably miss some very convenient features that Catalyst offers.

Here is an example of doing it manually:

package MyApp;

use strict;
use warnings;
use base qw[ Catalyst
             Catalyst::Plugin::Email
             Catalyst::Plugin::Static
             Catalyst::Dispatcher
             Catalyst::Engine::HTTP ];

MyApp->engine('Catalyst::Engine::HTTP');
MyApp->dispatcher('Catalyst::Dispatcher');
MyApp->log( Catalyst::Log->new );

MyApp->config(
    home => '/path/to/my/home',
    root => '/path/to/my/home/root'
);

MyApp->setup;

1;
[download]

Catalyst will automagically try to find the best Engine class for it's environment, so if you do it your self you'll have to create several application classes, one for each environment: development, testing and deployment.

I agree that the documentation could be more clear about what import() is does.

As long as we're talking about this code, I would also suggest breaking up this long method into smaller ones

This has been on my TODO for a while, the import has now been broken down to five methods.

and avoiding the use of UNIVERSAL::require to put a method into everyone else's namespace, but those are very minor things.

This could be done, but i don't see the benefits of doing that. Using UNIVERSAL::require gives less and more readable code IMO.