chore: docs ++

TODO.md

@@ -31,6 +31,9 @@
 - [ ] @babel/register@7.18.x has a bug
 - [ ] `$flecks/db/sequelize` should be `$flecks/db.sequelize`
 - [x] `url()` in styles breaks HMR
+- [ ] 2 underscores for `FLECKS_ENV` variables
+- [ ] flecks add
+
 # Next
 
 # Webpack 5

build/docusaurus.config.js

@@ -27,7 +27,7 @@ export default async function flecksDocusaurus() {
           title: 'flecks',
           logo: {
             alt: 'flecks logo',
-            src: 'flecks.png',
+            src: 'flecks-textless.png',
           },
           items: [
             {
@@ -39,7 +39,7 @@ export default async function flecksDocusaurus() {
         },
         footer: {
           style: 'dark',
-          copyright: `Copyright © ${new Date().getFullYear()} cha0s. Built with Docusaurus.`,
+          copyright: `Copyright © ${new Date().getFullYear()} cha0s. Built with flecks and Docusaurus.`,
         },
       }),
   };

website/docs/cli.mdx

@@ -1,8 +1,10 @@
 ---
 title: Command-line interface
-description: Document your project.
+description: Use built-in commands and write your own.
 ---
 
+import Create from '@site/helpers/create';
+
 # Command-line interface
 
 flecks has a command-line interface for building, linting, testing, and so much more.
@@ -56,5 +58,178 @@ starter configuration will also be copied to your `build` directory, if it doesn
 ## Your commands
 
 You can implement your own command by implementing
-[`@flecks/core.commands`](/docs/flecks/@flecks/dox/hooks#fleckscorecommands) in your fleck.
+[`@flecks/core.commands`](/docs/flecks/@flecks/dox/hooks#fleckscorecommands) in your fleck. Let's
+run through the process.
+
+### Implement <code>@flecks/core&#8203;.commands</code>
+
+First, create an application:
+
+<Create type="app" pkg="cli_test" />
+
+Move into the new project and create a fleck:
+
+<Create type="app" pkg="fortune" />
+
+We're going to be creating a fortune teller command that will tell you when you will find love.
+:heart_eyes:
+
+Edit your `build/flecks.yml` and add your new fleck:
+
+```yml
+'@flecks/core': {}
+'@flecks/server': {}
+// highlight-next-line
+'@cli_test/fortune:./packages/fortune/src': {}
+```
+
+### Create a command that takes an option
+
+Now, edit `packages/fortune/src/index.js` to look like this:
+
+```javascript
+export const hooks = {
+  '@flecks/core.commands': () => ({
+    fortune: {
+      options: [
+        ['-n, --be-nice', 'be nice'],
+      ],
+      description: 'find your true love',
+      action: async ({beNice}) => {
+        console.log(`It will be ${Math.floor(Math.random() * 10) + 2} days until you meet your true love!`);
+        if (!beNice) {
+          console.log('You might also stub your toe.');
+        }
+      },
+    },
+  }),
+};
+```
+
+### Inspect and invoke your command
+
+Now, invoke flecks like so:
+
+```bash
+npx flecks --help
+```
+
+You will see among the commands listed:
+
+```
+  fortune [options]         find your true love
+```
+
+Run the command with the `--help` option:
+
+```bash
+npx flecks fortune --help
+```
+
+You will see this output:
+
+```
+Usage: flecks fortune [options]
+
+find your true love
+
+Options:
+  -n, --be-nice  be nice
+```
+
+Let's try it!
+
+```bash
+npx flecks fortune --be-nice
+```
+
+You will see something like:
+
+```
+It will be 11 days until you meet your true love!
+```
+
+How about without our option:
+
+```bash
+npx flecks fortune
+```
+
+You will see something like:
+
+```
+It will be 7 days until you meet your true love!
+You might also stub your toe.
+```
+
+### Define arguments
+
+You can also define arguments in addition to options. Let's add an argument that takes the user's
+name to personalize the output:
+
+```javascript
+export const hooks = {
+  // highlight-start
+  '@flecks/core.commands': (program, flecks) => {
+    const {Argument} = flecks.fleck('@flecks/core/server');
+    return {
+    // highlight-end
+      fortune: {
+        // highlight-start
+        args: [
+          new Argument('[name]', 'your name')
+        ],
+        // highlight-end
+        options: [
+          ['-n, --be-nice', 'be nice'],
+        ],
+        description: 'find your true love',
+        // highlight-next-line
+        action: async (name = 'person', {beNice}) => {
+          // highlight-next-line
+          console.log(`Hey, ${name}. It will be ${Math.floor(Math.random() * 10) + 2} days until you meet your true love!`);
+          if (!beNice) {
+            console.log('You might also stub your toe.');
+          }
+        },
+      },
+    // highlight-start
+    };
+  },
+  // highlight-end
+};
+```
+
+Notice that we added the argument to... the arguments.
+
+Try it again:
+
+```bash
+npx flecks fortune --be-nice
+```
+
+You will see e.g.:
+
+```
+Hey, person. It will be 7 days until you meet your true love!
+```
+
+That's because we set the default name to `'person'` in the code above. Let's try passing in a
+name:
+
+```bash
+npx flecks fortune cha0s
+```
+
+Now the output looks like:
+
+```
+Hey, cha0s. It will be 7 days until you meet your true love!
+You might also stub your toe.
+```
+
+### Going further
+
+flecks uses [Commander.js](https://github.com/tj/commander.js#quick-start) under the hood to build its CLI.
+It might be worth checking out their documentation for any more advanced usage.
 

website/docs/configuration.mdx

@@ -1,20 +1,30 @@
 ---
 title: Configuration
-description: Configure `flecks.yml` and your application.
+description: Configure `build/flecks.yml` and your application.
 ---
 
 import InstallPackage from '@site/helpers/install-package';
 
-You have a flecks application! ...but it doesn't do much. This is because a flecks application is
-composed of individual flecks. By default, your application will have two flecks: `@flecks/core` and
-`@flecks/server`. Each fleck may have configuration that can be set through `flecks.yml`. For a
-list of configurable core flecks, see [the generated configuration page](/docs/flecks/@flecks/dox/config).
+# Configuration
 
-## First steps
+You have a flecks application! ...but it doesn't do much. This is because a flecks application is
+composed of individual flecks and by default, your application will have only two flecks:
+`@flecks/core` and `@flecks/server`. Your `build/flecks.yml` file will look like this:
+
+```yml
+'@flecks/core': {}
+'@flecks/server': {}
+```
+
+Each fleck may have configuration that can be set through `build/flecks.yml`.
+For a deep dive of configurable core flecks, see
+[the generated configuration page](/docs/flecks/@flecks/dox/config).
+
+## `build/flecks.yml`
 
 A good first configuration step is to set the ID of your application.
 
-Your `flecks.yml` will look like this after you generate your application:
+Your `build/flecks.yml` will look like this after you generate your application:
 
 ```yml
 '@flecks/core': {}
@@ -22,7 +32,7 @@ Your `flecks.yml` will look like this after you generate your application:
 ```
 
 Your application's ID is configured at the `id` key of `@flecks/core`'s configuration. To set your
-application's ID to `hello_world`, update your `flecks.yml` to look like this:
+application's ID to `hello_world`, update your `build/flecks.yml` to look like this:
 
 ```yml
 // highlight-start
@@ -32,10 +42,10 @@ application's ID to `hello_world`, update your `flecks.yml` to look like this:
 '@flecks/server': {}
 ```
 
-## Getting somewhere
+## Adding more
 
 If you were studious enough to take a peek at [the generated configuration page](/docs/flecks/@flecks/dox/config)
-above, you may have noticed that there were a bunch more flecks there than just the two in our
+above, you may have noticed that there were a lot more flecks there than just the two in our
 application.
 
 For instance, there is a `@flecks/web` fleck that turns your little old server application into one
@@ -45,7 +55,7 @@ that can build and serve a webpage. You can add it to your application in two st
 
 <InstallPackage pkg="@flecks/web" />
 
-2. Add the fleck to your `flecks.yml`:
+2. Add the fleck to your `build/flecks.yml`:
 
 ```yml
 '@flecks/core':

website/docs/creating-flecks.mdx

@@ -3,6 +3,7 @@ title: Creating a fleck
 description: A fleck is a module but also so much more.
 ---
 
+import Create from '@site/helpers/create';
 import InstallPackage from '@site/helpers/install-package';
 
 So you want to create a fleck. Think you got what it takes?
@@ -40,20 +41,24 @@ If you are following along from the previous getting started
 
 Let's make your website greet the user with a good ol' **hello world**.
 
-To do this, you'll be creating your own little fleck. You'll create the fleck at `src/hello-world`.
-A fleck is just a package, so we'll need to add a `package.json`. Nothing much; a name will suffice:
+To do this, you'll be creating your own little fleck. flecks also provides a built-in utility to
+create a fleck.
 
-### `package.json`
+:::note
 
-```json
-{
-  "name": "hello-world",
-}
-```
+You may have noticed that your little starter application has a `packages` directory. By default,
+flecks structures your application as a monorepo.
 
-and we'll add our little source file:
+This isn't any hard requirement, it's only a suggestion.
 
-### `index.js`
+:::
+
+Let's create our little fleck:
+
+<Create type="fleck" pkg="say-hello" />
+
+After some output, you'll find your new fleck at `packages/say-hello`. There is a source file at
+`packages/say-hello/src/index.js` but for now it's empty. Let's fill it out a bit:
 
 ```javascript
 exports.hooks = {
@@ -63,16 +68,7 @@ exports.hooks = {
 };
 ```
 
-You should now have a `src` directory that looks like this:
-
-```
-src
-└── hello-world
-    ├── index.js
-    └── package.json
-```
-
-Good? Good! Now, let's add this to our `flecks.yml`:
+Good? Good! Now, let's add this to our `build/flecks.yml`:
 
 ```yml
 '@flecks/core':
@@ -80,7 +76,7 @@ Good? Good! Now, let's add this to our `flecks.yml`:
 '@flecks/server': {}
 '@flecks/web': {}
 // highlight-next-line
-'hello-world:./src/hello-world': {}
+'@hello-world/say-hello:./packages/say-hello/src': {}
 ```
 
 ### Aliasing for the win
@@ -91,21 +87,26 @@ path to the package.
 
 Now, restart your application and visit your website. Glorious, isn't it?
 
-By the way, your other application code can import the alias (e.g. `require('hello-world');`)
+By the way, your other application code can import using the alias (e.g.
+`require('@hello-world/say-hello');`)
 [as if it were a package](https://webpack.js.org/configuration/resolve/#resolvealias).
 
 <details>
   <summary>Wait, my flecks don't have to be in <code>node_modules</code>?</summary>
 
-  Nope! That's an intentional feature. When you're developing applications, it can be real nice to
+  Nope! When you're developing applications, it can be real nice to
   just pull in local source "packages". If you're wondering how this works, see
   [the alias concept page](#todo).
 
   You probably shouldn't do things like name an alias the same thing as a package that actually
-  exists in your `node_modules` directory. If you'd like to help define what happens in that case
-  you could always [submit a pull request](https://github.com/cha0s/flecks/compare).
+  exists in your `node_modules` directory. This is mitigated if you use the default monorepo
+  structure (unless your application name is identical to a monorepo organization that already
+  exists on `npm`: don't do that).
 
-  That being said, sharing your package on npm is a cool thing to do, so be rad and share your
+  If you'd like to help define what happens in these edge cases you could
+  always [submit a pull request](https://github.com/cha0s/flecks/compare). :smile:
+
+  That being said, sharing your packages on npm is a cool thing to do, so be rad and share your
   awesome flecks with the rest of us!
 </details>
 
@@ -116,7 +117,7 @@ application inside of an instance of [Electron](https://www.electronjs.org/). Yo
 
 <InstallPackage pkg="@flecks/electron" />
 
-Then you'll update your `flecks.yml` like so:
+Then you'll update your `build/flecks.yml` like so:
 
 ```yml
 '@flecks/core':
@@ -130,18 +131,23 @@ Then you'll update your `flecks.yml` like so:
     - '@flecks/electron'
 // highlight-end
 '@flecks/web': {}
-'hello-world:./src/hello-world': {}
+'@hello-world/say-hello:./packages/say-hello/src': {}
 ```
 
 ### ~~flecking~~ pecking order
 
 Did you notice we added some configuration to `@flecks/server`? The `up` key configures the order in
-which flecks are initialized when the server comes up. We make sure `@flecks/web` initializes
-before `@flecks/electron` so there's a webpage to visit. There are future plans to make this the
-default with no configuration required.
+which flecks are initialized when the server comes up. We make sure `@flecks/web` serves a webpage
+before `@flecks/electron` tries to visit it.
+
+:::note
+
+There are future plans to make this the default with no configuration required.
+
+:::
 
 Finally `npm start` and you should see something like this:
 
 ![An image of our simple hello world application running inside an Electron window](./flecks-electron.png)
 
-Cool, huh?
+Isn't it beautiful? :relieved:

website/docs/database.mdx

@@ -1,6 +1,6 @@
 ---
 title: Database
-description: How to define models and connect to a database.
+description: Define models and connect to a database.
 ---
 
 import Create from '@site/helpers/create';
@@ -9,7 +9,7 @@ import InstallPackage from '@site/helpers/install-package';
 # Database
 
 flecks provides database connection through [Sequelize](https://sequelize.org/) and database
-server instances through either flat SQLite databases or [Docker](https://www.docker.com/)ized
+server instances through either flat SQLite databases or [Docker](https://www.docker.com/)-ized
 database servers.
 
 ## Install and configure
@@ -24,7 +24,7 @@ Now in your new application directory, install `@flecks/db`:
 
 Then, add the fleck to your `build/flecks.yml`:
 
-```yml
+```yml title="build/flecks.yml"
 '@flecks/core': {}
 // highlight-next-line
 '@flecks/db': {}
@@ -57,7 +57,7 @@ First, create a fleck in your application:
 
 Then, add it to `build/flecks.yml`:
 
-```yml
+```yml title="build/flecks.yml"
 '@flecks/core': {}
 '@flecks/db': {}
 '@flecks/server': {}
@@ -67,7 +67,7 @@ Then, add it to `build/flecks.yml`:
 
 Now, let's hop into `packages/tags/src/index.js` and add a hook implementation:
 
-```javascript
+```javascript title="packages/tags/src/index.js"
 export const hooks = {
   '@flecks/db/server.models': (flecks) => {
     const {Model, Types} = flecks.fleck('@flecks/db/server');
@@ -116,10 +116,61 @@ Now, `npm start` your application and you will see that line looks different:
   @flecks/core/flecks gathered '@flecks/db/server.models': [ 'Tags' ] +0ms
 ```
 
-Our model is recognized! Let's do something with it. Edit `packages/tags/src/index.js` again like
+Our model is recognized!
+
+## Gathering models
+
+If we stuff all of our models into that file, things are going to start getting unwieldy. Let's
+create a `src/models` directory in our `packages/tags` fleck and add a `tags.js` source file with the following
+code:
+
+```javascript title="packages/tags/src/models/tags.js"
+export default (flecks) => {
+  const {Model, Types} = flecks.fleck('@flecks/db/server');
+  return class Tags extends Model {
+    static get attributes() {
+      return {
+        key: {
+          type: Types.STRING,
+          allowNull: false,
+        },
+        value: {
+          type: Types.STRING,
+          allowNull: false,
+        },
+      };
+    }
+  };
+}
+```
+
+Notice that this looks very similar to how we defined the model above, but this time we're only
+returning the class.
+
+Now, hop over to `src/index.js` and let's rewrite the hook implementation:
+
+```javascript title="packages/tags/src/index.js"
+export const hooks = {
+  '@flecks/db/server.models': Flecks.provide(require.context('./models')),
+}
+```
+
+We're passing the path to our models directory to `require.context` which is then passed to
+`Flecks.provide`. This is completely equivalent to our original code, but now we can add more
+models and keep things tidy.
+
+:::info
+
+For a more detailed treatment of gathering in flecks, see [the gathering guide](#todo).
+
+:::
+
+## Working with models
+
+Let's do something with it. Edit `packages/tags/src/index.js` again like
 so:
 
-```javascript
+```javascript title="packages/tags/src/index.js"
 export const hooks = {
   // highlight-start
   '@flecks/server.up': async (flecks) => {
@@ -127,9 +178,7 @@ export const hooks = {
     console.log('There were', await Tags.count(), 'tags.');
   },
   // highlight-end
-  '@flecks/db/server.models': (flecks) => {
-    // Omitted for clarity...
-  },
+  '@flecks/db/server.models': Flecks.provide(require.context('./models')),
 }
 ```
 
@@ -141,7 +190,7 @@ There were 0 tags.
 
 Not very interesting. Let's add some, but only if there aren't any tags yet:
 
-```javascript
+```javascript title="packages/tags/src/index.js"
 export const hooks = {
   '@flecks/server.up': async (flecks) => {
     const {Tags} = flecks.get('$flecks/db.models');
@@ -154,9 +203,7 @@ export const hooks = {
     console.log('There are', await Tags.count(), 'tags.');
     // highlight-end
   },
-  '@flecks/db/server.models': (flecks) => {
-    // Omitted for clarity...
-  },
+  '@flecks/db/server.models': Flecks.provide(require.context('./models')),
 }
 ```
 
@@ -179,7 +226,7 @@ This means that the database will only persist as long as the life of your appli
 restart it, you'll get a fresh new database every time. Obviously, this isn't very helpful for
 any real purpose. Let's make a change to our `build/flecks.yml`:
 
-```yml
+```yml title="build/flecks.yml"
 '@flecks/core': {}
 '@flecks/db': {}
 // highlight-start
@@ -240,7 +287,7 @@ Let's add another fleck to our project:
 
 Configure `build/flecks.yml`:
 
-```yml
+```yml title="build/flecks.yml"
 '@flecks/core': {}
 '@flecks/db': {}
 // highlight-start
@@ -358,7 +405,7 @@ Then, take a look in the `dist` directory. You'll see a file there called `docke
 `@flecks/docker` automatically emits this file when you build your application for production to
 make container orchestration easier. Let's take a look:
 
-```yml
+```yml title="dist/docker-compose.yml"
 version: '3'
 services:
   flecks_app:
@@ -393,3 +440,8 @@ docker-compose -f dist/docker-compose.yml up
 
 This demonstrates that your application is now being orchestrated by Docker Compose and is
 chugging right along!
+
+## Going further
+
+`@flecks/db` uses Sequelize under the hood. You can dive into
+[their documentation](https://sequelize.org/docs/v6/getting-started/) to learn even more.

website/docs/electron.mdx

@@ -1,4 +1,4 @@
 ---
 title: Electron
-description: How to run your application in Electron and build for distribution.
+description: Run your application in Electron and build for distribution.
 ---

website/docs/installation.mdx

@@ -1,6 +1,32 @@
 ---
 title: Installation
-description: How to get started with your first flecks project
+description: How to get started with your first flecks project.
 ---
 
-This is some text.
+import Create from '@site/helpers/create';
+
+# Installation
+
+The first step toward creating an application with flecks is to use the built-in
+creation utility:
+
+<Create type="app" pkg="hello-world" />
+
+## Start your application
+
+Now, move into your new project directory and run `npm start`. You'll see a bunch of output, but the
+important thing is the last line:
+
+```
+  @flecks/server/entry up! +7ms
+```
+
+That means we've got an application up and running!
+
+## Do something interesting
+
+The only problem is that it doesn't do a single
+thing except sit there. Let's get into how to configure our application to do something interesting
+and start working on creating a fleck of our own.
+
+

website/docs/react.mdx

@@ -1,4 +1,4 @@
 ---
 title: React
-description: How to define a root component, enable, SSR, and more.
+description: Define root components, enable SSR, and more.
 ---

website/docs/redux.mdx

@@ -1,4 +1,4 @@
 ---
 title: Redux
-description: How to define your reducers and state.
+description: Define your actions, reducers, and state.
 ---

website/docs/repl.mdx

@@ -1,4 +1,4 @@
 ---
 title: REPL
-description: How to start a REPL server and connect to it.
+description: Start a REPL server and connect to it.
 ---

website/docs/sockets.mdx

@@ -1,4 +1,4 @@
 ---
 title: Sockets
-description: How to run a websocket server and define packets.
+description: Run a websocket server and define packets.
 ---

website/pages/index.jsx

@@ -11,16 +11,17 @@ function HomepageHeader() {
   return (
     <header className={clsx('hero hero--primary', styles.heroBanner)}>
       <div className="container">
+        <img src="flecks.png" width="128px" />
         <Heading as="h1" className="hero__title">
-          {siteConfig.title}
+          Craft modular apps with ease
         </Heading>
-        <p className="hero__subtitle">{siteConfig.tagline}</p>
+        <p className="hero__subtitle">Uncomplicated, efficient, and customizable</p>
         <div className={styles.buttons}>
           <Link
             className="button button--secondary button--lg"
             to="/docs"
           >
-            Your documentation here
+            Get started
           </Link>
         </div>
       </div>