cassiopeia: adding more types to the time file abstraction

1 files changed, 64 insertions, 0 deletions

diff --git a/apps/cassiopeia/README.md b/apps/cassiopeia/README.md
new file mode 100644
index 000000000000..d6456bf7f403
--- /dev/null
+++ b/apps/cassiopeia/README.md
@@ -0,0 +1,64 @@
+# cassiopeia
+
+A simple time tracking tool for the kookie office ecosystem.
+
+The kookie office ecosystem is a set of free software, plain text
+tools that I use to run my business.  The other tool you may want to
+look at is called [invoice]!
+
+[invoice]: https://git.spacekookie.de/kookienomicon/tree/infra/libkookie/overlays/kookie/invoice
+    
+## How to use
+
+Each time file only tracks a single customer or project that you are
+working on.  The time file itself is simply a set of commands,
+followed by associated data.  The following four keywords exist:
+
+* `HEADER`: define metadata about the client, and store the time file
+  version to avoid parsing with an incompatible version in the future
+* `START`: opens a work session with a local timezone timestamp
+* `STOP`: closes a work session with a local timezone timestamp
+* `INVOICE`: mark the previous section of sessions as "billed".  This
+  is useful if a project is long-running and you want to bill parts of
+  the work that you have been doing.
+
+It is recommended not to write this file by hand, although you
+definitely can.  Lines starting with `;;` are comments and will be
+ignored.  Careful though: they will be stripped from the file next
+time that cassiopeia writes it out.  Comment pass-through is on the
+roadmap, but not yet implemented!
+
+`cass(1)` comes with a few commands
+
+- `start` will start tracking for an account
+- `stop` will stop tracking and error if no open slot exists
+- `invoice` will add an invoice block to the time file
+
+All commands require a `-f` (or `--file`) parameter to know which time
+file they are operating on.  If none is provided, the `time.cass` file
+in the current working directory is tried.  If this does not exist,
+the program exits with an error.
+
+By default time values are rounded to the next 15 minutes.  To disable
+this, pass `-r` to any command.
+
+
+## Interaction with invoice
+
+cassiopeia is designed to output `.yml` configuration that can be used
+to generate invoices for your clients.  For this, it needs access to
+your client database, and uses the `client` and `project` keys in your
+time file header to look them up.  If none are present, you can pass
+this data to the `invoice` command manually with `--client` and
+`--project`.  You provide your client database path with `--client-db`
+
+The following command will generate an invoice for a project done for
+the `ACME inc.` client:
+
+```
+$ cass invoice --client-db /home/office/clients.yml --client acme --project world-domination
+```
+
+Contrutions welcome via my [public inbox]
+
+[public-inbox]: https://lists.sr.ht/~spacekookie/public-inbox