simple-module-cli 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

simple_module_cli/app_project.py

@@ -15,6 +15,8 @@ from __future__ import annotations
 import json as _json
 import secrets as _secrets
 from collections.abc import Sequence
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
 from pathlib import Path
 
 from simple_module_cli._env import set_env_key
@@ -25,7 +27,23 @@ from simple_module_cli.scaffolding import create_host
 
 __all__ = ["create_app_project"]
 
-_FRAMEWORK_VERSION = "0.0.1"
+
+def _resolve_framework_version() -> str:
+    """Resolve the framework version to pin scaffolded apps against.
+
+    The CLI ships in lockstep with the rest of the framework (one
+    ``bump_version.py`` rewrites every ``pyproject.toml`` in the repo), so
+    its own installed version is the source of truth. Falling back to a
+    placeholder lets editable installs without dist-info still scaffold —
+    but that path should never be reached in a release wheel.
+    """
+    try:
+        return _pkg_version("simple_module_cli")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+_FRAMEWORK_VERSION = _resolve_framework_version()
 
 _APP_PY_DEV_DEPS = [f"simple_module_test=={_FRAMEWORK_VERSION}", "pytest>=8.0"]
 

simple_module_cli/case.py

@@ -13,9 +13,17 @@ __all__ = ["to_kebab_case", "to_pascal_case", "to_snake_case"]
 
 
 def to_snake_case(name: str) -> str:
-    """'MyFeature' / 'my-feature' / 'My Feature' -> 'my_feature'."""
-    s = re.sub(r"(?<!^)(?=[A-Z])", "_", name)
-    s = re.sub(r"[\s\-]+", "_", s)
+    """'MyFeature' / 'my-feature' / 'My Feature' / 'URLPath' -> 'my_feature' / 'url_path'.
+
+    Handles acronyms by treating ``Acronym|Word`` and ``word|Capital`` as
+    boundaries: ``URLPath`` -> ``url_path``, ``APIClient`` -> ``api_client``,
+    ``HTTPServer2`` -> ``http_server2``. The single-pass ``(?=[A-Z])`` form
+    that preceded this would emit ``u_r_l_path`` and propagate the typo
+    into the PyPI slug + display name.
+    """
+    s = re.sub(r"[\s\-]+", "_", name)
+    s = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", s)
+    s = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s)
     return s.lower()
 
 

simple_module_cli/catalog.py

@@ -36,12 +36,11 @@ CATALOG: dict[str, ModuleEntry] = {
         "Permissions",
         requires=("auth", "users"),
     ),
-    "products": ModuleEntry("products", "simple_module_products", "Products"),
     "dashboard": ModuleEntry(
         "dashboard",
         "simple_module_dashboard",
         "Dashboard",
-        requires=("users", "products"),
+        requires=("users",),
     ),
     "settings": ModuleEntry("settings", "simple_module_settings", "Settings"),
     "feature_flags": ModuleEntry("feature_flags", "simple_module_feature_flags", "Feature Flags"),
@@ -58,12 +57,6 @@ CATALOG: dict[str, ModuleEntry] = {
         requires=("users",),
         recipe="background_tasks",
     ),
-    "datasets": ModuleEntry(
-        "datasets",
-        "simple_module_datasets",
-        "Datasets",
-        requires=("file_storage", "background_tasks"),
-    ),
 }
 
 

simple_module_cli/cli.py

@@ -4,6 +4,7 @@ Built-in commands:
   sm new
   sm create-host
   sm create-module
+  sm skills add / list / update
 
 Plugins discovered via the ``simple_module_cli.cli_plugins`` entry-point
 group are mounted as named subgroups (e.g. ``sm host gen-pages``).
@@ -18,9 +19,11 @@ import typer
 
 from simple_module_cli.case import to_kebab_case
 from simple_module_cli.new import new_project
+from simple_module_cli.package_update import package_update
 from simple_module_cli.plugins import discover_and_mount
 from simple_module_cli.scaffolding import create_host as _create_host
 from simple_module_cli.scaffolding import create_module as _create_module
+from simple_module_cli.skills_cmd import app as skills_app
 
 app = typer.Typer(
     help="SimpleModule developer CLI.",
@@ -29,6 +32,8 @@ app = typer.Typer(
 )
 
 app.command("new")(new_project)
+app.command("package-update")(package_update)
+app.add_typer(skills_app, name="skills")
 
 
 @app.command("create-host")
@@ -42,7 +47,7 @@ def create_host(
         str,
         typer.Option(
             "--with",
-            help="Comma-separated module names to declare as deps (e.g. Auth,Products).",
+            help="Comma-separated module names to declare as deps (e.g. Auth,Dashboard).",
         ),
     ] = "",
 ) -> None:

simple_module_cli/new.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import shutil
 import subprocess
 from enum import StrEnum
 from pathlib import Path
@@ -109,6 +110,13 @@ def new_project(
 
     typer.echo("Installing dependencies...")
     for cmd in (["uv", "sync"], ["npm", "install"]):
+        if shutil.which(cmd[0]) is None:
+            typer.echo(
+                f"WARNING: '{cmd[0]}' not found on PATH; skipping `{' '.join(cmd)}`. "
+                "Install it and finish setup manually.",
+                err=True,
+            )
+            return
         result = subprocess.run(cmd, cwd=target, check=False)
         if result.returncode != 0:
             typer.echo(

simple_module_cli/package_update.py

@@ -0,0 +1,287 @@
+"""``sm package-update`` — bump simple_module_* deps to latest PyPI versions.
+
+Walks the project's ``pyproject.toml`` (and any ``[tool.uv.workspace]`` members),
+finds every dependency whose distribution name starts with ``simple_module_`` /
+``simple-module-``, queries PyPI for the latest non-yanked release, and rewrites
+the constraint to ``name>=<latest>``.
+
+Dependencies whose ``[tool.uv.sources]`` entry points at a workspace member, a
+local path, a git ref, or a URL are left untouched — those aren't installed
+from PyPI.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated, Any
+
+import tomlkit
+import typer
+from tomlkit.items import Array, Table
+
+__all__ = ["package_update", "run_update"]
+
+Fetcher = Callable[[str], dict[str, Any]]
+
+_PYPI_URL = "https://pypi.org/pypi/{name}/json"
+_SM_PREFIX_RE = re.compile(r"^simple[_-]module[_-]", re.IGNORECASE)
+# PEP 440 release segments contain only digits + dots; any letter signals
+# a pre/post/dev release (a, b, rc, post, dev). Coarser than packaging.version
+# but `packaging` isn't a CLI dep (see test_no_framework_deps.py).
+_PRE_RELEASE_RE = re.compile(r"[a-zA-Z]")
+_REQ_OPS = ("===", "==", ">=", "<=", "!=", "~=", ">", "<")
+
+
+@dataclass(frozen=True)
+class Change:
+    file: Path
+    package: str
+    old: str
+    new: str
+
+
+@dataclass(frozen=True)
+class Skip:
+    file: Path
+    package: str
+    reason: str
+
+
+def _is_sm_package(name: str) -> bool:
+    return bool(_SM_PREFIX_RE.match(name))
+
+
+def _dep_name(spec: str) -> str | None:
+    """Extract the distribution name from a PEP 508 requirement string."""
+    base = spec.split(";", 1)[0].strip()
+    base = base.split("[", 1)[0]
+    for op in _REQ_OPS:
+        if op in base:
+            base = base.split(op, 1)[0]
+            break
+    name = base.strip()
+    return name or None
+
+
+def _is_local_source(source: Any) -> bool:
+    if not isinstance(source, dict):
+        return False
+    if source.get("workspace") is True:
+        return True
+    return any(key in source for key in ("path", "git", "url"))
+
+
+def _get_uv_section(doc: tomlkit.TOMLDocument, key: str) -> dict[str, Any] | None:
+    tool = doc.get("tool")
+    if not isinstance(tool, dict):
+        return None
+    uv = tool.get("uv")
+    if not isinstance(uv, dict):
+        return None
+    section = uv.get(key)
+    return section if isinstance(section, dict) else None
+
+
+def _fetch_latest(name: str, *, include_pre: bool, fetcher: Fetcher) -> str | None:
+    try:
+        data = fetcher(_PYPI_URL.format(name=name))
+    except (urllib.error.HTTPError, urllib.error.URLError):
+        return None
+    releases = data.get("releases") or {}
+    candidates: list[str] = []
+    for version, files in releases.items():
+        if not files:
+            continue
+        if any(f.get("yanked") for f in files):
+            continue
+        if not include_pre and _PRE_RELEASE_RE.search(version):
+            continue
+        candidates.append(version)
+    if candidates:
+        return max(candidates, key=_version_key)
+    info = data.get("info") or {}
+    return info.get("version")
+
+
+def _version_key(v: str) -> tuple[int, ...]:
+    parts: list[int] = []
+    for part in v.split("."):
+        digits = re.match(r"\d+", part)
+        parts.append(int(digits.group()) if digits else 0)
+    return tuple(parts)
+
+
+def _default_fetcher(url: str) -> dict[str, Any]:
+    with urllib.request.urlopen(url, timeout=10) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def _workspace_member_dirs(root_pyproject: Path, doc: tomlkit.TOMLDocument) -> list[Path]:
+    workspace = _get_uv_section(doc, "workspace")
+    if workspace is None:
+        return []
+    members = workspace.get("members") or []
+    base = root_pyproject.parent
+    out: list[Path] = []
+    for pattern in members:
+        for match in sorted(base.glob(str(pattern))):
+            if (match / "pyproject.toml").is_file():
+                out.append(match / "pyproject.toml")
+    return out
+
+
+def _local_sources(doc: tomlkit.TOMLDocument) -> set[str]:
+    sources = _get_uv_section(doc, "sources")
+    if sources is None:
+        return set()
+    return {name for name, src in sources.items() if _is_local_source(src)}
+
+
+def _collect_sm_deps(doc: tomlkit.TOMLDocument) -> list[str]:
+    """Return distribution names of simple_module_* deps in this doc that aren't local-sourced."""
+    project = doc.get("project")
+    if not isinstance(project, (dict, Table)):
+        return []
+    deps = project.get("dependencies")
+    if not isinstance(deps, (list, Array)):
+        return []
+    local = _local_sources(doc)
+    out: list[str] = []
+    for raw in deps:
+        name = _dep_name(str(raw))
+        if name and _is_sm_package(name) and name not in local:
+            out.append(name)
+    return out
+
+
+def _process_file(
+    path: Path,
+    doc: tomlkit.TOMLDocument,
+    *,
+    cache: dict[str, str | None],
+) -> tuple[list[Change], list[Skip], tomlkit.TOMLDocument | None]:
+    project = doc.get("project")
+    if not isinstance(project, (dict, Table)):
+        return [], [], None
+    deps = project.get("dependencies")
+    if not isinstance(deps, (list, Array)):
+        return [], [], None
+
+    local = _local_sources(doc)
+    changes: list[Change] = []
+    skips: list[Skip] = []
+
+    for idx, raw in enumerate(deps):
+        dep_str = str(raw)
+        name = _dep_name(dep_str)
+        if not name or not _is_sm_package(name):
+            continue
+        if name in local:
+            skips.append(Skip(path, name, "workspace/local source"))
+            continue
+        latest = cache.get(name)
+        if latest is None:
+            skips.append(Skip(path, name, "not found on PyPI"))
+            continue
+        new_dep = f"{name}>={latest}"
+        if new_dep == dep_str.strip():
+            continue
+        deps[idx] = new_dep
+        changes.append(Change(path, name, dep_str.strip(), new_dep))
+
+    return changes, skips, doc if changes else None
+
+
+def _print_summary(changes: list[Change], skips: list[Skip], dry_run: bool) -> None:
+    if not changes and not skips:
+        typer.echo("No simple_module_* dependencies found.")
+        return
+    by_file: dict[Path, list[str]] = {}
+    for c in changes:
+        by_file.setdefault(c.file, []).append(f"  {c.package}: {c.old}  →  {c.new}")
+    for s in skips:
+        by_file.setdefault(s.file, []).append(f"  {s.package}: skipped ({s.reason})")
+    for file, lines in by_file.items():
+        typer.echo(f"\n{file}")
+        for line in lines:
+            typer.echo(line)
+    if changes:
+        verb = "Would update" if dry_run else "Updated"
+        typer.echo(f"\n{verb} {len(changes)} dependency(ies) across {len(by_file)} file(s).")
+        if not dry_run:
+            typer.echo("Run `uv sync` to apply.")
+    elif skips:
+        typer.echo("\nNo updates applied.")
+
+
+def run_update(
+    path: Path,
+    *,
+    dry_run: bool = False,
+    include_pre: bool = False,
+    fetcher: Fetcher | None = None,
+) -> None:
+    """Programmatic entry point — separated from the Typer command for testing."""
+    root = path if path.name == "pyproject.toml" else path / "pyproject.toml"
+    if not root.is_file():
+        typer.echo(f"ERROR: {root} not found.", err=True)
+        raise typer.Exit(code=1)
+
+    fetch = fetcher or _default_fetcher
+    root_doc = tomlkit.parse(root.read_text(encoding="utf-8"))
+    files: list[tuple[Path, tomlkit.TOMLDocument]] = [(root, root_doc)]
+    for member in _workspace_member_dirs(root, root_doc):
+        files.append((member, tomlkit.parse(member.read_text(encoding="utf-8"))))
+
+    # Pre-fetch all unique sm packages in parallel — PyPI calls dominate runtime.
+    unique_names = sorted({n for _, doc in files for n in _collect_sm_deps(doc)})
+    cache: dict[str, str | None] = {}
+    if unique_names:
+        with ThreadPoolExecutor(max_workers=min(8, len(unique_names))) as pool:
+            results = pool.map(
+                lambda n: (n, _fetch_latest(n, include_pre=include_pre, fetcher=fetch)),
+                unique_names,
+            )
+            cache = dict(results)
+
+    all_changes: list[Change] = []
+    all_skips: list[Skip] = []
+    pending: list[tuple[Path, tomlkit.TOMLDocument]] = []
+
+    for file, doc in files:
+        changes, skips, new_doc = _process_file(file, doc, cache=cache)
+        all_changes.extend(changes)
+        all_skips.extend(skips)
+        if new_doc is not None:
+            pending.append((file, new_doc))
+
+    if not dry_run:
+        for file, doc in pending:
+            file.write_text(tomlkit.dumps(doc), encoding="utf-8")
+
+    _print_summary(all_changes, all_skips, dry_run)
+
+
+def package_update(
+    path: Annotated[
+        Path,
+        typer.Option("--path", help="Project root or pyproject.toml. Defaults to cwd."),
+    ] = Path(),
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Show planned changes without writing."),
+    ] = False,
+    include_pre: Annotated[
+        bool,
+        typer.Option("--include-pre", help="Include pre-release versions."),
+    ] = False,
+) -> None:
+    """Update all simple_module_* dependencies to the latest PyPI versions."""
+    run_update(path, dry_run=dry_run, include_pre=include_pre)

simple_module_cli/skills/README.md

@@ -0,0 +1,58 @@
+# simple_module_python skills
+
+Agent skills for working in a [simple_module_python](https://github.com/antosubash/simple_module_python) codebase. Compatible with Claude Code, Codex, Cursor, Windsurf, OpenCode, and any other agent that supports the [Agent Skills format](https://agentskills.io/specification).
+
+## Install
+
+There are two install paths — pick whichever fits your project.
+
+### Option A — `sm skills` (recommended for `simple_module_cli` users)
+
+Every project produced by `sm new` already depends on `simple_module_cli`, which ships these skills inside its wheel. From the project root:
+
+```bash
+sm skills list                                          # see what's available
+sm skills add                                           # install ALL skills into ./.claude/skills/
+sm skills add simple-module-creating                    # install just one
+sm skills add -g                                        # install into ~/.claude/skills (machine-wide)
+sm skills add --dest agents/skills                      # custom target dir
+sm skills add --symlink                                 # symlink to the bundled source (good for skill devs)
+sm skills update                                        # re-pull updates for skills already installed
+sm skills update simple-module-doctor                   # explicit re-pull (force-overwrites)
+```
+
+`sm skills` resolves the bundled set against whatever version of `simple_module_cli` is installed, so upgrading the CLI ships skill updates the next time you run `sm skills update`.
+
+### Option B — `npx skills` (no Python install needed)
+
+```bash
+npx skills add antosubash/simple_module_python          # all skills, current project
+npx skills add antosubash/simple_module_python -g       # globally
+npx skills add antosubash/simple_module_python --skill simple-module-creating -a claude-code
+npx skills add antosubash/simple_module_python --list
+```
+
+The CLI is [vercel-labs/skills](https://github.com/vercel-labs/skills); see its README for symlink-vs-copy and other options.
+
+## What's here
+
+| Skill | Use when |
+|---|---|
+| [simple-module-cli](./simple-module-cli/SKILL.md) | Invoking the `sm` CLI — `sm new`, `sm create-host`, `sm create-module`, `sm host gen-pages`, `sm users create-admin`, etc. |
+| [simple-module-creating](./simple-module-creating/SKILL.md) | Adding a new feature package — scaffolding, entry-point, `ModuleMeta` |
+| [simple-module-conventions](./simple-module-conventions/SKILL.md) | Writing or reviewing module code — the invariant list (SQLModel everywhere, settings layout, framework→plugin direction, etc.) |
+| [simple-module-database](./simple-module-database/SKILL.md) | Adding SQLModel tables, picking a mixin, or debugging session/transaction behavior |
+| [simple-module-migrations](./simple-module-migrations/SKILL.md) | Generating, applying, or reviewing Alembic migrations after installing or changing a module |
+| [simple-module-inertia-pages](./simple-module-inertia-pages/SKILL.md) | Adding or debugging an Inertia page in a module — render keys, shared props, common pitfalls |
+| [simple-module-locales](./simple-module-locales/SKILL.md) | Adding or debugging i18n in a module — `locale_dirs()`, namespaces, CLDR plurals, the Zod-in-hook rule |
+| [simple-module-registries](./simple-module-registries/SKILL.md) | Contributing menu items, permissions, feature flags, or events from a module |
+| [simple-module-testing](./simple-module-testing/SKILL.md) | Writing pytest tests — picking the right fixture (`db_session` / `app` / `authenticated_client`), single-test runs, e2e |
+| [simple-module-doctor](./simple-module-doctor/SKILL.md) | Interpreting a diagnostic code (`SM001`–`SM018`) printed at boot |
+
+The skills are designed to stand alone — install them into any host or module-package project and they'll work without needing access to the framework's source repo.
+
+## Contributing
+
+Each skill is a directory containing a `SKILL.md` with YAML frontmatter (`name`, `description`). The description is "use when…" triggers only — never a workflow summary, because agents will follow the description in lieu of reading the body.
+
+PRs welcome.

simple_module_cli/skills/simple-module-cli/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: simple-module-cli
+description: Use when invoking the `sm` CLI for a simple_module_python project — starting a new app, scaffolding a host or a publishable module, regenerating the Inertia page manifest, importing settings overrides from env, creating an admin user, or installing the bundled agent skills. Triggers on "sm new", "sm create-host", "sm create-module", "sm host gen-pages", "sm users create-admin", "sm skills add", or any unfamiliar `sm` subcommand.
+---
+
+# simple_module_python: the `sm` CLI
+
+The `sm` command is provided by `simple_module_cli` (installed as a dep of `simple_module_hosting`). It groups four kinds of operations: scaffolding new things, project-time helpers for the host, admin shortcuts for the bundled modules, and installing the bundled agent skills.
+
+## Top-level commands
+
+| Command | When to use |
+|---|---|
+| `sm new <name>` | Greenfield: scaffold a complete app (host + selected modules) in one shot, with an interactive wizard for DB / tenancy / module preset |
+| `sm create-host <name>` | You want just a bare host project; you'll add modules later by `pip install`-ing them |
+| `sm create-module <name>` | You're authoring a publishable module package (separate repo, distributed via PyPI) |
+| `sm skills …` | Install / update the bundled agent-skill packs into a project (`add`, `list`, `update`) |
+| `sm host …` | Project-time helpers run from inside a host directory (page manifest, JS dep sync) |
+| `sm settings …` | Settings-module admin — currently `import-from-env` |
+| `sm users …` | Users-module admin — currently `create-admin` |
+
+## `sm new <name>` — the wizard
+
+The fastest way from zero to a working app. It calls `create-host` under the hood, then installs and wires up the modules you pick.
+
+```bash
+# Interactive (asks for DB, tenancy, preset, module list)
+sm new MyApp
+
+# Non-interactive: take all defaults (sqlite, no tenancy, standard preset)
+sm new MyApp --yes
+
+# Pick a preset and add extras
+sm new MyApp --preset full --tenancy --db postgres
+sm new MyApp --preset minimal --with background_tasks,file_storage --yes
+
+# Scaffold only — skip uv sync / npm install / alembic upgrade head
+sm new MyApp --no-install
+```
+
+**Module presets:**
+
+| Preset | Modules included |
+|---|---|
+| `minimal` | `users` (and `auth` as a dep) |
+| `standard` (default) | `users`, `dashboard`, `permissions` (+ deps) |
+| `full` | every module in the catalog |
+| `custom` | interactive — pick each module yes/no |
+
+`--with` accepts a comma-separated list of catalog keys (`auth, users, permissions, products, dashboard, settings, feature_flags, file_storage, background_tasks, …`). Transitive `requires` are auto-added; the wizard prints `Added X (required by Y)` so you can see what got pulled in.
+
+**Options summary:**
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--dest <PATH>` | `./<name>` | Where to write the project |
+| `--db sqlite\|postgres` | `sqlite` | Backend configured in `.env.example` |
+| `--tenancy / --no-tenancy` | `--no-tenancy` | Enable the multi-tenant middleware |
+| `--preset minimal\|standard\|full` | wizard asks | Module bundle |
+| `--with <names>` | none | Extra catalog keys beyond the preset |
+| `--yes / -y` | off | Skip prompts; accept defaults |
+| `--no-install` | off | Skip `uv sync` / `npm install` / `alembic upgrade head` |
+
+## `sm create-host <name>` — bare host
+
+```bash
+sm create-host MyApp                       # empty host, no modules declared
+sm create-host MyApp --with Auth,Products  # declare module deps in pyproject.toml
+sm create-host MyApp --dest ./apps/myapp   # custom destination
+```
+
+`--with` takes **PascalCase module names** (matching `ModuleMeta.name`), not catalog keys. Use this when you want to drive the build yourself rather than via `sm new`'s wizard.
+
+## `sm create-module <name>` — module package
+
+For module authors publishing to PyPI. Scaffolds a standalone repo containing one module.
+
+```bash
+sm create-module orders                    # writes ./simple_module_orders/
+sm create-module orders --dest ./packages/orders
+```
+
+The result is a complete package: `pyproject.toml` with the entry point declared, `module.py` with `ModuleBase`/`ModuleMeta` skeleton, `models.py`, `contracts/`, `endpoints/{api,views}.py`, `pages/`, `locales/en.json`, plus a tests directory wired up with `simple_module_test` fixtures.
+
+`<name>` accepts any case — `orders`, `Orders`, `ORDERS`, `blog_posts` all work. The CLI lowercases it for the directory and PascalCases it for `ModuleMeta.name`.
+
+For the post-scaffold steps (entry point, Inertia namespace, etc.) see **simple-module-creating**.
+
+## `sm skills` — install the bundled agent skills
+
+`simple_module_cli` ships a set of [SKILL.md](https://agentskills.io/specification) packs (the ones in this directory). Drop them into any project so Claude Code / Cursor / Codex / etc. find them automatically.
+
+```bash
+sm skills list                                          # see what's available
+sm skills add                                           # install ALL skills into ./.claude/skills/
+sm skills add simple-module-creating simple-module-cli  # specific ones only
+sm skills add -g                                        # ~/.claude/skills (machine-wide)
+sm skills add --dest agents/skills                      # explicit target dir
+sm skills add --symlink                                 # symlink to bundled source (good when iterating on the skills themselves)
+sm skills update                                        # re-pull whatever is already installed at the dest
+sm skills update simple-module-doctor                   # explicitly re-pull one (always force-overwrites)
+```
+
+**Without `--force`, `sm skills add` skips skills that already exist at the destination** — so re-running it is safe. Use `--force` (or `sm skills update`) to overwrite.
+
+The bundle resolves against your installed `simple_module_cli`. To get newer skills, upgrade the CLI (`uv sync` or `pip install -U simple_module_cli`) and re-run `sm skills update`.
+
+## `sm host gen-pages` — regenerate the Inertia manifest
+
+Run from a host project. Scans every installed module's `pages/*.tsx`, writes `client_app/modules.{manifest.json,generated.ts,generated.css}`, and extends Vite's `server.fs.allow`.
+
+```bash
+sm host gen-pages                              # uses ./client_app
+sm host gen-pages --host-dir=apps/web/client_app
+```
+
+`sm new` runs this at scaffold time; you only need to call it manually after adding/renaming `.tsx` files mid-session, or after `pip install`-ing a new module that ships pages.
+
+## `sm host sync-js-deps` — install module JS deps
+
+Wheel-installed modules ship `package.json` declarations that need to land in the host's `client_app/node_modules`. This command does that. **In-repo workspace modules don't need it** — npm workspaces resolve them automatically.
+
+```bash
+sm host sync-js-deps                           # uses ./client_app
+sm host sync-js-deps --host-client-app=apps/web/client_app
+```
+
+Run after `pip install <module>` if the new module ships frontend code.
+
+## `sm settings import-from-env`
+
+Walks the live environment for every `SM_<PREFIX>_<FIELD>` variable matching a registered settings dataclass and writes a SYSTEM-tier override into the settings module's store. Useful when promoting from environment-driven config (typical in Docker) to in-DB overrides (manageable in the admin UI) without re-keying values by hand.
+
+```bash
+sm settings import-from-env
+```
+
+## `sm users create-admin`
+
+Bootstraps the first admin user, or rotates an existing admin's password.
+
+```bash
+sm users create-admin -e admin@example.com -p hunter2
+sm users create-admin -e admin@example.com -p new-password --force      # rotate
+sm users create-admin -e admin@example.com -p hunter2 --full-name "Admin"
+```
+
+| Flag | Meaning |
+|---|---|
+| `-e, --email` (required) | Admin email |
+| `-p, --password` (required) | Initial password (or new password with `--force`) |
+| `--full-name` | Display name |
+| `--force` | Update the password if the admin already exists; without it, the command exits if the email is taken |
+
+Don't bake `--password` literals into a script you commit; use a secrets store and pass via shell expansion.
+
+## Pitfalls
+
+- **Wrong shell for `--with`.** `sm new` `--with auth,users` (catalog keys, lowercase). `sm create-host` `--with Auth,Users` (`ModuleMeta.name`, PascalCase). They're not interchangeable.
+- **Ran `sm new` inside an existing project.** The default `--dest ./<name>` creates a sibling directory. If the directory already exists and is non-empty, the command errors out — pass `--dest` explicitly to disambiguate.
+- **Ran `sm host gen-pages` from outside the host directory.** Defaults to `./client_app`; pass `--host-dir` from elsewhere.
+- **Forgot `sm host sync-js-deps` after `pip install`-ing a module with pages.** Vite resolves module imports against `client_app/node_modules`; the new module's JS deps won't land until you sync.
+- **Used `sm create-module` to add a module to an existing host.** That command is for **publishable** packages, intended to live in their own repo. To add a module to an existing host: install it (`pip install simple_module_<name>` or add to `pyproject.toml` and `uv sync`), then autogenerate a migration. See **simple-module-creating** + **simple-module-migrations**.
+- **Calling `sm create-admin` before migrations have run.** The users tables don't exist yet; the command will error. Run `alembic upgrade head` first (or use `sm new` which does it for you when `--no-install` isn't set).
+
+## Related skills
+
+- **simple-module-creating** — what `sm create-module` produces and the post-scaffold contract
+- **simple-module-inertia-pages** — what `sm host gen-pages` regenerates and why
+- **simple-module-migrations** — the `alembic upgrade head` step `sm new` runs