llms.txt and editor rules

Not every agent speaks MCP, and sometimes you just want to paste the docs into a chat. This site publishes itself as plain text for language models, following the llms.txt convention, and this page has ready-made instruction files that teach any AI editor how to write Pyzed.

The docs as text

URL	What it has	Use it for
/pyzed/llms.txt	An index: every page with its title, link and one-line summary.	Letting an agent pick what to read.
/pyzed/llms-small.txt	The essentials in one file: getting started, tutorials, guides, AI and FAQ.	Pasting into a chat or a model with a small context.
/pyzed/llms-full.txt	The whole documentation in one file.	Indexing in an AI IDE, long-context models.
/pyzed/llms/<section>.txt	One section, such as guides, library or blocks.	Just what a task needs.
/pyzed/<page>.md	Any page as Markdown: /pyzed/guides/layout.md.	Linking one page from a prompt or a rule.
/pyzed/es/llms.txt, /pyzed/es/llms-full.txt	The same in Spanish.	Working in Spanish.

The full address starts with https://albakore.github.io, for example https://albakore.github.io/pyzed/llms-full.txt. All of them are generated from the same pages you are reading, so they always match the current release.

In your AI editor

• Cursor: Settings → Indexing & Docs → Add doc with https://albakore.github.io/pyzed/llms-full.txt, then mention it as @Pyzed in a chat. Add the Cursor rule below for every request.
• VS Code with Copilot: add the instructions file below; in a chat, #fetch a page such as https://albakore.github.io/pyzed/guides/async.md when you need its details.
• Zed: /fetch https://albakore.github.io/pyzed/llms-small.txt in the agent panel, and add the AGENTS.md to the project.
• A chat in the browser: attach or paste llms-small.txt, or give the model the link if it can browse.
• Any agent with MCP: prefer the MCP server. It reads the same pages on demand and also validates code and takes screenshots.

The package also ships type stubs (pyzed/_core.pyi and inline types), so editors and agents that read types see every widget’s parameters even without the docs.

AGENTS.md for a Pyzed project

Many agents read an AGENTS.md at the root of the project. Copy this one; pyzed new projects are a good fit.

AGENTS.md

This is a desktop app written with Pyzed (Python UI on Iced/Rust, with ready-made themed components).
Docs: https://albakore.github.io/pyzed/llms-small.txt (all of it: /pyzed/llms-full.txt).
If the `pyzed` MCP server is available, use its tools instead of guessing APIs.

## Commands
- Run with hot reload: `uv run pyzed dev main.py`
- Check (ruff + types): `uv run pyzed check`
- Tests: `uv run pytest -q`
- Package: `uv run pyzed build`

## How Pyzed apps work
- An app is a `pz.App` subclass. State lives on `self` (set in `__init__`), `view()` returns widgets,
  events call methods or send messages to `update(message)`.
- `view()` runs after every event: no I/O, no sleeps, no state changes inside it.
- Slow work: return a coroutine (`async def`) or an async generator from a callback or `update`;
  each result or yielded value goes back to `update`. Timers and streams go in `subscriptions()`
  (`pz.every`, `pz.listen`).
- Effects (focus, scroll, clipboard, windows) are `pz.Command`s returned from callbacks.

## Rules
- Prefer `pyzed.ui` components (`ui.button`, `ui.input`, `ui.table`, `ui.card`...) over raw `pz.*` widgets.
- Look up signatures (MCP `describe_component`, or the docs) before using a component. Never invent parameters.
- Colors: use theme tokens (`"accent"`, `"panel"`, `"text_muted"`, `"border"`) so light and dark both work.
  `pz.container(bg=...)` takes real colors; use `.style(background="panel")` for tokens.
- Icons are Lucide names (`pyzed icons` lists them).
- Lambdas in loops capture the variable: `lambda item=item: self.open(item)`.
- Don't name app attributes after window options (`title`, `size`, `position`, `theme`, `style`...)
  unless you mean them.
- Reusable pieces with their own state: `pz.Component` with typed props, `pz.state()` and `events`.
- Call `pz.run(App)` once, under `if __name__ == "__main__":`.

## Before you finish
- Run `pyzed check` (or the MCP `validate_code` tool) and fix every issue.
- Smoke-test the UI off-screen: `App().screenshot("shot.png")` (or the MCP `screenshot` tool) and look at it.

Cursor rules

Save as .cursor/rules/pyzed.mdc. It applies to every Python file and points Cursor at the docs and the AGENTS.md above:

---
description: Writing desktop UIs with Pyzed
globs: ["**/*.py", "**/*.pzform"]
alwaysApply: false
---

- This project uses Pyzed for its UI. Follow AGENTS.md at the repository root.
- Before using a Pyzed component, check its signature with the `pyzed` MCP tools
  (`describe_component`) or in https://albakore.github.io/pyzed/llms/library.txt.
- Build screens from `pyzed.ui` components; start from a block when one fits:
  https://albakore.github.io/pyzed/llms/blocks.txt
- After editing, run `validate_code` (MCP) or `uv run pyzed check`, and fix what it reports.

GitHub Copilot

Save as .github/copilot-instructions.md (repository-wide), or as .github/instructions/pyzed.instructions.md with an applyTo header to scope it:

---
applyTo: "**/*.py"
---

This repository's UI is written with Pyzed (https://albakore.github.io/pyzed/).
Read https://albakore.github.io/pyzed/llms-small.txt for how Pyzed apps work, and follow AGENTS.md.

- `pz.App` subclasses hold state on `self`; `view()` only builds widgets from that state.
- Use `pyzed.ui` components and theme tokens ("accent", "panel", "text_muted").
- Long work goes in coroutines or async generators returned from callbacks; never block `view()`.
- Verify component parameters in https://albakore.github.io/pyzed/llms/library.txt instead of guessing.

A system prompt for your own agent

Building an agent that writes Pyzed (with pyzed.agents or any SDK)? Give it the guide and the tools:

from pyzed import agents
from pyzed.mcp import knowledge

system = knowledge.guide("overview") + "\n\n" + knowledge.guide("best-practices")
agent = agents.Agent(tools=agents.pyzed_tools(), system=system)

agents.pyzed_tools() gives the model the same lookups, generators and checks as the MCP server.