docs(plugins): clear up some ideas and fix links

update castopod-plugins-manager + other dependencies to latest

docs/src/content/docs/en/plugins/create.mdx

@@ -8,12 +8,12 @@ Missing a feature in Castopod? Build it as a plugin and even
 [share it with the community](./share)!
 
 In order to get started, you first need to
-[setup your Castopod dev environment](https://code.castopod.org/adaures/castopod/-/blob/develop/CONTRIBUTING-DEV.md).
+[set up your Castopod dev environment](https://code.castopod.org/adaures/castopod/-/blob/develop/CONTRIBUTING-DEV.md).
 
 ## 1. Create the plugin folder
 
-You'll first need to create your [plugin folder](./#plugin-folder-structure) in
-the `plugins/` directory.
+You'll first need to create your
+[plugin folder](./#anatomy-of-a-castopod-plugin) in the `plugins/` directory.
 
 ### Using the create command <Badge text="Recommended" size="small" />
 
@@ -24,8 +24,8 @@ following CLI command:
 php spark plugins:create
 ```
 
-👉 You will be prompted for metadata and hooks usage to have a skeleton plugin
-project generated for you!
+👉 You will be prompted for metadata and hooks usage in order to have a
+personalized skeleton plugin generated for you!
 
 ### Manual setup
 
@@ -49,7 +49,7 @@ project generated for you!
 
         </FileTree>
 
-          See the [manifest reference](./manifest).
+          See the [manifest reference](./reference/manifest-json).
 
     3. add the Plugin.php class
 
@@ -64,7 +64,7 @@ project generated for you!
 
 ## 2. Build your plugin
 
-Now that your plugin folder is set, you can start working on your Plugin's logic
+Now that your plugin folder is set, you can start working on your plugin's logic
 by implementing [the hooks](./reference/hooks) needed.
 
 ### Settings forms
@@ -72,7 +72,7 @@ by implementing [the hooks](./reference/hooks) needed.
 You can prompt users for data through settings forms.
 
 These forms can be built declaratively using the
-[settings attribute](./manifest#settings) in your manifest.
+[`settings` attribute](./reference/manifest#settings) in your manifest.
 
 ```json
 // manifest.json
@@ -100,14 +100,15 @@ These forms can be built declaratively using the
 }
 ```
 
-This example will generate settings forms at 3 levels:
+This example will generate 3 different settings forms at 3 different levels in
+the Castopod admin area:
 
-- `general`: a general form to prompt data to be used by the plugin
-- `podcast`: a form for each podcast to prompt for podcast specific data
-- `episode`: a form for each episode to prompt for episode specific data
+- `general`: a general form
+- `podcast`: a form for each podcast
+- `episode`: a form for each episode
 
-The data can then be accessed in the Plugin class methods via helper methods
-taking in the field key:
+You can then access the data (input by the user) via helper methods by
+specifying the field key as a parameter:
 
 ```php
 $this->getGeneralSetting('field-key');

docs/src/content/docs/en/plugins/index.mdx

@@ -50,7 +50,7 @@ easily add new features and enhancements to your podcasting setup!
 ### Plugin manifest (required)
 
 The plugin manifest is a JSON file containing the plugin's metadata and
-declarations.
+technical declarations.
 
 This file will determine whether a plugin is valid or not. The minimal required
 data being:
@@ -64,7 +64,7 @@ data being:
 }
 ```
 
-Checkout the [manifest.json reference](./reference/manifest).
+Checkout the [manifest.json reference](./reference/manifest-json).
 
 ### Plugin class (required)
 
@@ -99,28 +99,30 @@ For example, a plugin living under the `acme/hello-world` folder must be named
 `AcmeHelloWorldPlugin`:
 
 - the first letter of every word is capitalized (ie. PascalCase)
-- any special caracter is removed
+- any special character is removed
 - the `Plugin` suffix is added
 
 </Aside>
 
 ### Plugin README
 
-The `README.md` file is loaded into the plugin's view page for the user to read
-through.  
-It should be used for any additional information to help guide the user in using
-the plugin.
+The `README.md` file should contain with any additional information to help
+guide the user in using the plugin.
+
+It is loaded on Castopod's admin area when the plugin is installed.
 
 ### Plugin LICENSE
 
 In addition to specifying [the license in the manifest](./manifest#license), you
-may add a `LICENSE.md` file. Just as the `README.md` file, its contents will be
-loaded into the plugin's view page for the user to read.
+may add a `LICENSE.md` file.
+
+Just like the `README.md` file, its contents will be loaded into Castopod's
+admin area, in the plugin's view page for the user to read.
 
 ### Plugin icon
 
-The plugin icon is displayed next to its title, it is an SVG file intended to
-give a graphical representation of the plugin.
+Generally, the plugin icon is displayed next to its title, it is an SVG file
+intended to give a graphical representation of the plugin.
 
 The icon should be squared, and be legible in a 64px by 64px circle.
 

docs/src/content/docs/en/plugins/install.mdx

@@ -28,8 +28,8 @@ whenever you run the commands:
 
 - [`plugins-lock.json`](./reference/plugins-lock-json): records the exact
   versions that were actually installed, along with extra metadata. This ensures
-  that even if a plugin updates later, Castopod can reproduce the same working
-  setup you had before.
+  that even if a plugin is updated later, Castopod can reproduce the same
+  working setup you had before.
 
 ### Commands
 
@@ -39,7 +39,7 @@ whenever you run the commands:
   php spark plugins:add acme/hello-world
   ```
 
-- Install a specific version to pin environments:
+- Install a specific version in order to pin environments:
 
   ```sh
   php spark plugins:add acme/hello-world@1.0.0

docs/src/content/docs/en/plugins/reference/hooks.mdx

@@ -75,7 +75,7 @@ public function rssAfterItem(Epsiode $episode, RssFeed $item): void
 
 This hook is executed in the public pages' `<head>` tag.
 
-This is a good place to add meta tags, custom styles, and third-party scripts to
+Here is a good place to add meta tags, custom styles, and third-party scripts to
 Castopod's public pages.
 
 ```php

docs/src/content/docs/en/plugins/reference/manifest-json.mdx

@@ -2,8 +2,10 @@
 title: manifest.json reference
 ---
 
+import { Aside } from "@astrojs/starlight/components";
+
 This page details the attributes of a
-[Castopod Plugin's manifest](../../../../pages/plugin-manifest.schema.json),
+[Castopod Plugin's manifest](../../../../../pages/plugin-manifest.schema.json.ts),
 which must be a JSON file.
 
 ### `name` (required)
@@ -32,8 +34,8 @@ repositories.
 
 ### `authors`
 
-Array one or more persons having authored the plugin. A person is an object with
-a required "name" field and optional "email" and "url" fields:
+Array of one or more persons having authored the plugin. A person is represented
+by object with a required "name" field and optional "email" and "url" fields:
 
 ```json
 {
@@ -43,15 +45,19 @@ a required "name" field and optional "email" and "url" fields:
 }
 ```
 
-Or you can shorten the object into a single string:
+<Aside type="note">
+
+You can shorten the object into a single string:
 
 ```json
 "Jean Deau <jean.deau@example.com> (https://example.com/)"
 ```
 
+</Aside>
+
 ### `homepage`
 
-The URL to the project homepage.
+The URL to the plugin's homepage.
 
 ### `license`
 
@@ -109,8 +115,8 @@ Each level accepts one or more fields, identified by a key.
 }
 ```
 
-The `general`, `podcast`, and `episode` settings are of `Fields` object with
-each property being a field key and the value being a `Field` object.
+The `general`, `podcast`, and `episode` settings are maps with each key being a
+field key and the value being a `Field` object.
 
 #### Field object
 

docs/src/content/docs/en/plugins/reference/plugins-json.mdx

@@ -3,8 +3,8 @@ title: plugins.json
 ---
 
 `plugins.json` declares which plugins are intended for installation and the
-version ranges to satisfy. It is human-edited, concise, and designed for sharing
-intent across environments.
+version ranges they have to satisfy. It is human-edited, concise, and designed
+for sharing intent across environments.
 
 ## Example
 

docs/src/content/docs/en/plugins/reference/plugins-lock-json.mdx

@@ -21,6 +21,7 @@ deployments. It is generated and updated by tooling, not hand-edited.
       },
       "dist": {
         "url": "https://plugins.castopod.org/static/plugins/db/cf/15/ad-aures_custom-rss_dev-main.zip",
+        "path": "",
         "checksum": "dbcf153694f09c5788e6cccbca2db4cb9605faa7c1399d59960edee00fa9f853"
       }
     }
@@ -39,8 +40,8 @@ field shapes or semantics.
 
 ### `plugins`
 
-A mapping from plugin identifier to a locked entry that captures the exact
-resolved version plus source and distribution details. This section is the
+A mapping from a plugin identifier to a locked entry that captures the exact
+resolved version, the source and distribution details. This section is the
 authoritative record for reinstalls.
 
 Each plugin entry contains:
@@ -48,8 +49,9 @@ Each plugin entry contains:
     - `version`: The exact version (or branch reference such as dev-main) that was resolved and installed for this plugin, guaranteeing consistent reinstallation.
 
     - `source`: Describes the canonical source of the plugin’s code used to produce the distribution artifact.
-        - `url`: The upstream repository, typically a Git URL.
-        - `reference`: The exact commit, tag, or revision used, enabling precise provenance and reproducibility.
-    - `dist` Points to the installable artifact and verifies its integrity, analogous to resolved tarballs in npm locks or dist in Composer.
+        - `url`: The upstream Git repository.
+        - `path`: The root path of the plugin.
+        - `reference`: The exact commit or revision used, for provenance and reproducibility.
+    - `dist`: Points to the installable artifact and verifies its integrity.
         - `url`: A direct link to the packaged plugin archive that the installer downloads.
         - `checksum`: A cryptographic hash of the archive used to validate integrity and prevent tampering during install.

docs/src/content/docs/en/plugins/share.mdx

@@ -14,14 +14,15 @@ other podcasters can install it in a few clicks or with one
 
 ## Before submitting
 
-The official Castopod plugin repository has stricter requirements than what’s
-needed for a plugin to merely load in Castopod; it also requires rich metadata
-to improve search, categorization, and discovery.
+The official Castopod plugin repository has stricter requirements than than the
+ones needed for a plugin to merely load in Castopod; it also requires rich
+metadata to improve search, categorization, and discovery.
 
 <Aside type="note">
 
-Quick refresher: skim through [“Anatomy of a plugin”](./#anatomy-of-a-plugin) to
-confirm basic structure and required files before proceeding.
+Quick refresher: skim through
+[“Anatomy of a plugin”](./#anatomy-of-a-castopod-plugin) to confirm basic
+structure and required files before proceeding.
 
 </Aside>