docs: add docs

README.md

@@ -1,2 +1,154 @@
-# cuddle
+# Cuddle
 
+Cuddle aims to reduce the complexity of building code projects. It allows either
+individuals or organisations to share scripts and workflows, as well as keep a
+dynamic inventory of their code.
+
+At its most basic allows enforcing a schema for projects, further it allows the
+sharing of scripts, pipelines, templates, and much more.
+
+```bash
+cuddle init
+```
+
+Cuddle is meant to be used in the degree that it makes sense for you, it can be
+adopted quickly to improve code sharing, and be fully bought into to provide a
+full suite of project level solutions to offload requirements of developers.
+Start small with scripts and plans, and gradually adopt features from there as
+you need them.
+
+## Usage
+
+Cuddle is primarily a cli based tool, but ships with optional server components.
+Server components helps enhance the features of cuddle, such that variables can
+be enforced at runtime, actions be downloaded instead of built and much more. It
+all works on a gradual adoption process, so as an operator you can gradually add
+features as you mature and need them.
+
+A cuddle workflow is split up into:
+
+- Projects: A project is what most users interface with, you can think of it as
+  the cockpit of a car. You can use all the bells and whistles, but somebody
+  else has built up all the user journeys you're interacting with.
+- Plans: A plan is the engine room of the car, it ties together components,
+  features and requirements for use in the cockpit. The plan usually faciliates
+  most of the infrastructure an application stands to outsource. Such as scripts
+  to run, build, test an application, build its templates for deployment, run
+  pipelines, common actions. Plans specialize in building preciely what the
+  projects needs, as such your organisation or yourself, should only have a
+  handful of them at most. To further reduce duplication of work between plans,
+  components can be used to abstract common features required by plans, such as
+  templating, individual components for templates.
+- Components: Components are a slice of features not useful in of itself, but
+  used by plans to further their behavior, a sample component may be a template
+  part, which includes a list of allowed ip addresses for internal
+  communication, it may be how to build an ingress, ship a docker container to a
+  registry, basically small individual components useful for a larger whole.
+- Actions: are code units that can take a variety of forms, golang, rust, bash,
+  what have you. All of them are accessed by `cuddle do`, individual components
+  can take the form of actions, if desired
+- Global: Is a set of actions and features that are available anywhere a user
+  might need them. For example it can be a solution to easily log into
+  production environments, release code to production, get the menu from the
+  canteen, etc.
+- Personal: Is a config an org can decide the users and develoeprs fill out, it
+  can help other tooling better enhance the experience. For example it may be
+  useful to always have the developers email available, if for example we want
+  to trigger an automatic login for them.
+
+### Init
+
+`cuddle init` will bootstrap a project either from scratch, or just adding
+required `cuddle.toml` parts.
+
+A `cuddle.toml` is required to access project level `cuddle` commands. Such as
+`cuddle do`, `cuddle get`, `cuddle validate`, etc.
+
+`cuddle.toml` looks something like this:
+
+```toml
+[project]
+name = "some-cuddle-project"
+owner = "kjuulh"
+```
+
+What is generated out of the box is a _bare_ project. A bare project doesn't
+share any features, or enforce any requirements on its schema from its plan. It
+is most useful for projects that doesn't fit any mold, or for individual users
+simply testing out the framework.
+
+### Actions
+
+`cuddle actions` are project level scripts that can take a variety of forms.
+Actions are invoked via. `cuddle do` when inside of a project, most projects
+won't build actions themselves, instead they will depend on what their plan
+provides for them.
+
+Actions can be bootstrapped via. `cuddle init actions`, an action is slice of a
+cli. Cuddle provides a convenient way of building them, such that they are easy
+to build, maintain and operate. Most actions are written in either golang or
+rust, but bash and lua is also available.
+
+```toml
+[project]
+# ...  
+
+[project.actions.run]
+type = "bash"
+command = """
+  cargo run -p some-cuddle-project -- $@
+"""
+```
+
+This action can be invoked via.
+
+```bash
+cuddle do run
+```
+
+Scripts are also based on convention, so if a rust action is used:
+
+```bash
+cuddle init action rust
+```
+
+Nothing will be added to the `cuddle.toml` instead you'll receive a
+`actions/rust/` project where you can fill out the clis according to the
+template given.
+
+### Plans
+
+Plans are a crucial component for code sharing, enforcement of values, metrics
+and so on. Plans provide a predefined journey for how to work with a specific
+type of application. I.e. what does our organisation think a Rust application
+look like?
+
+Plans are maintained via. the `plan` section of the `cuddle.toml` file
+
+```toml
+[plan]
+git = "https://github.com/kjuulh/some-cuddle-plan.git"
+branch = "main"
+
+# Alternatively
+plan = "https://github.com/kjuulh/some-cuddle-plan.git" # if you want the default
+
+[project]
+# ...
+```
+
+A plan itself will be maintained via. a `cuddle.plan.toml` file.
+
+```bash
+cuddle init plan
+```
+
+```toml
+[plan]
+name = "some-cuddle-plan"
+
+[plan.components]
+canteen = {git = "https://github.com/kjuulh/canteen"}
+ingress = {git = "https://github.com/kjuulh/cuddle-ingress"}
+ip-allowlist = {git = "https://github.com/kjuulh/ip-allowlist"}
+```