framework

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.

Working on Uvicore CLI/console, the event dispatcher, or the jobs system — uvicore/console/ (command/group decorators, console bootstrap, schematic generators, vendored asyncclick), uvicore/events/ (Dispatcher, Event, Handler), uvicore/jobs/ (Dispatcher, Job). Read before editing those, or before adding CLI commands, events, or jobs to the framework.

Working on the Uvicore HTTP subsystem under uvicore/http/ — routing (WebRouter/ApiRouter/Router), Routes/Controller classes, AutoApi + ModelRouter auto-CRUD, Guard/auth scopes, the base+web+api server build, responses, middleware, and OpenAPI. Read before editing anything in uvicore/http/.