# llms.txt and editor rules

> Feed the Pyzed docs to any LLM or AI IDE: llms.txt, llms-full.txt, Markdown pages, plus copy-ready AGENTS.md, Cursor rules and Copilot instructions for Pyzed projects.

Source: https://albakore.github.io/pyzed/ai/llms-txt/

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](https://llmstxt.org) 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`](https://albakore.github.io/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`](https://albakore.github.io/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`](https://albakore.github.io/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`](https://albakore.github.io/pyzed/llms/guides.txt), [`library`](https://albakore.github.io/pyzed/llms/library.txt) or [`blocks`](https://albakore.github.io/pyzed/llms/blocks.txt). | Just what a task needs. |
| `/pyzed/<page>.md` | Any page as Markdown: [`/pyzed/guides/layout.md`](https://albakore.github.io/pyzed/guides/layout.md). | Linking one page from a prompt or a rule. |
| [`/pyzed/es/llms.txt`](https://albakore.github.io/pyzed/es/llms.txt), [`/pyzed/es/llms-full.txt`](https://albakore.github.io/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](#cursor-rules) below for every request.
- **VS Code with Copilot**: add the [instructions file](#github-copilot) 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`](#agentsmd-for-a-pyzed-project) 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](https://albakore.github.io/pyzed/ai/mcp/). 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.

```markdown
# 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:

```markdown
---
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:

```markdown
---
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:

```python
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.