uvicore

Use at the END of any substantive task in this repo (new feature, behavior change, notable refactor, non-trivial fix, doc/skill change) to append a dated journal entry, and WHENEVER you make a significant, hard-to-reverse architectural decision to also write an ADR. Covers the journal/ and adr/ folder conventions, the entry templates, ADR numbering and the supersede rule, and the repo-vs-machine-local knowledge principle. Invoke before finishing work so durable reasoning lands in the repo, not just in chat.

End-to-end workflow for adding a new capability to the Uvicore framework itself — a new bound service, a new framework package (provider + config + mixin), a new provider register_* helper, a new IoC-bound type, or a new CLI/event/job. Use when extending the framework's own feature set (not when building an app on top of Uvicore).

Core mental model for the Uvicore framework: the bootstrap sequence, IoC container, Application, Package, Provider lifecycle, the @uvicore decorators, and the IoC override/_BASE mechanism. Read this BEFORE editing anything under uvicore/foundation, uvicore/container, uvicore/package, or any provider/register/boot code, or when you need to understand how services are bound and resolved.

Working on the Uvicore ORM internals under uvicore/orm/ — Model, ModelMetaclass, Field, relations (BelongsTo/HasMany/HasOne/BelongsToMany/Morph*), the async ORM query builder, the mapper, and model lifecycle hooks. Read before editing model.py, metaclass.py, fields.py, query.py, mapper.py, or drivers/.

Quick public-API reference for Uvicore's leaf service subsystems that don't have a dedicated skill — templating (Jinja2), mail, redis, cache, logging, auth (UserInfo/authenticators/guards), and the exception classes (SmartException + HTTP exceptions + status codes). Use when working on or wiring up uvicore/templating, uvicore/mail, uvicore/redis, uvicore/cache, uvicore/logging, uvicore/auth, or uvicore/exceptions.

Writing and running tests for the Uvicore framework itself. Covers the bin/test*.sh scripts, the app1 reference-app fixture + in-memory SQLite bootstrap in tests/conftest.py, async pytest patterns, and where tests for each subsystem live. Use whenever adding/changing framework behavior that needs test coverage, or when running the suite.

Run this WHENEVER you make a substantive change to the Uvicore framework (new feature, new/changed/removed/renamed public API, new config key, new CLI/event/job, or any user-observable behavior change) — ideally before you consider the change done. A framework code change is NOT complete until its matching TESTS and DOCS are updated. Docs means both the relevant docs/docs feature page(s) AND the epologue trio: release-notes, the major-version changelog, and the version upgrade guide. Use this because framework changes routinely ship without tests or docs — close that gap every time.

Working on the Uvicore database layer, configuration system, and the foundational Dict/SuperDict type — uvicore/database/ (db service, low-level query builder, Table, seeders, connections), uvicore/configuration/ (config + env()), uvicore/typing/dictionary.py. Read before editing db.py, builder.py, query.py, table.py, the config service, or the Dict type.

Configuration and authentication for a Uvicore app — the package-vs-app config split, env() variables, concern config files, accessing config at runtime, overriding other packages' config/IoC bindings, HTTP middleware, and auth (Guards, scopes/permissions, the current user, the Authentication middleware). Use when working with config, middleware, permissions, or login in a Uvicore application.

Working with data in a Uvicore app — defining database tables (database/tables/), ORM models (models/) with fields and relations, seeders (database/seeders/), querying with the async ORM query builder, configuring connections (config/database.py), and the ./uvicore db CLI commands. Use when adding or querying models/tables/seeders in a Uvicore application. Requires the 'database' extra.

Quick reference for the Uvicore framework that an app developer needs but cannot see (the framework is installed as a library in the uv virtualenv, not in this repo). Covers the import cheatsheet (where to import everything from), the uvicore.* globals, debugging with dump/dd, useful ./uvicore inspection commands, and how to read the installed framework source when a skill doesn't cover something.

Building server-rendered web features in a Uvicore app — web routes (http/routes/web.py), web controllers (http/controllers/), Jinja2 views/templates (http/views/), public files and static assets, the response.View/HTML/Text/Redirect helpers, route naming, and route groups. Use when adding browser-facing HTML pages to a Uvicore application.

Building REST API features in a Uvicore app — API routes (http/routes/api.py), API controllers (http/api/), the APIResponse envelope, returning ORM models, the automatic model CRUD API (ModelRouter / auto_api), OpenAPI/Swagger docs, route guards/scopes, and HTTP exceptions. Use when adding JSON/REST endpoints to a Uvicore application.

Writing and running tests for a Uvicore application — the pytest layout in tests/, the appstub fixture in tests/conftest.py that boots the app, enabling DB drop/create/seed, async test patterns, testing HTTP routes with a client, and running via uv run ./bin/test.sh. Use when adding or running tests in a Uvicore application.

Orientation for developing a Uvicore application — the folder layout, the package-vs-app config split, config/dependencies.py, the provider register()/boot() lifecycle and its register_* helpers, the console + HTTP entrypoints, and the ./uvicore gen schematic generators. Read this first before adding any feature to a Uvicore app.

Adding CLI commands to a Uvicore app — async command modules in commands/, the @command/@argument/@option decorators (AsyncClick), registering commands/groups in the provider via register_cli_commands, running them with ./uvicore <group> <command>, and the ./uvicore gen generators. Use when adding console commands to a Uvicore application.

Author, edit, or audit Uvicore documentation pages in this MkDocs repo. Use when adding a new docs page, editing existing docs, checking a docs section for gaps/redundancy/Web-API parallelism, or building/previewing the site. Encodes the house conventions, the Poetry-based build commands, and the dual-router structure.