byterover-cli 0.1.0 → 0.1.1

package/README.md

@@ -1,69 +1,35 @@
 # ByteRover CLI
 
-Command-line interface for ByteRover, enabling seamless project management, authentication, and workspace operations directly from your terminal.
+Command-line interface for ByteRover, enabling seamless team/space management, authentication, and space's memory operations directly from your terminal.
 
-[![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
 [![Version](https://img.shields.io/npm/v/byterover-cli.svg)](https://npmjs.org/package/byterover-cli)
 [![Downloads/week](https://img.shields.io/npm/dw/byterover-cli.svg)](https://npmjs.org/package/byterover-cli)
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Node](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org)
+[![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
 
 ## Table of Contents
 
-<!-- toc -->
-* [Development Testing](#development-testing)
 * [Installation](#installation)
 * [Quick Start](#quick-start)
-* [Agentic Context Engineering (ACE)](#agentic-context-engineering-ace)
+* [What is ACE?](#what-is-ace)
+* [Core Workflow](#core-workflow)
+* [Essential Commands](#essential-commands)
 * [Authentication](#authentication)
-* [Usage](#usage)
-* [Commands](#commands)
 * [Configuration](#configuration)
-* [Development](#development)
-* [Architecture](#architecture)
-<!-- tocstop -->
-
-## Development Testing
-
-Make sure you're on the `develop` branch.
-
-Build:
-
-```bash
-npm run build
-```
-
-In `./bin/run.js`, change `process.env.BR_ENV` to `'development'`.
-
-Run:
-
-```bash
-npm link
-```
-
-This will:
-
-- Create a **folder symlink** `<npm_global_prefix>/lib/node_modules/<package_name>`
-  which points to the **package's directory**.
-- Create a symlink for **the package's bin**
-  in
-  `<npm_global_prefix>/bin/<package_bin_command_or_package_name>`
-  which points to
-  `<npm_global_prefix>/lib/node_modules/<package_name>/<path_to_executable>`.
-- Register the package as being globally installed.
-
-Once testing is done, the package can be "unlink" by:
-
-```bash
-npm uninstall -g package-name
-```
+* [Getting Help](#getting-help)
 
 ## Installation
 
 ### Requirements
 
-- **Node.js**: >= 22.0.0
-- **Operating System**: macOS (keychain integration for secure token storage)
+- **Node.js**: >= 18.0.0
+- **Operating System**:
+  - macOS
+  - Windows
+  - Linux
+    - Currently this CLI uses `libsecret`. Depending on your distribution, you will need to run the following command:
+      - Debian/Ubuntu: `sudo apt-get install libsecret-1-dev`
+      - Red Hat-based: `sudo yum install libsecret-devel`
+      - Arch Linux: `sudo pacman -S libsecret`
 
 ### Install globally via npm
 
@@ -96,17 +62,17 @@ cd your-project-directory
 br init
 ```
 
-Select a workspace from your available spaces and configure your project.
+Select a space from your available spaces and configure your project.
 
 ### 3. Start using ByteRover
 
 You're ready to use ByteRover commands in your project!
 
-## Agentic Context Engineering (ACE)
+## What is ACE?
 
-**ACE** is a systematic workflow for coding agents (like Claude Code, Cursor, etc.) to capture their work, learn from feedback, and build cumulative knowledge in a living playbook.
+**Agentic Context Engineering (ACE)** is a systematic workflow that helps coding agents (like Claude Code, Cursor, etc.) capture their work, learn from feedback, and build cumulative knowledge in a living playbook.
 
-This implementation is based on the research paper: [**Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models**](https://arxiv.org/abs/2510.04618) by Dang et al., which introduces a framework for language models to iteratively improve their performance through structured context evolution.
+Based on the research paper [**Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models**](https://arxiv.org/abs/2510.04618) by Dang et al., ACE enables language models to iteratively improve their performance through structured context evolution.
 
 ### Why Use ACE?
 
@@ -115,15 +81,22 @@ This implementation is based on the research paper: [**Agentic Context Engineeri
 - **Context Persistence**: Maintain project-specific best practices that improve over time
 - **Traceability**: Track what worked, what didn't, and why
 
-### The ACE Workflow
+## Core Workflow
+
+ACE follows a simple 3-phase cycle that coding agents can use to improve over time:
+
+### 1. Executor
+Agent performs coding task and saves detailed output with context.
 
-ACE follows a 3-phase cycle:
+### 2. Reflector
+Agent analyzes results and provides honest feedback on what worked and what didn't.
 
-1. **Executor** - Agent performs coding task and saves output with detailed context
-2. **Reflector** - Agent analyzes results and provides honest feedback
-3. **Curator** - Agent transforms insights into playbook updates (automatically applied)
+### 3. Curator
+Agent transforms insights into playbook updates that are automatically applied to improve future work.
 
-### Quick ACE Example
+### Quick Example
+
+If you're using a coding agent like Claude Code:
 
 ```bash
 # Complete ACE workflow in a single command
@@ -132,650 +105,122 @@ br complete "auth-feature" \
   "Successfully added OAuth2 authentication" \
   --tool-usage "Read:src/auth.ts,Edit:src/auth.ts,Bash:npm test" \
   --feedback "All tests passed, auth works correctly"
-
-# Update an existing playbook bullet
-br complete "auth-update" \
-  "Improved error handling in auth flow" \
-  "Better error messages for failed login" \
-  --tool-usage "Edit:src/auth.ts" \
-  --feedback "Tests passed" \
-  --update-bullet "bullet-5"
 ```
 
-### For Coding Agents
-
-**📘 Complete ACE Guide**: See [rules](./src/templates/README.md) for comprehensive instructions on using ACE in your development workflow.
+For comprehensive ACE instructions for coding agents, check the corresponding coding agents' instruction files after `br init` or `br gen-rules`.
 
-`br gen-rules` (integrated into `br init`) helps users quickly set up their coding agents with the ACE workflow.
+## Essential Commands
 
-### ACE Commands
+### Authentication
 
 ```bash
-# Complete ACE workflow (executor + reflector + curator in one command)
-br complete <hint> <reasoning> <answer> \
-  --tool-usage <tools> \
-  --feedback <feedback> \
-  [--bullet-ids <ids>] \
-  [--update-bullet <id>]                           # Complete workflow: save, reflect, and update playbook
-
-# Direct playbook manipulation (bypasses ACE workflow)
-br add -s "Section" -c "Content"                   # Add new bullet (auto-generates ID)
-br add -s "Section" -c "Updated" -b "bullet-id"    # Update existing bullet
-
-# Memory operations
-br push [--branch name]                            # Push playbook to blob storage and cleanup local files
-br retrieve --query <text> [--node-keys <paths>]   # Retrieve memories from ByteRover and load into playbook
+# Log in to ByteRover
+br login
 
-# Utility commands
-br status                                          # View CLI status and playbook statistics
-br clear [--yes]                                   # Reset playbook
+# Check your authentication and project status
+br status
 ```
 
-#### Quick Add Command
-
-For agents that need to quickly add context without the full ACE workflow:
+### Project Setup
 
 ```bash
-# 1. First, check the current playbook
-br show
+# Initialize project with ByteRover
+br init
 
-# 2. Add a new bullet to an existing or new section
-br add -s "Common Errors" -c "Always validate API responses before processing"
+# List available spaces
+br space list
 
-# 3. Update an existing bullet (use ID from br show)
-br add -s "Common Errors" -c "Updated content" -b "common-00001"
+# Switch to a different space or team
+br space switch
 ```
 
-The `add` command automatically tags bullets with `['manual']` and is ideal for quick knowledge capture during development.
-
-### Memory Push
-
-The `br push` command uploads your playbook to ByteRover's memory storage (blob storage) and automatically cleans up local ACE files. This is useful when you want to:
-
-- **Share playbook knowledge** with other team members or agents
-- **Archive completed work** to cloud storage
-- **Reset local state** after pushing insights to the system
-- **Free up local storage** by removing processed ACE outputs
-
-#### Usage
+### Memory Operations
 
 ```bash
-# Push to default branch (main)
-br push
-
-# Push to a specific branch
-br push --branch develop
-br push -b feature-auth
-```
-
-#### What Gets Pushed
-
-- `.br/ace/playbook.json` - Your accumulated knowledge base
-
-#### What Gets Cleaned Up (After Successful Push)
-
-After successfully uploading to blob storage, the command automatically:
-
-1. **Clears playbook content** - Resets to empty playbook (file remains, content cleared)
-2. **Removes executor outputs** - Deletes all files in `.br/ace/executor-outputs/`
-3. **Removes reflections** - Deletes all files in `.br/ace/reflections/`
-4. **Removes deltas** - Deletes all files in `.br/ace/deltas/`
-
-**Note**: Cleanup only happens after successful upload. If the upload fails, your local files remain unchanged.
-
-#### Example Output
-
-```text
-Requesting upload URLs... done
-Loading playbook... done
-
-Uploading files...
-  Uploading playbook.json... ✓
-
-Cleaning up local files...
-  Clearing playbook... ✓
-  Cleaning executor outputs... ✓ (3 files removed)
-  Cleaning reflections... ✓ (2 files removed)
-  Cleaning deltas... ✓ (5 files removed)
-
-✓ Successfully pushed playbook to ByteRover memory storage!
-  Branch: main
-  Files uploaded: 1
-```
-
-#### Branches
-
-The `--branch` parameter refers to **ByteRover's internal branching system**, not Git branches. This allows you to organize different versions of your playbook in blob storage (e.g., `main`, `develop`, `experimental`).
-
-### File Organization
-
-ACE stores all outputs in `.br/ace/` with hint-based naming for traceability:
+# Retrieve memories from ByteRover (outputs to stdout for agent context)
+br retrieve --query "authentication best practices"
+br retrieve -q "error handling" -n "src/auth/login.ts,src/auth/oauth.ts"
 
+# Push your playbook to ByteRover's memory storage
+br push
 ```
-.br/ace/
-├── playbook.json                                    # Living knowledge base
-├── executor-outputs/
-│   └── executor-{hint}-{timestamp}.json            # Your coding work
-├── reflections/
-│   └── reflection-{hint}-{timestamp}.json          # Analysis and feedback
-└── deltas/
-    └── delta-{hint}-{timestamp}.json               # Playbook updates
-```
-
-**Note**: When you run `br push`, all files in `executor-outputs/`, `reflections/`, and `deltas/` are removed after successful upload. The `playbook.json` is cleared (reset to empty). This keeps your local workspace clean while preserving your knowledge in ByteRover's blob storage.
-
-### Memory Retrieve
-
-The `br retrieve` command fetches memories from ByteRover's Memora service and loads them to `stdout` as parts of the coding agents' current context. This is useful when you want to:
 
-- **Access team knowledge** - Retrieve insights and best practices shared by your team
-- **Find relevant context** - Search for specific topics or code patterns
-- **Filter by files** - Narrow results to specific file paths using `--node-keys`
-- **Start with knowledge** - Begin work with relevant memories already in your playbook
-
-#### Retrieve Usage
+### For Coding Agents
 
 ```bash
-# Retrieve memories by query
-br retrieve --query "authentication best practices"
-
-# Retrieve with file path filtering
-br retrieve -q "error handling" -n "src/auth/login.ts,src/auth/oauth.ts"
+# Complete ACE workflow (recommended for agents)
+br complete <hint> <reasoning> <answer> \
+  --tool-usage <tools> \
+  --feedback <feedback>
 
-# Short form
-br retrieve -q "database connection issues"
+# Generate agent rules (sets up ACE workflow for your coding agent)
+br gen-rules
 ```
 
-#### How Retrieve Works
-
-1. **Searches** ByteRover's memory storage for matches to your query
-2. **Filters** results by node keys (file paths) if specified
-3. **Clears** your existing local playbook
-4. **Loads** retrieved memories and related memories into `stdout`.
-
 ## Authentication
 
-ByteRover CLI uses **OAuth 2.0 with PKCE** (Proof Key for Code Exchange) for secure authentication:
+ByteRover CLI uses **OAuth 2.0 with PKCE** (Proof Key for Code Exchange) for secure authentication.
 
 ### How it works
 
-1. Run `br login` to initiate authentication
-2. A local callback server starts on a random port
-3. Your default browser opens to the ByteRover authorization page
-4. After successful authentication, tokens are securely stored in your system keychain
-5. All subsequent commands automatically use your stored credentials
+1. Run `br login` to start authentication
+2. Your browser opens to the ByteRover authorization page
+3. After successful login, tokens are securely stored in your system keychain
+4. All subsequent commands automatically use your stored credentials
 
 ### Security features
 
 - **PKCE flow**: Prevents authorization code interception attacks
-- **System keychain**: Tokens stored using native OS secure storage (macOS Keychain)
-- **Session tracking**: Each authentication session includes a session key for request tracking
+- **System keychain**: Tokens stored in macOS Keychain
+- **Session tracking**: Each session includes a session key for request tracking
 - **Auto-refresh**: Refresh tokens enable seamless credential renewal
 
-### Environment-aware
-
-The CLI supports separate development and production environments:
-
-- **Development**: Uses `./bin/dev.js` and points to dev authentication servers
-- **Production**: Uses `./bin/run.js` and points to production servers
-
-### Token storage
-
-After authentication, the CLI stores:
-
-- **Access token**: For API authorization (`Authorization: Bearer {token}`)
-- **Refresh token**: For obtaining new access tokens
-- **Session key**: For request tracking (`x-byterover-session-id` header)
-- **Expiration time**: For automatic token refresh
-
-All tokens are stored in your system keychain via the `keytar` library.
-
-## Usage
-
-```sh-session
-$ npm install -g byterover-cli
-$ br COMMAND
-running command...
-$ br (--version)
-byterover-cli/0.0.0 darwin-arm64 node-v22.19.0
-$ br --help [COMMAND]
-USAGE
-  $ br COMMAND
-...
-```
-
-## Commands
-
-* [`br add`](#br-add)
-* [`br clear`](#br-clear)
-* [`br complete`](#br-complete)
-* [`br gen-rules`](#br-gen-rules)
-* [`br help [COMMAND]`](#br-help-command)
-* [`br init`](#br-init)
-* [`br login`](#br-login)
-* [`br push`](#br-push)
-* [`br retrieve`](#br-retrieve)
-* [`br space list`](#br-space-list)
-* [`br space switch`](#br-space-switch)
-* [`br status`](#br-status)
-
-## `br add`
-
-Add or update a bullet in the playbook (bypasses ACE workflow for direct agent usage)
-
-```txt
-USAGE
-  $ br add -c <value> -s <value> [-b <value>]
-
-FLAGS
-  -b, --bullet-id=<value>  Bullet ID to update (if not provided, a new bullet will be created)
-  -c, --content=<value>    (required) Content of the bullet
-  -s, --section=<value>    (required) Section name for the bullet
-
-DESCRIPTION
-  Add or update a bullet in the playbook (bypasses ACE workflow for direct agent usage)
-
-  This command allows agents to directly manipulate the playbook without going through
-  the full ACE workflow (executor → reflector → curator → apply-delta). Use this for
-  quick knowledge capture during development.
-
-  Before using this command, run 'br show' to view existing sections and bullet IDs.
-
-EXAMPLES
-  $ br add --section "Common Errors" --content "Always validate API responses"
-
-  $ br add --section "Common Errors" --bullet-id "common-00001" --content "Updated: Validate and sanitize API responses"
-
-  $ br add -s "Best Practices" -c "Use dependency injection for better testability"
-```
-
-## `br clear`
-
-Clear local ACE context (playbook) managed by ByteRover CLI
-
-```txt
-USAGE
-  $ br clear [DIRECTORY] [-y]
-
-ARGUMENTS
-  DIRECTORY  Project directory (defaults to current directory)
-
-FLAGS
-  -y, --yes  Skip confirmation prompt
-
-DESCRIPTION
-  Clear local ACE context (playbook) managed by ByteRover CLI
-
-EXAMPLES
-  $ br clear
-
-  $ br clear --yes
-
-  $ br clear /path/to/project
-```
-
-## `br complete`
-
-Complete ACE workflow: save executor output, generate reflection, and update playbook in one command
-
-```txt
-USAGE
-  $ br complete HINT REASONING FINALANSWER -t <value> -f <value> [-b <value>] [-u <value>]
-
-ARGUMENTS
-  HINT         Short hint for naming output files (e.g., "user-auth", "bug-fix")
-  REASONING    Detailed reasoning and approach for completing the task
-  FINALANSWER  The final answer/solution to the task
-
-FLAGS
-  -b, --bullet-ids=<value>    Comma-separated list of playbook bullet IDs referenced
-  -f, --feedback=<value>      (required) Environment feedback about task execution (e.g., "Tests passed", "Build failed")
-  -t, --tool-usage=<value>    (required) Comma-separated list of tool calls with arguments (format: "ToolName:argument", e.g., "Read:src/file.ts,Bash:npm test")
-  -u, --update-bullet=<value> Bullet ID to update with new knowledge (if not provided, adds new bullet)
-
-DESCRIPTION
-  Complete ACE workflow: save executor output, generate reflection, and update playbook in one command
-
-  This command executes the full ACE (Agentic Context Engineering) workflow in a single step:
-  1. Executor phase: Saves your task output with detailed context
-  2. Reflector phase: Analyzes results and generates reflection
-  3. Curator phase: Updates the playbook with new knowledge
-
-EXAMPLES
-  $ br complete "user-auth" "Implemented OAuth2 flow" "Auth works" --tool-usage "Read:src/auth.ts,Edit:src/auth.ts,Bash:npm test" --feedback "All tests passed"
-
-  $ br complete "validation-fix" "Analyzed validator" "Fixed bug" --tool-usage "Grep:pattern:\"validate\",Read:src/validator.ts" --bullet-ids "bullet-123" --feedback "Tests passed"
-
-  $ br complete "auth-update" "Improved error handling" "Better errors" --tool-usage "Edit:src/auth.ts" --feedback "Tests passed" --update-bullet "bullet-5"
-```
-
-## `br gen-rules`
-
-Generate rule instructions for coding agents to work with ByteRover correctly
-
-```txt
-USAGE
-  $ br gen-rules
-
-DESCRIPTION
-  Generate rule instructions for coding agents to work with ByteRover correctly
-
-  This command generates agent-specific rule files that provide instructions for coding agents
-  (like Claude Code, Cursor, Aider, etc.) to work correctly with ByteRover CLI and the ACE workflow.
-
-EXAMPLES
-  $ br gen-rules
-```
-
-## `br login`
-
-Authenticate with ByteRover
-
-```txt
-USAGE
-  $ br login
-
-DESCRIPTION
-  Authenticate with ByteRover
-```
-
-## `br help [COMMAND]`
-
-Display help for br.
-
-```txt
-USAGE
-  $ br help [COMMAND...] [-n]
-
-ARGUMENTS
-  COMMAND...  Command to show help for.
-
-FLAGS
-  -n, --nested-commands  Include all nested commands in the output.
-
-DESCRIPTION
-  Display help for br.
-```
-
-## `br init`
-
-Initialize a project with ByteRover
-
-```txt
-USAGE
-  $ br init
-
-DESCRIPTION
-  Initialize a project with ByteRover
-
-EXAMPLES
-  $ br init
-```
-
-## `br push`
-
-Push playbook to ByteRover memory storage and clean up local ACE files
-
-```txt
-USAGE
-  $ br push [-b <value>]
-
-FLAGS
-  -b, --branch=<value>  [default: main] ByteRover branch name (not Git branch)
-
-DESCRIPTION
-  Push playbook to ByteRover memory storage and clean up local ACE files
-
-  This command uploads your playbook to ByteRover's memory storage and automatically cleans up
-  local ACE files after successful upload. The cleanup includes:
-  - Clearing playbook content
-  - Removing executor outputs
-  - Removing reflections
-  - Removing deltas
-
-EXAMPLES
-  $ br push
-
-  $ br push --branch develop
-
-  $ br push -b feature-auth
-```
-
-## `br retrieve`
-
-Retrieve memories from ByteRover Memora service and output as JSON
-
-```txt
-USAGE
-  $ br retrieve -q <value> [-n <value>] [--compact]
-
-FLAGS
-  -n, --node-keys=<value>  Comma-separated list of node keys (file paths) to filter results
-  -q, --query=<value>      (required) Search query string
-  --compact                Output compact JSON (single line)
-
-DESCRIPTION
-  Retrieve memories from ByteRover Memora service and output as JSON
-
-  This command fetches memories from ByteRover's memory storage based on your query.
-  You can optionally filter results by specific file paths using the --node-keys flag.
-
-EXAMPLES
-  $ br retrieve --query "authentication best practices"
-
-  $ br retrieve -q "error handling" -n "src/auth/login.ts,src/auth/oauth.ts"
-
-  $ br retrieve -q "database connection issues" --compact
-```
-
-## `br status`
-
-Show CLI status and project information
-
-```txt
-USAGE
-  $ br status
-
-DESCRIPTION
-  Show CLI status and project information
-
-  Displays comprehensive information about your ByteRover CLI setup including:
-  - CLI version
-  - Authentication status (with user email if logged in)
-  - Current working directory
-  - Project initialization status (with connected space if initialized)
-
-EXAMPLES
-  $ br status
-```
-
-## `br space list`
-
-List all spaces for the current team (requires project initialization)
-
-```txt
-USAGE
-  $ br space list [-a] [-j] [-l <value>] [-o <value>]
-
-FLAGS
-  -a, --all             Fetch all spaces (may be slow for large teams)
-  -j, --json            Output in JSON format
-  -l, --limit=<value>   [default: 50] Maximum number of spaces to fetch
-  -o, --offset=<value>  [default: 0] Number of spaces to skip
-
-DESCRIPTION
-  List all spaces for the current team (requires project initialization)
-
-  This command lists all available spaces in the current team. By default, it shows 50 spaces.
-  Use --all to fetch all spaces or use --limit and --offset for manual pagination.
-
-EXAMPLES
-  $ br space list
-
-  $ br space list --all
-
-  $ br space list --limit 10
-
-  $ br space list --limit 10 --offset 20
-
-  $ br space list --json
-```
-
-## `br space switch`
-
-Switch to a different team or space (updates .br/config.json)
-
-```txt
-USAGE
-  $ br space switch
-
-DESCRIPTION
-  Switch to a different team or space (updates .br/config.json)
-
-  This command allows you to switch your project to a different team or space.
-  It shows your current configuration, then prompts you to select a new team and space.
-  The configuration is updated in .br/config.json.
-
-EXAMPLES
-  $ br space switch
-```
-
 ## Configuration
 
-### Environment Configuration
-
-ByteRover CLI supports runtime environment selection:
-
-* **Development Environment** (`./bin/dev.js`)
-  * Issuer URL: `https://dev-beta-iam.byterover.dev/api/v1/oidc`
-  * Client ID: `byterover-cli-client`
-  * Scopes: `read`, `write`, `debug`
-
-* **Production Environment** (`./bin/run.js`)
-  * Issuer URL: `https://prod-beta-iam.byterover.dev/api/v1/oidc`
-  * Client ID: `byterover-cli-prod`
-  * Scopes: `read`, `write`
-
-The environment is automatically set when you run the CLI:
-
-```bash
-# Development mode
-./bin/dev.js [command]
-
-# Production mode (installed globally)
-br [command]
-```
-
-### Environment Variables
-
-* **BR_ENV** - Runtime environment (`development` | `production`) - automatically set by launcher scripts
-
 ### Project Configuration
 
-When you run `br init`, a configuration file is created at `.byterover/config.json` in your project directory. This file contains:
-
-* **Space ID**: The ByteRover workspace/space associated with this project
-* **Project settings**: Project-specific configuration
-* **User's information**: User's ID and user's email.
-
-## Development
-
-### Clone and Setup
+When you run `br init`, a configuration file is created at `.br/config.json` in your project directory containing:
 
-```bash
-git clone https://github.com/campfirein/byterover-cli.git
-cd byterover-cli
-npm install
-```
-
-### Build
-
-```bash
-npm run build
-```
-
-Compiles TypeScript to JavaScript in the `dist/` directory.
+- **Space ID**: The ByteRover workspace/space associated with this project
+- **User information**: Your user ID and email
+- **Project settings**: Project-specific configuration
 
-### Test
+### ACE File Structure
 
-```bash
-# Run all tests
-npm test
-
-# Run a specific test file
-npx mocha --forbid-only "test/path/to/file.test.ts"
-```
-
-Tests use Mocha + Chai and are organized in `test/` with subdirectories:
+ACE stores all outputs in `.br/ace/`:
 
-* `test/commands/` - Command integration tests
-* `test/unit/` - Unit tests mirroring `src/` structure
-* `test/learning/` - Learning/exploration tests
-
-### Lint
-
-```bash
-npm run lint
 ```
-
-Runs ESLint with oclif and prettier configurations.
-
-### Run Locally
-
-```bash
-# Development mode (uses ts-node, points to dev environment)
-./bin/dev.js [command]
-
-# Production mode (uses compiled dist/, points to prod environment)
-./bin/run.js [command]
+.br/ace/
+├── playbook.json                # Your living knowledge base
+├── executor-outputs/            # Coding task outputs
+├── reflections/                 # Task analysis and feedback
+└── deltas/                      # Playbook updates
 ```
 
-### Create New Command
+**Note**: When you run `br push`, the playbook is uploaded to ByteRover's memory storage, and local ACE files are automatically cleaned up to keep your workspace organized.
 
-```bash
-npx oclif generate command
-```
+## Getting Help
 
-### Distribution
+### Command Help
 
 ```bash
-# Create development tarball
-npm run pack:dev
+# Get general help
+br help
 
-# Create production tarball
-npm run pack:prod
+# Get help for a specific command
+br help login
+br help init
+br help push
 ```
 
-## Architecture
-
-ByteRover CLI follows **Clean Architecture** principles with a clear separation of concerns:
-
-### Layers
-
-* **Core Layer** (`src/core/`) - Domain logic independent of frameworks
-  * `domain/entities/` - Business entities with validation and behavior
-  * `domain/errors/` - Domain-specific error types
-  * `interfaces/` - Port definitions (dependency inversion)
-
-* **Infrastructure Layer** (`src/infra/`) - Concrete implementations using external dependencies
-  * `auth/` - OAuth 2.0 + PKCE implementation
-  * `http/` - HTTP clients and callback servers
-  * `storage/` - Keychain token storage
-  * `space/` - Space/workspace service implementations
-
-* **Application Layer** (`src/commands/`) - oclif command definitions
-
-### Key Technologies
+### Support
 
-* **[oclif](https://oclif.io) v4** - CLI framework with plugin system
-* **TypeScript** - Strict mode, ES2022 target, Node16 modules
-* **axios** - HTTP client for OAuth and API operations
-* **express** - Local callback server for OAuth flows
-* **keytar** - Secure system keychain access
-* **Mocha + Chai** - Testing framework
+If you encounter issues or have questions:
 
-### Detailed Documentation
+1. Check the command help: `br help [command]`
+2. Review your status: `br status`
+3. Contact ByteRover support
 
-For comprehensive architecture documentation, design patterns, and development guidelines, see [CLAUDE.md](CLAUDE.md).
+---
 
-Copyright (c) ByteRover
+**Copyright (c) ByteRover**

package/dist/commands/add.d.ts

@@ -1,18 +1,11 @@
 import { Command } from '@oclif/core';
-import type { Bullet } from '../core/domain/entities/bullet.js';
 import type { IPlaybookService } from '../core/interfaces/i-playbook-service.js';
 import type { IPlaybookStore } from '../core/interfaces/i-playbook-store.js';
 import type { ITrackingService } from '../core/interfaces/i-tracking-service.js';
-type UserAction = 'add' | 'update';
 interface SectionPromptOptions {
     readonly existingSections: readonly string[];
     readonly suggestedSections: readonly string[];
 }
-interface ContentPromptContext {
-    readonly action: UserAction;
-    readonly existingContent?: string;
-    readonly section: string;
-}
 export default class Add extends Command {
     static description: string;
     static examples: string[];
@@ -28,24 +21,20 @@ export default class Add extends Command {
         trackingService: ITrackingService;
     };
     /**
-     * Prompt user to choose between adding a new bullet or updating an existing one
-     */
-    protected promptForAction(): Promise<UserAction>;
-    /**
-     * Prompt user to select a bullet to update
+     * Prompt user to confirm adding the bullet
      */
-    protected promptForBullet(bullets: Bullet[]): Promise<string>;
+    protected promptForConfirmation(bulletId: string, section: string, content: string): Promise<boolean>;
     /**
      * Prompt user to enter bullet content
      */
-    protected promptForContent(context: ContentPromptContext): Promise<string>;
+    protected promptForContent(section: string): Promise<string>;
     /**
      * Prompt user to select or create a section name
      */
     protected promptForSection(options: SectionPromptOptions): Promise<string>;
     run(): Promise<void>;
     /**
-     * Display success message after adding or updating a bullet
+     * Display success message after adding a bullet
      */
     private displaySuccess;
     /**

package/dist/commands/add.js

@@ -1,4 +1,4 @@
-import { input, search, select } from '@inquirer/prompts';
+import { confirm, input, search } from '@inquirer/prompts';
 import { Command, Flags } from '@oclif/core';
 import { Playbook } from '../core/domain/entities/playbook.js';
 import { FilePlaybookStore } from '../infra/ace/file-playbook-store.js';
@@ -54,55 +54,27 @@ export default class Add extends Command {
         };
     }
     /**
-     * Prompt user to choose between adding a new bullet or updating an existing one
+     * Prompt user to confirm adding the bullet
      */
-    async promptForAction() {
-        const action = await select({
-            choices: [
-                { name: 'Add a new bullet', value: 'add' },
-                { name: 'Update an existing bullet', value: 'update' },
-            ],
-            message: 'What would you like to do?',
+    async promptForConfirmation(bulletId, section, content) {
+        this.log('\nReview your bullet:');
+        this.log(`  ID: ${bulletId}`);
+        this.log(`  Section: ${section}`);
+        const contentDisplay = content.length > 200 ? `${content.slice(0, 200)}...` : content;
+        this.log(`  Content: ${contentDisplay}`);
+        this.log('\nTip: Use `br status` to view and update bullets later');
+        const confirmed = await confirm({
+            default: true,
+            message: 'Add this bullet?',
         });
-        return action;
-    }
-    /**
-     * Prompt user to select a bullet to update
-     */
-    async promptForBullet(bullets) {
-        const displayBullets = bullets.map((bullet) => ({
-            contentPreview: bullet.content.length > 60 ? `${bullet.content.slice(0, 60)}...` : bullet.content,
-            id: bullet.id,
-            section: bullet.section,
-            tags: bullet.metadata.tags,
-            timestamp: new Date(bullet.metadata.timestamp).toLocaleDateString(),
-        }));
-        const bulletId = await search({
-            message: 'Select a bullet to update:',
-            async source(input) {
-                const filtered = input
-                    ? displayBullets.filter((b) => b.section.toLowerCase().includes(input.toLowerCase()) ||
-                        b.contentPreview.toLowerCase().includes(input.toLowerCase()) ||
-                        b.id.toLowerCase().includes(input.toLowerCase()))
-                    : displayBullets;
-                return filtered.map((b) => ({
-                    description: `Tags: ${b.tags.join(', ')} | Date: ${b.timestamp}`,
-                    name: `[${b.id}] ${b.section}: ${b.contentPreview}`,
-                    value: b.id,
-                }));
-            },
-        });
-        return bulletId;
+        return confirmed;
     }
     /**
      * Prompt user to enter bullet content
      */
-    async promptForContent(context) {
-        const message = context.action === 'update'
-            ? `Enter new content for bullet in "${context.section}":`
-            : `Enter content for new bullet in "${context.section}":`;
+    async promptForContent(section) {
+        const message = `Enter content for new bullet in "${section}":`;
         const content = await input({
-            default: context.existingContent,
             message,
             validate(value) {
                 if (!validateContent(value)) {
@@ -139,11 +111,10 @@ export default class Add extends Command {
         return flags.interactive ? this.runInteractive() : this.runFlagBased(flags);
     }
     /**
-     * Display success message after adding or updating a bullet
+     * Display success message after adding a bullet
      */
-    displaySuccess(bullet, action) {
-        const actionText = action === 'update' ? 'Updated' : 'Added';
-        this.log(`\n✓ ${actionText} bullet successfully!`);
+    displaySuccess(bullet) {
+        this.log(`\n✓ Added bullet successfully!`);
         this.log(`  ID: ${bullet.id}`);
         this.log(`  Section: ${bullet.section}`);
         this.log(`  Content: ${bullet.content}`);
@@ -173,7 +144,7 @@ export default class Add extends Command {
                 content: flags.content,
                 section: flags.section,
             });
-            this.displaySuccess(bullet, flags['bullet-id'] ? 'update' : 'add');
+            this.displaySuccess(bullet);
         }
         catch (error) {
             this.error(error instanceof Error ? error.message : 'Unexpected error occurred');
@@ -185,43 +156,34 @@ export default class Add extends Command {
     async runInteractive() {
         const { playbookService, playbookStore, trackingService } = this.createServices();
         try {
+            // Display welcome message
+            this.log('Press Ctrl+C at any time to cancel the process\n');
             // Load existing playbook or create new one
             let playbook = await playbookStore.load();
             if (!playbook) {
                 playbook = new Playbook();
             }
-            const action = await this.promptForAction();
             const sectionOptions = {
                 existingSections: playbook.getSections(),
                 suggestedSections: SUGGESTED_SECTIONS,
             };
             const section = await this.promptForSection(sectionOptions);
-            let bulletId;
-            let existingContent;
-            if (action === 'update') {
-                const bullets = playbook.getBullets();
-                if (bullets.length === 0) {
-                    this.warn('No bullets available to update. Creating new bullet instead.');
-                }
-                else {
-                    bulletId = await this.promptForBullet(bullets);
-                    const bullet = playbook.getBullet(bulletId);
-                    existingContent = bullet?.content;
-                }
+            const content = await this.promptForContent(section);
+            // Get next bullet ID for confirmation
+            const nextId = playbook.getNextId();
+            // Prompt for confirmation
+            const confirmed = await this.promptForConfirmation(nextId, section, content);
+            if (!confirmed) {
+                this.log('\nBullet not added. Operation cancelled.');
+                return;
             }
-            const contentContext = {
-                action: bulletId ? 'update' : 'add',
-                existingContent,
-                section,
-            };
-            const content = await this.promptForContent(contentContext);
             const bullet = await playbookService.addOrUpdateBullet({
-                bulletId,
+                bulletId: undefined,
                 content,
                 section,
             });
             await trackingService.track('ace:add_bullet');
-            this.displaySuccess(bullet, bulletId ? 'update' : 'add');
+            this.displaySuccess(bullet);
         }
         catch (error) {
             this.error(error instanceof Error ? error.message : 'Unexpected error occurred');

package/dist/commands/push.d.ts

@@ -13,9 +13,11 @@ export default class Push extends Command {
     static examples: string[];
     static flags: {
         branch: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     protected checkProjectInit(projectConfigStore: IProjectConfigStore): Promise<BrConfig>;
     protected cleanUpLocalFiles(playbookStore: IPlaybookStore): Promise<void>;
+    protected confirmPush(projectConfig: BrConfig, branch: string, fileCount: number): Promise<boolean>;
     protected confirmUpload(memoryService: IMemoryStorageService, token: AuthToken, projectConfig: BrConfig, requestId: string): Promise<void>;
     protected createServices(): {
         memoryService: IMemoryStorageService;

package/dist/commands/push.js

@@ -1,3 +1,4 @@
+import { confirm } from '@inquirer/prompts';
 import { Command, Flags, ux } from '@oclif/core';
 import { join } from 'node:path';
 import { getCurrentConfig } from '../config/environment.js';
@@ -22,6 +23,11 @@ export default class Push extends Command {
             default: DEFAULT_BRANCH,
             description: 'ByteRover branch name (not Git branch)',
         }),
+        yes: Flags.boolean({
+            char: 'y',
+            default: false,
+            description: 'Skip confirmation prompt',
+        }),
     };
     async checkProjectInit(projectConfigStore) {
         const projectConfig = await projectConfigStore.read();
@@ -32,8 +38,8 @@ export default class Push extends Command {
     }
     async cleanUpLocalFiles(playbookStore) {
         this.log('\nCleaning up local files...');
-        // Clear playbook content
-        ux.action.start('  Clearing playbook');
+        // Clear playbook content and bullet files
+        ux.action.start('  Clearing playbook and bullet files');
         await playbookStore.clear();
         ux.action.stop('✓');
         // Clean executor outputs
@@ -54,6 +60,22 @@ export default class Push extends Command {
         const deltaCount = await clearDirectory(deltasDir);
         ux.action.stop(`✓ (${deltaCount} files removed)`);
     }
+    async confirmPush(projectConfig, branch, fileCount) {
+        this.log('\nYou are about to push to ByteRover memory storage:');
+        this.log(`  Space: ${projectConfig.spaceName}`);
+        this.log(`  Branch: ${branch}`);
+        this.log(`  Files to upload: ${fileCount}`);
+        this.log('\nAfter successful push, these local files will be cleaned up:');
+        this.log('  - Playbook content');
+        this.log('  - Bullet files (.br/ace/bullets/)');
+        this.log('  - Executor outputs (.br/ace/executor-outputs/)');
+        this.log('  - Reflections (.br/ace/reflections/)');
+        this.log('  - Deltas (.br/ace/deltas/)');
+        return confirm({
+            default: false,
+            message: 'Push to ByteRover and clean up local files?',
+        });
+    }
     async confirmUpload(memoryService, token, projectConfig, requestId) {
         ux.action.start('Confirming upload');
         await memoryService.confirmUpload({
@@ -111,6 +133,14 @@ export default class Push extends Command {
             const token = await this.validateAuth(tokenStore);
             const projectConfig = await this.checkProjectInit(projectConfigStore);
             await this.verifyPlaybookExists(playbookStore);
+            // Prompt for confirmation unless --yes flag is provided
+            if (!flags.yes) {
+                const confirmed = await this.confirmPush(projectConfig, flags.branch, 1);
+                if (!confirmed) {
+                    this.log('Push cancelled. No files were uploaded or cleaned.');
+                    return;
+                }
+            }
             const response = await this.getPresignedUrls(memoryService, token, projectConfig);
             const playbookContent = await this.loadPlaybookContent(playbookStore);
             await this.uploadFiles(memoryService, response.presignedUrls, playbookContent);

package/dist/commands/status.js

@@ -106,8 +106,7 @@ export default class Status extends Command {
                     this.log(`  ${chalk.red(relativePath)}`);
                 }
             }
-            // Guide user to push memory to cloud
-            this.log(`Use "br push" to push memory to cloud.`);
+            this.log(`\nUse "br push" to push playbook to ByteRover memory storage.`);
         }
         catch (error) {
             this.error(error instanceof Error ? error.message : 'Failed to load playbook statistics');

package/dist/config/environment.js

@@ -21,15 +21,15 @@ export const ENV_CONFIG = {
         tokenUrl: 'https://dev-beta-iam.byterover.dev/api/v1/oidc/token',
     },
     production: {
-        apiBaseUrl: 'https://prod-beta-iam.byterover.dev/api/v1',
-        authorizationUrl: 'https://prod-beta-iam.byterover.dev/api/v1/oidc/authorize',
-        clientId: 'byterover-cli-prod',
-        cogitApiBaseUrl: 'https://prod-beta-cogit.byterover.dev/api/v1',
-        issuerUrl: 'https://prod-beta-iam.byterover.dev/api/v1/oidc',
-        memoraApiBaseUrl: 'https://prod-beta-memora-retrieve.byterover.dev/api/v3',
-        mixpanelToken: 'fac9051df8242c885a9e0eaf60f78b10',
+        apiBaseUrl: 'https://beta-iam.byterover.dev/api/v1',
+        authorizationUrl: 'https://beta-iam.byterover.dev/api/v1/oidc/authorize',
+        clientId: 'byterover-cli',
+        cogitApiBaseUrl: 'https://beta-cogit.byterover.dev/api/v1',
+        issuerUrl: 'https://beta-iam.byterover.dev/api/v1/oidc',
+        memoraApiBaseUrl: 'https://beta-memora-retrieve.byterover.dev/api/v3',
+        mixpanelToken: '4d1198b346d2d6ac75f2e77905cc65ac',
         scopes: ['read', 'write'],
-        tokenUrl: 'https://prod-beta-iam.byterover.dev/api/v1/oidc/token',
+        tokenUrl: 'https://beta-iam.byterover.dev/api/v1/oidc/token',
     },
 };
 /**

package/dist/core/domain/entities/playbook.d.ts

@@ -68,6 +68,10 @@ export declare class Playbook {
      * Returns bullets in a specific section
      */
     getBulletsInSection(section: string): Bullet[];
+    /**
+     * Returns the next bullet ID that will be generated
+     */
+    getNextId(): string;
     /**
      * Returns all section names
      */

package/dist/core/domain/entities/playbook.js

@@ -149,6 +149,13 @@ export class Playbook {
         const bulletIds = this.sections.get(section) ?? [];
         return bulletIds.map((id) => this.bullets.get(id)).filter((b) => b !== undefined);
     }
+    /**
+     * Returns the next bullet ID that will be generated
+     */
+    getNextId() {
+        // Use "temp" as prefix since we don't know the section yet
+        return String(this.nextId).padStart(5, '0');
+    }
     /**
      * Returns all section names
      */

package/oclif.manifest.json

@@ -269,6 +269,13 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "yes": {
+          "char": "y",
+          "description": "Skip confirmation prompt",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -472,5 +479,5 @@
       ]
     }
   },
-  "version": "0.1.0"
+  "version": "0.1.1"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "byterover-cli",
   "description": "ByteRover's CLI",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "author": "ByteRover",
   "bin": {
     "br": "./bin/run.js"
@@ -51,7 +51,7 @@
   "keywords": [
     "oclif"
   ],
-  "license": "MIT",
+  "license": "UNLICENSED",
   "main": "dist/index.js",
   "type": "module",
   "oclif": {