From 358b6abf36610dc5e880685ec353b5d61bf6ae78 Mon Sep 17 00:00:00 2001
From: Scott Wu <sw@scottwu.ca>
Date: Tue, 31 Mar 2026 11:34:14 +0800
Subject: [PATCH 01/12] first pass

---
 documentation/docs/20-commands/20-sv-add.md | 20 ++---
 documentation/docs/40-api/10-add-on.md      | 83 ++++++++++++---------
 2 files changed, 54 insertions(+), 49 deletions(-)

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index d4993651c..5239b8709 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -76,7 +76,7 @@ You can find [community add-ons on npm](https://www.npmx.dev/search?q=keyword:sv
 ### How to install a community add-on
 
 ```sh
-npx sv add [PROTOCOL][COMMUNITY_ADDON]
+npx sv add [addon_package_name]
 ```
 
 You can:
@@ -86,18 +86,18 @@ You can:
 - use the `--add` option in the `create` command
 
 ```sh
-npx sv add eslint "@supacool"
+npx sv add eslint @supacool
 ```
 
 ```sh
-npx sv create --add eslint "@supacool"
+npx sv create --add eslint @supacool
 ```
 
 ### Package Protocols
 
 ```sh
-# Scoped package: @org (preferred), we will look for @org/sv
-npx sv add "@supacool"
+# Scoped package: @org/sv
+npx sv add @supacool
 
 # Regular npm package (with or without scope)
 npx sv add my-cool-addon
@@ -108,12 +108,4 @@ npx sv add file:../path/to/my-addon
 
 ### How to create a community add-on
 
-To start on a good track, create your add-on with the `addon` template.
-
-```sh
-npx sv create --template addon [path]
-```
-
-In your new add-on directory, check out the `README.md` and `CONTRIBUTING.md` to get started.
-
-Then you can continue with the [API docs](/docs/cli/add-on) to start building your add-on. You can also have a look at the [official addons source code](https://github.com/sveltejs/cli/tree/main/packages/sv/src/addons) to get some inspiration on what can be done.
+Please checkout the [Add-on Docs](/docs/cli/add-on) for more details.
diff --git a/documentation/docs/40-api/10-add-on.md b/documentation/docs/40-api/10-add-on.md
index db4bc8ebc..fa5061e5b 100644
--- a/documentation/docs/40-api/10-add-on.md
+++ b/documentation/docs/40-api/10-add-on.md
@@ -9,13 +9,15 @@ This guide covers how to create, test, and publish community add-ons for `sv`.
 
 ## Quick start
 
-The easiest way to create an add-on is using the addon template:
+The easiest way to create an add-on is using the `addon` template:
 
 ```sh
-npx sv create --template addon my-addon
+npx sv create --template addon [path]
 ```
 
-## Add-on structure
+The project has a `README.md` and `CONTRIBUTING.md` to guide you along.
+
+## Project structure
 
 Typically, an add-on looks like this:
 
@@ -24,21 +26,23 @@ Typically, an add-on looks like this:
 import { transforms } from '@sveltejs/sv-utils';
 import { defineAddon, defineAddonOptions } from 'sv';
 
-// Define options that will be prompted to the user (or passed as arguments)
-const options = defineAddonOptions()
-	.add('who', {
-		question: 'To whom should the addon say hello?',
-		type: 'string' // boolean | number | select | multiselect
-	})
-	.build();
-
 // your add-on definition, the entry point
 export default defineAddon({
 	id: 'your-addon-name',
-	// shortDescription: 'does X',   // optional: one-liner shown in prompts
-	// homepage: 'https://...',      // optional: link to docs/repo
 
-	options,
+	// optional: one-liner shown in prompts
+	shortDescription: 'does X',
+
+	// optional: link to docs/repo
+	homepage: 'https://...',
+
+	// Define options for user prompts (or passed as arguments)
+	options: defineAddonOptions()
+		.add('who', {
+			question: 'To whom should the addon say hello?',
+			type: 'string' // boolean | number | select | multiselect
+		})
+		.build(),
 
 	// preparing step, check requirements and dependencies
 	setup: ({ dependsOn }) => {
@@ -60,21 +64,24 @@ export default defineAddon({
 });
 ```
 
-> `sv` owns the file system - `sv.file()` resolves the path, reads the file, applies the edit function, and writes the result.
-> `@sveltejs/sv-utils` owns the content - `transforms.svelte()` returns a curried function that handles parsing, gives you the AST and utils, and serializes back. See [sv-utils](/docs/cli/sv-utils) for the full API.
+> `sv` is responsible for the file system - `sv.file()` accepts a `path` to the file and a callback function to modify it.
+> `@sveltejs/sv-utils` is responsible for the content - `transforms.svelte()` provides you with the proper AST and utils to modify the file. See [sv-utils](/docs/cli/sv-utils) for the full API.
 
-## Development with `file:` protocol
+## Development
 
 While developing your add-on, you can test it locally using the `file:` protocol:
 
 ```sh
-# In your test project
+cd /path/to/test-project
 npx sv add file:../path/to/my-addon
 ```
 
 This allows you to iterate quickly without publishing to npm.
 
-## Testing with `sv/testing`
+> [!NOTE]
+> It is not necessary to build your add-on during development.
+
+## Testing
 
 The `sv/testing` module provides utilities for testing your add-on:
 
@@ -96,47 +103,47 @@ test('adds hello message', async () => {
 });
 ```
 
-## Building and publishing
+> [!NOTE]
+> It is not necessary to build your add-on during development.
+
+## Publishing
 
 ### Bundling
 
-Community add-ons are bundled with [tsdown](https://tsdown.dev/) into a single file. Everything is bundled except `sv` (peer dependency, provided at runtime).
+Community add-ons are bundled with [tsdown](https://tsdown.dev/) into a single file. Everything is bundled except `sv`. (It is a peer dependency provided at runtime.)
 
-```sh
-npm run build
-```
-
-### Package structure
+### `package.json`
 
 Your add-on must have `sv` as a peer dependency and **no** `dependencies` in `package.json`:
 
 ```json
 {
+	// must be scoped to `/sv`
 	"name": "@your-org/sv",
 	"version": "1.0.0",
 	"type": "module",
+	// entrypoint during developemnt
 	"exports": {
 		".": "./src/index.js"
 	},
 	"publishConfig": {
 		"access": "public",
+		// entrypoint on build
 		"exports": {
 			".": { "default": "./dist/index.js" }
 		}
 	},
+	// cannot have dependencies
+	"dependencies": {},
 	"peerDependencies": {
+		// minimum version required to run by this addon
 		"sv": "^0.13.0"
 	},
+	// Add this keyword so users can discover your add-on
 	"keywords": ["sv-add"]
 }
 ```
 
-- `exports` points to `./src/index.js` for local development with the `file:` protocol.
-- `publishConfig.exports` overrides exports when publishing, pointing to the bundled `./dist/index.js`.
-
-> [!NOTE]
-> Add the `sv-add` keyword so users can discover your add-on on npm.
-
 ### Export options
 
 Your package can export the add-on in two ways:
@@ -161,7 +168,7 @@ Your package can export the add-on in two ways:
    }
    ```
 
-### Publishing
+### Publish to npm
 
 Community add-ons must be scoped packages (e.g. `@your-org/sv`). Users install with `npx sv add @your-org`.
 
@@ -174,10 +181,12 @@ npm publish
 
 ## Next steps
 
-You can optionally display guidance after your add-on runs:
+You can optionally display guidance in the console after your add-on runs:
 
 ```js
 // @noErrors
+import { color } from '@sveltejs/sv-utils';
+
 export default defineAddon({
 	// ...
 	nextSteps: ({ options }) => [
@@ -189,4 +198,8 @@ export default defineAddon({
 
 ## Version compatibility
 
-Your add-on should specify the minimum `sv` version it requires in `peerDependencies`. If a user's `sv` version has a different major version than what your add-on was built for, they will see a compatibility warning.
+Your add-on should specify a minimum `sv` version in `peerDependencies`. Your user will get a compatibility warning if their `sv` version has a different major version than what was specified.
+
+## Examples
+
+See the [official add-on source code](https://github.com/sveltejs/cli/tree/main/packages/sv/src/addons) for some real world examples.

From 4285eb3529a36556bb032161fbfedd81cc94ea8a Mon Sep 17 00:00:00 2001
From: Scott Wu <sw@scottwu.ca>
Date: Tue, 31 Mar 2026 11:41:50 +0800
Subject: [PATCH 02/12] use `path.join`

---
 documentation/docs/40-api/10-add-on.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/documentation/docs/40-api/10-add-on.md b/documentation/docs/40-api/10-add-on.md
index fa5061e5b..cf7fcc96e 100644
--- a/documentation/docs/40-api/10-add-on.md
+++ b/documentation/docs/40-api/10-add-on.md
@@ -2,6 +2,8 @@
 title: add-on
 ---
 
+<!-- moved to /community-addon -->
+
 > [!NOTE]
 > Community add-ons are currently **experimental**. The API may change. Don't use them in production yet!
 
@@ -55,7 +57,7 @@ export default defineAddon({
 
 		// Add "Hello [who]!" to the root page
 		sv.file(
-			directory.routes + '/+page.svelte',
+      path.join(directory.routes,'+page.svelte')
 			transforms.svelte(({ ast, svelte }) => {
 				svelte.addFragment(ast, `<p>Hello ${options.who}!</p>`);
 			})

From 68a514981656765b40c7be9c27c034470c5655f2 Mon Sep 17 00:00:00 2001
From: Scott Wu <sw@scottwu.ca>
Date: Tue, 31 Mar 2026 11:48:51 +0800
Subject: [PATCH 03/12] move addon doc out of api

---
 documentation/docs/20-commands/20-sv-add.md                    | 2 +-
 .../docs/{40-api => 40-community-add-ons}/10-add-on.md         | 2 --
 documentation/docs/40-community-add-ons/index.md               | 3 +++
 documentation/docs/{40-api => 50-api}/20-sv-utils.md           | 0
 documentation/docs/{40-api => 50-api}/index.md                 | 0
 5 files changed, 4 insertions(+), 3 deletions(-)
 rename documentation/docs/{40-api => 40-community-add-ons}/10-add-on.md (99%)
 create mode 100644 documentation/docs/40-community-add-ons/index.md
 rename documentation/docs/{40-api => 50-api}/20-sv-utils.md (100%)
 rename documentation/docs/{40-api => 50-api}/index.md (100%)

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index 5239b8709..32fb144c6 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -108,4 +108,4 @@ npx sv add file:../path/to/my-addon
 
 ### How to create a community add-on
 
-Please checkout the [Add-on Docs](/docs/cli/add-on) for more details.
+Please checkout the [Add-on Docs](/docs/cli/community-add-on) for more details.
diff --git a/documentation/docs/40-api/10-add-on.md b/documentation/docs/40-community-add-ons/10-add-on.md
similarity index 99%
rename from documentation/docs/40-api/10-add-on.md
rename to documentation/docs/40-community-add-ons/10-add-on.md
index cf7fcc96e..c638b3cb2 100644
--- a/documentation/docs/40-api/10-add-on.md
+++ b/documentation/docs/40-community-add-ons/10-add-on.md
@@ -2,8 +2,6 @@
 title: add-on
 ---
 
-<!-- moved to /community-addon -->
-
 > [!NOTE]
 > Community add-ons are currently **experimental**. The API may change. Don't use them in production yet!
 
diff --git a/documentation/docs/40-community-add-ons/index.md b/documentation/docs/40-community-add-ons/index.md
new file mode 100644
index 000000000..f312885b1
--- /dev/null
+++ b/documentation/docs/40-community-add-ons/index.md
@@ -0,0 +1,3 @@
+---
+title: Community Add-ons
+---
diff --git a/documentation/docs/40-api/20-sv-utils.md b/documentation/docs/50-api/20-sv-utils.md
similarity index 100%
rename from documentation/docs/40-api/20-sv-utils.md
rename to documentation/docs/50-api/20-sv-utils.md
diff --git a/documentation/docs/40-api/index.md b/documentation/docs/50-api/index.md
similarity index 100%
rename from documentation/docs/40-api/index.md
rename to documentation/docs/50-api/index.md

From 77d80cfa5e717ab8d553f02d3cd5770cade0d6b8 Mon Sep 17 00:00:00 2001
From: Scott Wu <sw@scottwu.ca>
Date: Tue, 31 Mar 2026 12:31:18 +0800
Subject: [PATCH 04/12] fix link

---
 documentation/docs/20-commands/20-sv-add.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index 32fb144c6..9622c26ea 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -108,4 +108,4 @@ npx sv add file:../path/to/my-addon
 
 ### How to create a community add-on
 
-Please checkout the [Add-on Docs](/docs/cli/community-add-on) for more details.
+Please checkout the [Add-on Docs](/docs/cli/community-add-ons) for more details.

From 838b421a6c48daf6f6e4e069635d3943b3e264b6 Mon Sep 17 00:00:00 2001
From: Scott Wu <sw@scottwu.ca>
Date: Tue, 31 Mar 2026 12:36:29 +0800
Subject: [PATCH 05/12] reverse path.join

---
 documentation/docs/40-community-add-ons/10-add-on.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/40-community-add-ons/10-add-on.md b/documentation/docs/40-community-add-ons/10-add-on.md
index c638b3cb2..fa5061e5b 100644
--- a/documentation/docs/40-community-add-ons/10-add-on.md
+++ b/documentation/docs/40-community-add-ons/10-add-on.md
@@ -55,7 +55,7 @@ export default defineAddon({
 
 		// Add "Hello [who]!" to the root page
 		sv.file(
-      path.join(directory.routes,'+page.svelte')
+			directory.routes + '/+page.svelte',
 			transforms.svelte(({ ast, svelte }) => {
 				svelte.addFragment(ast, `<p>Hello ${options.who}!</p>`);
 			})

From 5963d8b978e116527bcd1843a01e8c53ec5cab90 Mon Sep 17 00:00:00 2001
From: Scott Wu <sw@scottwu.ca>
Date: Tue, 31 Mar 2026 17:11:12 +0800
Subject: [PATCH 06/12] something

---
 documentation/docs/20-commands/20-sv-add.md   |  2 +-
 .../10-create-your-own.md}                    | 13 +++++-
 .../docs/40-add-ons-community/index.md        |  3 ++
 .../docs/40-community-add-ons/index.md        |  3 --
 documentation/docs/50-api/20-sv-utils.md      | 42 ++++++++++---------
 5 files changed, 38 insertions(+), 25 deletions(-)
 rename documentation/docs/{40-community-add-ons/10-add-on.md => 40-add-ons-community/10-create-your-own.md} (89%)
 create mode 100644 documentation/docs/40-add-ons-community/index.md
 delete mode 100644 documentation/docs/40-community-add-ons/index.md

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index 9622c26ea..147ead32f 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -108,4 +108,4 @@ npx sv add file:../path/to/my-addon
 
 ### How to create a community add-on
 
-Please checkout the [Add-on Docs](/docs/cli/community-add-ons) for more details.
+Please checkout the [Add-on Docs](/docs/cli/create-your-own) for more details.
diff --git a/documentation/docs/40-community-add-ons/10-add-on.md b/documentation/docs/40-add-ons-community/10-create-your-own.md
similarity index 89%
rename from documentation/docs/40-community-add-ons/10-add-on.md
rename to documentation/docs/40-add-ons-community/10-create-your-own.md
index fa5061e5b..312ef1458 100644
--- a/documentation/docs/40-community-add-ons/10-add-on.md
+++ b/documentation/docs/40-add-ons-community/10-create-your-own.md
@@ -1,5 +1,5 @@
 ---
-title: add-on
+title: create your own
 ---
 
 > [!NOTE]
@@ -55,7 +55,7 @@ export default defineAddon({
 
 		// Add "Hello [who]!" to the root page
 		sv.file(
-			directory.routes + '/+page.svelte',
+			directory.kitRoutes + '/+page.svelte',
 			transforms.svelte(({ ast, svelte }) => {
 				svelte.addFragment(ast, `<p>Hello ${options.who}!</p>`);
 			})
@@ -203,3 +203,12 @@ Your add-on should specify a minimum `sv` version in `peerDependencies`. Your us
 ## Examples
 
 See the [official add-on source code](https://github.com/sveltejs/cli/tree/main/packages/sv/src/addons) for some real world examples.
+
+## Architecture
+
+The Svelte CLI is split into two packages with a clear boundary:
+
+- **`sv`** = **where and when** to do it. It owns paths, workspace detection, dependency tracking, and file I/O. The engine orchestrates add-on execution.
+- **`@sveltejs/sv-utils`** = **what** to do to content. It provides parsers, language tooling, and typed transforms. Everything here is pure - no file system, no workspace awareness.
+
+This separation means transforms are testable without a workspace and composable across add-ons.
diff --git a/documentation/docs/40-add-ons-community/index.md b/documentation/docs/40-add-ons-community/index.md
new file mode 100644
index 000000000..70930b7ca
--- /dev/null
+++ b/documentation/docs/40-add-ons-community/index.md
@@ -0,0 +1,3 @@
+---
+title: Add-ons (Community)
+---
diff --git a/documentation/docs/40-community-add-ons/index.md b/documentation/docs/40-community-add-ons/index.md
deleted file mode 100644
index f312885b1..000000000
--- a/documentation/docs/40-community-add-ons/index.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-title: Community Add-ons
----
diff --git a/documentation/docs/50-api/20-sv-utils.md b/documentation/docs/50-api/20-sv-utils.md
index daa0b82ac..cceb4e611 100644
--- a/documentation/docs/50-api/20-sv-utils.md
+++ b/documentation/docs/50-api/20-sv-utils.md
@@ -5,29 +5,24 @@ title: sv-utils
 > [!NOTE]
 > `@sveltejs/sv-utils` is currently **experimental**. The API may change. Full documentation is not yet available.
 
-`@sveltejs/sv-utils` provides utilities for parsing, transforming, and generating code in add-ons.
+`@sveltejs/sv-utils` is an add-on utilty for parsing, transforming, and generating code..
 
 ```sh
 npm install -D @sveltejs/sv-utils
 ```
 
-## Architecture
+## transforms
 
-The Svelte CLI is split into two packages with a clear boundary:
-
-- **`sv`** = **where and when** to do it. It owns paths, workspace detection, dependency tracking, and file I/O. The engine orchestrates add-on execution.
-- **`@sveltejs/sv-utils`** = **what** to do to content. It provides parsers, language tooling, and typed transforms. Everything here is pure - no file system, no workspace awareness.
-
-This separation means transforms are testable without a workspace and composable across add-ons.
-
-## Transforms
-
-Transforms are curried, parser-aware functions that turn `string -> string`. Call a transform with your callback to get a function that plugs directly into `sv.file()`. The parser choice is baked into the transform type - you can't accidentally parse a vite config as Svelte because you never call a parser yourself.
+`transforms` is a collection of parser-aware functions that lets you modify the files via abstract syntax tree (AST). It accepts a callback function. The return value is designed to be be passed directly into `sv.file()`. The parser choice is baked into the transform type - you can't accidentally parse a vite config as Svelte because you never call a parser yourself.
 
 Each transform injects relevant utilities into the callback, so you only need one import:
 
 ```js
 import { transforms } from '@sveltejs/sv-utils';
+
+transforms.script(...)
+transforms.svelte(...)
+// ...
 ```
 
 ### `transforms.script`
@@ -73,7 +68,7 @@ import { transforms } from '@sveltejs/sv-utils';
 
 sv.file(
 	layoutPath,
-	transforms.svelteScript({ language }, ({ ast, svelte, js }) => {
+	transforms.svelteScript({ language: 'ts' }, ({ ast, svelte, js }) => {
 		js.imports.addDefault(ast.instance.content, { as: 'Foo', from: './Foo.svelte' });
 		svelte.addFragment(ast, '<Foo />');
 	})
@@ -161,22 +156,26 @@ Transforms are curried functions - call them with the callback, then apply to co
 ```js
 import { transforms } from '@sveltejs/sv-utils';
 
-const result = transforms.script(({ ast, js }) => {
+const transform = transforms.script(({ ast, js }) => {
 	js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
-})('export default {}');
+});
+const result = transform('export default {}');
 ```
 
 ### Composability
 
-For cases where you need to mix transforms and raw edits, use `sv.file` with a content callback and invoke the curried transform manually:
+For cases where you need to mix and match transforms and raw edits, use `sv.file` with a content callback and invoke the curried transform manually:
 
 ```js
 // @noErrors
 sv.file(path, (content) => {
 	// curried
-	content = transforms.script(({ ast, js }) => {
+	const transform = transforms.script(({ ast, js }) => {
 		js.imports.addDefault(ast, { as: 'foo', from: 'bar' });
-	})(content);
+	});
+
+	// parser manipulation
+	content = transform(content);
 
 	// raw string manipulation
 	content = content.replace('foo', 'baz');
@@ -198,9 +197,14 @@ export const addFooImport = transforms.svelte(({ ast, svelte, js }) => {
 });
 ```
 
+```js
+sv.file('+page.svelte', addFooImport);
+sv.file('index.svelte', addFooImport);
+```
+
 ## Parsers (low-level)
 
-For cases where transforms don't fit (e.g., conditional parsing, error handling around the parser), the `parse` namespace is still available:
+`transforms` will fit most users needs (e.g., conditional parsing, error handling around the parser). If not, `parse` is a low-level API available to you:
 
 ```js
 // @noErrors

From 929e40ef854c52a67b54fdec919b4b3552e4e441 Mon Sep 17 00:00:00 2001
From: Scott Wu <sw@scottwu.ca>
Date: Tue, 31 Mar 2026 17:25:56 +0800
Subject: [PATCH 07/12] why wont it work!

---
 documentation/docs/20-commands/20-sv-add.md                     | 2 +-
 .../10-create-your-own.md => 30-add-ons/99-community.md}        | 0
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename documentation/docs/{40-add-ons-community/10-create-your-own.md => 30-add-ons/99-community.md} (100%)

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index 147ead32f..1ff8a2638 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -108,4 +108,4 @@ npx sv add file:../path/to/my-addon
 
 ### How to create a community add-on
 
-Please checkout the [Add-on Docs](/docs/cli/create-your-own) for more details.
+Please checkout the [Add-on Docs](community) for more details.
diff --git a/documentation/docs/40-add-ons-community/10-create-your-own.md b/documentation/docs/30-add-ons/99-community.md
similarity index 100%
rename from documentation/docs/40-add-ons-community/10-create-your-own.md
rename to documentation/docs/30-add-ons/99-community.md

From cf38bc9447e3b8306c7fe5d1c4568f7a08f6edd6 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 17:33:40 +0200
Subject: [PATCH 08/12] first part

---
 documentation/docs/20-commands/20-sv-add.md | 28 +++++++++++----------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index 1ff8a2638..13b9fb13b 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -76,36 +76,38 @@ You can find [community add-ons on npm](https://www.npmx.dev/search?q=keyword:sv
 ### How to install a community add-on
 
 ```sh
-npx sv add [addon_package_name]
+npx sv add @scope
+npx sv add file:../path/to/my-addon
 ```
 
-You can:
-
-- mix and match official and community add-ons
-- use the interactive prompt or give args to the cli
-- use the `--add` option in the `create` command
+You can mix and match official and community add-ons, use the interactive prompt or pass args directly:
 
 ```sh
+# In an existing project
 npx sv add eslint @supacool
-```
 
-```sh
+# Or when creating a new project
 npx sv create --add eslint @supacool
 ```
 
-### Package Protocols
+### Package protocols
+
+For **scoped packages**, the npm package name should be `@org/sv`. Users only need to type the scope:
 
 ```sh
-# Scoped package: @org/sv
+# Installs the npm package `@supacool/sv`
 npx sv add @supacool
+```
 
-# Regular npm package (with or without scope)
-npx sv add my-cool-addon
+For **local add-ons**, use the `file:` protocol. This is useful during development, but also for running custom add-ons that don't need to be published:
 
-# Local add-on
+```sh
 npx sv add file:../path/to/my-addon
 ```
 
+> [!NOTE]
+> Unscoped packages are not supported yet
+
 ### How to create a community add-on
 
 Please checkout the [Add-on Docs](community) for more details.

From c910bb7fed94d94f43ac9896c7b49a6db763097f Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 17:36:04 +0200
Subject: [PATCH 09/12] doc review

---
 documentation/docs/30-add-ons/99-community.md | 30 ++++++++++++-------
 1 file changed, 19 insertions(+), 11 deletions(-)

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index 312ef1458..4a635ec2f 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -69,7 +69,7 @@ export default defineAddon({
 
 ## Development
 
-While developing your add-on, you can test it locally using the `file:` protocol:
+You can run your add-on locally using the `file:` protocol:
 
 ```sh
 cd /path/to/test-project
@@ -78,6 +78,8 @@ npx sv add file:../path/to/my-addon
 
 This allows you to iterate quickly without publishing to npm.
 
+The `file:` protocol also works for custom or private add-ons that you don't intend to publish - for example, to standardize project setup across your team or organization.
+
 > [!NOTE]
 > It is not necessary to build your add-on during development.
 
@@ -103,9 +105,6 @@ test('adds hello message', async () => {
 });
 ```
 
-> [!NOTE]
-> It is not necessary to build your add-on during development.
-
 ## Publishing
 
 ### Bundling
@@ -116,13 +115,12 @@ Community add-ons are bundled with [tsdown](https://tsdown.dev/) into a single f
 
 Your add-on must have `sv` as a peer dependency and **no** `dependencies` in `package.json`:
 
-```json
+```jsonc
 {
-	// must be scoped to `/sv`
 	"name": "@your-org/sv",
 	"version": "1.0.0",
 	"type": "module",
-	// entrypoint during developemnt
+	// entrypoint during development
 	"exports": {
 		".": "./src/index.js"
 	},
@@ -144,9 +142,21 @@ Your add-on must have `sv` as a peer dependency and **no** `dependencies` in `pa
 }
 ```
 
+### Naming convention
+
+Name your package `@your-org/sv`. Users install it by typing just the scope:
+
+```sh
+# npm package: @your-org/sv
+npx sv add @your-org
+```
+
+> [!NOTE]
+> Unscoped packages are not supported yet
+
 ### Export options
 
-Your package can export the add-on in two ways:
+`sv` first tries to import `your-package/sv`, then falls back to the default export. This means you have two options:
 
 1. **Default export** (recommended for dedicated add-on packages):
 
@@ -158,7 +168,7 @@ Your package can export the add-on in two ways:
    }
    ```
 
-2. **`/sv` export** (for packages that have other functionality):
+2. **`./sv` export** (for packages that also export other functionality):
    ```json
    {
    	"exports": {
@@ -170,8 +180,6 @@ Your package can export the add-on in two ways:
 
 ### Publish to npm
 
-Community add-ons must be scoped packages (e.g. `@your-org/sv`). Users install with `npx sv add @your-org`.
-
 ```sh
 npm login
 npm publish

From a1331ed1292900b09d81c23efe34abb095af9834 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 17:38:13 +0200
Subject: [PATCH 10/12] fix preview ?

---
 documentation/docs/50-api/20-sv-utils.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation/docs/50-api/20-sv-utils.md b/documentation/docs/50-api/20-sv-utils.md
index cceb4e611..4a714618d 100644
--- a/documentation/docs/50-api/20-sv-utils.md
+++ b/documentation/docs/50-api/20-sv-utils.md
@@ -20,8 +20,8 @@ Each transform injects relevant utilities into the callback, so you only need on
 ```js
 import { transforms } from '@sveltejs/sv-utils';
 
-transforms.script(...)
-transforms.svelte(...)
+transforms.script(/* ... */);
+transforms.svelte(/* ... */);
 // ...
 ```
 

From 530545a1228445b28e137aa9d449a7953341fd11 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 17:53:06 +0200
Subject: [PATCH 11/12] refacto

---
 documentation/docs/20-commands/20-sv-add.md | 39 +++++----------------
 1 file changed, 8 insertions(+), 31 deletions(-)

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index 13b9fb13b..d8fc782e8 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -71,43 +71,20 @@ Prevents installing dependencies
 > [!NOTE]
 > Svelte maintainers have not reviewed community add-ons for malicious code!
 
-You can find [community add-ons on npm](https://www.npmx.dev/search?q=keyword:sv-add) by searching for keyword: `sv-add`.
-
-### How to install a community add-on
+Community add-ons are npm packages published by the community. Look out for add-ons from your favorite libraries and tools. _(soon)_ many are building `sv` add-ons to make integration a one-liner. You can find them [on npm](https://www.npmx.dev/search?q=keyword:sv-add) by searching for keyword: `sv-add`.
 
 ```sh
-npx sv add @scope
-npx sv add file:../path/to/my-addon
-```
+# Install a community add-on by org
+npx sv add @supacool
 
-You can mix and match official and community add-ons, use the interactive prompt or pass args directly:
+# Use a local add-on (for development or custom/private add-ons)
+npx sv add file:../path/to/my-addon
 
-```sh
-# In an existing project
+# Mix and match official and community add-ons
 npx sv add eslint @supacool
 
-# Or when creating a new project
+# Also works when creating a new project directly
 npx sv create --add eslint @supacool
 ```
 
-### Package protocols
-
-For **scoped packages**, the npm package name should be `@org/sv`. Users only need to type the scope:
-
-```sh
-# Installs the npm package `@supacool/sv`
-npx sv add @supacool
-```
-
-For **local add-ons**, use the `file:` protocol. This is useful during development, but also for running custom add-ons that don't need to be published:
-
-```sh
-npx sv add file:../path/to/my-addon
-```
-
-> [!NOTE]
-> Unscoped packages are not supported yet
-
-### How to create a community add-on
-
-Please checkout the [Add-on Docs](community) for more details.
+Want to create your own? Check the [Add-on Docs](community).

From 0c3f9ee33388f43f5afc91b49db773f003b6061a Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 17:56:34 +0200
Subject: [PATCH 12/12] move things around

---
 .../docs/30-add-ons/{16-better-auth.md => 02-better-auth.md}  | 0
 documentation/docs/30-add-ons/99-community.md                 | 4 ++--
 documentation/docs/40-add-ons-community/index.md              | 3 ---
 3 files changed, 2 insertions(+), 5 deletions(-)
 rename documentation/docs/30-add-ons/{16-better-auth.md => 02-better-auth.md} (100%)
 delete mode 100644 documentation/docs/40-add-ons-community/index.md

diff --git a/documentation/docs/30-add-ons/16-better-auth.md b/documentation/docs/30-add-ons/02-better-auth.md
similarity index 100%
rename from documentation/docs/30-add-ons/16-better-auth.md
rename to documentation/docs/30-add-ons/02-better-auth.md
diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index 4a635ec2f..438d25fca 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -1,5 +1,5 @@
 ---
-title: create your own
+title: [create your own]
 ---
 
 > [!NOTE]
@@ -144,7 +144,7 @@ Your add-on must have `sv` as a peer dependency and **no** `dependencies` in `pa
 
 ### Naming convention
 
-Name your package `@your-org/sv`. Users install it by typing just the scope:
+Name your package `@your-org/sv`. Users install it by typing just the org:
 
 ```sh
 # npm package: @your-org/sv
diff --git a/documentation/docs/40-add-ons-community/index.md b/documentation/docs/40-add-ons-community/index.md
deleted file mode 100644
index 70930b7ca..000000000
--- a/documentation/docs/40-add-ons-community/index.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-title: Add-ons (Community)
----