karni-cli 0.3.1__py3-none-any.whl

karni_cli/_errorcodes/__main__.py

@@ -0,0 +1,34 @@
+"""``python -m karni.errorcodes CODE [--json]``: one registry entry, modules included.
+
+karni-cli's ``karni explain`` runs this in the project interpreter for codes
+it does not bundle (an installed module's, such as ``PAY004``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from karni.errorcodes import get
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m karni.errorcodes")
+    parser.add_argument("code")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    entry = get(args.code)
+    if entry is None:
+        print(f"Unknown code {args.code!r}.", file=sys.stderr)
+        return 1
+    data = entry.as_dict()
+    if args.json:
+        print(json.dumps(data))
+    else:
+        print("\n".join(f"{key}: {value}" for key, value in data.items()))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

karni_cli/_errorcodes/links.py

@@ -0,0 +1,217 @@
+"""Every external URL and address Karni publishes, in one place.
+
+Error messages, deprecation warnings, the changelog, the CLI, the docs site,
+the package metadata and the README all point at these. Change them here,
+then run ``python -m karni.links sync`` to rewrite the files that cannot
+import Python (``pyproject.toml``, ``package.json``, ``mkdocs.yml``, the
+Markdown pages); ``python -m karni.links check`` (run by the test suite)
+fails while any of them still carries an old value.
+
+Stdlib only: ``karni.errorcodes`` imports this module, and karni-cli
+bundles both so ``karni explain`` works without Django or a project.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Final
+
+__all__ = [
+    "DOCS_BASE_URL",
+    "ISSUES_URL",
+    "REPO_SLUG",
+    "REPO_URL",
+    "SECURITY_ADVISORY_URL",
+    "SUPPORT_EMAIL",
+    "docs_page",
+]
+
+#: ``owner/name`` on GitHub.
+REPO_SLUG: Final[str] = "cbsshekhawat18-lab/karni"
+#: The repository.
+REPO_URL: Final[str] = f"https://github.com/{REPO_SLUG}"
+#: The documentation site; ends with a slash. Pages are ``DOCS_BASE_URL + "page/"``.
+DOCS_BASE_URL: Final[str] = "https://cbsshekhawat18-lab.github.io/karni/"
+#: Where bugs go.
+ISSUES_URL: Final[str] = f"{REPO_URL}/issues"
+#: Private vulnerability reports.
+SECURITY_ADVISORY_URL: Final[str] = f"{REPO_URL}/security/advisories/new"
+#: The maintainer's address for security reports that cannot use GitHub.
+SUPPORT_EMAIL: Final[str] = "cbsshekhawat18@gmail.com"
+
+
+def docs_page(page: str, anchor: str = "") -> str:
+    """``docs/<page>.md#anchor`` as the published URL (``…/page/#anchor``)."""
+    path = page.removesuffix(".md").strip("/")
+    url = f"{DOCS_BASE_URL}{path}/" if path else DOCS_BASE_URL
+    return f"{url}#{anchor}" if anchor else url
+
+
+# The files that carry these values literally, and the pattern each one uses.
+# `sync` rewrites them; `check` reports the ones that drifted.
+
+_PYPROJECT_URLS = {
+    "Homepage": lambda: REPO_URL,
+    "Documentation": lambda: DOCS_BASE_URL,
+    "Repository": lambda: REPO_URL,
+    "Issues": lambda: ISSUES_URL,
+    "Changelog": lambda: f"{REPO_URL}/tree/main/docs/migrations",
+}
+
+_PACKAGE_JSON = {
+    "packages/karni-ui/package.json": "packages/karni-ui",
+    "modules/karni-payments/ui/package.json": "modules/karni-payments/ui",
+}
+
+_MKDOCS = {
+    "site_url": lambda: DOCS_BASE_URL,
+    "repo_url": lambda: REPO_URL,
+    "repo_name": lambda: REPO_SLUG,
+}
+
+
+def repo_root() -> Path | None:
+    for parent in Path(__file__).resolve().parents:
+        if (parent / "mkdocs.yml").is_file() and (parent / "packages").is_dir():
+            return parent
+    return None
+
+
+def _sync_pyproject(path: Path, dry_run: bool) -> list[str]:
+    text = path.read_text()
+    out = text
+    for key, value in _PYPROJECT_URLS.items():
+        out = re.sub(rf'^{key} = "[^"]*"$', f'{key} = "{value()}"', out, flags=re.M)
+    return _write(path, text, out, dry_run)
+
+
+def _sync_package_json(path: Path, subdir: str, dry_run: bool) -> list[str]:
+    text = path.read_text()
+    data = json.loads(text)
+    data["repository"] = {"type": "git", "url": f"git+{REPO_URL}.git", "directory": subdir}
+    data["homepage"] = f"{REPO_URL}/tree/main/{subdir}#readme"
+    data["bugs"] = {"url": ISSUES_URL}
+    out = json.dumps(data, indent=2, ensure_ascii=False) + "\n"
+    return _write(path, text, out, dry_run)
+
+
+def _sync_mkdocs(path: Path, dry_run: bool) -> list[str]:
+    text = path.read_text()
+    out = text
+    for key, value in _MKDOCS.items():
+        out = re.sub(rf"^{key}: .*$", f"{key}: {value()}", out, flags=re.M)
+    return _write(path, text, out, dry_run)
+
+
+def _write(path: Path, before: str, after: str, dry_run: bool) -> list[str]:
+    if before == after:
+        return []
+    if not dry_run:
+        path.write_text(after)
+    return [str(path)]
+
+
+def _sync_eslint_docs(path: Path, dry_run: bool) -> list[str]:
+    text = path.read_text()
+    out = re.sub(
+        r'^export const DOCS_BASE_URL = "[^"]*";$',
+        f'export const DOCS_BASE_URL = "{DOCS_BASE_URL}";',
+        text,
+        flags=re.M,
+    )
+    return _write(path, text, out, dry_run)
+
+
+def sync(root: Path, *, dry_run: bool = False) -> list[str]:
+    """Rewrite the metadata files from these constants; returns the files that changed."""
+    changed: list[str] = []
+    for rel in ("packages/karni", "packages/karni-cli", "modules/karni-payments"):
+        changed += _sync_pyproject(root / rel / "pyproject.toml", dry_run)
+    for rel, subdir in _PACKAGE_JSON.items():
+        changed += _sync_package_json(root / rel, subdir, dry_run)
+    changed += _sync_mkdocs(root / "mkdocs.yml", dry_run)
+    changed += _sync_eslint_docs(root / "packages/karni-ui/eslint-plugin/lib/docs.js", dry_run)
+    return changed
+
+
+# Prose (Markdown, YAML, HTML, templates) links to the site and repository by
+# URL. A Karni-looking URL that is not the configured one is stale.
+_PROSE_GLOBS = (
+    "README.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md",
+    "docs/**/*.md",
+    "docs/**/*.html",
+    "docs/**/*.txt",
+    ".github/**/*.yml",
+    "packages/*/README.md",
+    "modules/*/README.md",
+    "modules/*/ui/README.md",
+    "templates/**/*.md",
+    "examples/*/README.md",
+)
+_KARNI_URL = re.compile(
+    r"https://(?:[\w.-]+\.github\.io/karni/?|github\.com/[\w.-]+/karni(?:[/#.)]|$))"
+)
+
+
+def stale_prose(root: Path) -> list[str]:
+    """``file:line: url`` for every Karni site or repository URL that differs from the constants."""
+    stale: list[str] = []
+    for glob in _PROSE_GLOBS:
+        for path in sorted(root.glob(glob)):
+            if "node_modules" in path.parts or "site" in path.parts[:1]:
+                continue
+            for number, line in enumerate(path.read_text(errors="replace").splitlines(), 1):
+                for match in _KARNI_URL.finditer(line):
+                    url = match.group(0).rstrip("/#.)")
+                    if not (url.startswith(DOCS_BASE_URL.rstrip("/")) or url.startswith(REPO_URL)):
+                        stale.append(f"{path.relative_to(root)}:{number}: {url}")
+    return stale
+
+
+def rewrite_prose(root: Path, old: str, new: str) -> list[str]:
+    """Replace ``old`` with ``new`` in every prose file; returns the files that changed."""
+    changed: list[str] = []
+    for glob in _PROSE_GLOBS:
+        for path in sorted(root.glob(glob)):
+            if "node_modules" in path.parts:
+                continue
+            text = path.read_text(errors="replace")
+            changed += _write(path, text, text.replace(old, new), dry_run=False)
+    return changed
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    root = repo_root()
+    if root is None:
+        print("karni.links: not inside the Karni repository", file=sys.stderr)
+        return 2
+    if args == ["sync"]:
+        for path in sync(root):
+            print(f"updated {path}")
+        for entry in stale_prose(root):
+            print(f"still stale (prose; use `sync --rewrite OLD NEW`): {entry}")
+        return 0
+    if len(args) == 4 and args[:2] == ["sync", "--rewrite"]:
+        for path in [*sync(root), *rewrite_prose(root, args[2], args[3])]:
+            print(f"updated {path}")
+        return 0
+    if args == ["check"]:
+        stale = [f"stale: {path}" for path in sync(root, dry_run=True)] + [
+            f"stale: {entry}" for entry in stale_prose(root)
+        ]
+        for line in stale:
+            print(f"{line} (run `python -m karni.links sync`)")
+        return 1 if stale else 0
+    print("usage: python -m karni.links [check|sync|sync --rewrite OLD NEW]", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

karni_cli/_templates/project/cookiecutter.json

@@ -0,0 +1,8 @@
+{
+    "project_name": "My Project",
+    "project_slug": "{{ cookiecutter.project_name.lower().replace(' ', '_').replace('-', '_') }}",
+    "domain": "example.com",
+    "karni_ui": "^0.3.0",
+    "karni_ui_mount": "",
+    "karni_baseline": "0.0.0"
+}

karni_cli/_templates/project/{{cookiecutter.project_slug}}/.dockerignore

@@ -0,0 +1,7 @@
+.git
+.env
+.venv
+**/__pycache__
+*.pyc
+frontend/node_modules
+frontend/dist

karni_cli/_templates/project/{{cookiecutter.project_slug}}/.env.example

@@ -0,0 +1,85 @@
+# Environment for {{ cookiecutter.project_name }}. Copy to .env:
+#   cp .env.example .env
+# Every value has a sane dev default baked into karni; this file makes them
+# explicit. Commented-out vars are optional — leave them commented rather
+# than empty (an empty value overrides the karni default with "").
+
+# --- Core --------------------------------------------------------------------
+DJANGO_ENV=dev
+SECRET_KEY=karni-insecure-dev-key
+DEBUG=True
+ALLOWED_HOSTS=*
+PROJECT_NAME={{ cookiecutter.project_slug }}
+
+# --- Services (docker-compose hostnames) -------------------------------------
+DATABASE_URL=postgres://karni:karni@db:5432/karni
+REDIS_URL=redis://redis:6379/0
+# "redis" (at REDIS_URL) or "locmem" — an in-process cache for a host run
+# without Redis (development only: throttle counters are then per process).
+# KARNI_CACHE=redis
+
+# --- API ---------------------------------------------------------------------
+KARNI_PAGE_SIZE=50
+THROTTLE_ANON=100/min
+THROTTLE_USER=1000/min
+# Comma-separated origins; dev allows all origins regardless.
+# CORS_ALLOWED_ORIGINS=https://app.{{ cookiecutter.domain }}
+# Proxies between clients and Django (Caddy = 1) for throttle IP resolution.
+# KARNI_NUM_PROXIES=1
+# Max ?expand= nesting depth on auto-generated endpoints.
+# KARNI_API_MAX_EXPAND_DEPTH=2
+# Swap the search backend (dotted path to a karni SearchProvider subclass).
+# KARNI_SEARCH_PROVIDER=karni.api.search.postgres.PostgresSearchProvider
+
+# --- Auth & accounts ---------------------------------------------------------
+# "jwt" (SimpleJWT token pairs) or "session" (cookie auth + CSRF bootstrap).
+KARNI_AUTH_MODE=jwt
+# SPA origin used in account emails (verify/reset links) and, in session
+# mode, added to CSRF_TRUSTED_ORIGINS — the browser's origin must match it.
+KARNI_FRONTEND_URL=http://localhost:5173
+# Roles (Django groups) every self-registered user starts with.
+# KARNI_ACCOUNTS_DEFAULT_ROLES=attendee
+# Extra `karni seed` logins (demo password) with their roles, as JSON.
+# KARNI_SEED_LOGINS={"organizer@example.com": ["organizer"], "attendee@example.com": ["attendee"]}
+# Social login via django-allauth (requires karni[social]; session mode only).
+KARNI_SOCIAL_AUTH=False
+# TOTP two-factor auth via django-otp (requires karni[2fa]).
+KARNI_2FA=False
+# Comma-separated allauth providers, e.g. google,github (with KARNI_SOCIAL_AUTH).
+# KARNI_SOCIAL_PROVIDERS=google
+# JWT lifetimes: access in minutes, refresh in days.
+# KARNI_JWT_ACCESS_LIFETIME=15
+# KARNI_JWT_REFRESH_LIFETIME=7
+# JSON object of per-scope auth throttle overrides (null disables a scope).
+# KARNI_AUTH_THROTTLE_RATES={"auth.login": "10/min"}
+
+# --- Admin -------------------------------------------------------------------
+# KARNI_ADMIN_TITLE={{ cookiecutter.project_name }} admin
+# KARNI_ADMIN_AUTODISCOVER=True
+# Comma-separated app labels or app_label.ModelName entries to skip.
+# KARNI_ADMIN_EXCLUDE=sessions,contenttypes,admin
+
+# --- Storage -----------------------------------------------------------------
+# "local" (filesystem) or "s3" (any S3-compatible service; requires karni[s3]).
+KARNI_STORAGE=local
+MEDIA_ROOT=/data/media
+STATIC_ROOT=/data/static
+# AWS_ACCESS_KEY_ID=
+# AWS_SECRET_ACCESS_KEY=
+# AWS_STORAGE_BUCKET_NAME=
+# AWS_S3_ENDPOINT_URL=
+# AWS_S3_REGION_NAME=
+
+# --- Observability -----------------------------------------------------------
+# Sentry is disabled while SENTRY_DSN is empty (requires karni[sentry]).
+SENTRY_DSN=
+SENTRY_TRACES_SAMPLE_RATE=0.0
+
+# --- Deployment --------------------------------------------------------------
+# Domain Caddy serves (and provisions TLS for) in production.
+DOMAIN={{ cookiecutter.domain }}
+
+# Path *inside this project* to a local karni checkout, installed at image
+# build time instead of the PyPI release (see README.md). Example:
+#   cp -r /path/to/Karni/packages/karni ./.karni-src   then   KARNI_SRC=.karni-src
+KARNI_SRC=

karni_cli/_templates/project/{{cookiecutter.project_slug}}/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+.karni-src/
+frontend/node_modules/
+frontend/dist/
+/data/
+# Machine-local karni state (one-time tips etc.); also self-ignored via its own .gitignore.
+.karni/local/

karni_cli/_templates/project/{{cookiecutter.project_slug}}/Caddyfile

@@ -0,0 +1,22 @@
+# Caddy front for {{ cookiecutter.project_name }} in production.
+#
+# Caddy provisions TLS automatically for the DOMAIN env var (defaults to
+# localhost, which uses a self-signed local CA). Static and media files are
+# served straight from /data — share the /data volume with the django
+# container (STATIC_ROOT=/data/static, MEDIA_ROOT=/data/media).
+
+{$DOMAIN:localhost} {
+	encode gzip
+
+	handle /static/* {
+		root * /data
+		file_server
+	}
+
+	handle /media/* {
+		root * /data
+		file_server
+	}
+
+	reverse_proxy django:8000
+}

karni_cli/_templates/project/{{cookiecutter.project_slug}}/Dockerfile

@@ -0,0 +1,53 @@
+# syntax=docker/dockerfile:1
+# Multi-stage build for {{ cookiecutter.project_name }}.
+#
+# Targets:
+#   dev  — used by docker-compose; runserver-friendly, source bind-mounted over /app.
+#   prod — fresh slim image, non-root user, gunicorn with uvicorn workers.
+#
+# Build arg KARNI_SRC: path *inside this project* to a local karni checkout,
+# installed before (and therefore instead of) the PyPI release. Until karni is
+# published, vendor it and set KARNI_SRC in .env — see README.md.
+
+FROM python:3.12-slim AS base
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+FROM base AS deps
+WORKDIR /app
+RUN uv venv /venv
+ARG KARNI_SRC=""
+# Copy the whole context so a vendored karni checkout (KARNI_SRC) is available.
+COPY . /app/
+# Installing KARNI_SRC first satisfies the "karni" requirement, so the
+# pyproject install below skips resolving it from PyPI.
+RUN if [ -n "${KARNI_SRC}" ]; then \
+        uv pip install --python /venv/bin/python "./${KARNI_SRC}"; \
+    fi \
+    && uv pip install --python /venv/bin/python -r pyproject.toml
+
+FROM base AS dev
+WORKDIR /app
+ENV PATH="/venv/bin:${PATH}"
+COPY --from=deps /venv /venv
+COPY . /app/
+EXPOSE 8000
+CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]
+
+FROM python:3.12-slim AS prod
+WORKDIR /app
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PATH="/venv/bin:${PATH}"
+RUN addgroup --system app && adduser --system --ingroup app app
+COPY --from=deps /venv /venv
+COPY . /app/
+# collectstatic at build time. DJANGO_ENV=dev + a dummy SECRET_KEY keep the
+# strict prod validation out of a command that touches no real config.
+RUN mkdir -p /data/static /data/media \
+    && DJANGO_ENV=dev SECRET_KEY=build-only-dummy python manage.py collectstatic --noinput \
+    && chown -R app:app /data
+USER app
+EXPOSE 8000
+CMD ["gunicorn", "config.asgi:application", "-k", "uvicorn_worker.UvicornWorker", "-b", "0.0.0.0:8000"]

karni_cli/_templates/project/{{cookiecutter.project_slug}}/Makefile

@@ -0,0 +1,52 @@
+.PHONY: up down serve migrate types check context rules agents test shell routes schedules superuser logs
+
+# Every target is a thin alias for a `karni` command, which runs through the
+# project .venv when present, else the running compose service.
+
+up:
+	karni serve -d
+
+down:
+	docker compose down
+
+serve:
+	karni serve
+
+migrate:
+	karni make migration
+	karni migrate
+
+types:
+	karni types
+
+check:
+	karni check
+	karni rules sync --check
+
+# Agent guidance: conventions, and regenerating AGENTS.md / CLAUDE.md / tool adapters.
+rules:
+	karni rules
+
+agents:
+	karni rules sync
+
+context:
+	karni context
+
+test:
+	karni test
+
+shell:
+	karni shell
+
+routes:
+	karni routes
+
+schedules:
+	karni schedule list
+
+superuser:
+	karni createsuperuser
+
+logs:
+	docker compose logs -f django worker beat

karni_cli/_templates/project/{{cookiecutter.project_slug}}/README.md

@@ -0,0 +1,169 @@
+# {{ cookiecutter.project_name }}
+
+A [Karni](https://github.com/karni) project: batteries-included Django + DRF +
+Celery, configured almost entirely by `karni_settings(globals())` in
+`config/settings.py`. Every Karni default can be overridden from that file —
+anything you assign after the call wins.
+
+## Quickstart
+
+```sh
+cp .env.example .env
+docker compose up --build
+```
+
+This boots:
+
+| Service    | What                                            | Where                  |
+| ---------- | ----------------------------------------------- | ---------------------- |
+| `django`   | migrations, then Django dev server              | http://localhost:8000  |
+| `db`       | postgres:16                                     | internal (`db:5432`)   |
+| `redis`    | redis:7 (Celery broker + cache)                 | internal (`redis:6379`)|
+| `worker`   | Celery worker                                   | —                      |
+| `beat`     | Celery beat (django-celery-beat DB scheduler)   | —                      |
+| `frontend` | Vite dev server (React + TS), proxies `/api` and `/health` to django | http://localhost:5173 |
+
+Verify the stack (Postgres, Redis and Celery all checked):
+
+```sh
+curl http://localhost:8000/health/ready/
+# {"status": "ok", "checks": {"database": ..., "cache": ..., "celery": ...}}
+```
+
+Other endpoints: liveness at `/health/`, admin at `/admin/`, OpenAPI schema at
+`/api/schema/`, Swagger UI at `/api/docs/`.
+
+## Frontend
+
+`frontend/` is Vite + React + TypeScript on [@karni/ui](https://github.com/karni):
+`src/App.tsx` mounts `KarniProvider` (one `createKarniClient({ baseUrl: "/api" })`),
+`AuthProvider`, the router and a `Toaster`; `src/main.tsx` imports
+`@karni/ui/styles.css` (the `--karni-*` design tokens) and `src/index.css`
+(Tailwind v3 with the `@karni/ui/tailwind-preset`, see `tailwind.config.ts`).
+Every route renders inside `src/layout.tsx` — @karni/ui's `Layout` with one
+nav entry per static route in `src/routes.tsx`, so pages from
+`karni make page` (or `karni make model ... -a`) appear in the sidebar.
+
+```sh
+cd frontend
+npm install
+npm run dev     # http://localhost:5173 — proxies /api and /health to Django
+npm run build   # tsc + vite build into frontend/dist
+npm run lint    # ESLint with the karni/* enforcement rules
+```
+
+The dev server proxies to `http://127.0.0.1:8000` (`karni serve --local`);
+docker compose sets `KARNI_API_PROXY=http://django:8000` for its container.
+
+## Using a local Karni checkout
+
+Until karni and @karni/ui are published, a project can run against a Karni
+checkout.
+
+**@karni/ui.** `karni new` resolves it like the project template:
+`KARNI_UI_SRC=/path/to/Karni/packages/karni-ui` > the Karni checkout `karni`
+itself runs from > the npm release (`^0.1.0`). A local source is written into
+`frontend/package.json` as `"@karni/ui": "file:/abs/path/to/packages/karni-ui"`,
+and `frontend/.npmrc` (`install-links=true`) installs it as a packed copy —
+exactly like the npm release, so React and TanStack Query exist once. The copy
+ships the checkout's built `dist/` (`karni new` builds it when missing). The
+copy is a snapshot — a plain `npm install` does not notice a rebuilt checkout.
+After changing @karni/ui, rebuild it and refresh the copy:
+
+```sh
+(cd /path/to/Karni/packages/karni-ui && npm run build)
+(cd frontend && rm -rf node_modules/@karni/ui && npm install)
+# docker compose: docker compose exec frontend rm -rf node_modules/@karni/ui
+#                 docker compose restart frontend
+```
+
+Under docker compose the `frontend` container runs `npm install` on start and
+gets the checkout mounted read-only at the same absolute path, so the `file:`
+spec resolves inside the container too (the mount is in `docker-compose.yml`
+when `karni new` found a local @karni/ui). The container ignores
+`package-lock.json`, which records the checkout relative to the host's
+`frontend/`. Moving the checkout means updating both `frontend/package.json`
+and that mount, or running `karni new` again.
+
+Without Docker, run everything on the host. Install the project's own
+dependencies into the venv first (`pip install -e . pytest pytest-django`:
+that is what brings `psycopg` for a host PostgreSQL, and pytest for
+`karni test`). Point `.env` at local services
+(`DATABASE_URL=sqlite:///db.sqlite3`, `REDIS_URL=redis://127.0.0.1:6379/0`,
+or `KARNI_CACHE=locmem` to run without Redis at all); settings.py loads it
+automatically (variables you already exported win; set `KARNI_DOTENV=false`
+to skip it). Then `karni serve --local` for Django and `npm run dev` in
+`frontend/`; `karni worker` only when something needs Celery:
+
+```sh
+karni migrate && karni serve --local    # http://127.0.0.1:8000
+(cd frontend && npm run dev)            # http://localhost:5173, in a second shell
+```
+
+**karni (Python).** For the host `.venv` (`karni serve --local`,
+`karni migrate`, ...), install the checkout next to the project's other
+dependencies:
+
+```sh
+uv venv && uv pip install -e /path/to/Karni/packages/karni -r pyproject.toml
+```
+
+For Docker, vendor a checkout into the project and point the `KARNI_SRC`
+build arg at it (docker-compose reads it from `.env`):
+
+```sh
+cp -r /path/to/Karni/packages/karni ./.karni-src
+echo "KARNI_SRC=.karni-src" >> .env   # or edit the existing line
+docker compose build
+```
+
+`KARNI_SRC` must be a path inside this project (the Docker build context).
+The vendored copy is installed before the PyPI dependencies, so it takes
+precedence.
+
+## Day-to-day
+
+Generate code with `karni make` (`karni make --list` shows every generator;
+each runs through the project's `.venv` or the running compose service where
+it needs Django):
+
+```sh
+karni make app events                       # replaces manage.py startapp; wires INSTALLED_APPS
+karni make model Event title:str:200 starts_at:datetime organizer:fk:User -a \
+    --access owned:organizer                # model + viewset + list/detail/form pages
+karni make migration && karni migrate
+karni createsuperuser
+```
+
+Override any Django, DRF, Celery or Karni setting in `config/settings.py`,
+below the `karni_settings()` call. Generators add apps to the `# karni:apps`
+block and middleware to the `# karni:middleware` block — keep those markers.
+
+## AI coding agents
+
+`karni new` generated thin agent adapters — `AGENTS.md`, `CLAUDE.md`,
+`.cursor/rules/karni.mdc`, `.windsurf/rules/karni.md`,
+`.github/copilot-instructions.md`, `.clinerules/karni.md`, `CONVENTIONS.md`,
+`.junie/AGENTS.md` and slash commands. They all say the same thing: run
+`karni context` and `karni rules` first. Do not edit them; put project rules
+in `karni.rules.py` and run `karni rules sync` (`make check` fails when they
+are stale). `karni mcp` serves the same surface over MCP.
+
+## Production
+
+The `prod` Dockerfile target builds a slim, non-root image that runs
+`gunicorn config.asgi:application` with uvicorn workers and collects static
+files to `/data/static` at build time:
+
+```sh
+docker build --target prod -t {{ cookiecutter.project_slug }}:latest .
+```
+
+Run it with `DJANGO_ENV=prod`, a real `SECRET_KEY` and `ALLOWED_HOSTS` —
+Karni validates the configuration at startup and fails loudly on anything
+insecure or missing. Put Caddy in front using the provided `Caddyfile`: it
+provisions TLS for `$DOMAIN` automatically, serves `/static/*` and `/media/*`
+from `/data` (share the `/data` volume between the django container and
+Caddy), and reverse-proxies everything else to `django:8000`. For the
+frontend, `npm run build` in `frontend/` produces static assets you can serve
+from Caddy or any CDN.

karni_cli/_templates/project/{{cookiecutter.project_slug}}/config/__init__.py

@@ -0,0 +1,16 @@
+"""Project package for {{ cookiecutter.project_name }}.
+
+Runs first for every entry point (manage.py, ASGI/WSGI, ``celery -A config``):
+it loads ``.env`` for host runs (variables already set, e.g. by Docker Compose
+or CI, always win; ``KARNI_DOTENV=false`` skips it), then imports the Celery
+app so ``@shared_task`` binds to it whenever Django starts
+(see https://docs.celeryq.dev/en/stable/django/).
+"""
+
+from karni.dotenv import load_dotenv
+
+load_dotenv(__file__)
+
+from config.celery import app as celery_app  # noqa: E402
+
+__all__ = ["celery_app"]