stkit 17.0.0__py3-none-any.whl

stk/public/views.py

@@ -0,0 +1,344 @@
+import datetime
+import secrets
+
+import httpx
+from authlib.integrations.httpx_client import AsyncOAuth2Client
+from authlib.oidc.core import CodeIDToken
+from joserfc import jwt
+from joserfc.jwk import KeySet
+from quart import (
+    Blueprint,
+    current_app,
+    flash,
+    g,
+    redirect,
+    render_template,
+    request,
+    send_from_directory,
+    session,
+    url_for,
+)
+from quart_security import current_user
+from quart_security.proxies import _security
+from sqlalchemy import select
+
+from stk.user.models import OAuth, User
+
+public = Blueprint("public", __name__, static_folder="../static")
+
+
+def get_real_ip():
+    return request.remote_addr
+
+
+def create_oauth_user(provider_data, ip_address):
+    now = datetime.datetime.now()
+    user = User(
+        email=provider_data.get("email"),
+        username=provider_data.get("email"),
+        name=provider_data.get("name", ""),
+        password=User.random_password(),
+        password_set=False,
+        active=True,
+        confirmed_at=now,
+        current_login_at=now,
+        current_login_ip=ip_address,
+        login_count=1,
+    )
+    return user
+
+
+@public.route("/health")
+async def health():
+    import stk.extensions as ext
+
+    status = {"status": "ok", "checks": {}}
+
+    # DB check
+    try:
+        from sqlalchemy import text
+
+        async with ext.engine.connect() as conn:
+            await conn.execute(text("SELECT 1"))
+        status["checks"]["database"] = "ok"
+    except Exception:
+        status["checks"]["database"] = "error"
+        status["status"] = "degraded"
+
+    # Redis check (if configured)
+    session_interface = getattr(current_app, "session_interface", None)
+    backend = getattr(session_interface, "backend", None)
+    if backend is not None:
+        try:
+            await backend.ping()
+            status["checks"]["redis"] = "ok"
+        except Exception:
+            status["checks"]["redis"] = "error"
+            status["status"] = "degraded"
+
+    code = 200 if status["status"] == "ok" else 503
+    return status, code
+
+
+@public.route("/")
+async def index():
+    return await render_template("index.html")
+
+
+@public.route("/robots.txt")
+async def static_from_root():
+    return await send_from_directory(public.static_folder, request.path[1:])
+
+
+# OAuth transactions use single-use server state and PKCE.
+GOOGLE_DISCOVERY_URL = "https://accounts.google.com/.well-known/openid-configuration"
+GITHUB_AUTHORIZE_URL = "https://github.com/login/oauth/authorize"
+GITHUB_TOKEN_URL = "https://github.com/login/oauth/access_token"
+GITHUB_API_URL = "https://api.github.com"
+
+
+async def authentication_failed():
+    await flash(
+        "Authentication failed. Use your existing sign-in method.", category="error"
+    )
+    return redirect(url_for("security.login"))
+
+
+async def handle_oauth_callback(provider_name, token, user_info):
+    provider_user_id = (
+        user_info.get("sub") if provider_name == "google" else user_info.get("id")
+    )
+    email = user_info.get("email")
+    if (
+        not token
+        or not provider_user_id
+        or not email
+        or user_info.get("email_verified") is not True
+    ):
+        return await authentication_failed()
+    account = await g.db_session.scalar(
+        select(OAuth).where(
+            OAuth.provider == provider_name,
+            OAuth.provider_user_id == str(provider_user_id),
+        )
+    )
+    if account:
+        user = account.user
+    else:
+        # Email ownership at an IdP does not authorize linking local credentials.
+        existing = await g.db_session.scalar(select(User).where(User.email == email))
+        if existing:
+            return await authentication_failed()
+        user = create_oauth_user(
+            {
+                "email": email,
+                "name": user_info.get("name") or user_info.get("login", ""),
+            },
+            get_real_ip(),
+        )
+        g.db_session.add_all(
+            [
+                user,
+                OAuth(
+                    provider=provider_name,
+                    provider_user_id=str(provider_user_id),
+                    user=user,
+                ),
+            ]
+        )
+        await g.db_session.commit()
+    if not user.active or (
+        user.locked_until
+        and user.locked_until > datetime.datetime.now(datetime.UTC).replace(tzinfo=None)
+    ):
+        return await authentication_failed()
+    if current_user.is_authenticated:
+        await _security.logout_user()
+    if current_app.config.get("SECURITY_TWO_FACTOR") and user.tf_primary_method:
+        session["tf_user_id"] = await _security.state_store.put(
+            {"user_id": user.get_id()}, ttl=300
+        )
+        return redirect(url_for("security.two_factor_token_validation"))
+    await _security.login_user(user)
+    return redirect(url_for("portal.dashboard"))
+
+
+def get_google_client():
+    return AsyncOAuth2Client(
+        client_id=current_app.config.get("GOOGLE_OAUTH_CLIENT_ID"),
+        client_secret=current_app.config.get("GOOGLE_OAUTH_CLIENT_SECRET"),
+        code_challenge_method="S256",
+    )
+
+
+def get_github_client():
+    return AsyncOAuth2Client(
+        client_id=current_app.config.get("GITHUB_OAUTH_CLIENT_ID"),
+        client_secret=current_app.config.get("GITHUB_OAUTH_CLIENT_SECRET"),
+        code_challenge_method="S256",
+    )
+
+
+async def google_discovery():
+    async with httpx.AsyncClient(timeout=10) as client:
+        response = await client.get(GOOGLE_DISCOVERY_URL)
+        response.raise_for_status()
+        return response.json()
+
+
+async def start_oauth(provider):
+    if current_user.is_authenticated or not current_app.config.get(
+        f"{provider.upper()}_AUTH_ENABLED"
+    ):
+        return await authentication_failed()
+    verifier, nonce = secrets.token_urlsafe(48), secrets.token_urlsafe(32)
+    public_url = current_app.config.get("STK_PUBLIC_URL")
+    redirect_uri = (
+        (public_url.rstrip("/") + url_for(f"public.{provider}_callback"))
+        if public_url
+        else url_for(f"public.{provider}_callback", _external=True)
+    )
+    client = get_google_client() if provider == "google" else get_github_client()
+    try:
+        endpoint = (
+            (await google_discovery())["authorization_endpoint"]
+            if provider == "google"
+            else GITHUB_AUTHORIZE_URL
+        )
+        auth_url, state = client.create_authorization_url(
+            endpoint,
+            redirect_uri=redirect_uri,
+            scope="openid profile email"
+            if provider == "google"
+            else "read:user user:email",
+            code_verifier=verifier,
+            nonce=nonce,
+        )
+        session[f"oauth_{provider}"] = await _security.state_store.put(
+            {
+                "state": state,
+                "verifier": verifier,
+                "nonce": nonce,
+                "redirect_uri": redirect_uri,
+            },
+            ttl=300,
+        )
+        return redirect(auth_url)
+    finally:
+        await client.aclose()
+
+
+async def consume_oauth(provider):
+    if not current_app.config.get(f"{provider.upper()}_AUTH_ENABLED"):
+        return None
+    token = session.pop(f"oauth_{provider}", None)
+    state, code = request.args.get("state"), request.args.get("code")
+    if not token or not state or not code:
+        return None
+    transaction = await _security.state_store.pop(token)
+    if not transaction or not secrets.compare_digest(state, transaction["state"]):
+        return None
+    return transaction
+
+
+@public.route("/login/google")
+async def google_login():
+    return await start_oauth("google")
+
+
+@public.route("/login/github")
+async def github_login():
+    return await start_oauth("github")
+
+
+@public.route("/login/google/callback")
+async def google_callback():
+    try:
+        transaction = await consume_oauth("google")
+        if transaction is None:
+            return await authentication_failed()
+        discovery = await google_discovery()
+        async with get_google_client() as client:
+            token = await client.fetch_token(
+                discovery["token_endpoint"],
+                code=request.args["code"],
+                redirect_uri=transaction["redirect_uri"],
+                code_verifier=transaction["verifier"],
+            )
+        async with httpx.AsyncClient(timeout=10) as client:
+            response = await client.get(discovery["jwks_uri"])
+            response.raise_for_status()
+            decoded = jwt.decode(
+                token["id_token"],
+                KeySet.import_key_set(response.json()),
+                algorithms=["RS256"],
+            )
+            claims = CodeIDToken(
+                decoded.claims,
+                decoded.header,
+                options={
+                    "iss": {
+                        "essential": True,
+                        "values": [
+                            "https://accounts.google.com",
+                            "accounts.google.com",
+                        ],
+                    },
+                    "aud": {
+                        "essential": True,
+                        "value": current_app.config["GOOGLE_OAUTH_CLIENT_ID"],
+                    },
+                },
+                params={
+                    "client_id": current_app.config["GOOGLE_OAUTH_CLIENT_ID"],
+                    "nonce": transaction["nonce"],
+                    "access_token": token["access_token"],
+                },
+            )
+            claims.validate(leeway=60)
+        return await handle_oauth_callback("google", token, claims)
+    except Exception:
+        current_app.logger.exception("Google OAuth failed")
+        return await authentication_failed()
+
+
+@public.route("/login/github/callback")
+async def github_callback():
+    try:
+        transaction = await consume_oauth("github")
+        if transaction is None:
+            return await authentication_failed()
+        async with get_github_client() as client:
+            token = await client.fetch_token(
+                GITHUB_TOKEN_URL,
+                code=request.args["code"],
+                redirect_uri=transaction["redirect_uri"],
+                code_verifier=transaction["verifier"],
+            )
+        async with httpx.AsyncClient(timeout=10) as client:
+            headers = {
+                "Authorization": f"Bearer {token['access_token']}",
+                "Accept": "application/json",
+            }
+            response = await client.get(f"{GITHUB_API_URL}/user", headers=headers)
+            response.raise_for_status()
+            user_info = response.json()
+            response = await client.get(
+                f"{GITHUB_API_URL}/user/emails", headers=headers
+            )
+            response.raise_for_status()
+            primary = next(
+                (
+                    email
+                    for email in response.json()
+                    if email.get("primary") and email.get("verified")
+                ),
+                None,
+            )
+            if not primary:
+                return await authentication_failed()
+            user_info.update(email=primary["email"], email_verified=True)
+        return await handle_oauth_callback("github", token, user_info)
+    except Exception:
+        current_app.logger.exception("GitHub OAuth failed")
+        return await authentication_failed()

stk/scaffold/__init__.py

@@ -0,0 +1 @@
+"""Module scaffolder for stk -- generates deterministic blueprint structure."""

stk/scaffold/app/CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+Guidance for coding agents working on __App__. `AGENTS.md` is a symlink to this file.
+
+__App__ is built on stk, installed as the `stkit` package and imported as `stk`.
+`__app__/app.py` composes it: `Stk(__name__, config=Config, extensions=[...])`, where each
+extension is a package in `__app__/` with `init_app(app)`. Never edit stk's files: they
+are replaced on every upgrade. Override a template or static file by putting one at the
+same path in `__app__/templates/` or `__app__/static/`; `stk/<name>` is the original.
+
+## Where truth lives
+
+1. **The running app.** Ask it before reading files: `uv run stk inspect context --json` (routes with auth, models), `uv run stk inspect commands --json` (every command and option), `uv run stk doctor` (app state, each problem with its fix). `uv run stk new <module>` writes the canonical CRUD extension; copy its patterns.
+2. **stk's docs** at https://docs.stk.dev, indexed for agents at https://docs.stk.dev/llms.txt. Read the page for your task before writing code.
+3. **Skills** in `.claude/skills/` (mirrored at `.agents/skills/`): `stk-blueprint`, `stk-api`, `stk-migrate`, `stk-deploy`, and `stk-lessons` (when a gotcha the docs missed costs you time, log one line in `.stk/lessons.md`).
+
+## Commands
+
+```bash
+uv run stk run                      # Dev server at localhost:5000 (--port 5001 on macOS)
+uv run stk db upgrade               # stk's migrations, then the app's
+uv run stk install                  # Create admin user
+uv run stk doctor                   # What is wrong, and the command that fixes it
+uv run stk new <module>             # Extension + migration, ends at a URL
+uv run stk verify --watch           # Re-run affected checks on every save
+uv run stk smoke --json             # Real-browser behavioral check
+uv run stk shell -c "await count(User)"   # One-shot query against the real app
+uv run stk db revision -m "desc"    # Autogenerate in the app's lineage, then: uv run stk db upgrade
+uv run ruff check --fix . && uv run ruff format .
+uv run python -m unittest discover -s tests
+```
+
+## Rules that fail silently
+
+Backend:
+- Async SQLAlchemy, no `db` object. Models inherit `Base` from `stk/extensions.py`. Requests use `g.db_session`; CLI code and tasks use `ext.async_session_factory()`.
+- Every handler is `async def`; every DB call is awaited. Import from `quart` and `quart_security`, never `flask*`.
+- Every relationship uses `lazy="selectin"`. Never read a relationship on a row you just `add()`ed: load it with `await session.get(...)` or a query, or you get `MissingGreenlet`.
+- `User.from_dict()`, `Activity.register()`, `Session.create_session()` and the auth signal handlers are async.
+- Pagination is manual: `offset().limit()` plus `select(func.count())`. List endpoints return `orjson` via `Response(json.dumps(data), content_type="application/json")`.
+- Mutations arrive as `{item: {...}}`: read `json_data.get("item", {})`.
+- `Activity.register()` stores audit events and does not broadcast. `broadcast()` needs an explicit recipient and reaches only sockets on the same worker.
+- SQLite migrations: DDL is not transactional; a new NOT NULL column needs `server_default` in migration and model; keep the constraint naming convention on `Base.metadata`.
+- `stk verify` blocks drops, renames, retypes, and NOT NULL adds without a default in `upgrade()`. A rename is usually a mistaken drop + add from autogenerate; mark a deliberate one with `# destructive: <reason>`.
+- Tests: subclass `TestingConfig` (`stk/settings.py`), never `Config`; `.env` loads at import. Pin any other env-driven switch a test depends on.
+- Apps attach tables to core ones by foreign key (`user.id`); core models are fixed. App revisions depend on stk's head, so never merge heads by hand.
+- An app overrides a template or static file by putting one at the same path; `stk/<name>` is the original. Override a block, do not copy the layout. Python is never overridden.
+
+Frontend:
+- Vue Options API (`data()`, `methods`, `mounted()`), never Composition API. Delimiters are `${}`. Every page uses `mixins: [layoutMixin]` and calls `registerStkComponents(app)` before mount.
+- Server data JSON `<script>` tags go in `{% block js %}`, never `{% block content %}`: Vue strips scripts inside `#app`.
+- Template expressions cannot see page globals: `app.config.globalProperties.name = value` before mount. The production build fails silently, so look at the rendered page.
+- Vuetify 4 uses MD3 type classes (`text-title-large`, not `text-h6`); MD2 classes do nothing. Icons are Tabler (`ti ti-*`), never MDI.
+- Logout is POST-only (`layoutMixin.logout()`).
+
+Security:
+- stk owns authentication in-process. Do not swap in a third-party auth service unless that is the task.
+- All mutations require CSRF. A sessionless webhook opts out with `@csrf_exempt` from `stk.security` under the route decorator and must authenticate the caller itself (e.g. HMAC).
+- Public password registration stays off by default. OAuth never auto-links emails and still enforces local MFA.
+- Agent browser login (`STK_ENABLE_AGENT_LOGIN`) is development/testing only; startup fails elsewhere.
+- Never commit secrets, databases, reviews, or machine paths: `stk verify` fails on them.
+
+Product:
+- Rename an app with `APP_NAME` / `APP_TAGLINE` / `APP_DESCRIPTION` and its own `templates/_brand.html` and favicon. Never edit names across templates.
+- Before reporting UI work done, run `uv run stk smoke` and look at a screenshot with real rows. A 200 and green tests do not prove a page renders.

stk/scaffold/app/Dockerfile

@@ -0,0 +1,41 @@
+# syntax=docker/dockerfile:1.4
+FROM python:3.12-slim AS builder
+
+WORKDIR /app
+
+# Install build deps + uv in one layer (git, for dependencies pinned to a commit)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential python3-dev git \
+    && rm -rf /var/lib/apt/lists/* \
+    && pip install --no-cache-dir uv
+
+# Install dependencies
+COPY pyproject.toml uv.lock ./
+RUN uv sync --extra full --frozen --no-dev --no-install-project
+
+# Runtime
+FROM python:3.12-slim
+
+WORKDIR /app
+ENV PATH="/app/.venv/bin:$PATH" \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+# Install runtime deps and create user
+RUN apt-get update && apt-get install -y --no-install-recommends curl libexpat1 \
+    && rm -rf /var/lib/apt/lists/* \
+    && useradd -m -u 1000 stk
+
+# Copy venv and app
+COPY --from=builder --chown=stk:stk /app/.venv ./.venv
+COPY --chown=stk:stk . .
+
+# Create instance dir with correct ownership
+RUN mkdir -p /app/instance && chown stk:stk /app/instance
+
+USER stk
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:5000/ || exit 1
+
+CMD ["uvicorn", "__app__.app:app", "--host", "0.0.0.0", "--port", "5000"]

stk/scaffold/app/README.md

@@ -0,0 +1,16 @@
+# __App__
+
+Built on [stk](https://github.com/level09/stk) __stk_version__. The app composes stk
+from `__app__/app.py` and never edits stk's files.
+
+```bash
+uv run stk db upgrade     # stk's migrations, then the app's
+uv run stk install        # admin user
+uv run stk run            # http://localhost:5000
+uv run stk new <module>   # an extension: blueprint, model, page, migration
+uv run stk verify && uv run stk smoke
+```
+
+Upgrade stk by reading its release note, raising the `stkit` range in
+`dependencies` if the major version changed, then `uv lock --upgrade-package stkit`,
+`uv sync`, `uv run stk db upgrade`, `uv run stk verify`, and `uv run stk smoke`.

stk/scaffold/app/__app__/__init__.py

@@ -0,0 +1 @@
+"""__App__."""

stk/scaffold/app/__app__/app.py

@@ -0,0 +1,8 @@
+from stk import Stk
+
+from __app__.settings import Config
+
+# Each extension is a package with init_app(app); order is precedence.
+extensions = []
+
+app = Stk(__name__, config=Config, extensions=extensions)

stk/scaffold/app/__app__/settings.py

@@ -0,0 +1,7 @@
+import os
+
+import stk
+
+
+class Config(stk.Config):
+    APP_NAME = os.environ.get("APP_NAME", "__App__")

stk/scaffold/app/claude/skills/stk-api/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: stk-api
+description: |
+  Generate async CRUD API endpoints for an existing stk model. Use when adding API routes, REST endpoints, or CRUD operations to an stk blueprint.
+argument-hint: "[ModelName]"
+---
+
+# Generate CRUD API for $ARGUMENTS
+
+## Current state
+
+Models available:
+!`grep -rn "class.*Base" */*/models.py 2>/dev/null`
+
+Existing API routes:
+!`grep -rn "@bp_[a-z_]*\.\(get\|post\|put\|delete\|patch\|route\)" */*/views.py 2>/dev/null | head -30`
+
+## Steps
+
+1. **Find the model** named `$ARGUMENTS` in the codebase. Read its full definition to understand fields, relationships, and existing `to_dict()`/`from_dict()`.
+
+2. **Generate these endpoints** in the model's blueprint views.py:
+
+   - `GET /api/<plural>` — List with pagination, search, filtering
+   - `POST /api/<singular>/` — Create (note trailing slash)
+   - `POST /api/<singular>/<id>` — Update (POST, not PUT — stk convention)
+   - `DELETE /api/<singular>/<id>` — Delete
+
+3. **Follow the conventions** in https://docs.stk.dev/api/: blueprint-level auth, `{item: {...}}`
+   payloads, `{items, total, perPage}` list responses via `orjson`, `Activity.register` on
+   every mutation, rollback plus `log.exception` on failure, and `{"message": ...}` with
+   400/404/412. The reference implementation is what `uv run stk new` writes
+   (`render_views` in `stk/scaffold/templates.py`); match it.
+
+4. **List endpoint:** `PER_PAGE = 25`, `page`/`per_page` params, an optional `search` param
+   with `ilike` on the text fields, and the total counted from `query.subquery()` so filters
+   apply to it.
+
+5. **Create/Update:** create calls `await Model().from_dict(data)` and `flush()`es before the
+   audit entry so the ID exists; update stores `to_dict()` before changing the row and logs
+   old and new.
+
+6. **If a page route doesn't exist yet**, add one:
+   ```python
+   @bp.get("/<plural>/")
+   async def <plural>_page():
+       return await render_template("<name>/index.html")
+   ```
+
+7. **Verify:**
+   - Run `uv run ruff check --fix . && uv run ruff format .`
+   - Run `uv run stk verify`

stk/scaffold/app/claude/skills/stk-blueprint/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: stk-blueprint
+description: |
+  Scaffold a new extension in an stk app: blueprint, model, page, sidebar entry, and Alembic migration. Use when creating a new feature module, adding a new section to the app, or scaffolding a blueprint.
+argument-hint: "[blueprint-name]"
+---
+
+# Scaffold stk Blueprint
+
+Create a complete extension for `$ARGUMENTS` in the app package (run from the app's directory).
+
+## Workflow
+
+The scaffolder generates the full module structure. Run it first, then customize domain fields and logic.
+
+```bash
+uv run stk new <name>
+```
+
+`<name>` must be lowercase snake_case (e.g. `blog_post`, `invoice_line`). Reserved names (`user`, `role`, `portal`, `public`, `session`, `admin`, etc.) are rejected with a clear error.
+
+The command generates, inside the app package (`myapp/`):
+- `<name>/__init__.py` with `init_app(app)`: registers the blueprint and appends the sidebar entry to `app.navigation`
+- `<name>/models.py`, `<name>/views.py`, `<name>/templates/<name>/index.html`
+- Adds `<name>` to `extensions` in the app module (import + list entry)
+- Generates AND applies the migration in the app's lineage, then prints the page URL
+
+It never edits a stk file. Then:
+1. Customize `<name>/models.py` -- add/rename fields to fit your domain; point at core tables by foreign key (`ForeignKey("user.id")`)
+2. If you changed the model after scaffolding: `uv run stk db revision -m "update <name>"` and review, then `uv run stk db upgrade`
+   (only needed for post-scaffold model edits; the initial migration is already applied. With `--no-migrate`, the first revision is manual)
+3. Verify: `uv run stk verify && uv run stk smoke`
+
+## Conventions
+
+The generated files already follow every stk convention. When you change them, the rules
+are in `CLAUDE.md` and the details in https://docs.stk.dev/models/, https://docs.stk.dev/api/, and
+https://docs.stk.dev/frontend/. Read the page before editing that layer.
+
+## Before you report done
+
+Each line is a mistake an agent made while building a real app on stk.
+
+- Lint and format only the files you changed (`uv run ruff format path/a.py path/b.py`), never a whole package another person owns.
+- Tests: give test-only blueprints names an app cannot already use.
+- Migrations: check each command's exit code, never behind a pipe to `tail`. Never delete a revision file before `stk db downgrade <target>` has succeeded.
+- Tables inside Vue's in-DOM templates: never put `<tbody>`/`<tr>` inside `<v-table>` or another custom element; the browser parser moves the rows out before Vue mounts and they never render. Use `v-data-table`, a native `<table>`, or flex rows.
+- Verify UI in a browser: `uv run stk smoke`, then look at a screenshot of the page with real rows. A 200 and green tests do not prove columns, labels or buttons render.

stk/scaffold/app/claude/skills/stk-deploy/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: stk-deploy
+description: Deploy an stk app to production on a fresh VPS with HTTPS, systemd, and a hardened OS. Use when taking an stk app live, deploying to a server, or setting up production hosting for a domain.
+argument-hint: "[domain]"
+---
+
+# Deploy stk App to Production
+
+One-shot production install via `deploy.sh` (framework root). Installs Caddy
+(auto-TLS, security headers, static caching), a systemd service, a non-root app
+user, generated secrets, and hardens the box (SSH key-only, fail2ban, ufw).
+SQLite by default, PostgreSQL+Redis optional.
+
+## Prerequisites
+
+1. Fresh Ubuntu/Debian VPS with root SSH access.
+2. DNS A record for the domain pointing at the server (Caddy needs it for TLS).
+3. App repo pushed to GitHub **and public**, or see the private-repo note below.
+
+## Install (non-interactive)
+
+Run from your machine against the server, or on the server as root:
+
+```bash
+wget -qO /tmp/deploy.sh https://raw.githubusercontent.com/level09/stk/master/deploy.sh
+sudo DOMAIN=example.com REPO=<github-user>/<repo> bash /tmp/deploy.sh
+```
+
+Every variable and what the script installs: https://docs.stk.dev/deployment/.
+
+Ends at a live `https://<domain>` with an admin login. Credentials are saved
+on the server at `/home/<app-user>/.credentials`.
+
+## Hard warnings
+
+- **Never re-run deploy.sh on a live app.** It is install-only: it deletes and
+  re-clones the app directory. With SQLite the database is
+  `instance/stk.db` *inside* that directory, so a re-run destroys production
+  data. Use the update flow below.
+- **Private repos fail silently at the clone step**: the script clones over
+  plain HTTPS. Either make the repo public, or pre-seed a read-only GitHub
+  token on the server and clone via `git@github.com:` manually first.
+
+## Update flow (every deploy after the first)
+
+```bash
+ssh <app-user>@<domain>
+cd ~/<domain>
+git pull
+uv sync --frozen --no-dev
+uv run --no-sync stk db upgrade   # stk's migrations and the app's, if any are new
+sudo systemctl restart <domain>.service
+```
+
+The app user's sudoers allows managing only its own service.
+
+## Verify
+
+- `curl -I https://<domain>` returns 200/302 with the security headers.
+- Log in as admin, create a throwaway record, restart the service, confirm it
+  survives (proves the DB path).