add core

go tool gpsystem add core <module> [--db <name>]

Renders the module-level shared skeletons into an existing module: the core/ package (home of the entities, rules and sentinel errors every surface shares) and the skeleton of the module's single repository/ persistence layer. New modules do not need it: add surface stamps both automatically alongside a module's first surface. add core is the retrofit case: modules generated before the rename (domain → surface), or modules whose shared core was deleted.

What it renders

• internal/modules/<module>/core/core.go: the package documentation, including the import direction rule (http → service → core → repository; core never imports a surface package, handlers never import the repository package)
• internal/modules/<module>/core/errors.go: an ErrNotFound sentinel via errs.Define, as the example of defining "no such record" errors in core (or re-exporting them from the repository) so handlers always check them through their own surface's service package
• internal/modules/<module>/repository/doc.go: the package skeleton of the module's shared persistence layer (row structs + interface + implementation go here, once per module)

The command is purely additive: it touches no anchors and modifies no existing file, it only creates new files. If the module already has a core/ package, the command refuses to run.

--db: named connection

By default the repository skeleton is flat (repository/doc.go), bound to the project's default database connection. --db <name> binds it to a named connection added earlier with add db, and renders the skeleton as a connection-named subfolder instead:

go tool gpsystem add db news analytics --connector bun
go tool gpsystem add core news --db analytics
# -> internal/modules/news/repository/analytics/doc.go

<name> must already exist on the module; the command fails fast, listing the module's available connections, if it does not.

When to use it

When migrating pre-rename modules (with per-surface repositories): after moving the surface folders under surfaces/, add core provides the shared core/ + repository/ skeletons into which you consolidate the duplicated rules and the persistence layer. See the rename note on the add surface page for the full migration steps.