From 92e312fd680b8b9bd4b1c3aa818799d023178ade Mon Sep 17 00:00:00 2001
From: "Lance R. Vick" <lance@distrust.co>
Date: Fri, 6 Dec 2024 15:51:08 -0800
Subject: [PATCH] Document desired data-driven end-game

---
 README.md | 173 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 160 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 1c2a0db..d15f07a 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,168 @@
-# Tracking Time
+# Punchin
 
-To start running PunchIn for a specific client, use:
+A time billing tool for FOSS teams that want to spend as little time tracking time as possible
+
+# Features
+- Invoice Management
+    - automatically log hours to draft invoices via invoice system integration
+- Conversation discovery
+    - Find potentially billable conversations with tracked people, domains, or channels
+- Work Discovery
+    - Find potentially billable commits, tickets, milestones
+- Secret Management
+    - Store all credentials in hardware-token-backed PGP encrypted storage
+
+# Integrations
+- Slack
+- Matrix
+- Forgejo
+- Firefox
+- IMAP
+- InvoiceNinja
+- git
+
+# Workflow
+
+## Setup
+
+1. Register data sources
+
+    ```
+    > punchin login [service]
+    ```
+    - setup chat, email, git accounts, invoice system, etc
+    - Will be asked to add all services if none specified
+
+2. Register a new client
+
+    ```
+    > punchin client add
+    ```
+    - Select client from list of clients defined in invoicing system
+    - Setup minimum time increment (e.g. 30m)
+    - Setup rate from list of supported rates in invoicing system
+    - Setup reduced rate for first x hours for retainers
+    - Setup monitored keywords, domains, repos
+    - Setup milestones, projects, issues to log time to
+    - Setup target invoice template
+
+## Usage
 
-```sh
-cargo run -- start <client>.json
 ```
+> punchin
 
-Enter the projects as you start working on them. Each time you switch to a new
-project, the current project will be committed and rounded to the next chunk
-(by default, 30 minutes). Once finished, be sure to exit the program using
-ctrl-d or EOL to properly save progress.
+-> Select Client
+--> 1. ACME Co. [Default]
+--> 2. John Doe Intustries
 
-# Generating Reports
+[Enter] for default
+> 1
 
-PunchIn natively supports Markdown and CSV.
+-> Time: 14:34 2024-12-06
+Last Update: Nov 5
+Search time: Nov 3-5
 
-```sh
-cargo run -- report <client>.json --format markdown --timescale hours
-cargo run -- report <client>.json --format csv --timescale hours
+-> Searching Events...
+
+------------------------------------------------------------------
+-> Found meeting:
+- Description: "Meeting: Discussing Priorities"
+- Source: Email Invite
+- Context: [Link] 
+- Timeframe: Nov 4 - Nov 5
+- Words: 345
+- Participants: Joe C, Jim G., Bob H.
+- Time [Estimated]: 2.5h
+--> 1. Bill [Default]
+--> 2. Mark non-billable
+--> 3. Update time
+--> 4. Update description
+> 1
+
+------------------------------------------------------------------
+-> Found conversation
+- Description: "Matrix Chat in 'Team'"
+- Keywords: "ACME"
+- Channel: #acme-team@matrix.org
+- Participants: Joe C, Jim G.
+- Words: 195
+- Context: [Link] 
+- Time [Estimated]: 30m
+--> 1. Bill [Default]
+--> 2. Mark non-billable
+--> 3. Update time
+--> 4. Update description
+> 3
+New Total:
+> 1h
+> 4
+New Description:
+> Architecture Discussion 
+> 1
+--> Invoice Line Submitted
+
+------------------------------------------------------------------
+-> Found commit
+- Description: "Refactor to be more readable"
+- Source: git@codeberg.org/acme/website.git#joe/refactor-stuff
+- Channel: "Team"
+- Ticket: [None]
+- Milestone: [None]
+- Participants: Joe C, Jim G.
+- Lines: 2534
+- Context: [Link] 
+- Time [Estimated]: 5h
+--> 1. Bill [Default]
+--> 2. Mark non-billable
+--> 3. Update time
+--> 4. Update description
+> 1
+
+Error: Client "ACME" requires "Ticket" and "Milestone" to be set
+
+Choose ticket:
+--> 1. Cleanup Refactor
+--> 2. Spellcheck support
+--> N. [New]
+> 1
+
+Choose milestone:
+--> 1. Usability
+--> 2. Doc Improvements
+--> N. [New] 
+> N
+
+New Milestone Name
+> Refactor/Cleanup
+
+-> Updated Hours: "acme/website - Cleanup Refactor"
+-> Updated Invoice: "ACME Consulting - 2025/01/12"
+
+------------------------------------------------------------------
+-> Found review
+- Description: "Review: add spell checking"
+- Source: git@codeberg.org/acme/website.git#jim/spellcheck-support
+- Issue: "#154"
+- Context: [Link] 
+- Participants: Joe C, Jim G.
+- Lines: 2534
+- Time [Estimated]: 1h
+--> 1. Bill [Default]
+--> 2. Mark non-billable
+--> 3. Update time
+--> 4. Update description
+> 1
+
+------------------------------------------------------------------
+-> Log manual hours?
+--> [Y/n]
+> Y
+Start:
+> 2024-12-06 15:41 PT
+End:
+> 2024-12-06 16:00 PT
+Description:
+> Took a walk trying to do debugging
+-> Adjusted time: 30m
+-> Updated Invoice: "ACME Consulting - 2025/01/12"
 ```