Project tools

• uv for package management, virtual environment construction, and running scripts
• ruff for linting and formatting
• mypy for type checking
• Implementation code uses AnyIO primitives. Direct asyncio usage is allowed only in tests, examples, and documentation.

Commands

• uv run poe qa — Run lint, typecheck, and tests. Accepts package or file scopes plus -q/--quiet and -v/--verbose; does not accept tool-specific options after --.
• uv run poe test — Run tests (excludes example tests).
• uv run poe test-examples — Run opted-in root and package example tests.
• uv run poe lint — Run lint checks (ruff check + format).
• uv run poe typecheck — Run type checks (mypy + ty).
• uv run poe fix — Auto-fix lint issues and reformat code with ruff.
• ./scripts/test-python-matrix.sh — Run tests through tox across local Python versions. Accepts tox args before --, then normal test.sh scopes and pytest args after --.

The workspace test, lint, and typecheck Poe commands accept zero or more scopes before -- and tool args after --. The aggregate qa command accepts scopes but intentionally rejects tool-specific arguments after --.

Example: uv run poe test tests/unit/test_time.py -- -k coerce_duration Or by package name: uv run poe test vercel-oidc. Matrix example: ./scripts/test-python-matrix.sh -e py310,py314 -- vercel-queue -- -k subscriptions.

Example tests use the same scope and pytest passthrough conventions:

uv run poe test-examples
uv run poe test-examples vercel-sandbox
uv run poe test-examples vercel-sandbox -- -k sessions_and_resume
VERCEL_OIDC_TOKEN="$(vc project token)" uv run poe test-examples vercel-sandbox

Example testing is opt-in: a package declares a local [tool.poe.tasks.test-examples] task, and owns its executable-example selection, runner, pytest configuration, credentials, setup, and cleanup. The root package declares the public aggregate plus the internal test-examples-root task for root examples. Packages without a declaration are excluded from an unscoped aggregate and produce a clear error when requested explicitly.

The workspace task system is documented in scripts/poe/README.md. Workspace packages should include scripts/poe/poe.toml and inherit the shared lint, typecheck, and test tasks unless they have package-specific behavior.

Example package pyproject.toml Poe setup:

[tool.poe]
include = "../../scripts/poe/poe.toml"
verbosity = -1

Testing

• Do not combine pytest.mark.parametrize with Hypothesis @given tests. Draw the varying value from a strategy instead, such as st.booleans() for a sync/async mode. ggt fails every parametrization after the first one of an async @given test that runs in the same worker, with asyncio.run() cannot be called from a running event loop.

News Fragments

• Before opening a pull request or handing work back to the user, run uv run poe check-news-fragments.
• If the check reports missing fragments, add them with uv run poe changelog or explicitly tell the user that the pull request requires them to pass CI. Do not silently hand off package-code changes without the required fragments.

Commit Message Guidance

• Keep commit messages short and specific.
• Use a title line of 50 characters or fewer.
• Wrap commit message body lines at 72 characters.
• Explain what changed and why.
• Do not list file-by-file changes that are obvious from the diff.
• Do not include any Co-authored-by: line.

%% lat:begin %%

Before starting work

Use Lat's knowledge graph to ground each task before changing code.

• Run lat search to find sections relevant to your task. Read them to understand the design intent before writing code.

Post-task checklist (REQUIRED — do not skip)

After EVERY task, before responding to the user:

• Update lat.md/ if you added or changed meaningful implemented functionality, architecture, tests, or behavior. Keep it a focused snapshot of the current implemented state, not a journal/changelog. Plans may be drafted in lat.md/ alongside implementation, with the intent that by commit time they describe what was implemented. Otherwise, keep proposals, hypothetical designs, and future work outside lat.md/ unless the user explicitly requests them there.
• Run lat check — all validations must pass
• Do not skip these steps. Do not consider your task done until both are complete.

What is lat.md?

Lat.md is the project's structured knowledge graph for architecture, design decisions, behavior, and tests.

The graph lives in lat.md/ as cross-linked Markdown describing what the project does and why. Use it to ground work in actual architecture, and keep it a focused snapshot of the current implemented state rather than a journal or changelog.

Project-specific lat documentation belongs in lat.md/. Do not modify this generated instruction file or a generated lat-md SKILL.md to record project guidance: both are owned by lat tooling and may be replaced by a later lat init.

Commands

Use these commands to navigate and validate the project knowledge graph.

lat locate "Section Name"      # find a section by name (exact, fuzzy)
lat refs "file#Section"        # find what references a section
lat search "natural language"  # semantic search across all sections
lat external show <handle>      # inspect a pinned external source before cloning it
lat check                      # run full graph and documentation validation

Run lat --help when in doubt about available commands or options.

If lat search fails because no API key is configured, explain to the user that semantic search requires a key provided via LAT_LLM_KEY (direct value), LAT_LLM_KEY_FILE (path to key file), or LAT_LLM_KEY_HELPER (command that prints the key). Supported key prefixes: sk-... (OpenAI) or vck_... (Vercel). If the user doesn't want to set it up, use lat locate for direct lookups instead.

Syntax primer

Lat uses stable section ids, wiki links, source links, and code references to connect documentation with implementation.

• Section ids: lat.md/path/to/file#Heading#SubHeading — full form uses project-root-relative path (e.g. lat.md/tests/search#RAG Replay Tests). Short form uses bare file name when unique (e.g. search#RAG Replay Tests, cli#search#Indexing).
• Wiki links: [[target]] or [[target|alias]] — cross-references between sections. Can also reference repository paths or source code: [[schema.sql]], [[src/components]], [[src/foo.ts#myFunction]].
• Link specificity: When documenting implemented behavior, prefer the narrowest relevant source-symbol link over a whole-file link. Use whole-file or directory links when discussing the module or resource as a whole, or when no supported symbol represents the target. If prose names a symbol, link that symbol directly.
• Repository path links: Wiki links without a # fragment may target any existing file or directory inside the project. Unsupported formats validate but cannot be opened by Lat; fragments require a lat.md/ section or supported source file.
• Source code links: Wiki links in lat.md/ files can reference functions, classes, constants, and methods in supported source files. Use the full path: [[src/config.ts#getConfigDir]], [[src/server.ts#App#listen]] (class method), [[lib/utils.py#parse_args]], [[src/lib.rs#Greeter#greet]] (Rust impl method), [[src/app.go#Greeter#Greet]] (Go method), [[src/app.h#Greeter]] (C struct). When prose names an implementation symbol or a behavior governed by one, link the symbol instead of using a bare code span or copying its literal value. Prefer [[src/config.ts#DEFAULT_TIMEOUT]] (or an aliased form) over a bare identifier or copied value. lat check validates these exist.
• Code refs: // @lat: [[section-id]] (JS/TS/Rust/Go/C/PHP) or # @lat: [[section-id]] (Python/PHP) — ties source code to concepts

Diagrams

Default to prose. Reserve Mermaid diagrams for concepts involving more than seven interacting subjects (such as components, states, or stages) with complex sequencing, branching, or dependencies that prose alone makes hard to follow.

The subject count alone does not justify a diagram; omit diagrams for simple sequences or relationships that a short paragraph or list explains clearly. A diagram should give users and later agents an overview of the interactions.

Keep each diagram focused on one process, use readable labels, and explain the important decisions in surrounding prose with precise source-symbol links. Prefer a small overview or several focused diagrams over one dense diagram. Use fenced mermaid blocks and run lat check to validate syntax and readability.

Test specs

Key tests can be described as sections in lat.md/ files (e.g. tests.md). Add frontmatter to require that every leaf section is referenced by a // @lat: or # @lat: comment in test code:

---
lat:
  require-code-mention: true
---
# Tests

Authentication and authorization test specifications.

## User login

Verify credential validation and error handling for the login endpoint.

### Rejects expired tokens
Tokens past their expiry timestamp are rejected with 401, even if otherwise valid.

### Handles missing password
Login request without a password field returns 400 with a descriptive error.

Every section MUST have a description — at least one sentence explaining what the test verifies and why. Empty sections with just a heading are not acceptable. (This is a specific case of the general leading paragraph rule below.)

Each test in code should reference its spec with exactly one comment placed next to the relevant test — not at the top of the file:

# @lat: [[tests#User login#Rejects expired tokens]]
def test_rejects_expired_tokens():
    ...

# @lat: [[tests#User login#Handles missing password]]
def test_handles_missing_password():
    ...

Do not duplicate refs. One @lat: comment per spec section, placed at the test that covers it. lat check will flag any spec section not covered by a code reference, and any code reference pointing to a nonexistent section.

Section structure

Concise opening paragraphs give every section a stable overview for validation and discovery.

Every section in lat.md/ must have a leading paragraph — at least one sentence immediately after the heading, before any child headings or other block content. The first paragraph must be ≤250 characters (excluding [[wiki link]] content). This paragraph serves as the section's overview and is used in search results, command output, and RAG context — keeping it concise guarantees the section's essence is always captured.

# Good Section

Brief overview of what this section documents and why it matters.

More detail can go in subsequent paragraphs, code blocks, or lists.

## Child heading

Details about this child topic.

# Bad Section

## Child heading

Details about this child topic.

The second example is invalid because Bad Section has no leading paragraph. lat check validates this rule and reports errors for missing or overly long leading paragraphs. %% lat:end %%