agentel 0.2.0 → 0.2.2

package/docs/history-source-handling.md

@@ -27,18 +27,22 @@ All supported sources are normalized into the same archive shape before write:
 - `events`: provider-independent canonical events generated from transcript
   messages and structured tool metadata.
 - stats metadata: `messageCount`, `userMessageCount`, aggregate `usage`, and
-  `models` are computed while writing the archive.
-
-Before writing, message content is redacted by `src/redaction.js`. The redacted
-transcript is written to `conversation.md`, `transcript.jsonl`, and
-`events.jsonl`. Unredacted original source files are copied or referenced from
-`session=<id>.raw/` with a manifest. Large multi-session stores such as Cursor
-SQLite use a shared raw-source copy under `raw-sources/`, with each session raw
-manifest pointing at that shared file instead of duplicating the same database
-hundreds of times. The optional reveal cache stores the unredacted normalized
-JSONL when enabled and when the session is repo-scoped. Reimports are skipped by
-fingerprint unless the source file changes or the importer fingerprint version
-changes.
+  `models` are computed while writing the archive. Each transcript message also
+  gets `metadata.tokenEstimate` when visible text or tool-call text can be
+  counted.
+
+Redaction is opt-in. When `~/.agentlog/redaction.yaml` has `enabled: true`,
+message content and structured metadata strings are redacted by
+`src/redaction.js` before writing `conversation.md`, `transcript.jsonl`, and
+`events.jsonl`. Use `agentlog redact init` to create the config, then toggle
+built-in detectors under `built_ins`. Original source files are copied or
+referenced from `session=<id>.raw/` with a manifest. Large multi-session stores
+such as Cursor SQLite use a shared raw-source copy under `raw-sources/`, with
+each session raw manifest pointing at that shared file instead of duplicating
+the same database hundreds of times. The optional reveal cache stores the
+unredacted normalized JSONL when enabled and when the session is repo-scoped.
+Reimports are skipped by fingerprint unless the source file changes or the
+importer fingerprint version changes.
 Use `agentlog import --source cursor --since all --explain-skips` to print
 Cursor skip reasons for one run. Add `--json` to inspect `skipReasons` counts
 and `skippedItems[]` with session ids, source types, paths, and titles.
@@ -55,15 +59,46 @@ usage is preserved separately and repeated provider request ids are counted once
 which avoids inflating Claude Code/Desktop sessions that repeat the same request
 usage across assistant text and tool-call rows.
 
+When provider token usage is missing, message-level estimates use visible text
+length plus visible tool-call summaries at roughly four characters per token.
+The generic archive estimate is stored as `metadata.tokenEstimate` on each
+message and is not treated as provider-reported `metadata.usage`. ChatGPT and
+Claude.ai export importers additionally populate estimated `metadata.usage` from
+their native message parts so stats can count chat input/output at import time.
+
+Provider, model-company, and model breakdowns are emitted directly in the stats
+payload. Daily and folder buckets retain provider splits, inferred model-company
+splits, and primary-model splits so the web viewer can switch between provider,
+company, and model charts without reparsing transcripts. The company dimension
+means the model maker, such as OpenAI, Anthropic, Google, Cognition, or
+Windsurf. Model-routing clients such as Cursor group under unknown when their
+archived metadata does not identify the actual model. Claude.ai export sessions
+without a specific archived model group as `claude-unknown`, because the model
+family is still known. Favorite-model stats still use known archived model
+metadata.
+
+Cursor sessions that still lack provider-reported usage get a separate
+`estimatedUsage` metadata field instead of synthetic `usage`. The estimate uses
+empirical per-assistant-turn Cursor rates by model family, with visible
+transcript context as a lower bound, and the stats payload reports how much of
+the token total is estimated via `total_estimated_tokens` / `tokens_estimated`.
+ChatGPT and Claude.ai web exports get estimated per-message `metadata.usage`
+when provider usage is absent; those estimates are native message-part totals
+split as non-assistant input, assistant output, and Claude thinking output, not
+reconstructed billing context windows.
+
 ```sh
-agentlog reset --yes
-agentlog init
-agentlog import --source all --since all
+agentlog update --yes --since all
 ```
 
-`agentlog reset` removes agentlog state and archive objects only; it does not
-delete source application histories such as Cursor, Codex, Claude, Gemini, or
-Devin logs.
+`agentlog update` preserves config preferences, redaction settings, web account
+labels, source histories, and recall integrations. It removes derived local
+archive/import/index state and reimports configured local sources. Manual web
+exports still need to be imported again from the original export file when those
+archives need to be rebuilt. `agentlog reset` is the heavier path: it removes
+agentlog state and archive objects, including config, while still leaving source
+application histories such as Cursor, Codex, Claude, Gemini, or Devin logs
+untouched.
 
 Archive paths are grouped by repo or scope:
 
@@ -136,40 +171,42 @@ context headers, and interruption markers.
 
 ## Parser Versions
 
-Parser versions live in `src/parser-versions.js`. They are semantic-version
-strings. The first npm release uses `1.0.0` as the parser baseline for every
-source type.
-
-After release, bump the affected source type in the same change whenever parser
-output changes for the same raw input: message roles, timestamps, tool-call
-metadata, tool-result metadata, source classification, fingerprints, or
-canonical event text. Use patch bumps for narrow correctness fixes, minor bumps
-for additive parser enrichment, and major bumps for source identity,
-fingerprint, archive-contract, or meaningfully incompatible output changes.
+Parser versions live in `src/parser-versions.js`. They are package-prefixed
+four-part strings: `<package-version>.<source-suffix>`. During development,
+bump the affected source suffix whenever parser output changes for the same raw
+input: message roles, timestamps, tool-call metadata, tool-result metadata,
+source classification, fingerprints, or canonical event text. When cutting a
+new package release, the package version supplies the new baseline, so suffixes
+can reset to `0` unless parser output changes again during that package cycle.
+Legacy three-part parser versions are treated as older than the current
+package-prefixed scheme.
 
 | Source type | Version |
 | --- | --- |
-| `codex-cli-history` | `1.0.0` |
-| `codex-desktop-history` | `1.0.0` |
-| `cli-history` | `1.0.0` |
-| `claude-sdk-history` | `1.0.0` |
-| `claude-code-desktop-metadata` | `1.0.0` |
-| `claude-workspace-desktop` | `1.0.0` |
-| `cursor-workspace-sqlite` | `1.0.0` |
-| `cursor-global-sqlite` | `1.0.0` |
-| `cursor-raw-sqlite-salvage` | `1.0.0` |
-| `cursor-agent-transcripts` | `1.0.0` |
-| `devin-cli-history` | `1.0.0` |
-| `gemini-cli-history` | `1.0.0` |
-| `cline-task-history` | `1.0.0` |
-| `opencode-history` | `1.0.0` |
-| `aider-chat-history` | `1.0.0` |
-| `antigravity-history` | `1.0.0` |
-| `web-chat-export` | `1.0.0` |
-| `chatgpt-export` | `1.0.0` |
-| `claude-web-export` | `1.0.0` |
-| `claude-web-memory` | `1.0.0` |
-| `import` | `1.0.0` |
+| `codex-cli-history` | `0.2.2.0` |
+| `codex-desktop-history` | `0.2.2.0` |
+| `cli-history` | `0.2.2.0` |
+| `claude-sdk-history` | `0.2.2.0` |
+| `claude-code-desktop-metadata` | `0.2.2.0` |
+| `claude-workspace-desktop` | `0.2.2.0` |
+| `cursor-workspace-sqlite` | `0.2.2.0` |
+| `cursor-global-sqlite` | `0.2.2.0` |
+| `cursor-raw-sqlite-salvage` | `0.2.2.0` |
+| `cursor-agent-transcripts` | `0.2.2.0` |
+| `devin-cli-history` | `0.2.2.0` |
+| `gemini-cli-history` | `0.2.2.0` |
+| `cline-task-history` | `0.2.2.0` |
+| `opencode-history` | `0.2.2.0` |
+| `opencode-sqlite-history` | `0.2.2.0` |
+| `aider-chat-history` | `0.2.2.0` |
+| `antigravity-history` | `0.2.2.0` |
+| `antigravity-trajectory-summary` | `0.2.2.0` |
+| `windsurf-trajectory-export` | `0.2.2.0` |
+| `web-chat-export` | `0.2.2.0` |
+| `chatgpt-export` | `0.2.2.0` |
+| `claude-web-export` | `0.2.2.0` |
+| `claude-web-memory` | `0.2.2.0` |
+| `import` | `0.2.2.0` |
 
 `cursor-sqlite-history` and `antigravity-brain` are compatibility aliases for
 older labels. Fingerprints include the parser version prefix, so changing the
@@ -182,6 +219,22 @@ version makes reimport replace stale archive copies.
 back to sessions for CLI/skill compatibility. Archives without `events.jsonl`
 remain searchable through transcript/markdown fallback, and missing
 `conversation.md` files are materialized from transcripts when needed.
+The web session API reads pre-baked `view.json` for the default readable pane.
+When the raw Markdown source view is requested, the browser asks for a
+Markdown-only payload instead of downloading the full transcript again. Browser
+session payloads compact duplicated tool output and use ETag revalidation so
+revisits and live refresh checks can avoid reparsing unchanged transcripts.
+The local BM25 JSON index stores term postings plus document metadata for
+compatibility. A SQLite FTS5 sidecar stores the same chunks for interactive
+search so browser, terminal, and MCP recall queries do not parse a large JSON
+index in short-lived search processes. Index format bumps trigger a rebuild from
+existing `transcript.jsonl` and `events.jsonl`; they do not require reparsing
+provider source files. The web search endpoint is optimized for typing: it uses
+the compatible warm FTS/index when present, skips obsolete or stale indexes
+rather than parsing/rebuilding inline, and does not scan every rendered Markdown
+archive as a fallback. Terminal and MCP recall search also avoid synchronous
+rebuilds and BM25 JSON parses, then fall back to the bounded Markdown search for
+legacy archives or misses.
 
 Recall quality has deterministic tests in `test/recall-eval.test.js` with
 fixtures under `test/fixtures/recall-evals.json`. Add a fixture when a vague
@@ -202,10 +255,11 @@ The setup UI, import defaults, and history source filters use this grouped order
 `src/sources.js`: `codex-cli`, `codex-desktop`, `claude`,
 `claude-code-desktop`, `claude-workspace`, `gemini-cli`, `antigravity`,
 `devin-cli`, `cursor`, `cline`, `opencode`, `aider`. Claude SDK jobs are
-intentionally opt-in. Windsurf is disabled for now because current Cascade
-transcripts are encrypted binary stores.
+intentionally opt-in. Windsurf local cache scanning is disabled for now because
+current Cascade transcripts are encrypted binary stores, but downloaded
+trajectory Markdown exports are importable with an explicit path.
 
-The background supervisor polls the watcher source list selected near the end of
+The background watcher polls the watcher source list selected near the end of
 `agentlog init`. New configs still support `imports.autoDiscoverSources=true`,
 but init now records the chosen watcher list exactly by setting
 `imports.autoDiscoverSources=false`.
@@ -333,7 +387,7 @@ though both archive under the same `codex` provider.
 
 - Import command: `agentlog import chatgpt --file <path> [--scope local|team]`
 - Provider: `chatgpt`
-- Source type: `web-chat-export`
+- Source type: `chatgpt-export`
 - Source file: ChatGPT JSON export or ZIP containing a JSON export
 - Default archive scope: `chatgpt`
 
@@ -344,7 +398,10 @@ file with `chat` in the name, then the first JSON file in the ZIP.
 For OpenAI export mappings, agentlog reads each node message, normalizes
 `author.role`, extracts `content.parts`, and uses `create_time` or `update_time`
 as the timestamp. Web imports are scope-based by default because they generally
-do not have a reliable local working directory.
+do not have a reliable local working directory. Since official exports do not
+usually include usage, the importer archives estimated per-message
+`metadata.usage` from native message content and marks the resulting session
+usage as estimated.
 
 ## Claude Code CLI
 
@@ -444,6 +501,15 @@ Claude.ai is not scanned automatically from the desktop app. The user provides
 an official export file. agentlog reads `chat_messages`, `messages`, or
 `children`, normalizes sender/role fields, extracts text content, and uses
 `created_at`, `updated_at`, or `timestamp`.
+For official `conversations.json` exports, the top-level conversation `summary`
+is archived as both `sessionSummary.summary` and a supplementary transcript row.
+Assistant messages prefer structured `content[]` parts over the legacy top-level
+`text` field so thinking/redacted-thinking parts are separated into
+supplementary `summaryKind=thinking` rows and the visible assistant answer stays
+clean.
+When usage is absent, chat messages get estimated `metadata.usage` from native
+message parts. Claude thinking/redacted-thinking parts contribute
+`reasoningOutputTokens`; visible assistant text remains `outputTokens`.
 
 Project-file conversations are imported as project-scoped sessions. Top-level
 conversation exports are assigned to a project only when Claude includes an
@@ -454,11 +520,14 @@ those conversations remain under the account-level chat scope.
 
 Memory exports are grouped under the synthetic `memory` chat folder instead of
 the original project folder. Root memory is titled `Claude Memory`; project
-memory is titled `Claude Project Memory: <project name>`. This keeps project
-folders from implying that account-level conversations were reliably tagged to
-Claude projects when the export did not preserve that relationship. Re-run
+memory is titled `Claude Project Memory: <project name>`. Claude memory exports
+do not include reliable memory creation/update timestamps, so memory sessions
+are marked `recovered-time-unknown` in history views instead of being displayed
+as if they happened at import time. This keeps project folders from implying
+that account-level conversations were reliably tagged to Claude projects when
+the export did not preserve that relationship. Re-run
 `agentlog import claude-web --file <path>` after importing an export that
-contains conversation project ids or after memory parser semantics change.
+contains conversation project ids or after Claude web parser semantics change.
 
 Like ChatGPT export imports, Claude.ai imports are scope-based by default because
 the export does not reliably describe a local repo.
@@ -483,9 +552,17 @@ JSON and JSONL files use a Gemini-specific parser for `role` / `parts` content,
 native Gemini CLI `type: "user"` / `type: "gemini"` content records, `model`
 role normalization, `functionCall`, `functionResponse`, direct tool call/result
 shapes, nested native `toolCalls[].result` entries, shell/code execution parts,
-usage metadata, and checkpoint or restore events. Gemini tmp prompt logs and
-chat JSONL sidecars with the same session id are coalesced so prompt-only
-`logs.json` files do not overwrite richer assistant/tool transcripts. Markdown
+usage metadata, topic context title updates, and checkpoint or restore events.
+Gemini tmp prompt logs can contain multiple sessions, so agentlog splits them by
+session id before coalescing matching prompt-only logs with richer chat JSONL
+sidecars. When Gemini `Update Topic Context` tool calls include a `title`,
+agentlog stores the latest topic title in session metadata so the web viewer and
+history lists can display it instead of a timestamp-like filename. Existing
+Gemini archives need `agentlog import --source gemini-cli --since all` after
+this parser bump to populate those titles. When Gemini shutdown interaction
+summaries appear in structured history, they are parsed into session metadata
+for tool-call counts, timing, model usage, and resume commands instead of being
+inserted into the chat transcript. Markdown
 files are split into messages by role headings such as
 `# User`, `# Assistant`, or bold role labels. The working directory comes from
 parsed cwd fields or Gemini tmp `.project_root` metadata. If no working
@@ -496,8 +573,10 @@ directory can be resolved, the session is archived under
 
 - Import selector: `antigravity`
 - Provider: `antigravity`
-- Source type: `antigravity-brain`
+- Source types: `antigravity-brain`, `antigravity-trajectory-summary`
 - Primary readable store: `~/.gemini/antigravity/brain/*`
+- Partial metadata store:
+  `Application Support/Antigravity/User/globalStorage/state.vscdb`
 - Binary store counted but not decoded:
   `~/.gemini/antigravity/conversations/*.pb`
 
@@ -506,10 +585,18 @@ artifact names are `task.md`, `implementation_plan.md`, `walkthrough.md`, and
 `plan.md`. Each artifact becomes an assistant message with a heading naming the
 artifact. Timestamps come from artifact file mtimes.
 
+When a conversation has no readable Markdown artifacts, agentlog also imports
+Antigravity trajectory summaries from the app's VS Code-style global state DB.
+Those summaries preserve the conversation id, visible prompt/title, timestamps,
+and workspace path when present. They are marked as partial summaries and do not
+claim to be full transcripts. The global state DB is referenced in the raw
+manifest but not copied, since it can contain auth-bearing settings.
+
 The importer tries to infer a working directory from `file://...` links inside
-the Markdown artifacts. If none can be inferred, it archives under
-`antigravity/uncategorized`. Binary protobuf transcripts are counted in
-discovery details but not imported as conversation messages yet.
+the Markdown artifacts or trajectory summary. If none can be inferred, it
+archives under `antigravity/uncategorized`. Binary protobuf transcripts are
+counted in discovery details but not imported as conversation messages yet.
+Antigravity token usage is therefore not populated from the current local stores.
 
 ## Devin CLI
 
@@ -537,6 +624,12 @@ Devin's `metadata.extensions["chisel/tool_call_content"]` is used for small
 display metadata (`title`, `status`, `kind`, and tool id) while arguments are
 stored as redaction-aware summaries.
 
+Assistant nodes preserve Devin's per-generation token metrics from
+`chat_message.metadata.metrics`, including input, output, cache creation, and
+cache read token counts. Re-run `agentlog import --source devin-cli --since all`
+after upgrading from older parser versions to populate these stats in existing Devin
+archives.
+
 Timestamps come from `sessions.created_at`, `sessions.last_activity_at`, and
 per-node `created_at` values. Devin currently stores these as Unix seconds.
 The working directory comes from `sessions.working_directory`, so repo
@@ -576,7 +669,14 @@ assistant messages, appends terminal/file-selection context, and uses bubble
 timestamps when present. Cursor tool call, tool result, usage, model, status,
 request id, composer id, and edit/diff-like records are normalized into the
 shared `metadata.toolCalls[]`, `metadata.toolResult`, and `metadata.usage`
-shapes when those fields appear in the stored blobs.
+shapes when those fields appear in the stored blobs. Cursor `tokenCount`
+objects are treated as split usage: `inputTokens` and `outputTokens` map to the
+standard in/out buckets, while Cursor cache aliases such as
+`cacheReadInputTokens` map to `cacheInputTokens`. If a Cursor session has no
+provider-reported token usage, agentlog stores rough `estimatedUsage` for stats
+only. The estimate is based on measured Cursor per-turn medians by model family,
+not transcript length alone; measured `usage` remains reserved for
+provider-reported values.
 
 When an old Cursor workspace has no full `bubbles` transcript but still has
 composer headers plus `aiService` prompt/generation breadcrumbs, agentlog imports
@@ -599,17 +699,26 @@ header/conversation list, loading only the matching bubble rows when needed,
 ordering bubbles by that list, and using the composer-level timestamps instead of
 Cursor's migrated bubble timestamps. This is the path that recovers old Cursor UI
 conversations whose workspace `state.vscdb` now only shows selected composer ids
-or prompt history.
+or prompt history. When the composer stores a concrete non-`default`
+`modelConfig`, agentlog applies that model to assistant bubbles that do not carry
+their own model metadata; `default` is intentionally ignored because it is a
+preference pointer rather than the model used at generation time.
 
 When the global composer record omits a workspace folder, agentlog cross-checks
 workspace `composer.composerData` and chat state for the same composer id and
 uses that workspace folder for repo attribution. It also mines absolute paths
-from Cursor bubble context, including object keys such as nested
+from Cursor bubble context, including top-level selections, object keys such as nested
 `context.mentions.fileSelections["file:///..."]`, `relevantFiles`,
 `attachedFolders`, workspace URIs, and recently viewed files. When old file
 paths in the bubble context no longer exist, cwd inference walks up to the
 nearest existing parent so the session can still resolve to the repo.
 
+Cursor assistant and bubble records are parsed for visible text, tool calls,
+tool results, token usage, selected model, selected files, terminal selections,
+suggested code blocks, and diff histories. Tool calls and results are normalized
+from common Cursor shapes into the same canonical tool metadata used by the web
+viewer.
+
 During dedupe, richer Cursor sources win over fallback sources. Newer project
 agent transcripts rank highest, global `cursorDiskKV` composer records rank
 above workspace SQLite, and `aiService` prompt/apply history ranks as a
@@ -727,8 +836,16 @@ original checkpoint files remain in raw backups.
 
 - Import selector: `opencode`
 - Provider: `opencode`
-- Source type: `opencode-history`
+- Source types:
+  - `opencode-sqlite-history` for the normalized `opencode.db` store
+  - `opencode-history` for the JSON `storage/` layout
 - Primary data root: `~/.local/share/opencode`
+- Alternate macOS data root: `~/Library/Application Support/opencode`
+- Additional desktop roots:
+  - `~/.local/share/ai.opencode.app`
+  - `~/Library/Application Support/ai.opencode.app`
+- SQLite database:
+  - `opencode.db`
 - Storage roots:
   - `~/.local/share/opencode/storage`
   - `~/.local/share/opencode/project/<project-slug>/storage`
@@ -740,14 +857,29 @@ original checkpoint files remain in raw backups.
   - `storage/project/<project-id>.json`
 - Overrides:
   - `AGENTLOG_OPENCODE_DATA_DIR` overrides the data root.
+  - `AGENTLOG_OPENCODE_DB`, `AGENTLOG_OPENCODE_DATABASE`, or `OPENCODE_DB`
+    points directly at one or more SQLite databases.
   - `AGENTLOG_OPENCODE_STORAGE_DIR` or `AGENTLOG_OPENCODE_STORAGE_ROOTS`
     points directly at one or more `storage` directories.
 
-agentlog reads OpenCode's JSON session store directly. Sessions provide the
+agentlog first reads OpenCode's normalized SQLite store when `opencode.db` is
+present. The `session`, `message`, `part`, and `project` tables provide session
+metadata, working directory, user/assistant messages, reasoning text, tool
+calls, tool outputs, model/provider ids, cost, and token usage. Because the
+database is a multi-session source, raw preservation stores it as a shared raw
+source instead of duplicating the same file into every session archive.
+
+agentlog also reads OpenCode's JSON session store directly. Sessions provide the
 archive id and project id; message and part files provide role text, reasoning
 text, tool calls, and tool outputs. Tool parts are normalized into
 `metadata.toolCalls[]` and `metadata.toolResult` records so the web viewer can
 render them with the same cards used for Codex, Claude, Devin, and Cursor.
+If a session metadata file is missing but `storage/message/<session-id>/` and
+`storage/part/<message-id>/` files remain, agentlog reconstructs a best-effort
+session from those message and part files.
+
+When both SQLite and JSON records exist for the same OpenCode session id,
+agentlog prefers `opencode-sqlite-history` and merges the raw source file list.
 
 When `session_diff/<session-id>.json` is present, agentlog adds a supplementary
 edit tool call with the diff payload. Unified diff text is rendered inline in
@@ -789,14 +921,31 @@ backups.
 
 - Import selector: `windsurf`
 - Provider: `windsurf`
-- Source type: `windsurf-cascade-brain`
+- Source types: `windsurf-trajectory-export`, `windsurf-cascade-brain`
+- Explicit export import: `agentlog import windsurf <downloaded-trajectory.md>`
+  or `agentlog import windsurf <folder-of-trajectories>`
 - Primary readable store: `~/.codeium/windsurf/brain/*`
 - Binary store counted but not decoded: `~/.codeium/windsurf/cascade/*.pb`
-- Status: disabled from setup, default imports, and history filters
-
-Windsurf support is currently disabled. Current Cascade sessions are written as
-encrypted binary stores, so agentlog can detect session IDs and workspace
-metadata but cannot archive readable conversation text from the local files.
+- Status: encrypted local cache scanning is disabled from setup, default imports,
+  and history filters; downloaded trajectory Markdown exports are importable
+
+Windsurf local cache scanning is currently disabled. Current Cascade sessions
+are written as encrypted binary stores, so agentlog can detect session IDs and
+workspace metadata but cannot archive readable conversation text from those
+local files.
+
+Windsurf's "Download trajectory" action produces Markdown headed
+`# Cascade Chat Conversation`. Agentlog imports those files explicitly with
+`agentlog import windsurf <path>`. The export is treated as a normalized
+provider transcript surface: `### User Input` sections become user messages,
+`### Planner Response` / assistant-like sections become assistant messages, and
+the original Markdown file is preserved in raw backups.
+
+Bulk export tools that automate Windsurf's hidden "Download trajectory" button
+can write many `*.md` files into one directory. Agentlog intentionally treats
+that directory as user-selected export input rather than scanning Windsurf's
+encrypted cache: run `agentlog import windsurf ~/windsurf-cascade-export` after
+the bulk exporter finishes.
 
 The older experimental helper can still read Markdown artifacts from Windsurf
 Cascade brain directories when present. Recognized artifact names are `plan.md`,
@@ -810,10 +959,15 @@ Binary Cascade protobuf stores are counted in discovery details but not decoded.
 
 ## Collector And Live Monitoring
 
-`agentlog start` runs the supervisor. The current supervisor periodically imports
-the watcher source list selected during init and can run archive sync. The
-collector path accepts OTLP JSON and stores telemetry payloads under the archive
-telemetry directory.
+`agentlog watcher start` runs the supervisor, which is agentlog's local background
+watcher. It periodically imports the watcher source list selected during init
+and can run archive sync. If a user opts out of starting the watcher at login
+by unchecking `Start watcher at login` or running `agentlog init --no-autostart`,
+agentlog still works in manual mode: `agentlog import --source all` performs a
+one-time catch-up, `agentlog watcher start` watches until stopped, and
+`agentlog watcher login enable` can install the login item later. The collector path
+accepts OTLP JSON and stores telemetry payloads under the archive telemetry
+directory.
 For Cursor, the supervisor handles incremental logs going forward; explicit
 full imports handle raw SQLite recovery/backfill.
 
@@ -827,7 +981,8 @@ as importing transcript history.
 
 - ChatGPT and Claude.ai are import-by-export only; agentlog does not read their
   desktop app local stores.
-- Windsurf is disabled because Cascade protobuf transcripts appear encrypted.
+- Windsurf encrypted cache scanning is disabled; downloaded trajectory Markdown
+  exports are supported.
 - Antigravity protobuf transcripts are counted but not decoded.
 - Cursor older `state.vscdb` stores are best-effort because Cursor has changed
   local storage layouts over time.

package/docs/release.md

@@ -1,10 +1,10 @@
 # Release Checklist
 
-Use this checklist before publishing the `agentlogs` npm package.
+Use this checklist before publishing the `agentel` npm package.
 
 ## Prerequisites
 
-- Confirm the npm publishing account can publish `agentlogs`.
+- Confirm the npm publishing account can publish `agentel`.
 - Confirm `https://github.com/brianlzhou/agentlog` is reachable for GitHub
   shorthand installs such as `npm install -g brianlzhou/agentlog`.
 - Use Node.js 20 or newer.
@@ -43,7 +43,7 @@ home/config directories:
 
 ```sh
 agentlog help
-agentlogs help
+agentel help
 agentlog init --yes --skip-import --no-autostart --no-claude --no-recall --no-telemetry
 agentlog doctor --json
 ```
@@ -53,17 +53,17 @@ agentlog doctor --json
 When the checks pass, publish from a clean working tree:
 
 ```sh
-npm publish --access public
+npm publish
 ```
 
 For the first public release, use npm 2FA or trusted publishing. The package
-name is plural (`agentlogs`) so it can coexist with the singular CLI command.
+name is `agentel` so it can coexist with the singular CLI command.
 Keep the `agentlog` binary for normal usage; the package also ships an
-`agentlogs` binary alias so `npx agentlogs init` works.
+`agentel` binary alias so `npx agentel init` works.
 
 After tagging and pushing the release, sanity-check both public install forms:
 
 ```sh
-npm install -g agentlogs
-npm install -g brianlzhou/agentlog#v0.2.0
+npm install -g agentel
+npm install -g brianlzhou/agentlog#v0.2.2
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentel",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Local-first archive and recall layer for agent coding sessions.",
   "type": "commonjs",
   "license": "MIT",
@@ -29,9 +29,9 @@
     "recall"
   ],
   "bin": {
-    "agentlog": "./bin/agentlog.js",
-    "agentlog-recall": "./bin/agentlog-recall.js",
-    "agentel": "./bin/agentlog.js"
+    "agentlog": "bin/agentlog.js",
+    "agentlog-recall": "bin/agentlog-recall.js",
+    "agentel": "bin/agentlog.js"
   },
   "files": [
     "bin/",
@@ -46,6 +46,7 @@
   "scripts": {
     "prepack": "npm run check && npm test",
     "pack:dry": "npm pack --dry-run",
+    "prepare:update": "node scripts/prepare-update.js",
     "smoke:pack": "node scripts/smoke-pack.js",
     "test": "node --test",
     "check": "node scripts/check-syntax.js"