Merge pull request #286 from shelltime/docs/polish-wording

docs: polish CLI documentation wording and fix stale references

Author: AnnatarHe

.goreleaser.yaml

@@ -105,15 +105,14 @@ release:
   mode: replace
   header: |
     ## shelltime.xyz CLI ({{ .Date }})
-    Welcome to this new release!
-    please install the latest cli by run command
+    Welcome to the latest release! Install or upgrade the CLI by running:
     ```bash
-    curl -sSL https://raw.githubusercontent.com/shelltime/installation/master/install.bash | bash
+    curl -sSL https://shelltime.xyz/i | bash
     ```
   footer: |
     ## Thanks!
 
-    Those were the changes on {{ .Tag }}!
+    That's everything in {{ .Tag }} — thanks for using ShellTime!
   name_template: "v{{.Version}}"
   disable: false
   skip_upload: false
@@ -158,12 +157,12 @@ brews:
     test: |
       system "#{bin}/shelltime", "--version"
     caveats: |
-      To get started with ShellTime, run:
+      Get started with a single command:
         shelltime init
 
-      Or set up manually:
+      Or set things up manually:
         shelltime auth
         shelltime hooks install
         shelltime daemon install
 
-      For more info, visit https://shelltime.xyz
+      Learn more at https://shelltime.xyz

AGENTS.md

@@ -1,9 +1,9 @@
 # Repository Guidelines
 
 ## Project Identity
-This repo is the ShellTime CLI and daemon. Public-facing docs, command examples, and product references should use `ShellTime` and `shelltime.xyz`.
+This repo is the ShellTime CLI and daemon. Use `ShellTime` and `shelltime.xyz` in public-facing docs, command examples, and product references.
 
-Code and imports currently use the module path `github.com/malamtime/cli`. Do not "fix" ShellTime branding in docs just because the module path says `malamtime`; the mismatch is intentional in the current repo state.
+Code and imports use the module path `github.com/malamtime/cli`. This mismatch is intentional — don't "fix" the ShellTime branding in docs just because the module path says `malamtime`.
 
 ## Project Structure & Package Boundaries
 This is a Go monorepo for the ShellTime CLI and daemon.
@@ -50,7 +50,7 @@ Use standard Go conventions and keep code `gofmt`-clean.
 - Ensure `go test -timeout 3m -coverprofile=coverage.txt -covermode=atomic ./...` passes before opening a PR or cutting a release
 
 ## Documentation Maintenance
-When command behavior, setup flow, config formats, or integrations change, update the docs in the same change.
+When command behavior, the setup flow, config formats, or integrations change, update the docs in the same commit.
 
 - `README.md`: concise user-facing overview, install/setup flow, current command surface, and links
 - `docs/CONFIG.md`: detailed config semantics, file locations, defaults, and OTEL settings

CLAUDE.md

@@ -68,7 +68,7 @@ go fmt ./...
 
 ### Service Interfaces (model package)
 Three key interfaces with dependency injection:
-- `ConfigService`: Reads and merges config from `config.toml` and `config.local.toml`
+- `ConfigService`: Reads and merges config from `config.yaml`/`config.toml` (YAML preferred) plus the matching `config.local.*` overrides
 - `AIService`: PromptPal integration for AI-powered command suggestions (`shelltime q`)
 - `CommandService`: Executable lookup with fallback paths (handles daemon's limited PATH)
 
@@ -96,8 +96,8 @@ Services initialize in `cmd/daemon/main.go`: check enabled flag → create → s
 4. Batch sync to shelltime.xyz API with optional encryption
 
 ### Configuration
-- Main config: `$HOME/.shelltime/config.toml`
-- Local overrides: `$HOME/.shelltime/config.local.toml` (merged, gitignored)
+- Main config: `$HOME/.shelltime/config.yaml` (YAML preferred; `config.yml` and `config.toml` are also accepted)
+- Local overrides: `$HOME/.shelltime/config.local.yaml` (merged over the base, gitignored)
 - Daemon socket: `/tmp/shelltime.sock` (configurable via `socketPath`)
 - AICodeOtel gRPC port: configurable via `aiCodeOtel.grpcPort` (default: 54027)
 

README.md

@@ -3,9 +3,7 @@
 [![codecov](https://codecov.io/gh/shelltime/cli/graph/badge.svg?token=N09WIJHNI2)](https://codecov.io/gh/shelltime/cli)
 [![shelltime](https://api.shelltime.xyz/badge/AnnatarHe/count)](https://shelltime.xyz/users/AnnatarHe)
 
-ShellTime is a CLI and background daemon for tracking shell activity, syncing command history, and wiring AI coding tools into a shared telemetry stream. The public product and hosted service are ShellTime at [shelltime.xyz](https://shelltime.xyz).
-
-The Go module path is `github.com/malamtime/cli`. That naming mismatch is intentional in this repo today; use `ShellTime` for product-facing docs and `github.com/malamtime/cli` for imports and module references.
+ShellTime is a CLI and background daemon that tracks your shell activity, syncs your command history, and pipes your AI coding tools into one shared telemetry stream. The hosted service lives at [shelltime.xyz](https://shelltime.xyz).
 
 ## Install
 
@@ -23,29 +21,29 @@ curl -sSL https://shelltime.xyz/i | bash
 
 ### Upgrading
 
-For curl-installed users, upgrade in place:
+If you installed with the curl script, upgrade in place:
 
 ```bash
 shelltime update
 ```
 
-Homebrew users should upgrade via brew:
+If you installed with Homebrew, upgrade through brew instead:
 
 ```bash
 brew upgrade shelltime/tap/shelltime
 ```
 
 ## Quick Start
 
-The fastest setup path is:
+The fastest way to get set up is a single command:
 
 ```bash
 shelltime init
 ```
 
-`shelltime init` authenticates the CLI, installs shell hooks, installs the daemon, and attempts to configure Claude Code and Codex OTEL integration.
+`shelltime init` authenticates the CLI, installs the shell hooks and daemon, and tries to wire up Claude Code and Codex OTEL integration for you.
 
-If you prefer the manual flow:
+Prefer to do it step by step?
 
 ```bash
 shelltime auth
@@ -57,11 +55,11 @@ shelltime codex install
 
 ## What ShellTime Does
 
-- Tracks shell commands locally with masking and exclusion support.
-- Syncs command history to ShellTime for search and analysis.
+- Tracks shell commands locally, with masking and exclusion rules to keep secrets out.
+- Syncs your command history to ShellTime so you can search and analyze it.
 - Runs a background daemon for low-latency, non-blocking sync.
-- Integrates with Claude Code and OpenAI Codex through OTEL forwarding.
-- Shows live Claude Code statusline data for cost, quota, time, and context.
+- Forwards Claude Code and OpenAI Codex telemetry through OTEL.
+- Shows a live Claude Code statusline with cost, quota, time, and context usage.
 - Syncs supported dotfiles to and from the ShellTime service.
 
 ## Command Overview
@@ -142,18 +140,18 @@ exclude:
   - "^export .*"
 ```
 
-For the full configuration surface, defaults, OTEL settings, and AI options, see [docs/CONFIG.md](docs/CONFIG.md).
+For every option, its default, and the OTEL and AI settings, see [docs/CONFIG.md](docs/CONFIG.md).
 
 ## Daemon Mode
 
-The daemon keeps tracking fast by buffering and syncing in the background.
+The daemon keeps your shell fast by buffering commands and syncing them in the background, so a slow network never blocks your prompt.
 
-| Mode | Latency | Network Blocking |
-|------|---------|------------------|
+| Mode | Latency | Blocks your shell? |
+|------|---------|--------------------|
 | Direct | ~100ms+ | Yes |
 | Daemon | <8ms | No |
 
-Use daemon mode if you want lower shell latency, retry handling, and background processing for sync and OTEL events.
+Run in daemon mode for lower shell latency, automatic sync retries, and background processing of sync and OTEL events. It is optional but recommended.
 
 ## Claude Code Statusline
 
@@ -180,10 +178,10 @@ For formatting details and platform notes, see [docs/CC_STATUSLINE.md](docs/CC_S
 
 ## Security and Privacy
 
-- Data masking can redact sensitive command content before upload.
-- Exclusion patterns let you skip matching commands entirely.
-- Optional end-to-end encryption is available for supported flows.
-- Local config overrides can keep sensitive values out of the primary config file.
+- **Data masking** redacts sensitive command content before it leaves your machine.
+- **Exclusion patterns** skip matching commands entirely, so they are never recorded.
+- **End-to-end encryption** is available for supported flows (opt-in).
+- **Local config overrides** keep secrets like tokens out of your main config file.
 
 ## Development
 
@@ -197,6 +195,8 @@ go fmt ./...
 go vet ./...
 ```
 
+> **Note on naming:** the product is **ShellTime** (`shelltime.xyz`), but the Go module path is `github.com/malamtime/cli`. This mismatch is intentional — use `ShellTime` in product-facing docs and `github.com/malamtime/cli` for imports.
+
 ## Links
 
 - [Configuration Guide](docs/CONFIG.md)

docs/CC_STATUSLINE.md

@@ -1,10 +1,10 @@
 # Claude Code Statusline Integration
 
-Display real-time cost and context usage in Claude Code's status bar using ShellTime.
+Show real-time cost and context usage right in Claude Code's status bar, powered by ShellTime.
 
 ## Overview
 
-The `shelltime cc statusline` command provides a custom status line for Claude Code that shows:
+The `shelltime cc statusline` command renders a custom status line for Claude Code that shows:
 
 - Git branch name and dirty status
 - Current model name
@@ -163,21 +163,21 @@ Color is based on the **maximum** utilization across both windows:
 
 ### For Session Cost & Context
 
-No additional setup required - data comes directly from Claude Code.
+No setup needed — this data comes straight from Claude Code.
 
 ### For Git Branch Info
 
 Requires the ShellTime daemon to be running:
 
 ```bash
-# Start the daemon
-shelltime daemon start
+# Install and start the daemon as a background service
+shelltime daemon install
 
 # Verify it's running
 shelltime daemon status
 ```
 
-The daemon caches git info and refreshes it periodically for optimal performance.
+The daemon caches git info and refreshes it in the background, so the statusline stays fast.
 
 ### For Today's Cost
 
@@ -209,7 +209,7 @@ If quota data is unavailable, the section will show as `🚦 -`.
 
 ## Performance
 
-- **Hard timeout:** 100ms for entire operation
+- **Hard timeout:** 100ms for the entire operation
 - **Daemon request timeout:** 50ms for the daemon socket request (fast path)
 - **Session mapping:** ~1ms fire-and-forget to daemon
 - **API caching:** 5-minute TTL for daily cost, 10-minute TTL for quota utilization
@@ -245,7 +245,7 @@ If quota data is unavailable, the section will show as `🚦 -`.
 1. Ensure you're on **macOS** - quota display is only available on macOS (omitted entirely on Linux)
 2. Verify you're logged into Claude Code (the OAuth token is stored in macOS Keychain)
 3. Ensure the daemon is running: `shelltime daemon status`
-4. Quota data is cached for 10 minutes - it may take a moment after daemon start
+4. Quota data is cached for 10 minutes — it may take a moment to appear after the daemon starts
 
 ### Colors not displaying
 

docs/CONFIG.md

@@ -1,6 +1,6 @@
 # ShellTime CLI Configuration Guide
 
-This guide explains all configuration options available in ShellTime CLI. Configuration is straightforward yet powerful, allowing you to customize everything from data syncing to AI features.
+This guide covers every configuration option in ShellTime CLI. ShellTime runs fine on its defaults, so you only need to set what you want to change — from sync behavior to AI features.
 
 ## Table of Contents
 
@@ -26,7 +26,7 @@ Create a configuration file at `~/.shelltime/config.yaml`:
 token: "your-api-token-from-shelltime.xyz"
 ```
 
-That's it! ShellTime works with sensible defaults. Read on to customize your experience.
+That's it — every other setting has a sensible default. Read on to fine-tune things.
 
 ---
 
@@ -298,7 +298,7 @@ codeTracking:
   token: "custom-heartbeat-token"
 ```
 
-When `apiEndpoint` or `token` is set under `codeTracking`, heartbeat data will use these values instead of the global configuration. This allows you to send coding activity to a different server or authenticate with a separate token.
+When `apiEndpoint` or `token` is set under `codeTracking`, heartbeats use those values instead of the global ones — handy for sending coding activity to a different server or authenticating with a separate token.
 
 ---
 
@@ -497,9 +497,9 @@ No, but it's recommended:
 - **With daemon:** <8ms latency, encryption support
 - **Without daemon:** ~100ms+ latency, no encryption
 
-Start the daemon:
+Install and start the daemon as a background service:
 ```bash
-shelltime-daemon
+shelltime daemon install
 ```
 
 ---