swelog-cli 0.7.0 → 0.9.0

package/README.md

@@ -1,4 +1,4 @@
-<!-- markdownlint-disable MD033-->
+<!-- markdownlint-disable MD033 -->
 
 # swelog-cli
 
@@ -9,138 +9,449 @@
     swelog-cli
 </h1>
 
-## Description
-
 `swelog-cli` is a Rust CLI for tracking daily accomplishments in Obsidian.
 
-The tool creates a small set of Markdown files in your Obsidian vault. Collect raw work notes throughout the day, and use LLMs to summarize the notes into a daily work log.
-
-Then, aggregate the daily logs into a weekly log for more long-term tracking.
+Capture raw notes and optional integration activity throughout the day, summarize
+them into daily logs with an LLM, and combine daily logs into a weekly summary.
 
 ## Installation
 
-Install with npm:
+Install the CLI with npm:
 
 ```sh
 npm install -g swelog-cli
 ```
 
-## Usage
-
-### Getting Started
-
-- Run `swelog init` to create a default config file
-
-- Update the config file with your Obsidian vault path and model provider
-
-- Run `swelog setup` to create the default swelog files in your Obsidian vault
-
-- Update the context file with information about your role, team, and current priorities
-
-### Daily Workflow
+Confirm the installation:
 
-- Add notes throughout the day with `swelog log "Meeting with manager"` or manually in Obsidian
-
-- Run `swelog fetch github` to fetch your GitHub PR activity and add it to your work file
-
-- Run `swelog summarize` or `swelog summarize day` to generate a daily log
+```sh
+swelog --help
+```
 
-- Run `swelog summarize week` to generate a weekly log
+## Quick Start
 
-### Other
+### 1. Create the configuration file
 
-- Run `swelog reset` to reset your work file to its default content
+```sh
+swelog init
+```
 
-- Run `swelog config` to display your current configuration and where it is stored
+This creates `swelog/swelog.json` inside your operating system's configuration
+directory. Run `swelog config` at any time to display the exact path.
 
-## Configuration
+### 2. Configure your Obsidian vault
 
-`swelog init` writes a config file to your OS config directory at
-`swelog/swelog.json` (for example `~/.config/swelog/swelog.json` on Linux). The
-default config looks like this:
+Open `swelog.json` and set `obsidianVaultPath` to the absolute path of your
+vault. You can also select a summarization provider and model at this point.
 
 ```json
 {
-  "obsidianVaultPath": "",
+  "obsidianVaultPath": "/absolute/path/to/your/vault",
   "swelogFolderName": "swelog",
   "workFileName": "WORK.md",
   "contextFileName": "CONTEXT.md",
   "dailyLogFolderName": "Daily",
   "weeklyLogFolderName": "Weekly",
   "llm": "ollama",
-  "llmModel": "llama3.2"
+  "llmModel": "llama3.2",
+  "linearUsername": null
 }
 ```
 
-Every field is described below. All of the swelog files and folders live inside
-`<obsidianVaultPath>/<swelogFolderName>`.
+### 3. Create the vault files
+
+```sh
+swelog setup
+```
+
+Swelog creates the work and context files plus the daily and weekly log
+directories under `<obsidianVaultPath>/<swelogFolderName>`.
+
+### 4. Add your context
+
+Open `CONTEXT.md` and describe your role, team, systems, and priorities. Swelog
+includes this context when generating daily and weekly summaries.
+
+### 5. Record and summarize work
+
+```sh
+swelog log "Met with the payments team about retry failures"
+swelog summarize
+```
+
+The first command adds a bullet to the `## Log` section of `WORK.md`. The second
+creates today's daily log and resets `WORK.md` unless `--keep` is provided.
+
+## Daily Workflow
+
+1. Add notes manually in Obsidian or from the terminal:
+
+   ```sh
+   swelog log "Reviewed the checkout migration plan"
+   ```
+
+2. Optionally fetch activity from GitHub or Linear:
+
+   ```sh
+   swelog fetch github
+   swelog fetch linear
+   ```
 
-| Field | Description |
+3. Review and edit `WORK.md`. Integration sections are created only after the
+   corresponding integration is used.
+
+4. Generate the daily log:
+
+   ```sh
+   swelog summarize
+   ```
+
+5. Generate a weekly log when ready:
+
+   ```sh
+   swelog summarize week
+   ```
+
+## Backfilling a Missed Day
+
+Every command that is tied to a day accepts `--date MM-DD-YYYY`, so a day you
+missed can be reconstructed later. `WORK.md` is always the scratch pad the
+summary is built from; the date flags only decide which day is fetched and which
+file the summary is written to.
+
+To backfill Monday, 08-17-2026:
+
+1. Reset the work file so the day starts clean:
+
+   ```sh
+   swelog reset
+   ```
+
+2. Write Monday's notes in `WORK.md`, or add them from the terminal:
+
+   ```sh
+   swelog log "Debugged the retry storm in the payments worker"
+   ```
+
+3. Fetch Monday's integration activity:
+
+   ```sh
+   swelog fetch github --date 08-17-2026
+   swelog fetch linear --date 08-17-2026
+   ```
+
+4. Summarize into Monday's daily log:
+
+   ```sh
+   swelog summarize day --date 08-17-2026
+   ```
+
+   This writes `Daily/08-17-2026.md` and resets `WORK.md`, so the next missed day
+   can be backfilled straight away. Add `--force` to replace a daily log that
+   already exists, or `--keep` to leave `WORK.md` alone.
+
+5. Once the week's daily logs exist, summarize the week:
+
+   ```sh
+   swelog summarize week --week-of 08-17-2026
+   ```
+
+| Command | Backfill flag |
 | --- | --- |
-| `obsidianVaultPath` | Absolute path to your Obsidian vault. Empty by default; you must set this before running other commands, otherwise swelog errors out. |
-| `swelogFolderName` | Name of the folder created inside your vault that holds all swelog files. |
-| `workFileName` | Name of the file where you collect raw daily work notes. |
-| `contextFileName` | Name of the file holding context about your role, team, and priorities, which is fed to the LLM during summarization. |
-| `dailyLogFolderName` | Name of the folder (inside the swelog folder) where generated daily logs are stored. |
-| `weeklyLogFolderName` | Name of the folder (inside the swelog folder) where generated weekly logs are stored. |
-| `llm` | LLM provider used for summarization. One of `ollama`, `openAi`, or `openRouter`. |
-| `llmModel` | Model used for summarization, interpreted by whichever provider `llm` names. Examples: `llama3.2` for `ollama`, `gpt-5.4-mini` for `openAi`, `openai/gpt-5.4-mini` for `openRouter`. |
+| `swelog fetch github` | `--date MM-DD-YYYY` |
+| `swelog fetch linear` | `--date MM-DD-YYYY` |
+| `swelog summarize day` | `--date MM-DD-YYYY` |
+| `swelog summarize week` | `--week-of MM-DD-YYYY` |
 
-### AI Summarization
+`swelog log` and `swelog reset` need no date; they act on `WORK.md`, which holds
+whichever day you are currently assembling.
 
-Configure your desired LLM provider and model in your config file.
+Linear backfill is best-effort. See [Linear](#linear) for what it can and cannot
+recover.
 
-#### Ollama
+## Configuration
 
-To use Ollama, ensure it is up and running at `localhost:11434` before running `swelog summarize`.
+All generated files and directories live inside
+`<obsidianVaultPath>/<swelogFolderName>`.
 
-#### OpenAI
+| Field | Required | Description |
+| --- | --- | --- |
+| `obsidianVaultPath` | Yes | Absolute path to the Obsidian vault. Commands fail until this is configured. |
+| `swelogFolderName` | Yes | Folder created inside the vault for Swelog files. |
+| `workFileName` | Yes | Markdown file used to collect the current day's raw notes. |
+| `contextFileName` | Yes | Markdown file containing role, team, systems, and priority context. |
+| `dailyLogFolderName` | Yes | Directory containing generated daily logs. |
+| `weeklyLogFolderName` | Yes | Directory containing generated weekly logs. |
+| `llm` | Yes | Summarization provider: `ollama`, `openAi`, or `openRouter`. |
+| `llmModel` | Yes | Model identifier interpreted by the configured provider. |
+| `linearUsername` | No | Exact Linear assignee name used by `swelog fetch linear`. Leave as `null` when Linear is not used. |
 
-To use OpenAI, provide your OpenAI API key through the environment before running
-`swelog summarize`:
+Display the current configuration and its location:
 
 ```sh
-export OPENAI_API_KEY="your_api_key_here"
+swelog config
+```
+
+## Summarization
+
+Swelog uses the same configured model for daily and weekly summaries.
+
+### Commands
+
+| Command | Behavior |
+| --- | --- |
+| `swelog summarize` | Generate today's daily log. Alias for `swelog summarize day`. |
+| `swelog summarize day` | Generate today's daily log and reset `WORK.md`. |
+| `swelog summarize day --keep` | Generate the daily log without resetting `WORK.md`. |
+| `swelog summarize day --force` | Replace an existing daily log for today. |
+| `swelog summarize day --date MM-DD-YYYY` | Write the daily log for the supplied date instead of today. |
+| `swelog summarize week` | Summarize available Monday-Friday daily logs for the default week. |
+| `swelog summarize week --week-of MM-DD-YYYY` | Summarize the week beginning on the supplied Monday. |
+| `swelog summarize week --force` | Replace an existing weekly log. |
+
+Without `--week-of`, weekly summarization uses the current week's Monday. When
+run on a Monday, it uses the previous Monday. The command skips missing weekday
+logs but fails when no daily logs exist for the selected week.
+
+Weekly summarization requires `WORK.md` to be empty/default so unfinished daily
+notes are not accidentally excluded from a daily log.
+
+Daily summarization always reads the current `WORK.md`. `--date` only chooses the
+file the summary is written to, so it is what you use to backfill a missed day.
+See [Backfilling a Missed Day](#backfilling-a-missed-day).
+
+### Providers and Models
+
+| Provider | `llm` | Example `llmModel` | Setup | Authentication | Notes |
+| --- | --- | --- | --- | --- | --- |
+| Ollama | `ollama` | `llama3.2` | Install Ollama, pull the model, and run the local service. | None | Swelog connects to Ollama at `localhost:11434`. |
+| OpenAI | `openAi` | `gpt-5.4-mini` | Select an OpenAI model supported by the Responses API. | API key, prompted on first use | The model value is sent directly to OpenAI. |
+| OpenRouter | `openRouter` | `openai/gpt-5.4-mini` | Select an OpenAI Responses-compatible model through OpenRouter. | API key, prompted on first use | The current implementation expects OpenAI Responses API output. |
+
+Model names are examples, not a fixed allowlist. Set `llmModel` to a model that
+is installed locally or available from the selected provider.
+
+### Ollama Setup
+
+1. Install and start Ollama.
+2. Pull the configured model:
+
+   ```sh
+   ollama pull llama3.2
+   ```
+
+3. Configure Swelog:
+
+   ```json
+   {
+     "llm": "ollama",
+     "llmModel": "llama3.2"
+   }
+   ```
+
+4. Run `swelog summarize`. Ensure Ollama remains available at
+   `localhost:11434` while the command runs.
+
+### OpenAI Setup
+
+1. Configure the provider and model:
+
+   ```json
+   {
+     "llm": "openAi",
+     "llmModel": "gpt-5.4-mini"
+   }
+   ```
+
+2. Run `swelog summarize`. The first run asks for your
+   [OpenAI API key](https://platform.openai.com/api-keys) and stores it in your
+   operating system keyring.
+
+### OpenRouter Setup
+
+1. Configure the provider and an OpenAI Responses-compatible model:
+
+   ```json
+   {
+     "llm": "openRouter",
+     "llmModel": "openai/gpt-5.4-mini"
+   }
+   ```
+
+2. Run `swelog summarize`. The first run asks for your
+   [OpenRouter API key](https://openrouter.ai/keys) and stores it in your
+   operating system keyring.
+
+Never store API keys in `swelog.json`. See [Authentication](#authentication) for
+how Swelog stores and clears them.
+
+## Integrations
+
+Integrations are optional. The default work file contains only `## Focus` and
+`## Log`; integration sections are created lazily when activity is fetched.
+
+| Integration | Command | Configuration | Authentication | Work-file output |
+| --- | --- | --- | --- | --- |
+| GitHub | `swelog fetch github` | None | Personal access token, prompted on first use | Pull requests opened or merged on the selected date. |
+| Linear | `swelog fetch linear` | `linearUsername` | Browser OAuth on first use | Assigned issues grouped by their current status. |
+
+Swelog surrounds generated sections with invisible HTML markers. Treat the
+content inside these managed blocks as generated data because future fetches
+replace it.
+
+### GitHub
+
+GitHub fetching records pull requests you opened or merged.
+
+1. Fetch today's activity:
+
+   ```sh
+   swelog fetch github
+   ```
+
+   The first run asks for a
+   [GitHub personal access token](https://github.com/settings/tokens) with the
+   `repo` scope and stores it in your operating system keyring.
+
+2. To fetch a previous date, provide `MM-DD-YYYY`:
+
+   ```sh
+   swelog fetch github --date 08-17-2026
+   ```
+
+The command creates or updates a managed `## GitHub` section before `## Log`.
+Never store the GitHub token in `swelog.json`.
+
+### Linear
+
+Linear fetching records issues assigned to a configured workspace user.
+Without `--date` it records your currently active issues and omits completed and
+canceled ones.
+
+1. Set the exact Linear assignee name in `swelog.json`:
+
+   ```json
+   {
+     "linearUsername": "Rudra Patel"
+   }
+   ```
+
+2. Run the fetch command:
+
+   ```sh
+   swelog fetch linear
+   ```
+
+3. On first use, Swelog prints a Linear authorization URL and attempts to open
+   it in your browser. If the browser does not open, use the printed URL.
+
+4. Complete authorization. Swelog stores the resulting OAuth credentials in
+   your operating system keyring and reuses or refreshes them on later runs.
+
+5. To backfill a previous date, provide `MM-DD-YYYY`:
+
+   ```sh
+   swelog fetch linear --date 08-17-2026
+   ```
+
+   This records the issues Linear shows activity on for that date, including the
+   ones you completed or canceled, because finishing an issue is exactly what a
+   past day's log should capture.
+
+The generated section groups issues by status:
+
+```markdown
+## Linear
+### In Progress
+- [ENG-123](https://linear.app/...) Implement OAuth callback handling
+
+### Todo
+- [ENG-456](https://linear.app/...) Document the Linear integration
 ```
 
-Do not store your OpenAI API key in the swelog config file.
+When no issues match, Swelog removes its managed Linear section.
+
+#### What `--date` can and cannot recover
 
-#### OpenRouter
+The Linear MCP server does not expose issue history, so Swelog can only match on
+the timestamps Linear stores on the issue itself: `updatedAt`, `completedAt`,
+`canceledAt`, `startedAt`, and `createdAt`. An issue is recorded for a date when
+any of those lands on it, read in your local time zone.
 
-To use OpenRouter, provide your OpenRouter API key through the environment before running
-`swelog summarize`:
+`completedAt`, `canceledAt`, `startedAt`, and `createdAt` never move, so issues
+you started, finished, canceled, or filed on a date are recovered no matter how
+much later you backfill. `updatedAt` only holds the most recent change, so an
+issue you touched on Monday and touched again on Tuesday is attributed to
+Tuesday alone. Backfill soon after the fact for the most complete result, and
+treat `--date` output as a prompt for your own notes rather than a full record.
+
+To switch Linear accounts or organizations, update `linearUsername` when needed,
+clear the stored authorization, and fetch again:
 
 ```sh
-export OPENROUTER_API_KEY="your_api_key_here"
+swelog auth clear linear
+swelog fetch linear
 ```
 
-Do not store your OpenRouter API key in the swelog config file.
+The next fetch starts a new browser authorization flow.
+
+## Authentication
 
-`llmModel` must be an OpenAI model slug prefixed with `openai/` (for example
-`openai/gpt-5.4-mini`), since swelog talks to OpenRouter using OpenAI's Responses API
-format. Non-OpenAI models will not work.
+Swelog stores every credential in your operating system's credential store —
+Keychain on macOS, Credential Manager on Windows, and the Secret Service on
+Linux. Nothing is written to `swelog.json` or any other file in your vault.
 
-### GitHub Integration
+| Credential | Used by | How it is obtained |
+| --- | --- | --- |
+| GitHub token | `swelog fetch github` | Prompted on first use |
+| OpenAI API key | `swelog summarize` with `"llm": "openAi"` | Prompted on first use |
+| OpenRouter API key | `swelog summarize` with `"llm": "openRouter"` | Prompted on first use |
+| Linear authorization | `swelog fetch linear` | Browser OAuth on first use |
 
-To fetch your GitHub PR activity and add it to your work file, you need to provide your GitHub token.
+Review what is stored — values are never printed:
 
 ```sh
-export GITHUB_TOKEN="your_github_token_here"
+swelog auth status
 ```
 
-Do not store your GitHub token in the swelog config file.
+If a credential is revoked or rejected, clear it and run the command again to
+enter a new one. Every authorization error names this command:
+
+```sh
+swelog auth clear github
+swelog auth clear --all
+```
+
+### Environment variable overrides
+
+`GITHUB_TOKEN`, `OPENAI_API_KEY`, and `OPENROUTER_API_KEY` take precedence over
+the keyring when set, so CI and scripted runs work without a credential store.
+When one of these is set, `swelog auth status` reports it instead of the stored
+value.
+
+In a non-interactive session — a pipe, a cron job, a CI job — Swelog never
+prompts. It fails immediately with the name of the environment variable to set.
+
+## Other Commands
+
+| Command | Behavior |
+| --- | --- |
+| `swelog log "message"` | Append a bullet to the `## Log` section. |
+| `swelog reset` | Reset `WORK.md` to its default Focus-and-Log template. |
+| `swelog setup --force` | Recreate and overwrite configured Swelog files. |
+| `swelog config` | Display the current configuration and config-file path. |
+| `swelog auth status` | Show which credentials are stored, without printing them. |
+| `swelog auth clear <credential>` | Remove a stored credential so the next command asks for it again. |
 
 ## Contributing
 
 ### Prerequisites
 
-Please have the following installed on your machine:
-
 - Rust
 - Just
-- Ollama, when using the default Ollama provider
-- An OpenAI / OpenRouter API key, when using the OpenAI / OpenRouter provider
 - Obsidian
+- Ollama when testing the default summarization provider
+- Provider credentials when testing hosted models or integrations
 
 ### Development
 
@@ -188,23 +499,11 @@ just update-release-version <release-tag>
 
 ### Pull Request Process
 
-Branch protections are enabled on this repository.
-
-To contribute, please create a new branch and make a pull request.
-
-The rules for branch names are lax, just be sure to include your name.
-
-An example branch name for a change that adds weekly log generation would be:
-
-```text
-rudra-weekly-log-generation
-```
-
-Your pull request title must follow the conventional commits specification. An
-example of a valid pull request title is:
+Create a branch and open a pull request. Branch naming is flexible, but pull
+request titles must use Conventional Commit style, for example:
 
 ```text
-feat: Add weekly log generation
+feat: add weekly log generation
 ```
 
-All PRs must pass `just pr`, which checks formatting, linting, and tests.
+All pull requests must pass `just pr`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swelog-cli",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "A Rust CLI to track your daily accomplishments in Obsidian",
   "license": "MIT",
   "homepage": "https://github.com/RudraPatel2003/swelog-cli",