docs(book): wrote docs on custom engines

docs/next/en-US/SUMMARY.md

@@ -55,6 +55,7 @@
     -   [Writing Plugins](/docs/reference/plugins/writing)
     -   [Security Considerations](/docs/reference/plugins/security)
     -   [Publishing Plugins](/docs/reference/plugins/publishing)
+-   [Engines](/docs/reference/engines)
 -   [Deploying](/docs/reference/deploying/intro)
     -   [Server Deployment](/docs/reference/deploying/serverful)
     -   [Serverless Deployment](/docs/reference/deploying/serverless)

docs/next/en-US/reference/engines.md

@@ -0,0 +1,31 @@
+# Engines
+
+Perseus' plugins system aims to enable extrreme extensibility of Perseus to support niche use-cases, but it can't do everything. Occasionally, a problem is best solved by rewriting significant parts of the contents of `.perseus/`. These contents constitute Perseus' *engine*, the thing that ties together all the code exposed by the various Perseus libraries into an app. As mentioned before, the engine actually takes in your app's code as a library and produces a final app based on it (so technically, the engine is your *app* in the strictest sense, you provide the details).
+
+The Perseus CLI comes bundled with the default Perseus engine, but, be it for experimentation of necessary workarounds, it also supports using custom engines by providing the `-e` option at the top level (that is, `perseus -e <engine> serve` or similar). The value of this should be a URL to a Git repository available online, and a branch name can be optionally supplied after an `@` at the end (e.g. `https://github.com/user/[email protected]`). The URL provided should be one that can be put into the `git clone` command, and the branch (if provided) must be available on the repository. If you're routinely using an alternative engine, it's best for convenience to alias the `perseus` command to `perseus -e <custom-engine-url>` on your system.
+
+Note that if a custom branch is not supplied, the CLI will fetch from the `stable` branch by default, which MUST correspond to the latest stable version of the engine.
+
+## Developing Engines
+
+Developing a custom engine can be quite difficult, because Perseus expects a lot of things to be true. For starters, you'll need to follow a folder structure *identical* to the default Perseus engine (which you can find [here](https://github.com/arctic-hen7/perseus/tree/main/examples/basic/.perseus)). There are three modules here, the root one (responsible for exposing a library that `wasm-pack` will interpret as the app and exposing the user's app's code to the other modules), the server, and the builder (responsible for building and exporting). 
+
+The process of actually coding your engine should best start by copying the code of the default engine, and then tweaking it piece by piece. For convenience, you may wish to do this in the context of the entire Perseus repository (which provides internal tools optimized for using an engine that's being actively developed). Beyond this, documentation is best provided by the actual code itself. However, any problems you have can be raised on [the Perseus Discord channel on Sycamore's server](https://discord.com/invite/GNqWYWNTdp).
+
+### Working with the CLI
+
+The CLI works with the binaries in `builder` in particular, and you should be careful to keep the same file structure as the default engine. Further, the CLI expects certain dependencies in certain places. Specifically, the root and builder crates are expected to import `perseus`, and the server crate is expected to import `perseus` and all of its integrations (though you don't need to use all of them). In the branch of your repository used by users to download from, you'll need to use the tokens `PERSEUS_VERSION`, `PERSEUS_ACTIX_WEB_VERSION`, and `PERSEUS_WARP_VERSION` to replace the versions of these packages in `Cargo.toml` files. The reason for this is that the CLI will replace them with the appropriate version directly (and relative paths to the packages will be used when working inside the Perseus repository).
+
+### Versioning
+
+You may version your engine however you'd like to, though, for simplicity, it's generally recommended that you keep your engine on the same version number as the Perseus packages. The reason for this is because the CLI will impose its own version onto your engine (e.g. if you were using `v0.2.2` but the user's copy of the CLI was at `v0.3.1`, the latter would be used). This means that your engine can break with changes in the CLI, hence why it's recommended to keep versions in lockstep.
+
+### Semantic Versioning
+
+Perseus is strict with semantic versioning and not introducing breaking changes to end users, but the same policy does **not** apply to engines. Internal code used by engines and not end users could experience breaking changes at any time, which is why it's recommended to explicitly tell your users to stay on one version of Perseus until you've prepared for an upgrade. Note also that, as Perseus becomes more mature, these changes will become much less frequent.
+
+*Once Perseus reaches v1.0.0, the policy of introducing breaking changes without warning to code used only by engines will be reviewed.*
+
+## A Final Note
+
+Engines are suitable for *extreme* customizations of Perseus. As a general rule, if you can do it with a plugin, even if it's inconvenient, you should, because maintaining a custom engine will likely be very difficult!