Docs for Agents

[zurfyx]

This issue moves around the idea of accelerating the Lexical's development via LLMs (aka Agents).

Agents tend to be particularly smooth with smaller repos (Lexical and many other OSS qualify), the context window can fit so many files and these are so easy to access that they can make particularly well tailored decisions.

However, we can do better. Internally, we've seen great degree of success with Agent specific documentation which reinforces the comments that LLMs often leave in file to explain architectural and tricky decisions made in different parts of the codebase, and we want to replicate this in this Lexical repo in one way or another. AGENTS.md is a fine entrypoint but it doesn't cover how to scale further, for which we have various options.

Option 1 (/docs folder) #8040

This is the most common option across OSS projects.

(+) Easily accessible by Agents, sits in the root.
(+) Very tailored. It's meant to be a guideline for Agents as opposed to humans, even if it's digestible by humans.
(-) Private. Needs to pull the repo to read the docs.

Option 2(/packages/lexical-website/docs) (Recommended)

This option allows to expose the documentation on the website.

(-) The path is not obvious to Agents, relies on linking.
(+) Tailored. We still follow the same patterns as the option 1 when it comes to documentation, with humans as an optional factor.
(+) Public. If anyone wants to read the documentation to understand the technicals, this is very easily accessible.

Option 3 (/packages/lexical-website/docs)

This option is a mix of 1 and 2 where documentation is public but more human oriented.

(-) The path is not obvious to Agents, relies on linking.
(-) Not so tailored. We make it accessible for humans so that they understand the technical decisions made in the project but also accessible for Agents to make better decisions.
(+) Public and the most useful.

---

I'm personally leaning toward 2 to start with until we have a clear picture about how this scales and whether it makes sense to mix it with human-first documentation. Moving to 3 too soon might silently hinder some of the potential benefits of Agents.

[etrepum]

I don't think that 1 and 2 are necessarily exclusive? For example in Effect they have a docs folder that just links to everything else https://github.com/Effect-TS/effect/tree/main/docs

It might be worth taking a closer look at what that ecosystem is doing, e.g. the agent guided setup at https://www.effect.solutions/ and the effect-solutions CLI to help agents efficiently find docs.

[etrepum]

That said I don't have any strong opinions about any of these, I think given that a large portion of the docs are only in the source code (the API docs are a build product and not in the repo as markdown) we might need to direct agents to the website, source code, and/or have a CLI like effect-solutions. For reference, this is what is injected into your project's docs once you do the effect solutions agent-guided setup (it also helps you do the appropriate clone):

<!-- effect-solutions:start -->
## Effect Solutions Usage

The Effect Solutions CLI provides curated best practices and patterns for Effect TypeScript. Before working on Effect code, check if there's a relevant topic that covers your use case.

- `effect-solutions list` - List all available topics
- `effect-solutions show <slug...>` - Read one or more topics
- `effect-solutions search <term>` - Search topics by keyword

**Local Effect Source:** The Effect repository is cloned to `~/.local/share/effect-solutions/effect` for reference. Use this to explore APIs, find usage examples, and understand implementation details when the documentation isn't enough.
<!-- effect-solutions:end -->