@genspark/opencode-conversation-archiver 0.1.0 → 0.1.1

package/README.md

@@ -11,7 +11,21 @@ records only user-visible text:
 Reasoning, tool calls, tool outputs, file URLs, synthetic text, ignored text,
 and child/subagent sessions are excluded.
 
-## Install From This Repository
+## Install
+
+```bash
+opencode plugin -g @genspark/opencode-conversation-archiver@0.1.1
+```
+
+Completely quit and restart OpenCode after installation. The first completed
+turn is archived locally under `~/opencode-conversations` with no additional
+setup.
+
+See the [User Guide](./USER_GUIDE.md) for Second Brain connection, sharing one
+remote repository with Claude Code, management commands, privacy details,
+upgrades, troubleshooting, and removal.
+
+## Install From Source
 
 Build the package:
 
@@ -88,7 +102,7 @@ OpenCode SDK and current session identity.
 
 ## Second Brain
 
-`conversation_archive_connect` and the CLI `connect` support:
+The CLI `connect` supports:
 
 1. A one-time `.../sb-connect/<code>` URL.
 2. No arguments, using `GSK_API_KEY` or the credential created by `gsk login`.

package/USER_GUIDE.md

@@ -0,0 +1,287 @@
+# OpenCode Conversation Archiver User Guide
+
+OpenCode Conversation Archiver saves each top-level OpenCode chat as readable
+Markdown and can synchronize it to a git repository. It archives completed
+turns automatically without changing the conversation or blocking OpenCode.
+
+## Requirements
+
+- OpenCode `1.17.18` or newer, below `2.0.0`
+- Git on `PATH`
+- Node.js 20 or newer for the management CLI
+
+## Install
+
+Install globally so the plugin is available in every OpenCode project:
+
+```bash
+opencode plugin -g @genspark/opencode-conversation-archiver@0.1.1
+```
+
+To enable it only in the current project, omit `-g`:
+
+```bash
+opencode plugin @genspark/opencode-conversation-archiver@0.1.1
+```
+
+OpenCode writes the package to the selected `opencode.json`. On the next
+startup it installs and caches the npm package automatically. Completely quit
+and restart OpenCode after installing or upgrading the plugin.
+
+To track the latest release rather than pinning a version:
+
+```bash
+opencode plugin -g @genspark/opencode-conversation-archiver
+```
+
+## First Conversation
+
+No setup is required for local archiving. After the next completed OpenCode
+turn, the plugin creates:
+
+```text
+~/opencode-conversations/
+└── YYYY-MM/
+    └── YYYY-MM-DD-HHMM-conversation-title.md
+```
+
+The directory is initialized as a git repository. With no remote configured,
+archives are committed locally and push failures never interrupt OpenCode.
+
+Check the setup from a terminal:
+
+```bash
+npx -y @genspark/opencode-conversation-archiver@0.1.1 status
+npx -y @genspark/opencode-conversation-archiver@0.1.1 doctor
+```
+
+If the package is installed globally with npm, the shorter executable also
+works:
+
+```bash
+opencode-conversation-archiver status
+```
+
+## Connect Second Brain
+
+Use one of these methods from a terminal. Connection credentials are never
+accepted through an LLM-visible OpenCode tool.
+
+### One-Time Link
+
+Copy the Second Brain connection link and run:
+
+```bash
+npx -y @genspark/opencode-conversation-archiver@0.1.1 connect '<sb-connect-link>'
+```
+
+### Existing Genspark CLI Login
+
+If `gsk login` has already created a local credential, run:
+
+```bash
+npx -y @genspark/opencode-conversation-archiver@0.1.1 connect
+```
+
+The command can also use `GSK_API_KEY` from the environment.
+
+### Explicit Git Remote
+
+For another HTTP(S) git server:
+
+```bash
+npx -y @genspark/opencode-conversation-archiver@0.1.1 \
+  connect 'https://git.example.com/archive.git' '<token>' 'opencode'
+```
+
+`connect` succeeds only after the initial remote synchronization succeeds. A
+partially configured connection with a failed first push exits nonzero so
+scripts can detect and retry it.
+
+## Share One Repository With Claude Code
+
+Claude Code and OpenCode can synchronize to the same remote repository without
+sharing a local working tree:
+
+```text
+Remote conversation repository
+├── YYYY-MM/             Claude Code archives
+└── opencode/
+    └── YYYY-MM/         OpenCode archives
+```
+
+Recommended local layout:
+
+```text
+~/claude-conversations/     Claude Code clone and locks
+~/opencode-conversations/   OpenCode clone and locks
+```
+
+Connect OpenCode to the same remote/token used by Claude Code, with `opencode`
+as the subdirectory. The default Second Brain connection already uses this
+layout.
+
+Do not point both plugins at the same local clone. Each plugin performs its own
+commit, rebase, push, state tracking, and locking. Separate clones prevent one
+plugin from staging the other plugin's in-progress files while still producing
+one combined remote history.
+
+## Daily Use
+
+Automatic mode is enabled by default. Each changed completed turn is written,
+committed, and pushed in the background when a remote exists.
+
+```bash
+# Show mode, repository, redacted remote, recent commits, and pending changes
+npx -y @genspark/opencode-conversation-archiver@0.1.1 status
+
+# Run read-only dependency, repository, and remote checks
+npx -y @genspark/opencode-conversation-archiver@0.1.1 doctor
+
+# Keep writing Markdown locally without commit or push
+npx -y @genspark/opencode-conversation-archiver@0.1.1 manual
+
+# Restore automatic commit and push
+npx -y @genspark/opencode-conversation-archiver@0.1.1 auto
+
+# Commit and push pending archives immediately
+npx -y @genspark/opencode-conversation-archiver@0.1.1 upload
+
+# Send future local archives to another dedicated clone
+npx -y @genspark/opencode-conversation-archiver@0.1.1 \
+  repo ~/Documents/opencode-conversations
+```
+
+The `repo` command repoints future archives. It does not move or delete the old
+repository.
+
+## OpenCode Tools
+
+The plugin gives OpenCode four tools:
+
+| Tool | Behavior |
+| --- | --- |
+| `conversation_archive_status` | Read-only archive status |
+| `conversation_archive_doctor` | Read-only diagnostics |
+| `conversation_archive_current` | Archive the current top-level project session after permission approval |
+| `conversation_archive_backfill` | Archive existing top-level sessions in the current project after permission approval |
+
+Examples to type in OpenCode:
+
+```text
+Check my conversation archive status.
+Diagnose my conversation archive.
+Archive this conversation now.
+Backfill this project's existing conversations.
+```
+
+Repository paths, modes, uploads, connection links, and tokens are CLI-only so
+those values do not enter the model conversation.
+
+## What Is Saved
+
+Saved:
+
+- User-visible user text
+- User-visible assistant text
+- Context compaction boundaries
+- Session ID, start time, title, machine name, and turn count
+
+Not saved:
+
+- Reasoning parts
+- Tool calls and tool outputs
+- Uploaded file URLs
+- Synthetic or ignored text parts
+- Child/subagent sessions
+- Git credentials
+
+Credentials are stored outside the archive repository at:
+
+```text
+~/.config/opencode/conversation-archiver/git-credentials
+```
+
+The file is created with mode `0600`. Status, doctor, and logs redact
+credentials embedded in HTTP(S) URLs.
+
+## Configuration And Files
+
+Runtime configuration:
+
+```text
+~/.config/opencode/conversation-archiver/config.json
+```
+
+Runtime state and logs:
+
+```text
+~/.config/opencode/conversation-archiver/state/
+~/.config/opencode/conversation-archiver/archive.log
+~/.config/opencode/conversation-archiver/push.log
+```
+
+Environment overrides:
+
+| Variable | Purpose |
+| --- | --- |
+| `OPENCODE_ARCHIVE_MODE` | `auto` or `manual` |
+| `OPENCODE_ARCHIVE_REPO` | Override the local archive clone |
+| `OPENCODE_ARCHIVE_NO_NOTIFY` | Disable terminal completion notification when set |
+
+## Upgrade
+
+Install a newer version with `--force`, then restart OpenCode:
+
+```bash
+opencode plugin -g -f @genspark/opencode-conversation-archiver@0.1.1
+```
+
+Your Markdown repository and runtime state are outside OpenCode's plugin cache
+and remain in place across upgrades.
+
+## Troubleshooting
+
+### No Markdown Appears
+
+1. Completely restart OpenCode after installation.
+2. Finish a top-level conversation turn; child/subagent sessions are excluded.
+3. Run `doctor` and confirm Git is available.
+4. Check the configured repository shown by `status`.
+
+### Local Commit Exists But Remote Is Behind
+
+Run:
+
+```bash
+npx -y @genspark/opencode-conversation-archiver@0.1.1 upload
+```
+
+Then run `doctor`. It tests remote authentication without printing the token.
+The plugin serializes pushes and performs `pull --rebase` before pushing, so a
+Claude Code commit arriving first is integrated into the same remote history.
+
+### Connect Link Does Not Work
+
+One-time links can expire or be consumed once. Generate a new link and run the
+CLI command again. Do not paste the link into an OpenCode chat.
+
+### OpenCode Loads The Plugin Twice
+
+Check both global and project `opencode.json`. Keep one npm entry unless you
+intentionally need different project-specific options. A local plugin file and
+an npm plugin are separate and can both load.
+
+## Remove
+
+Remove `@genspark/opencode-conversation-archiver` from the `plugin` array in the
+project or global `opencode.json`, then restart OpenCode.
+
+Uninstalling does not delete either of these locations:
+
+```text
+~/opencode-conversations/
+~/.config/opencode/conversation-archiver/
+```
+
+Delete or retain them according to your own backup policy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genspark/opencode-conversation-archiver",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Archive OpenCode conversations as readable Markdown in a git repository",
   "keywords": [
     "opencode",
@@ -33,7 +33,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "USER_GUIDE.md"
   ],
   "bin": {
     "opencode-conversation-archiver": "./dist/cli.js"