rework docs (#43)

* rework docs

* more justfile

Author: lostmygithubaccount

docs/_quarto.yml

@@ -53,8 +53,8 @@ website:
       #- sidebar:how-to
       #- sidebar:reference
 
-    right:
-      - posts.qmd
+    # right:
+      #- posts.qmd
       #- release_notes.md # TODO: release notes
       #- sidebar:contribute
 
@@ -74,7 +74,11 @@ website:
       collapse-level: 2
       contents:
         - why.qmd
-        - auto: concepts/*.qmd
+        - concepts/bots.qmd
+        - concepts/messages.qmd
+        - concepts/attachments.qmd
+        - concepts/flows.qmd
+        - concepts/tasks.qmd
     - id: how-to
       title: "How-to"
       style: "docked"

docs/concepts/llms.qmd renamed to docs/concepts/archive/llms.qmd

@@ -0,0 +1,43 @@
+# Attachments
+
+Ibis Birdbrain passes Python objects as `Attachments` to [`Messages`](./messages.qmd). This allows the user, itself, and (eventually) other bots to interact with data, code, and more.
+
+
+## Usage
+
+```{python}
+from ibis_birdbrain.attachments import Attachment, Attachments
+
+a1 = Attachment(content="Hello, world!")
+a1
+```
+
+## TableAttachment
+
+A `TableAttachment` contains an Ibis table:
+
+```{python}
+import ibis
+
+from ibis_birdbrain.attachments import TableAttachment
+
+ibis.options.interactive = True
+
+t = ibis.examples.penguins.fetch()
+
+a2 = TableAttachment(content=t)
+a2
+```
+
+Notice the name, description (schema), and preview are automatically populated.
+
+## CodeAttachment
+
+A `CodeAttachment` contains code -- typically Python or SQL:
+
+```{python}
+from ibis_birdbrain.attachments import CodeAttachment
+
+a3 = CodeAttachment(content="select 1 as id", language="sql")
+a3
+```

docs/concepts/ops.qmd renamed to docs/concepts/archive/ops.qmd

@@ -0,0 +1,10 @@
+# Bots
+
+Ibis Birdbrain implements a `Bot` calss that can be used to instantiate one or more bots that automate various tasks.
+
+## Usage
+
+```{python}
+from ibis_birdbrain import Bot
+Bot
+```

docs/concepts/platforms.qmd renamed to docs/concepts/archive/platforms.qmd

@@ -0,0 +1,14 @@
+# Flows
+
+Ibis Birdbrain's [`Bot`](./bot.qmd) chooses a `Flow` to execute based on [`Messages`](./messages.qmd).
+
+A Flow takes Messages as input and returns Messages as output. The details of a given Flow are specific to itself, running a series of [`Tasks`](./tasks.qmd) to accomplish its goal.
+
+## Usage
+
+```{python}
+from ibis_birdbrain.flows import Flow, Flows
+
+flow = Flow()
+flow
+```

docs/concepts/user-interfaces.qmd renamed to docs/concepts/archive/user-interfaces.qmd

@@ -0,0 +1,25 @@
+# Messages
+
+Ibis Birdbrain communicates with the user, itself, and (eventually) other bots through `Messages`. A `Message` is a simple wrapper around text with metadata and optional [`Attachments`](./attachments.qmd).
+
+
+## Usage
+
+```{python}
+from ibis_birdbrain.messages import Message, Messages, Email
+
+m1 = Message("Hello, world!")
+m1
+```
+
+## Emails
+
+Currently, the only implementation of `Message` that is viewable as a proper string is `Email`.
+
+```{python}
+e1 = Email("Hello")
+e2 = Email(", world!")
+
+messages = Messages([e1, e2])
+messages
+```

docs/concepts/attachments.qmd

@@ -0,0 +1,12 @@
+# Tasks
+
+Ibis Birdbrain's [`Flow`](./flow.qmd) executes one or more `Tasks` to accomplish its goal. A `Task` is a single unit of work that takes a [`Message`](./message.qmd) as input and returns a `Message` as output.
+
+## Usage
+
+```{python}
+from ibis_birdbrain.tasks import Task, Tasks
+
+task = Task()
+task
+```