plain 0.101.2__py3-none-any.whl → 0.103.0__py3-none-any.whl

plain/CHANGELOG.md

@@ -1,5 +1,33 @@
 # plain changelog
 
+## [0.103.0](https://github.com/dropseed/plain/releases/plain@0.103.0) (2026-01-30)
+
+### What's changed
+
+- `plain docs` now shows markdown documentation by default (previously required `--source`), with a new `--symbols` flag to show only the symbolicated API surface ([b71dab9d5d](https://github.com/dropseed/plain/commit/b71dab9d5d))
+- `plain docs --list` now shows all official Plain packages (installed and uninstalled) with descriptions and install status ([9cba705d62](https://github.com/dropseed/plain/commit/9cba705d62))
+- `plain docs` for uninstalled packages now shows the install command and an online docs URL instead of a generic error ([9cba705d62](https://github.com/dropseed/plain/commit/9cba705d62))
+- Removed the `plain agent context` command and the `SessionStart` hook setup — agent rules now provide context directly without needing a startup hook ([88d9424643](https://github.com/dropseed/plain/commit/88d9424643))
+- `plain agent install` now cleans up old SessionStart hooks from `.claude/settings.json` ([88d9424643](https://github.com/dropseed/plain/commit/88d9424643))
+
+### Upgrade instructions
+
+- The `--source` flag for `plain docs` has been removed. Use `--symbols` instead to see the symbolicated API surface.
+- The `--open` flag for `plain docs` has been removed.
+- Run `plain agent install` to clean up the old SessionStart hook from your `.claude/settings.json`.
+
+## [0.102.0](https://github.com/dropseed/plain/releases/plain@0.102.0) (2026-01-28)
+
+### What's changed
+
+- Refactored agent integration from skills-based to rules-based: packages now provide `agents/.claude/rules/` files and `agents/.claude/skills/` directories instead of `skills/` directories ([512040ac51](https://github.com/dropseed/plain/commit/512040ac51))
+- The `plain agent install` command now copies both rules (`.md` files) and skills to the project's `.claude/` directory, and cleans up orphaned `plain*` items ([512040ac51](https://github.com/dropseed/plain/commit/512040ac51))
+- Removed standalone skills (`plain-docs`, `plain-shell`, `plain-request`) that are now provided as passive rules instead ([512040ac51](https://github.com/dropseed/plain/commit/512040ac51))
+
+### Upgrade instructions
+
+- Run `plain agent install` to update your `.claude/` directory with the new rules-based structure.
+
 ## [0.101.2](https://github.com/dropseed/plain/releases/plain@0.101.2) (2026-01-28)
 
 ### What's changed

plain/agents/.claude/rules/plain.md

@@ -0,0 +1,88 @@
+# Plain Framework
+
+Plain is a Python web framework.
+
+- Always use `uv run` to execute commands — never use bare `python` or `plain` directly.
+- Plain is a Django fork but has different APIs — never assume Django patterns will work.
+- When unsure about an API or something doesn't work, run `uv run plain docs <package>` first. Add `--symbols` if you need the full API surface.
+- Use the `/plain-install` skill to add new Plain packages.
+- Use the `/plain-upgrade` skill to upgrade Plain packages.
+
+## Documentation
+
+Run `uv run plain docs --list` to see all official packages (installed and uninstalled) with descriptions.
+Run `uv run plain docs <package>` for markdown documentation (installed packages only).
+Run `uv run plain docs <package> --symbols` for the symbolicated API surface.
+For uninstalled packages, the CLI shows the install command and an online docs URL.
+
+Online docs URL pattern: `https://plainframework.com/docs/<pip-name>/<module/path>/README.md`
+Example: `https://plainframework.com/docs/plain-models/plain/models/README.md`
+
+Examples:
+
+- `uv run plain docs models` - Models and database docs
+- `uv run plain docs models --symbols` - Models API surface
+- `uv run plain docs templates` - Jinja2 templates
+- `uv run plain docs assets` - Static assets
+
+### All official packages
+
+- **plain** — Web framework core
+- **plain-admin** — Backend admin interface
+- **plain-api** — Class-based API views
+- **plain-auth** — User authentication and authorization
+- **plain-cache** — Database-backed cache with optional expiration
+- **plain-code** — Preconfigured code formatting and linting
+- **plain-dev** — Local development server with auto-reload
+- **plain-elements** — HTML template components
+- **plain-email** — Send email
+- **plain-esbuild** — Build JavaScript with esbuild
+- **plain-flags** — Feature flags via database models
+- **plain-htmx** — HTMX integration for templates and views
+- **plain-jobs** — Background jobs with a database-driven queue
+- **plain-loginlink** — Link-based authentication
+- **plain-models** — Model data and store it in a database
+- **plain-oauth** — OAuth provider login
+- **plain-observer** — On-page telemetry and observability
+- **plain-pages** — Serve static pages, markdown, and assets
+- **plain-pageviews** — Client-side pageview tracking
+- **plain-passwords** — Password authentication
+- **plain-pytest** — Test with pytest
+- **plain-redirection** — URL redirection with admin and logging
+- **plain-scan** — Test for production best practices
+- **plain-sessions** — Database-backed sessions
+- **plain-start** — Bootstrap a new project from templates
+- **plain-support** — Support forms for your application
+- **plain-tailwind** — Tailwind CSS without JavaScript or npm
+- **plain-toolbar** — Debug toolbar
+- **plain-tunnel** — Remote access to local dev server
+- **plain-vendor** — Vendor CDN scripts and styles
+
+## Shell
+
+`uv run plain shell` opens an interactive Python shell with Plain configured and database access.
+
+Run a one-off command:
+
+```
+uv run plain shell -c "from app.users.models import User; print(User.query.count())"
+```
+
+Run a script:
+
+```
+uv run plain run script.py
+```
+
+## HTTP Requests
+
+Use `uv run plain request` to make test HTTP requests against the dev database.
+
+```
+uv run plain request /path
+uv run plain request /path --user 1
+uv run plain request /path --header "Accept: application/json"
+uv run plain request /path --method POST --data '{"key": "value"}'
+uv run plain request /path --no-body    # Headers only
+uv run plain request /path --no-headers # Body only
+```

plain/cli/agent.py

@@ -9,34 +9,21 @@ from pathlib import Path
 import click
 
 
-def _get_packages_with_skills() -> dict[str, list[Path]]:
-    """Get dict mapping package names to lists of skill directory paths.
+def _get_agent_dirs() -> list[Path]:
+    """Get list of agents/.claude/ directories from installed plain.* packages."""
+    agent_dirs: list[Path] = []
 
-    Each skill is a directory containing a SKILL.md file.
-    """
-    skills_dirs: dict[str, list[Path]] = {}
-
-    # Check for plain.* subpackages (including core plain)
     try:
         import plain
 
         # Check core plain package (namespace package)
         plain_spec = importlib.util.find_spec("plain")
         if plain_spec and plain_spec.submodule_search_locations:
-            # For namespace packages, check all search locations
             for location in plain_spec.submodule_search_locations:
-                plain_path = Path(location)
-                skills_dir = plain_path / "skills"
-                if skills_dir.exists() and skills_dir.is_dir():
-                    # Find subdirectories that contain SKILL.md
-                    skill_dirs = [
-                        d
-                        for d in skills_dir.iterdir()
-                        if d.is_dir() and (d / "SKILL.md").exists()
-                    ]
-                    if skill_dirs:
-                        skills_dirs["plain"] = skill_dirs
-                    break  # Use the first one found
+                agent_dir = Path(location) / "agents" / ".claude"
+                if agent_dir.exists() and agent_dir.is_dir():
+                    agent_dirs.append(agent_dir)
+                    break
 
         # Check other plain.* subpackages
         if hasattr(plain, "__path__"):
@@ -47,126 +34,142 @@ def _get_packages_with_skills() -> dict[str, list[Path]]:
                     try:
                         spec = importlib.util.find_spec(modname)
                         if spec and spec.origin:
-                            package_path = Path(spec.origin).parent
-                            # Look for skills/ directory at package root
-                            skills_dir = package_path / "skills"
-                            if skills_dir.exists() and skills_dir.is_dir():
-                                # Find subdirectories that contain SKILL.md
-                                skill_dirs = [
-                                    d
-                                    for d in skills_dir.iterdir()
-                                    if d.is_dir() and (d / "SKILL.md").exists()
-                                ]
-                                if skill_dirs:
-                                    skills_dirs[modname] = skill_dirs
+                            agent_dir = Path(spec.origin).parent / "agents" / ".claude"
+                            if agent_dir.exists() and agent_dir.is_dir():
+                                agent_dirs.append(agent_dir)
                     except Exception:
                         continue
     except Exception:
         pass
 
-    return skills_dirs
-
-
-def _get_skill_destinations() -> list[Path]:
-    """Get list of skill directories to install to based on what's present."""
-    cwd = Path.cwd()
-    destinations = []
+    return agent_dirs
 
-    # Check for Claude (.claude/ directory)
-    if (cwd / ".claude").exists():
-        destinations.append(cwd / ".claude" / "skills")
 
-    # Check for Codex (.codex/ directory)
-    if (cwd / ".codex").exists():
-        destinations.append(cwd / ".codex" / "skills")
+def _install_agent_dir(source_dir: Path, dest_dir: Path) -> tuple[int, int]:
+    """Copy contents of a source agents/.claude/ dir to the project's .claude/ dir.
 
-    return destinations
+    Handles skills/ subdirectories and rules/ files.
+    Returns (installed_count, removed_count) for reporting.
+    """
+    installed_count = 0
 
+    # Copy skills (directories containing SKILL.md)
+    source_skills = source_dir / "skills"
+    if source_skills.exists():
+        dest_skills = dest_dir / "skills"
+        dest_skills.mkdir(parents=True, exist_ok=True)
+        for skill_dir in source_skills.iterdir():
+            if skill_dir.is_dir() and (skill_dir / "SKILL.md").exists():
+                dest_skill = dest_skills / skill_dir.name
+                # Check mtime to skip unchanged
+                if dest_skill.exists():
+                    source_mtime = (skill_dir / "SKILL.md").stat().st_mtime
+                    dest_mtime = (
+                        (dest_skill / "SKILL.md").stat().st_mtime
+                        if (dest_skill / "SKILL.md").exists()
+                        else 0
+                    )
+                    if source_mtime <= dest_mtime:
+                        continue
+                    shutil.rmtree(dest_skill)
+                shutil.copytree(skill_dir, dest_skill)
+                installed_count += 1
+
+    # Copy rules (individual .md files)
+    source_rules = source_dir / "rules"
+    if source_rules.exists():
+        dest_rules = dest_dir / "rules"
+        dest_rules.mkdir(parents=True, exist_ok=True)
+        for rule_file in source_rules.iterdir():
+            if rule_file.is_file() and rule_file.suffix == ".md":
+                dest_rule = dest_rules / rule_file.name
+                # Check mtime to skip unchanged
+                if dest_rule.exists():
+                    if rule_file.stat().st_mtime <= dest_rule.stat().st_mtime:
+                        continue
+                shutil.copy2(rule_file, dest_rule)
+                installed_count += 1
 
-def _install_skills_to(
-    dest_skills_dir: Path, skills_by_package: dict[str, list[Path]]
-) -> tuple[int, int]:
-    """Install skills to a destination directory. Returns (installed_count, removed_count)."""
-    dest_skills_dir.mkdir(parents=True, exist_ok=True)
+    return installed_count, 0
 
-    # Collect all source skill names
-    source_skill_names: set[str] = set()
-    for skill_dirs in skills_by_package.values():
-        for skill_dir in skill_dirs:
-            source_skill_names.add(skill_dir.name)
 
-    installed_count = 0
+def _cleanup_orphans(dest_dir: Path, agent_dirs: list[Path]) -> int:
+    """Remove plain* items from .claude/ that no longer exist in any source package."""
     removed_count = 0
 
-    # Remove orphaned plain-* skills (exist in dest but not in source)
-    # Only remove skills with plain- prefix to preserve user-created skills
-    if dest_skills_dir.exists():
-        for dest_dir in dest_skills_dir.iterdir():
+    # Collect all source skill and rule names
+    source_skills: set[str] = set()
+    source_rules: set[str] = set()
+    for agent_dir in agent_dirs:
+        skills_dir = agent_dir / "skills"
+        if skills_dir.exists():
+            for d in skills_dir.iterdir():
+                if d.is_dir() and (d / "SKILL.md").exists():
+                    source_skills.add(d.name)
+        rules_dir = agent_dir / "rules"
+        if rules_dir.exists():
+            for f in rules_dir.iterdir():
+                if f.is_file() and f.suffix == ".md":
+                    source_rules.add(f.name)
+
+    # Remove orphaned skills
+    dest_skills = dest_dir / "skills"
+    if dest_skills.exists():
+        for dest in dest_skills.iterdir():
             if (
-                dest_dir.is_dir()
-                and dest_dir.name.startswith("plain-")
-                and dest_dir.name not in source_skill_names
+                dest.is_dir()
+                and dest.name.startswith("plain")
+                and dest.name not in source_skills
             ):
-                shutil.rmtree(dest_dir)
+                shutil.rmtree(dest)
                 removed_count += 1
 
-    for pkg_name in sorted(skills_by_package.keys()):
-        for skill_dir in skills_by_package[pkg_name]:
-            dest_dir = dest_skills_dir / skill_dir.name
-            source_skill_file = skill_dir / "SKILL.md"
-
-            # Check if we need to copy (mtime checking)
-            if dest_dir.exists():
-                dest_skill_file = dest_dir / "SKILL.md"
-                if dest_skill_file.exists():
-                    source_mtime = source_skill_file.stat().st_mtime
-                    dest_mtime = dest_skill_file.stat().st_mtime
-                    if source_mtime <= dest_mtime:
-                        continue
-
-            # Copy the entire skill directory
-            if dest_dir.exists():
-                shutil.rmtree(dest_dir)
-            shutil.copytree(skill_dir, dest_dir)
-            installed_count += 1
+    # Remove orphaned rules
+    dest_rules = dest_dir / "rules"
+    if dest_rules.exists():
+        for dest in dest_rules.iterdir():
+            if (
+                dest.is_file()
+                and dest.name.startswith("plain")
+                and dest.suffix == ".md"
+                and dest.name not in source_rules
+            ):
+                dest.unlink()
+                removed_count += 1
 
-    return installed_count, removed_count
+    return removed_count
 
 
-def _setup_session_hook(dest_dir: Path) -> None:
-    """Create or update settings.json with SessionStart hook."""
+def _cleanup_session_hook(dest_dir: Path) -> None:
+    """Remove the old plain agent context SessionStart hook from settings.json."""
     settings_file = dest_dir / "settings.json"
 
-    # Load existing settings or start fresh
-    if settings_file.exists():
-        settings = json.loads(settings_file.read_text())
-    else:
-        settings = {}
-
-    # Ensure hooks structure exists
-    if "hooks" not in settings:
-        settings["hooks"] = {}
-
-    # Define the Plain hook - calls the agent context command directly
-    plain_hook = {
-        "matcher": "startup|resume",
-        "hooks": [
-            {
-                "type": "command",
-                "command": "uv run plain agent context 2>/dev/null || true",
-            }
-        ],
-    }
-
-    # Get existing SessionStart hooks, remove any existing plain hook
-    session_hooks = settings["hooks"].get("SessionStart", [])
+    if not settings_file.exists():
+        return
+
+    settings = json.loads(settings_file.read_text())
+
+    hooks = settings.get("hooks", {})
+    session_hooks = hooks.get("SessionStart", [])
+
+    # Remove any plain agent or plain-context.md hooks
     session_hooks = [h for h in session_hooks if "plain agent" not in str(h)]
-    # Also remove old plain-context.md hooks for migration
     session_hooks = [h for h in session_hooks if "plain-context.md" not in str(h)]
-    session_hooks.append(plain_hook)
-    settings["hooks"]["SessionStart"] = session_hooks
 
-    settings_file.write_text(json.dumps(settings, indent=2) + "\n")
+    if session_hooks:
+        hooks["SessionStart"] = session_hooks
+    else:
+        hooks.pop("SessionStart", None)
+
+    if hooks:
+        settings["hooks"] = hooks
+    else:
+        settings.pop("hooks", None)
+
+    if settings:
+        settings_file.write_text(json.dumps(settings, indent=2) + "\n")
+    else:
+        settings_file.unlink()
 
 
 @click.group()
@@ -175,62 +178,57 @@ def agent() -> None:
     pass
 
 
-@agent.command()
-def context() -> None:
-    """Output Plain framework context for AI agents"""
-    click.echo("This is a Plain project. Use the /plain-* skills for common tasks.")
-
-
 @agent.command()
 def install() -> None:
-    """Install skills and hooks to agent directories"""
-    skills_by_package = _get_packages_with_skills()
+    """Install skills and rules to agent directories"""
+    cwd = Path.cwd()
+    claude_dir = cwd / ".claude"
 
-    if not skills_by_package:
-        click.echo("No skills found in installed packages.")
+    if not claude_dir.exists():
+        click.secho("No .claude/ directory found.", fg="yellow")
         return
 
-    # Find destinations based on what agent directories exist
-    destinations = _get_skill_destinations()
-
-    if not destinations:
-        click.secho(
-            "No agent directories found (.claude/ or .codex/)",
-            fg="yellow",
-        )
-        return
+    agent_dirs = _get_agent_dirs()
 
-    # Install to each destination
-    for dest in destinations:
-        installed_count, removed_count = _install_skills_to(dest, skills_by_package)
+    # Clean up orphaned plain-* items
+    removed_count = _cleanup_orphans(claude_dir, agent_dirs)
 
-        parent_dir = dest.parent  # .claude/ or .codex/
+    # Install from each package
+    total_installed = 0
+    for source_dir in agent_dirs:
+        installed, _ = _install_agent_dir(source_dir, claude_dir)
+        total_installed += installed
 
-        # Setup hook only for Claude (Codex uses a different config format)
-        if parent_dir.name == ".claude":
-            _setup_session_hook(parent_dir)
+    # Clean up old session hook
+    _cleanup_session_hook(claude_dir)
 
-        parts = []
-        if installed_count > 0:
-            parts.append(f"installed {installed_count} skills")
-        if removed_count > 0:
-            parts.append(f"removed {removed_count} skills")
-        if parent_dir.name == ".claude":
-            parts.append("updated hooks")
-        if parts:
-            click.echo(f"Agent: {', '.join(parts)} in {parent_dir}/")
+    parts = []
+    if total_installed > 0:
+        parts.append(f"installed {total_installed}")
+    if removed_count > 0:
+        parts.append(f"removed {removed_count}")
+    click.echo(f"Agent: {', '.join(parts)} in .claude/") if parts else click.echo(
+        "Agent: up to date"
+    )
 
 
 @agent.command()
 def skills() -> None:
     """List available skills from installed packages"""
-    skills_by_package = _get_packages_with_skills()
+    agent_dirs = _get_agent_dirs()
+
+    skill_names = []
+    for agent_dir in agent_dirs:
+        skills_dir = agent_dir / "skills"
+        if skills_dir.exists():
+            for d in skills_dir.iterdir():
+                if d.is_dir() and (d / "SKILL.md").exists():
+                    skill_names.append(d.name)
 
-    if not skills_by_package:
+    if not skill_names:
         click.echo("No skills found in installed packages.")
         return
 
     click.echo("Available skills:")
-    for pkg_name in sorted(skills_by_package.keys()):
-        for skill_dir in skills_by_package[pkg_name]:
-            click.echo(f"  - {skill_dir.name} (from {pkg_name})")
+    for name in sorted(skill_names):
+        click.echo(f"  - {name}")

plain/cli/docs.py

@@ -1,46 +1,87 @@
+from __future__ import annotations
+
 import importlib.util
-import pkgutil
 from pathlib import Path
 
 import click
 
 from .llmdocs import LLMDocs
-from .output import iterate_markdown
+
+# All known official Plain packages: pip name -> short description
+KNOWN_PACKAGES = {
+    "plain": "Web framework core",
+    "plain-admin": "Backend admin interface",
+    "plain-api": "Class-based API views",
+    "plain-auth": "User authentication and authorization",
+    "plain-cache": "Database-backed cache with optional expiration",
+    "plain-code": "Preconfigured code formatting and linting",
+    "plain-dev": "Local development server with auto-reload",
+    "plain-elements": "HTML template components",
+    "plain-email": "Send email",
+    "plain-esbuild": "Build JavaScript with esbuild",
+    "plain-flags": "Feature flags via database models",
+    "plain-htmx": "HTMX integration for templates and views",
+    "plain-jobs": "Background jobs with a database-driven queue",
+    "plain-loginlink": "Link-based authentication",
+    "plain-models": "Model data and store it in a database",
+    "plain-oauth": "OAuth provider login",
+    "plain-observer": "On-page telemetry and observability",
+    "plain-pages": "Serve static pages, markdown, and assets",
+    "plain-pageviews": "Client-side pageview tracking",
+    "plain-passwords": "Password authentication",
+    "plain-pytest": "Test with pytest",
+    "plain-redirection": "URL redirection with admin and logging",
+    "plain-scan": "Test for production best practices",
+    "plain-sessions": "Database-backed sessions",
+    "plain-start": "Bootstrap a new project from templates",
+    "plain-support": "Support forms for your application",
+    "plain-tailwind": "Tailwind CSS without JavaScript or npm",
+    "plain-toolbar": "Debug toolbar",
+    "plain-tunnel": "Remote access to local dev server",
+    "plain-vendor": "Vendor CDN scripts and styles",
+}
+
+
+def _normalize_module(module: str) -> str:
+    """Normalize a module string to dotted form (e.g. plain-models -> plain.models)."""
+    module = module.replace("-", ".")
+    if not module.startswith("plain"):
+        module = f"plain.{module}"
+    return module
+
+
+def _pip_package_name(module: str) -> str:
+    """Convert a dotted module name to a pip package name (e.g. plain.models -> plain-models)."""
+    return module.replace(".", "-")
+
+
+def _is_installed(module: str) -> bool:
+    """Check if a dotted module name is installed."""
+    try:
+        return importlib.util.find_spec(module) is not None
+    except (ModuleNotFoundError, ValueError):
+        return False
+
+
+def _online_docs_url(pip_name: str) -> str:
+    """Return the online documentation URL for a package."""
+    module = pip_name.replace("-", ".")
+    return f"https://plainframework.com/docs/{pip_name}/{module.replace('.', '/')}/"
 
 
 @click.command()
-@click.option("--open", is_flag=True, help="Open the README in your default editor")
-@click.option("--source", is_flag=True, help="Include symbolicated source code")
+@click.option("--symbols", is_flag=True, help="Show symbolicated API surface only")
 @click.option("--list", "show_list", is_flag=True, help="List available packages")
 @click.argument("module", default="")
-def docs(module: str, open: bool, source: bool, show_list: bool) -> None:
+def docs(module: str, symbols: bool, show_list: bool) -> None:
     """Show documentation for a package"""
     if show_list:
-        # List available packages
-        available_packages = []
-        try:
-            import plain
-
-            # Check core plain package (namespace package)
-            plain_spec = importlib.util.find_spec("plain")
-            if plain_spec and plain_spec.submodule_search_locations:
-                available_packages.append("plain")
-
-            # Check other plain.* subpackages
-            if hasattr(plain, "__path__"):
-                for importer, modname, ispkg in pkgutil.iter_modules(
-                    plain.__path__, "plain."
-                ):
-                    if ispkg:
-                        available_packages.append(modname)
-        except Exception:
-            pass
-
-        if available_packages:
-            for pkg in sorted(available_packages):
-                click.echo(f"- {pkg}")
-        else:
-            click.echo("No packages found.")
+        for pip_name in sorted(KNOWN_PACKAGES):
+            description = KNOWN_PACKAGES[pip_name]
+            dotted = pip_name.replace("-", ".")
+            installed = _is_installed(dotted)
+            status = " (installed)" if installed else ""
+            click.echo(f"  {pip_name}{status} — {description}")
         return
 
     if not module:
@@ -48,32 +89,27 @@ def docs(module: str, open: bool, source: bool, show_list: bool) -> None:
             "You must specify a module. Use --list to see available packages."
         )
 
-    # Convert hyphens to dots (e.g., plain-models -> plain.models)
-    module = module.replace("-", ".")
-
-    # Automatically prefix if we need to
-    if not module.startswith("plain"):
-        module = f"plain.{module}"
+    module = _normalize_module(module)
 
     # Get the module path
     spec = importlib.util.find_spec(module)
     if not spec or not spec.origin:
-        raise click.UsageError(f"Module {module} not found")
+        pip_name = _pip_package_name(module)
+        if pip_name in KNOWN_PACKAGES:
+            msg = (
+                f"{module} is not installed.\n\n"
+                f"  Online docs:  {_online_docs_url(pip_name)}"
+            )
+        else:
+            msg = f"Module {module} not found. Use --list to see available packages."
+        raise click.UsageError(msg)
 
     module_path = Path(spec.origin).parent
 
-    if source:
-        # Output with symbolicated source
-        source_docs = LLMDocs([module_path])
-        source_docs.load()
-        source_docs.print(relative_to=module_path.parent)
-    else:
-        # Human-readable README output
-        readme_path = module_path / "README.md"
-        if not readme_path.exists():
-            raise click.UsageError(f"README.md not found for {module}")
-
-        if open:
-            click.launch(str(readme_path))
-        else:
-            click.echo_via_pager(iterate_markdown(readme_path.read_text()))
+    llm_docs = LLMDocs([module_path])
+    llm_docs.load()
+    llm_docs.print(
+        relative_to=module_path.parent,
+        include_docs=not symbols,
+        include_symbols=symbols,
+    )

plain/cli/llmdocs.py

@@ -26,7 +26,7 @@ class LLMDocs:
                 self.docs.add(path)
 
         # Exclude "migrations" code from plain apps, except for plain/models/migrations
-        # Also exclude CHANGELOG.md, AGENTS.md, and skills directory
+        # Also exclude CHANGELOG.md, AGENTS.md, and agents directory
         self.docs = {
             doc
             for doc in self.docs
@@ -35,7 +35,7 @@ class LLMDocs:
                 and "/plain/models/migrations/" not in str(doc)
             )
             and doc.name not in ("CHANGELOG.md", "AGENTS.md")
-            and "/skills/" not in str(doc)
+            and "/agents/" not in str(doc)
         }
         self.sources = {
             source
@@ -45,7 +45,7 @@ class LLMDocs:
                 and "/plain/models/migrations/" not in str(source)
             )
             and source.name != "cli.py"
-            and "/skills/" not in str(source)
+            and "/agents/" not in str(source)
         }
 
         self.docs = sorted(self.docs)
@@ -62,28 +62,35 @@ class LLMDocs:
         plain_root = Path(*path.parts[: root_index + 1])
         return path.relative_to(plain_root.parent)
 
-    def print(self, relative_to: Path | None = None) -> None:
-        for doc in self.docs:
-            if relative_to:
-                display_path = doc.relative_to(relative_to)
-            else:
-                display_path = self.display_path(doc)
-            click.secho(f"<Docs: {display_path}>", fg="yellow")
-            click.echo(doc.read_text())
-            click.secho(f"</Docs: {display_path}>", fg="yellow")
-            click.echo()
-
-        for source in self.sources:
-            if symbolicated := self.symbolicate(source):
+    def print(
+        self,
+        relative_to: Path | None = None,
+        include_docs: bool = True,
+        include_symbols: bool = True,
+    ) -> None:
+        if include_docs:
+            for doc in self.docs:
                 if relative_to:
-                    display_path = source.relative_to(relative_to)
+                    display_path = doc.relative_to(relative_to)
                 else:
-                    display_path = self.display_path(source)
-                click.secho(f"<Source: {display_path}>", fg="yellow")
-                click.echo(symbolicated)
-                click.secho(f"</Source: {display_path}>", fg="yellow")
+                    display_path = self.display_path(doc)
+                click.secho(f"<Docs: {display_path}>", fg="yellow")
+                click.echo(doc.read_text())
+                click.secho(f"</Docs: {display_path}>", fg="yellow")
                 click.echo()
 
+        if include_symbols:
+            for source in self.sources:
+                if symbolicated := self.symbolicate(source):
+                    if relative_to:
+                        display_path = source.relative_to(relative_to)
+                    else:
+                        display_path = self.display_path(source)
+                    click.secho(f"<Source: {display_path}>", fg="yellow")
+                    click.echo(symbolicated)
+                    click.secho(f"</Source: {display_path}>", fg="yellow")
+                    click.echo()
+
     @staticmethod
     def symbolicate(file_path: Path) -> str:
         if "internal" in str(file_path).split("/"):

{plain-0.101.2.dist-info → plain-0.103.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.101.2
+Version: 0.103.0
 Summary: A web framework for building products with Python.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause

{plain-0.101.2.dist-info → plain-0.103.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-plain/CHANGELOG.md,sha256=hvYn3NacP4SzrolTGeNiW9GT4__mq84UI2pxdZtpMfw,55077
+plain/CHANGELOG.md,sha256=FDaTDlnefZUH4Yq9XefuoXUf3CLLA0QKAM6Y0ln_q8I,57385
 plain/README.md,sha256=VvzhXNvf4I6ddmjBP9AExxxFXxs7RwyoxdgFm-W5dsg,4072
 plain/__main__.py,sha256=GK39854Lc_LO_JP8DzY9Y2MIQ4cQEl7SXFJy244-lC8,110
 plain/debug.py,sha256=C2OnFHtRGMrpCiHSt-P2r58JypgQZ62qzDBpV4mhtFM,855
@@ -8,6 +8,9 @@ plain/paginator.py,sha256=uModWWSnXISNt1Ecb5C17yoaKiTcHltFHLrfqQ-lio0,6240
 plain/signing.py,sha256=aFwfZew9Ot7_26F88wSOU82MdNUQ3i1A7kI1qKS1q-4,11634
 plain/validators.py,sha256=JBeycZFilWs69ai-QQb_4snpDgs1fjMGT0ICwVB1mvE,21297
 plain/wsgi.py,sha256=MWQ09DFNV2GxX752hYJMWka9LTEwzCp6XEC_4TdXF9g,287
+plain/agents/.claude/rules/plain.md,sha256=CgNYXI1pA3DWZv1T5iuempiMIJLD8w9VWbYDlJNuXNI,3617
+plain/agents/.claude/skills/plain-install/SKILL.md,sha256=lPhUMmKAQpjrVMp73T5pBkwkIaJjWTxAqtyS8Hio8mM,746
+plain/agents/.claude/skills/plain-upgrade/SKILL.md,sha256=79otYHv68Tfk3j08kRbg7o9eiNzzFZFyXCfLuIlT2Ho,927
 plain/assets/README.md,sha256=iRZHHoXZCEFooXoDYSomF12XTcDFl7oNbRHpAFwxTM8,4349
 plain/assets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 plain/assets/compile.py,sha256=a-e_nKHJLN3fOp9nw1MF7f7oP6q5qX8oYelowXKb_EE,3587
@@ -21,15 +24,15 @@ plain/chores/core.py,sha256=BxsCSJDQvMjYsAH4QhEoW9ZUEAUIwJgTYyHovPGSLjk,578
 plain/chores/registry.py,sha256=IRpx3f6Z1qlqcEpHTe6O6JocNmaplLu7BVOqGrafSXU,1221
 plain/cli/README.md,sha256=8OmOhvKvgFkndwGn8lW6q62mvIB6Zq_NAhEhBf7PVV0,6305
 plain/cli/__init__.py,sha256=o-dmnnNmXM3fZrKwW1qcoAPlcfG5pcFTFYWEBCocf8A,117
-plain/cli/agent.py,sha256=ApEeJRWt_oTksuURvmSTHHe1_eIKWe_2AtqYV20U8hc,8212
+plain/cli/agent.py,sha256=ZjCmeroPhX8Dc9Y0J_-ePzdZIZ4kicC3adsV6GL4xNI,7683
 plain/cli/build.py,sha256=UxgyAris4xtOZYS4FLMIOQLQ9DflHZkkenUJ650kZuA,3142
 plain/cli/changelog.py,sha256=ckuP99HtnUSJXf_AELWgmD9S0XjldCzh5urxPiDpRcI,3647
 plain/cli/chores.py,sha256=jhLKxFs_YpyQDvo5chNGiKnFc2_KK5atq53EpkGmMo0,2542
 plain/cli/core.py,sha256=_Kg_YnYeDZB3EKlzdejl4eJepzRd2aF1LSs0Ei2uCI8,6923
-plain/cli/docs.py,sha256=wC9ShvzCwJZoymV8G_Rs4AaPEU-_Eh-EkI0OFYJxKKA,2599
+plain/cli/docs.py,sha256=XeLt_Zf43NZV4yCkj0nqYcT5ejY7NR_NvyouClZTL0c,4321
 plain/cli/formatting.py,sha256=t0kxJ-r-his8kGcY38g38p699CfFGUgqEI1tJkEbjGs,3802
 plain/cli/install.py,sha256=28lXobloqqN50duuKlUqalAmNHUJdz-JlYYmdpXpzCs,1260
-plain/cli/llmdocs.py,sha256=xI2ta85zSEmVJePqrecxPd4EDhRSSY29pwSGor1DNJc,5599
+plain/cli/llmdocs.py,sha256=05lMHg6pYUb4zi6CTW5DDAidHFOkZWfG4ReMgUB42aM,5824
 plain/cli/output.py,sha256=uZTHZR-Axeoi2r6fgcDCpDA7iQSRrktBtTf1yBT5djI,1426
 plain/cli/preflight.py,sha256=zWnw9RFmN0CQQByAB2vWLbwlDNrQzUQTtKKySVzRucE,7036
 plain/cli/print.py,sha256=s_yNxtA4vg-AWn4C9TtFH-gOMnzMsXuEr7ak4-oOFPI,265
@@ -133,12 +136,6 @@ plain/signals/__init__.py,sha256=VDhotllLUQVg3eA1LuAJM9pwGTaf_bzRGzc4mJhd-sY,98
 plain/signals/dispatch/__init__.py,sha256=FzEygqV9HsM6gopio7O2Oh_X230nA4d5Q9s0sUjMq0E,292
 plain/signals/dispatch/dispatcher.py,sha256=ofpu8wMEx8O-I9SO9Rkk1ABH09-71QnmGZlt8vsZAw8,12317
 plain/signals/dispatch/license.txt,sha256=o9EhDhsC4Q5HbmD-IfNGVTEkXtNE33r5rIt3lleJ8gc,1727
-plain/skills/README.md,sha256=WUhXiLU42pIdcXiT-zugnsOXj4OjiCmec_XcM85KAyo,1434
-plain/skills/plain-docs/SKILL.md,sha256=CoOEhTsOpNczBuGxnHbGIVZ9Yahreq0RoXzqhVwtajY,560
-plain/skills/plain-install/SKILL.md,sha256=lPhUMmKAQpjrVMp73T5pBkwkIaJjWTxAqtyS8Hio8mM,746
-plain/skills/plain-request/SKILL.md,sha256=C37GEWRIpJFr-fbnEb08ENOJg-A7WUZxoYPneFAkHO4,771
-plain/skills/plain-shell/SKILL.md,sha256=njxD1dXVmSVZkcUnEm9_62hn_P6JMQmCpVOEzq29RvY,400
-plain/skills/plain-upgrade/SKILL.md,sha256=79otYHv68Tfk3j08kRbg7o9eiNzzFZFyXCfLuIlT2Ho,927
 plain/templates/README.md,sha256=zhAayenfxtwq6r1-NjoaD-wjaazyhm76BCacGF24ACc,8803
 plain/templates/__init__.py,sha256=bX76FakE9T7mfK3N0deN85HlwHNQpeigytSC9Z8LcOs,451
 plain/templates/core.py,sha256=mbcH0yTeFOI3XOg9dYSroXRIcdv9sETEy4HzY-ugwco,1258
@@ -194,8 +191,8 @@ plain/views/forms.py,sha256=j5WAMLeW1efU9M0q1W6SFHMDMBZfkFfW4WRLKwrXjqk,2435
 plain/views/objects.py,sha256=qKK8lYQKK7DTBPrMUebZ2HevgU9MmyWeXFWG1lT5ZbM,5393
 plain/views/redirect.py,sha256=rt5RF1Rs2yYFLole3Mznu5iU9aeumu49VAaX4WCd_xk,2139
 plain/views/templates.py,sha256=ElyqgpbkoJt72yU1gF7b626TB3R8viDAf-LYloulUBA,1925
-plain-0.101.2.dist-info/METADATA,sha256=EeQAZpll3Jn51d0GwuHSbstJjL_78xe-43GS_fSsQpU,4550
-plain-0.101.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-plain-0.101.2.dist-info/entry_points.txt,sha256=1Ys2lsSeMepD1vz8RSrJopna0RQfUd951vYvCRsvl6A,45
-plain-0.101.2.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
-plain-0.101.2.dist-info/RECORD,,
+plain-0.103.0.dist-info/METADATA,sha256=SQquYimnpZsPSt2gxBB7kw08UrCwGUgqYq0btTNOP34,4550
+plain-0.103.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+plain-0.103.0.dist-info/entry_points.txt,sha256=1Ys2lsSeMepD1vz8RSrJopna0RQfUd951vYvCRsvl6A,45
+plain-0.103.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
+plain-0.103.0.dist-info/RECORD,,

plain/skills/README.md

@@ -1,36 +0,0 @@
-# plain.skills
-
-**Agent skills for working with Plain projects.**
-
-These skills provide context and workflows for common tasks when using [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex](https://codex.openai.com/).
-
-## Available skills
-
-| Skill           | Description                                                    |
-| --------------- | -------------------------------------------------------------- |
-| `plain-docs`    | Retrieves detailed documentation for Plain packages            |
-| `plain-install` | Installs Plain packages and guides through setup steps         |
-| `plain-upgrade` | Upgrades Plain packages and applies required migration changes |
-| `plain-shell`   | Runs Python with Plain configured and database access          |
-| `plain-request` | Makes test HTTP requests against the development database      |
-
-## Installation
-
-To install skills to your project's `.claude/` or `.codex/` directory:
-
-```bash
-uv run plain agent install
-```
-
-This command:
-
-- Copies skill definitions so your agent can use them
-- Sets up a `SessionStart` hook that runs `plain agent context` at the start of every session
-
-Run it again after upgrading Plain to get updated skills.
-
-## Commands
-
-- `plain agent install` - Install skills and set up hooks
-- `plain agent skills` - List available skills from installed packages
-- `plain agent context` - Output framework context (used by the SessionStart hook)

plain/skills/plain-docs/SKILL.md

@@ -1,25 +0,0 @@
----
-name: plain-docs
-description: Retrieves detailed documentation for Plain packages. Use when looking up package APIs or feature details.
----
-
-# Getting Documentation
-
-## List Available Packages
-
-```
-uv run plain docs --list
-```
-
-## Get Package Documentation
-
-```
-uv run plain docs <package> --source
-```
-
-Examples:
-
-- `uv run plain docs models --source` - Models and database
-- `uv run plain docs templates --source` - Jinja2 templates
-- `uv run plain docs assets --source` - Static assets
-- `uv run plain docs tailwind --source` - Tailwind CSS integration

plain/skills/plain-request/SKILL.md

@@ -1,39 +0,0 @@
----
-name: plain-request
-description: Makes HTTP requests to test URLs, check endpoints, fetch pages, or debug routes. Use when asked to look at a URL, hit an endpoint, test a route, or make GET/POST requests.
----
-
-# Making HTTP Requests
-
-Use `uv run plain request` to make test requests against the dev database.
-
-## Basic Usage
-
-```
-uv run plain request /path
-```
-
-## With Authentication
-
-```
-uv run plain request /path --user 1
-```
-
-## With Custom Headers
-
-```
-uv run plain request /path --header "Accept: application/json"
-```
-
-## POST/PUT/PATCH with Data
-
-```
-uv run plain request /path --method POST --data '{"key": "value"}'
-```
-
-## Limiting Output
-
-```
-uv run plain request /path --no-body    # Headers only
-uv run plain request /path --no-headers # Body only
-```

plain/skills/plain-shell/SKILL.md

@@ -1,24 +0,0 @@
----
-name: plain-shell
-description: Runs Python with Plain configured and database access. Use for scripts, one-off commands, or interactive sessions.
----
-
-# Running Python with Plain
-
-## Interactive Shell
-
-```
-uv run plain shell
-```
-
-## One-off Command
-
-```
-uv run plain shell -c "from app.users.models import User; print(User.query.count())"
-```
-
-## Run a Script
-
-```
-uv run plain run script.py
-```