# AGENTS.md

This is the tinymist language service, integrated with editor frontends and other tools to provide features like code intelligence, linting, debugging, and preview rendering for Typst projects.

## Quick Start

1. Read the nearest relevant docs before editing. Start with `docs/dev-guide.md`, then inspect the affected crate or editor directory.
2. For any non-trivial behavior change, check OpenSpec first: accepted specs live in `openspec/specs/` and active work lives in `openspec/changes/`.
3. Keep changes scoped to the task, prefer source-of-truth files over generated outputs, and follow existing crate and feature boundaries.
4. Before finishing, run the smallest meaningful validation for the area you touched and summarize what you verified.

## Must-Follow Rules

- Use the OpenSpec workflow for new features, behavior changes, multi-step fixes, and refactors. Small local edits can skip it when a formal change would add more overhead than value.
- Do not hand-edit generated Markdown files. `README.md`, `MAINTAINERS.md`, `crates/typlite/README.md`, and many docs under `editors/` are generated by `node scripts/link-docs.mjs`.
- Treat `tinymist.lock` files and similar generated outputs as artifacts. If a change requires them to differ, regenerate them instead of patching them manually.
- Keep warnings at zero. CI runs with `RUSTFLAGS='-Dwarnings'`, and `cargo clippy`, `cargo fmt`, docs, and tests are part of the normal quality bar.
- Prefer the smallest test command that covers your change, but widen validation when work spans Rust, editor tooling, generated docs, or feature flags.
- Preserve unrelated user changes. The worktree may already be dirty.
- Avoid editing dependency pins, version metadata, or release files unless the task actually requires it.
- Use Conventional Commits for commit messages, for example `fix(renderer-diff): keep sidebar scrollable`.

## OpenSpec Workflow

- Start by reading `openspec/config.yaml`, the relevant accepted spec in `openspec/specs/`, and any matching active change under `openspec/changes/`.
- If the work fits an existing active change, continue in that change instead of creating parallel artifacts.
- Keep `proposal.md`, `design.md`, `tasks.md`, and spec deltas aligned with implementation when you work inside an OpenSpec change.
- Use archived changes in `openspec/changes/archive/` as prior art, not as the source of current requirements.

## Repo Map

- `crates/tinymist-cli/`: the `tinymist` binary entrypoint and top-level CLI commands.
- `crates/tinymist/`: shared runtime and service logic used by system and web builds.
- `crates/tinymist-query/`: analyzer engine behind most language-intelligence features. Snapshot tests are especially important here.
- `crates/tinymist-analysis/`: lower-level analysis utilities and supporting logic.
- `crates/tinymist-world/` and `crates/tinymist-project/`: Typst world, project model, config loading, package handling, and filesystem-facing state.
- `crates/tinymist-render/`, `crates/typst-preview/`, `crates/tinymist-assets/`, and `tools/typst-preview-frontend/`: preview and rendering pipeline, plus bundled frontend assets.
- `crates/tinymist-lint/`, `crates/tinymist-debug/`, `crates/tinymist-dap/`, and `crates/sync-lsp/`: linting, debugging, DAP, and protocol plumbing.
- `editors/vscode/`: the main editor frontend and most JavaScript and TypeScript tooling.
- `editors/`: other editor integrations. Many of their docs are generated, so check the source before editing Markdown directly.
- `tests/`: end-to-end coverage, command fixtures, and sample workspaces.
- `docs/`: developer and user documentation. `docs/dev-guide.md` is the best high-level entry point.
- `scripts/`: build, generation, validation, and release helpers.

## Workflow

### 1. Clarify the task

- Identify which crate, editor frontend, docs source, or generated asset is actually responsible for the behavior.
- Read nearby docs and tests before changing code. For analyzer work, inspect existing fixtures and snapshots first.
- Decide whether the task is a small local edit or needs OpenSpec artifacts.

### 2. Make the change

- Fix the root cause in the primary source file whenever possible, instead of layering workarounds onto generated outputs or secondary wrappers.
- Follow the repo's existing feature-flag structure. If you touch feature combinations, plan to run `scripts/feature-testing.sh`.
- When documentation is generated, edit the underlying Typst or source docs and then regenerate with `node scripts/link-docs.mjs`.

### 3. Validate

- Rust changes in one crate: `cargo test -p <crate>`
- Broad Rust changes: `cargo test --workspace -- --skip=e2e`
- Formatting: `cargo fmt --check --all`
- Lints: `cargo clippy --workspace --all-targets`
- Feature-flag coverage: `scripts/feature-testing.sh`
- Analyzer snapshots: `cargo insta test -p tinymist-query --accept`
- CLI or end-to-end behavior: `./scripts/e2e.sh`
- VS Code frontend: `yarn lint` and `yarn test:vsc`
- Preview or localization assets: `yarn build:preview` and `yarn build:l10n`
- Generated docs: `node scripts/link-docs.mjs --check`
- Grammar changes: `yarn test:grammar`

### 4. Summarize

- Report the behavior change in user-facing terms.
- List the validation you ran.
- Call out anything you could not verify locally.

## Commit and PR Conventions

- Write commit messages in Conventional Commits format, such as `fix(query): handle missing labels`.
- Keep PR content limited to a list of modified features and issue operations, such as `Close #123`.
- Do not include validation logs, command transcripts, or detailed execution notes in PR content.

## Rust Conventions

- Follow workspace lints in `Cargo.toml`. `missing_docs`, `missing_safety_doc`, and `undocumented_unsafe_blocks` are all watched in this repo.
- Keep code warning-free under the workspace toolchain and CI settings.
- Prefer targeted tests first, then widen to workspace checks if the change crosses crate boundaries or affects shared infrastructure.
- Inspect snapshot diffs before accepting them. Snapshot churn is expected in analyzer and e2e tests, but it should always be intentional.

## Docs Conventions

- Generated files are marked at the top with `Do not edit manually`. Respect that marker.
- If you change docs that are mirrored into generated Markdown, rerun `node scripts/link-docs.mjs` rather than editing the generated copies.
- Keep documentation changes close to the code or feature they describe, and update OpenSpec artifacts when behavior-level guidance changes.
