minix 0.3.2__tar.gz → 0.3.4__tar.gz

{minix-0.3.2 → minix-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minix
-Version: 0.3.2
+Version: 0.3.4
 Summary: A modular Python framework for backend, AI, and data projects
 Author: AmirHossein Advari
 Author-email: amiradvari@gmail.com
@@ -13,11 +13,15 @@ Classifier: Programming Language :: Python :: 3.14
 Provides-Extra: ai
 Provides-Extra: clickhouse
 Provides-Extra: mysql
+Provides-Extra: pgvector
 Provides-Extra: postgresql
 Provides-Extra: rag
 Provides-Extra: vdb
 Requires-Dist: Pillow (>=10.0.0) ; extra == "rag"
 Requires-Dist: aiokafka (>=0.12.0,<0.13.0)
+Requires-Dist: alembic (>=1.13) ; extra == "mysql"
+Requires-Dist: alembic (>=1.13) ; extra == "postgresql"
+Requires-Dist: alembic (>=1.13) ; extra == "rag"
 Requires-Dist: authlib (>=1.3,<2.0)
 Requires-Dist: boto3 (>=1.39.14,<2.0.0)
 Requires-Dist: celery (>=5.5.3,<6.0.0)
@@ -37,6 +41,8 @@ Requires-Dist: mlflow (>=2.0) ; extra == "ai"
 Requires-Dist: numpy (>=1.24) ; extra == "ai"
 Requires-Dist: numpy (>=1.24) ; extra == "vdb"
 Requires-Dist: pdf2image (>=1.17.0) ; extra == "rag"
+Requires-Dist: pgvector (>=0.4) ; extra == "pgvector"
+Requires-Dist: psycopg[binary] (>=3.1) ; extra == "pgvector"
 Requires-Dist: psycopg[binary] (>=3.1) ; extra == "postgresql"
 Requires-Dist: psycopg[binary] (>=3.1) ; extra == "rag"
 Requires-Dist: pydantic-settings (>=2.0,<3.0)
@@ -78,10 +84,12 @@ Description-Content-Type: text/markdown
     - [Entities](#entities)
       - [SQL Entity](#sql-entity)
       - [Qdrant Entity (Vector DB)](#qdrant-entity-vector-db)
+      - [PGVector Entity (PostgreSQL vectors)](#pgvector-entity-postgresql-vectors)
       - [Redis Entity](#redis-entity)
     - [Repositories](#repositories)
       - [SQL Repository](#sql-repository)
       - [Qdrant Repository](#qdrant-repository)
+      - [PGVector Repository](#pgvector-repository)
     - [Services](#services)
     - [Controllers](#controllers)
     - [Connectors](#connectors)
@@ -104,6 +112,7 @@ Description-Content-Type: text/markdown
       - [Embedding Model](#embedding-model)
       - [MLflow Model (requires `ai` extra)](#mlflow-model-requires-ai-extra)
   - [RAG Module](#rag-module)
+  - [OIDC Module](#oidc-module)
   - [Configuration](#configuration)
     - [Project config](#project-config)
     - [Connectors from config](#connectors-from-config)
@@ -112,6 +121,7 @@ Description-Content-Type: text/markdown
     - [SQL drivers](#sql-drivers)
     - [AI Capabilities](#ai-capabilities)
     - [Vector DB (Qdrant)](#vector-db-qdrant)
+    - [Vector DB (pgvector)](#vector-db-pgvector)
     - [ClickHouse Support](#clickhouse-support)
     - [Install All Extras](#install-all-extras)
   - [Registry Usage](#registry-usage)
@@ -119,6 +129,13 @@ Description-Content-Type: text/markdown
     - [Quick map](#quick-map)
     - [Global options](#global-options)
     - [`minix init`](#minix-init)
+    - [`minix db`](#minix-db)
+      - [Migration workflow](#migration-workflow)
+      - [Migration commands](#migration-commands)
+      - [Revision targets](#revision-targets)
+      - [Migration recipes](#migration-recipes)
+      - [How migrations work](#how-migrations-work)
+      - [Migration troubleshooting](#migration-troubleshooting)
     - [`minix add module`](#minix-add-module)
       - [SQL binding (all or none)](#sql-binding-all-or-none)
       - [Flags](#flags)
@@ -290,6 +307,24 @@ class DocumentEntity(QdrantEntity):
         return "documents"
 ```
 
+#### PGVector Entity (PostgreSQL vectors)
+
+Requires the `pgvector` extra and a PostgreSQL server with the `vector` extension.
+
+```python
+from sqlalchemy import Text
+from sqlalchemy.orm import Mapped, mapped_column
+from minix.core.entity import PGVectorEntity
+
+class DocumentEmbeddingEntity(PGVectorEntity):
+    vector_size = 1536
+
+    content: Mapped[str] = mapped_column(Text, nullable=False)
+```
+
+PGVector entities are SQL entities: they include `id`, `created_at` and
+`updated_at`, plus a `vector` column of type `VECTOR(vector_size)`.
+
 #### Redis Entity
 
 ```python
@@ -360,6 +395,27 @@ class DocumentRepository(QdrantRepository[DocumentEntity]):
 - `query(entity, top_k)` - Similarity search
 - `delete(entity_ids)` - Delete vectors
 
+#### PGVector Repository
+
+```python
+from minix.core.repository import PGVectorRepository
+
+class DocumentEmbeddingRepository(PGVectorRepository[DocumentEmbeddingEntity]):
+    def get_distance(self) -> str:
+        return 'Cosine'  # or 'Euclid', 'Dot', 'Manhattan'
+```
+
+It extends `SqlRepository` (all SQL methods above, `sql_transaction()`
+included) and uses the registered `SqlConnector`, which must point at PostgreSQL.
+
+**Additional methods:**
+- `create_extension()` - Run `CREATE EXTENSION IF NOT EXISTS vector`
+- `search(vector, top_k, max_distance=None, **kwargs)` - Nearest neighbours, closest first; `kwargs` filter like `get_by`
+- `search_with_distance(vector, top_k, max_distance=None, **kwargs)` - Same, as `(entity, distance)` pairs
+
+`PGVectorService` exposes the same `search` / `search_with_distance` methods,
+plus `get_knn(entity, top_k)`, on top of `SqlService`.
+
 ### Services
 
 Services contain business logic:
@@ -724,7 +780,7 @@ every request when the key is set but empty): `.env` gets a random key and
 Repeated `minix add rag` calls leave the generated files unchanged. Afterwards,
 reinstall (for example `poetry lock && poetry install`), install Poppler for local
 PDF ingestion, set the model provider's API key in `.env`, and create the SQL tables
-as described below.
+with `minix db makemigrations -m "add rag" && minix db migrate` (see [`minix db`](#minix-db)).
 
 **Manual registration** — in a project from `minix init` with PostgreSQL as the `default`
 database, add the module to `installed_modules` in `config.py`:
@@ -739,8 +795,15 @@ installed_modules: list[str] = Field(
 ```
 
 `bootstrap_from_settings()` (already called in `entries/api.py`) then registers
-the connectors and installs the module. Create its tables once, or manage the
-schema with Alembic:
+the connectors and installs the module. Create its tables with
+[`minix db`](#minix-db):
+
+```bash
+minix db makemigrations -m "add rag"
+minix db migrate
+```
+
+Without migrations, create them once from code instead:
 
 ```python
 from minix.core.connectors import SqlConnector
@@ -825,6 +888,64 @@ through `provides=` on the paired repository and service.
 
 ---
 
+## OIDC Module
+
+`minix.core.modules.oidc` is a standalone OpenID Connect module (it does not depend on the core `auth` module): authorization-code login with a signed session cookie, bearer-token validation against the IdP's JWKS, role mapping, tenant resolution, a token client and a login hook. Add `OidcModule` to `INSTALLED_MODULES` and set at least `OIDC_ISSUER` and `OIDC_CLIENT_ID`.
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `OIDC_ISSUER` / `OIDC_CLIENT_ID` / `OIDC_CLIENT_SECRET` | — | IdP issuer URL (discovery) and client credentials |
+| `OIDC_AUDIENCE` | `OIDC_CLIENT_ID` | Accepted `aud` for bearer tokens; a comma-separated list accepts several audiences. ID tokens at the login callback are always checked against `OIDC_CLIENT_ID` |
+| `OIDC_ALGORITHMS` | `RS256,ES256,PS256` | Allowed signing algorithms; `none` and `HS*` are always rejected |
+| `OIDC_ALLOWED_REDIRECT_HOSTS` | empty | Hosts allowed as absolute `redirect` targets on login/logout (otherwise only relative paths) |
+| `OIDC_AUTO_CREATE_TABLE` | `true` | Create the OIDC users table once at startup |
+| `OIDC_TENANT_CLAIM` | `organization` | Token claim holding the user's organization(s); `none` disables tenant resolution (everyone gets their personal tenant) |
+| `OIDC_SCOPES` | `openid profile email` | Add `offline_access` to receive a refresh token. Keycloak only emits the `organization` claim when the `organization` scope is requested, e.g. `openid profile email organization` |
+| `OIDC_ROLE_CLAIM` / `OIDC_ROLE_MAP` / `OIDC_DEFAULT_ROLE` | `realm_access.roles` / — / `user` | Role extraction and mapping |
+| `OIDC_JWKS_TTL` | `3600` | JWKS cache seconds (an unknown `kid` triggers one refetch, at most once per 60 s) |
+| `OIDC_SESSION_SECRET` / `OIDC_SESSION_COOKIE` / `OIDC_SESSION_TTL` / `OIDC_COOKIE_SECURE` | — / `minix_session` / `28800` / `true` | Session cookie |
+
+**Dependencies and identity** — `get_oidc_user` and `RequireOidcRole` return an `OidcContext` (`user_id`, `email`, `role`, `claims`, `tenant_id`, `tenant_name`, `tenant_is_personal`) or raise 401/403. `resolve_oidc_context(request)` returns an `OidcContext` or `None` when the request is unauthenticated. `resolve_identity(request, fallbacks)` returns an `OidcContext`, whatever identity the first matching fallback returns, or `None`. `resolve_identity` tries a bearer from the configured issuer, then the minix session cookie, then each fallback (`async (request) -> identity | None`). A bearer from a different issuer is skipped, so the app's own JWTs reach its fallbacks; an invalid bearer from the configured issuer returns `None` without trying fallbacks. An invalid or expired minix session cookie is treated as "no session" and falls through to the fallbacks (unlike an invalid bearer from the configured issuer).
+
+**Tenants** — the tenant comes from `OIDC_TENANT_CLAIM`, which may be a single alias string, a list of aliases, or Keycloak's map form `{alias: {"id": ...}}` (the `id` becomes `tenant_id`, the alias `tenant_name`; an entry without `id` uses its alias). With several organizations the caller picks one with the `X-Organization` header (matching id or alias). Users without an organization get a personal tenant `user:{sub}` (`tenant_is_personal=True`); organization ids starting with `user:` are ignored so they cannot collide with personal tenants. `resolve_oidc_context` and `resolve_identity` can raise `HTTPException` 400 (`organization_selection_required`) or 403 (`organization_not_in_token`) for multi-organization users: call them from FastAPI dependencies, or handle the exception. Set `OIDC_TENANT_CLAIM=none` (or `""` in `settings.py`) to disable tenant resolution: every identity gets its personal tenant and `X-Organization` is ignored.
+
+For browser sessions, organization membership is a snapshot taken at login and stored in the session cookie: changes at the IdP apply at the next login or when the session expires (`OIDC_SESSION_TTL`, default 8 h). Session cookies issued by 0.3.3 carry no organizations and resolve as personal until the user logs in again. Very large organization claims enlarge the cookie accordingly.
+
+**Token client** — `OidcTokenClient` (registered by `OidcModule`) wraps the token endpoint and returns `TokenSet` (`access_token`, `expires_at`, `refresh_token`, `scope`):
+
+```python
+from minix.core.registry import Registry
+from minix.core.modules.oidc import OidcTokenClient
+
+client = Registry().get(OidcTokenClient)
+svc = client.client_credentials(audience="billing-api")
+fresh = client.refresh(refresh_token)
+downstream = client.exchange(subject_token=access_token, audience="other-api")  # RFC 8693
+client.revoke(refresh_token)
+```
+
+Errors: `OidcError` (base), `OidcTokenRevoked`, `OidcExchangeDenied`, `OidcUnavailable` (also raised for 5xx and unexpected 3xx responses).
+
+`OidcTokenClient` is synchronous: each call blocks on an HTTP request (10 s timeout). From async code, run it in the threadpool:
+
+```python
+from starlette.concurrency import run_in_threadpool
+
+tokens = await run_in_threadpool(client.exchange, access_token, "other-api")
+```
+
+**Login hook** — implement `OidcLoginHook.on_login(claims, token_response)` (sync or `async def`) and register it with `Registry().register(OidcLoginHook, instance)`. It runs once per successful login, before the session cookie is issued; an async hook is awaited. If it raises, the login fails with HTTP 500 and no session is set. minix never stores the token response: the hook owns it.
+
+**Schema ownership** — apps that manage their schema with Alembic set `OIDC_AUTO_CREATE_TABLE=false` and include the exported table in their migrations:
+
+```python
+from minix.core.modules.oidc import OIDC_USERS_TABLE  # SQLAlchemy Table, usable in env.py / autogenerate
+```
+
+**Security notes** — login/logout `redirect` accepts relative paths only (absolute URLs only for `OIDC_ALLOWED_REDIRECT_HOSTS`; userinfo and percent-encoded authority are rejected). JWT verification and the user upsert run in a threadpool; the upsert is skipped when nothing changed (300 s cache).
+
+---
+
 ## Configuration
 
 Minix uses a **pydantic-settings** config module (`config.py`).
@@ -940,6 +1061,12 @@ pip install "minix[ai]"
 pip install "minix[vdb]"
 ```
 
+### Vector DB (pgvector)
+
+```bash
+pip install "minix[pgvector]"
+```
+
 ### ClickHouse Support
 
 ```bash
@@ -958,7 +1085,7 @@ pip install "minix[rag]"
 ### Install All Extras
 
 ```bash
-pip install "minix[postgresql,mysql,ai,vdb,clickhouse,rag]"
+pip install "minix[postgresql,pgvector,mysql,ai,vdb,clickhouse,rag]"
 ```
 
 ---
@@ -1003,8 +1130,13 @@ minix add module --help
 | New project in cwd | `minix init APP_NAME` |
 | New project with RAG | `minix init APP_NAME --rag` |
 | Enable built-in RAG in an existing project | `minix add rag` |
+| Set up migrations (once per project) | `minix db init` |
+| Generate a migration from entity changes | `minix db makemigrations -m "message"` |
+| Apply / revert migrations | `minix db migrate` / `minix db downgrade -1` |
+| Inspect migrations | `minix db current` / `minix db history` |
 | New feature module | `minix add module MODULE_NAME` |
 | Add to existing module | `minix add controller\|task\|periodic\|helper\|consumer\|binding [NAME] --module=MODULE` |
+| Refresh coding-agent guidance | `minix sync agents` (`--check` to verify) |
 | Version | `minix -v` / `minix --version` |
 
 ### Global options
@@ -1069,8 +1201,11 @@ installs the engines you selected.
 | `Dockerfile` | App image (`pip install "minix~=X.Y.Z"` / extras from PyPI) |
 | `docker-compose.yml` | PostgreSQL or MySQL, Redis, MinIO, API, Celery; optional Qdrant / ClickHouse / MLflow |
 | `.dockerignore` | Build context excludes |
-| `AGENTS.md` | CLI guide for AI coding agents (prefer `minix` over hand-scaffolding) |
+| `AGENTS.md` | Rules for AI coding agents (CLI, decision flow, upstream-first) inside a Minix-managed block |
+| `CLAUDE.md` | Imports `AGENTS.md` for Claude Code; add project rules below the managed block |
+| `.claude/skills/minix/` | Claude Code skill: concept map, patterns, upstream workflow |
 | `entries/` | `api.py`, `worker.py`, `beat.py` process entrypoints |
+| `migrations/<connection>/` | Alembic setup per SQL connection, driven by [`minix db`](#minix-db) |
 
 **App wiring after init** (settings, not legacy `app_connectors.py` / `app_modules.py`):
 
@@ -1114,6 +1249,192 @@ pip install "minix[mysql]"
 pip install "minix[postgresql,mysql]"
 ```
 
+### `minix db`
+
+Database migrations for your SQL entities, built on
+[Alembic](https://alembic.sqlalchemy.org/). If you know Django, the commands
+will feel familiar: change an entity, run `makemigrations`, review the file,
+then run `migrate`.
+
+Minix compares the database with the SQL entities of the modules in
+`INSTALLED_MODULES`, so you never list tables by hand. Alembic ships with the
+`postgresql`, `mysql` and `rag` extras.
+
+#### Migration workflow
+
+`minix init` already sets up migrations. For a project created another way,
+run `minix db init` once.
+
+```bash
+# 1. Change an entity (or add a module with `minix add module orders`)
+# 2. Generate a migration; the database must be running
+minix db makemigrations -m "add orders"
+#    → default: wrote migrations/default/versions/3f2a9c1b7d4e_add_orders.py
+
+# 3. Read the generated file and fix anything autogenerate got wrong
+# 4. Apply it
+minix db migrate
+#    → default: migrated to head
+
+# 5. Commit the file in migrations/<connection>/versions/ with the entity change
+```
+
+On every other machine, including CI, staging and production, only run
+`minix db migrate`.
+
+Autogenerate is a draft, not a guarantee. Always read the file before you
+apply it. In particular, a renamed column or table shows up as a drop plus an
+add, which loses data. Change it to `op.alter_column(..., new_column_name=...)`
+or `op.rename_table(...)`.
+
+#### Migration commands
+
+These commands do more than Alembic's equivalents:
+
+| Command | What it does | Options |
+|---------|--------------|---------|
+| `minix db init` | Creates `migrations/<connection>/` for each PostgreSQL / MySQL connection. Existing files are kept. | `--database/-d NAME` (repeatable; default: every PostgreSQL / MySQL connection) |
+| `minix db makemigrations` | Compares the entities with the live database and writes a migration. Writes nothing when there are no changes. | `-m/--message`, `--database/-d`, `--empty` (blank migration to write by hand) |
+| `minix db migrate [REVISION]` | Applies migrations, up to `head` by default. | `--database/-d` |
+| `minix db downgrade REVISION` | Reverts migrations. | `--database/-d` |
+
+These run the Alembic command of the same name. Minix picks the connection and
+loads `config.py` and `.env`; every other argument goes to Alembic unchanged,
+and `minix db <command> --help` shows Alembic's own help:
+
+| Command | What it does | Example |
+|---------|--------------|---------|
+| `current` | Shows the revision the database is at | `minix db current` |
+| `history` | Lists migrations, newest first | `minix db history -v`, `minix db history -r-3:current` (no space after `-r`) |
+| `heads` | Shows the latest revision(s); more than one means history has split | `minix db heads` |
+| `branches` | Shows where history splits | `minix db branches` |
+| `show` | Shows one migration | `minix db show 3f2a` |
+| `check` | Exits non-zero when entities have changes without a migration | `minix db check` |
+| `stamp` | Records a revision in the database without running anything | `minix db stamp head` |
+| `merge` | Writes a migration that joins two heads | `minix db merge -m "merge" heads` |
+| `edit` | Opens a migration in `$EDITOR` | `minix db edit head` |
+
+All commands accept `--database/-d NAME` (repeatable). Without it, they run for
+every connection that has a `migrations/` directory, with an `== name ==`
+header per connection when there are several.
+
+#### Revision targets
+
+`migrate`, `downgrade`, `stamp` and `show` take a revision:
+
+| Target | Meaning |
+|--------|---------|
+| `head` | The latest migration |
+| `heads` | Every head, when history has split |
+| `base` | Before the first migration (`downgrade base` reverts everything) |
+| `3f2a9c1b7d4e` or `3f2a` | A revision id, or any unique prefix of one |
+| `-1`, `-2` | Steps back from the current revision (`downgrade`) |
+| `+1`, `+2` | Steps forward from the current revision (`migrate`) |
+
+#### Migration recipes
+
+**Write a data migration.** Generate an empty migration and fill in
+`upgrade()` and `downgrade()`:
+
+```bash
+minix db makemigrations --empty -m "backfill order status"
+```
+
+```python
+def upgrade() -> None:
+    op.execute("UPDATE orders SET status = 'NEW' WHERE status IS NULL")
+
+
+def downgrade() -> None:
+    pass
+```
+
+**Catch missing migrations in CI.** With the database migrated to head, this
+fails when someone changed an entity without running `makemigrations`:
+
+```bash
+minix db migrate && minix db check
+```
+
+**Adopt migrations on a database that already has its tables.**
+`makemigrations` compares with the live database, so against a database that
+already has the tables it finds nothing to write. Generate the first migration
+against an empty database, then mark existing databases as up to date:
+
+```bash
+# Against an empty local database
+minix db makemigrations -m "initial"
+minix db migrate
+
+# Against each database that already has the tables (staging, production)
+minix db stamp head
+```
+
+**Resolve two migrations from parallel branches.** When two branches each add a
+migration, `migrate` and `makemigrations` fail with a "multiple heads" error.
+Join them, then migrate:
+
+```bash
+minix db heads                    # shows both
+minix db merge -m "merge" heads
+minix db migrate
+```
+
+**Remove a module.** Its tables stay in the database, because Minix never drops
+tables that no installed module owns. To drop them, write the drop in an empty
+migration (`makemigrations --empty`, then `op.drop_table("orders")`).
+
+**Use several databases.** Each `settings.DATABASES` connection gets its own
+`migrations/<connection>/` and only manages the tables of entities bound to it
+with `add_binding(..., connection="analytics")`:
+
+```bash
+minix db init -d analytics
+minix db makemigrations -m "add events" -d analytics
+minix db migrate                  # every connection
+minix db migrate -d analytics     # one connection
+```
+
+**Preview the SQL instead of running it.** Use Alembic directly with `--sql`:
+
+```bash
+alembic -c migrations/default/alembic.ini upgrade head --sql
+```
+
+**Run in Docker.** Migrate before the new app version starts serving:
+
+```bash
+docker compose run --rm app minix db migrate
+```
+
+#### How migrations work
+
+- `migrations/<connection>/` holds `alembic.ini`, `env.py`, `script.py.mako`
+  and `versions/`. `env.py` calls `minix.core.migrations.run_migrations`, which
+  loads `.env` and `config.py`, so plain `alembic -c migrations/<connection>/alembic.ini …`
+  works on the same files.
+- Each connection compares only the tables of the entities bound to it. Tables
+  that no installed module owns, including other connections' tables, are never
+  touched.
+- The `default` connection records its revision in `alembic_version`; others use
+  `alembic_version_<connection>`, so two connections can share one database.
+- On PostgreSQL, generated downgrades also drop the enum types of the tables
+  they drop, so a downgrade followed by `migrate` works.
+- ClickHouse connections are skipped, because Alembic does not support them.
+
+#### Migration troubleshooting
+
+| Message | Fix |
+|---------|-----|
+| `No config.py found` | Run the command in the project root. |
+| `Alembic is not installed` | `pip install "minix[postgresql]"` (or `mysql`). |
+| `No migrations set up` / `No migrations for 'x'` | `minix db init`, or `minix db init -d x`. |
+| `Target database is not up to date` | `minix db migrate`, then run `makemigrations` again. |
+| `Multiple head revisions are present` / `Multiple heads are present` | `minix db merge -m "merge" heads`, then `minix db migrate`. |
+| Connection refused | Start the database (`docker compose up -d`) and check `DB_*` in `.env`. |
+| `type "…" already exists` on PostgreSQL | An enum type was left behind by a downgrade. Drop it in the migration (`op.execute('DROP TYPE IF EXISTS "name"')`), or by hand. |
+| `type "…" does not exist` after adding an enum column | Alembic creates enum types with new tables but not with new columns. Add `sa.Enum(..., name="name").create(op.get_bind(), checkfirst=True)` before `op.add_column(...)`. |
+
 ### `minix add module`
 
 Scaffold a feature module under `src/modules/<name>/`.
@@ -1211,7 +1532,7 @@ src/modules/<name>/
 #### After scaffolding
 
 1. Confirm `INSTALLED_MODULES` contains e.g. `"src.modules.orders.OrdersModule"`.
-2. Implement fields on the entity; add an Alembic migration if the app uses one.
+2. Implement fields on the entity, then `minix db makemigrations -m "add orders" && minix db migrate`.
 3. Expand service / controller as needed.
 4. Restart API / worker.
 
@@ -1257,6 +1578,22 @@ minix add task ShipOrder -m orders               # ShipOrderTask
 minix add binding -m payments --entity=Payment
 ```
 
+### Coding agents
+
+`minix init` writes guidance for AI coding agents: `AGENTS.md`, `CLAUDE.md` and the
+Claude Code skill in `.claude/skills/minix/`. Minix owns the text between the
+`<!-- BEGIN MINIX -->` / `<!-- END MINIX -->` markers and the skill directory; anything
+you write outside the markers is kept. The guidance tells agents to build with the CLI
+and Minix's base classes, and to add missing generic capabilities to Minix instead of
+the project.
+
+After upgrading Minix, refresh it so the guidance matches the installed version:
+
+```bash
+minix sync agents            # write
+minix sync agents --check    # exit 1 if stale (for CI)
+```
+
 ---
 
 ## License