sidecar-cli 0.1.1 → 0.1.2-beta.1

package/README.md

@@ -21,6 +21,12 @@ Install globally (stable):
 npm install -g sidecar-cli
 ```
 
+Note on npm deprecation warnings:
+
+- You may see a transitive warning for `prebuild-install@7.1.3` during install.
+- This currently comes from `better-sqlite3` (Sidecar's SQLite dependency), not from Sidecar code directly.
+- Sidecar still installs/works normally; we will update when upstream dependency chain moves off it.
+
 Install beta:
 
 ```bash
@@ -103,7 +109,11 @@ Global:
 
 - `sidecar init [--force] [--name <project-name>] [--json]`
 - `sidecar status [--json]`
+- `sidecar preferences show [--json]`
+- `sidecar ui [--no-open] [--port <port>] [--install-only] [--project <path>] [--reinstall]`
 - `sidecar capabilities --json`
+- `sidecar event add ... [--json]`
+- `sidecar export [--format json|jsonl] [--output <path>]`
 - `sidecar help`
 
 Context and summary:
@@ -168,7 +178,18 @@ Optional local enforcement:
 npm run install:hooks
 ```
 
-This installs a non-blocking pre-commit reminder that runs `npm run sidecar:reminder`.
+This is optional and per-repository clone. `sidecar init` does not install git hooks automatically.
+
+This installs a pre-commit guard that checks staged non-doc code changes.
+If staged code changes are present, commit is blocked unless both are recorded since the last commit:
+
+- a `worklog` event
+- a `summary refresh` event
+
+The guard command is:
+
+- `npm run sidecar:reminder -- --staged --enforce`
+
 If a pre-commit hook already exists, Sidecar will not overwrite it unless you run:
 
 ```bash
@@ -205,6 +226,54 @@ Primary tables:
 
 No network dependency is required for normal operation.
 
+## Optional local UI
+
+`sidecar ui` launches a local browser UI for the selected Sidecar project.
+
+Lazy-install behavior:
+
+1. `sidecar ui` resolves the nearest `.sidecar` project root (or uses `--project`).
+2. Sidecar checks for `@sidecar/ui` in `~/.sidecar/ui`.
+3. If missing/incompatible, Sidecar installs or updates it automatically.
+4. Sidecar starts a local UI server and opens the browser (unless `--no-open`).
+
+UI runtime location:
+
+- `~/.sidecar/ui`
+- the CLI installs `@sidecar/ui` here (not in your project repo)
+
+Version compatibility rule:
+
+- CLI and UI must share the same major version.
+- If majors differ, `sidecar ui` auto-reinstalls/updates UI.
+
+Common examples:
+
+```bash
+sidecar ui
+sidecar ui --no-open --port 4311
+sidecar ui --install-only
+sidecar ui --project ../other-repo
+sidecar ui --reinstall
+```
+
+Initial UI screens:
+
+- Overview: project info, active session, recent decisions/worklogs, open tasks, recent notes
+- Timeline: recent events in chronological order
+- Tasks: open and completed tasks
+- Decisions: decision records with summary and timestamps
+- Preferences: `.sidecar/preferences.json` and `.sidecar/summary.md`
+
+UI write support (v1):
+
+- Add notes from Overview
+- Add open tasks from Overview
+- Edit `.sidecar/preferences.json` from Preferences
+  - `output.humanTime` controls timestamp style in human-readable CLI output:
+    - `true`: friendly local times (for example `3/18/2026, 11:51 AM`)
+    - `false`: raw ISO-style timestamps
+
 ## JSON output
 
 Most commands support `--json` and return structured output:
@@ -216,6 +285,68 @@ Most commands support `--json` and return structured output:
 
 This makes Sidecar easy to automate from scripts and AI agents.
 
+## Integration API
+
+Sidecar CLI is the first integration API for scripts, agents, and local tooling.
+
+Standard JSON envelope:
+
+```json
+{
+  "ok": true,
+  "version": "1.0",
+  "command": "task add",
+  "data": {},
+  "errors": []
+}
+```
+
+Failure envelope:
+
+```json
+{
+  "ok": false,
+  "version": "1.0",
+  "command": "task add",
+  "data": null,
+  "errors": ["..."]
+}
+```
+
+Generic event ingest:
+
+```bash
+sidecar event add --type decision --title "Use SQLite" --summary "Simple local storage for v1" --created-by agent --source cli --json
+sidecar event add --json-input '{"type":"note","summary":"Captured context","created_by":"agent"}' --json
+cat event.json | sidecar event add --stdin --json
+```
+
+Capabilities metadata:
+
+```bash
+sidecar capabilities --json
+```
+
+Includes:
+
+- `cli_version`
+- `json_contract_version`
+- `features`
+- command and option metadata
+
+Export project memory:
+
+```bash
+sidecar export --format json
+sidecar export --format json --output ./exports/sidecar.json
+sidecar export --format jsonl > sidecar-events.jsonl
+```
+
+JSONL note:
+
+- JSONL export currently emits events only, one JSON object per line.
+- each JSONL line includes `"version": "1.0"` and `"record_type": "event"`.
+
 ## Release and distribution
 
 See [RELEASE.md](./RELEASE.md) for publishing/release details.