Agreed, most of my knowledge of Svelte's internals has come from reading compiled outputs and skimming the source code, which probably isn't a good teacher in the long run.

Since you're still new to the code base: what specifically would have helped you?

• overview of file organization?
• compiler phases intro?
• signals intro tweaked for specific code base?
• ..?

Probably more information about the compiler(particularly the HTMLx parser), and also some in depth info on the internals would help. For example, what the differences between the different effects (template_effect, user_effect) are, and also maybe some examples of the different internal functions, such as $.init, $.reset and $.pop. Another thing about effects that would be nice to know is how re-runs are batched. It would be nice to have actual documentation on the entire svelte/internal package, but I don't know how practical that is, considering how often it may change.

This is actually something I had the idea of doing for signals to solidify my knowledge of the reactivity system but I agree, having a general document would be fantastic.

I've been thinking about this recently and I don't think we should approach it like we do the regular Svelte docs in which we document each function; due to the ever-changing function names and parameters, it'd be difficult to keep it up to date.
That's why I think it'd be better to document the concepts and implementation— instead of documenting every function relating to runes, for example, we document the rough compiler transformations made and the implementation details of each rune. For the compiler, and other more complex concepts, we could include links to some understandable prerequisite information (we shouldn't have to explain the entirety of how an AST works, but we also shouldn't just link to its Wikipedia page, due to its rather dense contents).
I also think showing some side-by-side comparisons could be helpful. This doesn't necessarily have to just be between Svelte code and its corresponding compiled output, but it could also be between phases like SSR and hydration, showing how the hydration comments are used and transformed.
One smaller thing that could be useful would be to add JSDoc descriptions to at least some of the internal functions. This is a bit iffier, since it could encourage the use of such functions by component authors, but 99% of the time the person using this documentation would be someone who needs it.
Also, since there's also been a few explanations for some of these concepts, it'd be helpful to link to these as well. We shouldn't depend on them, but it'd be useful if, for example, at the end of a basic overview of signals, before providing a more in-depth guide, we linked to @paoloricciuti's (really good) Feb 2025 Svelte London presentation (or a relevant timestamp of it) to better articulate the concept.
I'm not entirely sure what format this would be in, but it'd probably be best to have it as both a tutorial (with the REPL, showing various Svelte concepts, how the user interacts with them, and how they actually work), and reference documentation.

I would propose to add cursor rules to the project to get the most out of LLMs

It would help maintaining consistency and make the AI aware of how the repo is structured and eventually gotchas when modifying certain parts

Describe the proposed solution

Some ideas:

• workflow-contributing-debugging.mdc: similar to CONTRIBUTING.md with the addition of steps to ease the debugging of svelte eg (link the svelte repo to a local folder to troubleshoot the resolution of a bug)
• workflow-testing.mdc: how tests are structured, how to run them.
• code-tests.mdc: patterns to follow when creating or changing tests.
• code-svelte.mdc: pattern to follow in the main code and performance considerations eg: let vs var.
• code-reactivity.mdc: explaination on how the reactive system work and gotchas when changing it and performance tips
• code-compiler.mdc: same as signal but for compiler stuff

The list can keep expanding and can touch all the LSP stuff and the CLI and the lints and you can just keep going.