# Start an app on stk

You are a coding agent, and your user wants an app built on stk: a strict Python framework for AI coding agents (async Quart, async SQLAlchemy, Vue 3 + Vuetify with no build step, owned auth with 2FA, passkeys and OAuth). stk is published on PyPI as `stkit`; you `import stk` and run `stk`. The app is a separate, thin package that composes stk and never edits a framework file.

Do these steps in order and stop on the first failure. Report each failure with its output instead of patching around it.

## 1. Prerequisites

Python 3.11+ and [uv](https://docs.astral.sh/uv/). Check with `uv --version`; if uv is missing, ask your user to install it.

## 2. Create the app

Pick the package name from what your user described: lowercase snake_case, and no existing directory of that name. Then:

```bash
uvx --from stkit stk init <name>
cd <name>
```

This writes the app package, a `.env` with fresh secrets, `CLAUDE.md` (also `AGENTS.md`) and the stk skills, CI, and the Docker stack. Never copy a `.env` from another project.

## 3. Database and admin

```bash
uv run stk db upgrade
uv run stk install -e <email> -p <password>
```

Use your user's email if they gave one, and generate a strong password. Login rejects reserved domains such as `.local` and `.test`. Give your user the credentials; never commit them.

## 4. Prove it green before any feature work

```bash
uv run playwright install chromium
uv run stk doctor
uv run stk verify --json
uv run stk smoke --json
uv run python -m unittest discover -s tests
```

All must pass. A red bootstrap is a stk bug: report it at https://github.com/level09/stk/issues instead of working around it in the app.

## 5. Read the app's rules

Read the generated `CLAUDE.md` now. It lists the rules that fail silently and the docs page for each kind of task. From here on, ask the running app before reading files: `uv run stk inspect context --json` for routes and models, `uv run stk inspect commands --json` for every command, `uv run stk doctor` for what is wrong and the command that fixes it.

Docs: https://docs.stkit.dev/llms.txt. If your user connected the stk docs MCP server (https://mcp.stkit.dev/mcp), use its `search_docs`, `get_page` and `get_command` tools.

## 6. Commit

```bash
git init -b main && git add -A && git commit -m "chore: bootstrap <name> on stk"
```

`git add -A` is safe only here: `.gitignore` already keeps `.env` and `instance/` out. After this, stage files explicitly.

## 7. Build what your user asked for

- Scaffold each feature with `uv run stk new <module>` (a singular name). It writes an extension and its migration and ends at a URL; copy its patterns.
- Rename the product with `APP_NAME`, `APP_TAGLINE` and `APP_DESCRIPTION`, plus the app's own `templates/_brand.html` and favicon. Never edit names across templates.
- After every change run `uv run stk verify --json`. 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.

## 8. Hand it over

Start it with `uv run stk run` (add `--port 5001` if macOS holds port 5000) and give your user the URL and the admin login.