From 42d94876d843a54be21fff04f4414dac2a4907ab Mon Sep 17 00:00:00 2001
From: m3tm3re <p@m3ta.dev>
Date: Tue, 13 Jan 2026 21:09:02 +0100
Subject: [PATCH] docs: add documentation for beads, n8n, opencode packages

- Update AGENTS.md header with current commit (366af12) and date (2026-01-13)
- Add beads, n8n, opencode to README.md Available Packages table
- Update docs/README.md packages list
- Create docs/packages/beads.md (220 lines)
- Create docs/packages/n8n.md (310 lines)
- Create docs/packages/opencode.md (346 lines)

Documentation now reflects commit bc75505 which added these three packages.
---
 AGENTS.md                 |   4 +-
 README.md                 |   3 +
 docs/README.md            |   3 +
 docs/packages/beads.md    | 220 ++++++++++++++++++++++++
 docs/packages/n8n.md      | 310 ++++++++++++++++++++++++++++++++++
 docs/packages/opencode.md | 346 ++++++++++++++++++++++++++++++++++++++
 6 files changed, 884 insertions(+), 2 deletions(-)
 create mode 100644 docs/packages/beads.md
 create mode 100644 docs/packages/n8n.md
 create mode 100644 docs/packages/opencode.md

diff --git a/AGENTS.md b/AGENTS.md
index 84ddb0b..76a59e4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,7 +1,7 @@
 # m3ta-nixpkgs Knowledge Base
 
-**Generated:** 2025-12-30
-**Commit:** c5e1610
+**Generated:** 2026-01-13
+**Commit:** 366af12
 **Branch:** master
 
 ## OVERVIEW
diff --git a/README.md b/README.md
index 3b1d590..9acc0ed 100644
--- a/README.md
+++ b/README.md
@@ -40,11 +40,14 @@ nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#zellij-ps
 
 | Package            | Description                           |
 | ------------------ | ------------------------------------- |
+| `beads`            | Lightweight memory system for AI coding agents with graph-based issue tracking |
 | `code2prompt`      | Convert code to prompts               |
 | `hyprpaper-random` | Random wallpaper setter for Hyprpaper |
 | `launch-webapp`    | Launch web applications               |
 | `mem0`             | AI memory assistant with vector storage |
 | `msty-studio`      | Msty Studio application               |
+| `n8n`              | Free and source-available fair-code licensed workflow automation tool |
+| `opencode`         | AI coding agent built for the terminal |
 | `pomodoro-timer`   | Pomodoro timer utility                |
 | `rofi-project-opener` | Rofi-based project launcher        |
 | `stt-ptt`          | Push to Talk Speech to Text           |
diff --git a/docs/README.md b/docs/README.md
index b90379c..c4bdeab 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -28,11 +28,14 @@ Step-by-step guides for common tasks:
 
 Documentation for all custom packages:
 
+- [beads](./packages/beads.md) - Lightweight memory system for AI coding agents with graph-based issue tracking
 - [code2prompt](./packages/code2prompt.md) - Convert code to prompts
 - [hyprpaper-random](./packages/hyprpaper-random.md) - Random wallpaper setter for Hyprpaper
 - [launch-webapp](./packages/launch-webapp.md) - Launch web applications
 - [mem0](./packages/mem0.md) - AI memory assistant with vector storage
 - [msty-studio](./packages/msty-studio.md) - Msty Studio application
+- [n8n](./packages/n8n.md) - Free and source-available fair-code licensed workflow automation tool
+- [opencode](./packages/opencode.md) - AI coding agent built for terminal
 - [pomodoro-timer](./packages/pomodoro-timer.md) - Pomodoro timer utility
 - [rofi-project-opener](./packages/rofi-project-opener.md) - Rofi-based project launcher with custom args
 - [stt-ptt](./packages/stt-ptt.md) - Push to Talk Speech to Text using Whisper
diff --git a/docs/packages/beads.md b/docs/packages/beads.md
new file mode 100644
index 0000000..24e169b
--- /dev/null
+++ b/docs/packages/beads.md
@@ -0,0 +1,220 @@
+# beads
+
+Lightweight memory system for AI coding agents with graph-based issue tracking.
+
+## Description
+
+beads is a command-line tool designed to provide persistent memory and issue tracking for AI coding agents. It features a graph-based system for managing issues, dependencies, and discovered work across development sessions.
+
+## Features
+
+- 🧠 **Persistent Memory**: Store and retrieve context across AI sessions
+- 📊 **Graph-Based Issue Tracking**: Manage issues with dependency relationships
+- 🔄 **Discovered Work**: Track work discovered during development
+- 🎯 **Multi-Session Continuity**: Resume work from previous sessions
+- 📝 **Git Integration**: Seamless integration with git workflows
+- 🐚 **Shell Completions**: Bash, Fish, and Zsh completions included
+
+## Installation
+
+### Via Overlay
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    beads
+  ];
+}
+```
+
+### Direct Reference
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    inputs.m3ta-nixpkgs.packages.${pkgs.system}.beads
+  ];
+}
+```
+
+### Run Directly
+
+```bash
+nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#beads
+```
+
+## Usage
+
+### Basic Commands
+
+```bash
+# Show available issues ready to work on
+bd ready
+
+# Create a new issue
+bd create "Fix authentication bug" --type bug --priority 2
+
+# Show issue details
+bd show beads-123
+
+# Update issue status
+bd update beads-123 --status in_progress
+
+# Close completed issues
+bd close beads-123
+
+# Sync with git remote
+bd sync
+```
+
+### Issue Types
+
+- `task`: General tasks
+- `bug`: Bug fixes
+- `feature`: New features
+- `epic`: Large-scale initiatives
+
+### Priority Levels
+
+- `0` (P0): Critical
+- `1` (P1): High
+- `2` (P2): Medium
+- `3` (P3): Low
+- `4` (P4): Backlog
+
+### Dependency Management
+
+```bash
+# Add dependency (beads-123 depends on beads-456)
+bd dep add beads-123 beads-456
+
+# Show blocked issues
+bd blocked
+
+# Show what blocks an issue
+bd show beads-123 --blocked-by
+```
+
+## Advanced Usage
+
+### Finding Work
+
+```bash
+# Show ready tasks (no blockers)
+bd ready
+
+# Show all open issues
+bd list --status open
+
+# Show in-progress work
+bd list --status in_progress
+```
+
+### Assignment
+
+```bash
+# Assign issue to yourself
+bd update beads-123 --assignee username
+
+# Create assigned issue
+bd create "Review PR" --assignee reviewer
+```
+
+### Bulk Operations
+
+```bash
+# Close multiple issues at once
+bd close beads-123 beads-456 beads-789
+
+# Close with reason
+bd close beads-123 --reason "Completed in v1.2.0"
+```
+
+### Hooks
+
+```bash
+# Install git hooks for automatic sync
+bd hooks install
+
+# Remove hooks
+bd hooks uninstall
+```
+
+## Configuration
+
+### Environment Variables
+
+- `BEADS_DATA_DIR`: Custom directory for beads data (default: `.beads/`)
+- `BEADS_CONFIG`: Custom configuration file path
+- `BEADS_EDITOR`: Default editor for editing issues
+
+### Git Integration
+
+beads integrates with git for version-controlled issue tracking:
+
+- Automatic sync before commits (via hooks)
+- Issue references in commit messages
+- Branch name tracking
+- Git-aware issue states
+
+## Workflow Integration
+
+### Typical Development Workflow
+
+1. **Start session**: `bd prime` or check `bd ready`
+2. **Claim work**: `bd update beads-123 --status in_progress`
+3. **Work on task**: Implement changes
+4. **Discover new work**: `bd create "Discovered subtask"` as needed
+5. **Complete task**: `bd close beads-123`
+6. **Sync**: `bd sync` (automatic via hooks)
+
+### Team Collaboration
+
+```bash
+# Create issue and assign
+bd create "Implement feature X" --assignee dev1
+
+# Review assigned work
+bd list --assignee yourname
+
+# Close with review notes
+bd close beads-123 --reason "Reviewed and approved"
+```
+
+## Shell Completions
+
+beads provides shell completions for bash, fish, and zsh:
+
+```bash
+# Bash completions are auto-loaded
+source <(bd completion bash)
+
+# Fish completions
+bd completion fish | source
+
+# Zsh completions
+bd completion zsh > ~/.zfunc/_bd
+```
+
+## Build Information
+
+- **Version**: 0.47.1
+- **Language**: Go
+- **License**: MIT
+- **Source**: [GitHub](https://github.com/steveyegge/beads)
+
+## Platform Support
+
+- Linux
+- macOS
+
+## Notes
+
+- Tests are disabled in the Nix package due to git worktree operations that fail in the sandbox
+- Security tests on Darwin are skipped due to `/etc/passwd` unavailability in sandbox
+- Shell completions are installed for platforms that can execute the build target
+
+## Related
+
+- [Adding Packages](../guides/adding-packages.md) - How to add new packages
+- [Quick Start](../QUICKSTART.md) - Getting started guide
diff --git a/docs/packages/n8n.md b/docs/packages/n8n.md
new file mode 100644
index 0000000..d762302
--- /dev/null
+++ b/docs/packages/n8n.md
@@ -0,0 +1,310 @@
+# n8n
+
+Free and source-available fair-code licensed workflow automation tool. Easily automate tasks across different services.
+
+## Description
+
+n8n (pronounced "n-eight-n") is a workflow automation tool that helps you connect different services and automate tasks without writing code. It features a visual node-based editor for creating workflows with hundreds of integrations.
+
+## Features
+
+- 🎨 **Visual Workflow Editor**: Drag-and-drop interface for creating workflows
+- 🔗 **Hundreds of Integrations**: Connect to popular services (Slack, GitHub, Google, etc.)
+- 🔄 **Webhook Support**: Trigger workflows via HTTP requests
+- 📝 **Code Node**: Execute JavaScript/TypeScript code within workflows
+- 🚀 **Cloud & Self-Hosted**: Use n8n Cloud or self-host on your own infrastructure
+- 📊 **Data Transformation**: Map and transform data between services
+- ⏰ **Scheduling**: Run workflows on schedules (cron-like)
+- 🔒 **Security**: Credential management and secure data handling
+- 🎯 **Fair-Code License**: Source available with usage restrictions for commercial use
+
+## Installation
+
+### Via Overlay
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    n8n
+  ];
+}
+```
+
+### Direct Reference
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    inputs.m3ta-nixpkgs.packages.${pkgs.system}.n8n
+  ];
+}
+```
+
+### Run Directly
+
+```bash
+nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#n8n
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Start n8n (default configuration)
+n8n start
+
+# Start with custom configuration file
+n8n start --config /path/to/config
+
+# Run in worker mode (for production with queue)
+n8n worker
+
+# Execute a workflow from file
+n8n execute /path/to/workflow.json
+```
+
+### Development Mode
+
+```bash
+# Start with tunnel (external access)
+n8n start --tunnel
+
+# Disable telemetry
+n8n start --no-telemetry
+
+# Specify workflow directory
+n8n start --workflows /path/to/workflows
+
+# Enable/disable features
+n8n start --enable-editor
+n8n start --disable-metrics
+```
+
+### Workflow Management
+
+```bash
+# Export workflow to file
+n8n export:workflow --id=123 --output=workflow.json
+
+# Import workflow from file
+n8n import:workflow --input=workflow.json
+
+# Execute workflow
+n8n execute:workflow --id=123
+```
+
+## Configuration
+
+### Environment Variables
+
+- `N8N_BASIC_AUTH_ACTIVE`: Enable basic authentication (default: false)
+- `N8N_BASIC_AUTH_USER`: Basic auth username
+- `N8N_BASIC_AUTH_PASSWORD`: Basic auth password
+- `N8N_ENCRYPTION_KEY`: Encryption key for credentials
+- `N8N_HOST`: Host URL for web UI (default: localhost)
+- `N8N_PORT`: Port for web UI (default: 5678)
+- `N8N_PROTOCOL`: Protocol (http or https)
+- `N8N_PATH`: Path to mount n8n (default: /)
+- `N8N_EDITOR_BASE_URL`: Base URL for editor
+- `N8N_WEBHOOK_URL`: URL for webhook endpoints
+- `N8N_TIMEZONE`: Timezone for execution (default: UTC)
+- `N8N_LOG_LEVEL`: Logging level (output, warn, error, verbose)
+- `N8N_LOG_OUTPUT`: Log output destination (console, file)
+- `N8N_METRICS`: Enable metrics collection (default: true)
+- `DB_TYPE`: Database type (sqlite3db, postgresdb, mysqldb)
+- `DB_SQLITE_VACUUM_ON_STARTUP`: Vacuum SQLite on startup
+
+### Database Configuration
+
+By default, n8n uses SQLite for simplicity. For production, use PostgreSQL or MySQL:
+
+```bash
+# PostgreSQL
+export DB_TYPE=postgresdb
+export DB_POSTGRESDB_HOST=localhost
+export DB_POSTGRESDB_PORT=5432
+export DB_POSTGRESDB_DATABASE=n8n
+export DB_POSTGRESDB_USER=n8n
+export DB_POSTGRESDB_PASSWORD=yourpassword
+
+# MySQL/MariaDB
+export DB_TYPE=mysqldb
+export DB_MYSQLDB_HOST=localhost
+export DB_MYSQLDB_PORT=3306
+export DB_MYSQLDB_DATABASE=n8n
+export DB_MYSQLDB_USER=n8n
+export DB_MYSQLDB_PASSWORD=yourpassword
+```
+
+### Security
+
+Set up encryption for credentials:
+
+```bash
+# Generate encryption key
+export N8N_ENCRYPTION_KEY=$(openssl rand -base64 32)
+
+# Use in production
+export N8N_ENCRYPTION_KEY="your-32-char-encryption-key"
+```
+
+## NixOS Module
+
+For NixOS, use the n8n module from nixpkgs for a complete service configuration:
+
+```nix
+services.n8n = {
+  enable = true;
+  settings = {
+    host = "0.0.0.0";
+    port = 5678;
+    timezone = "UTC";
+  };
+  environment = {
+    N8N_ENCRYPTION_KEY = "your-encryption-key";
+    DB_TYPE = "postgresdb";
+    DB_POSTGRESDB_HOST = "/var/run/postgresql";
+    DB_POSTGRESDB_DATABASE = "n8n";
+  };
+};
+```
+
+## Use Cases
+
+### Webhook Automation
+
+Trigger workflows via HTTP requests:
+
+```bash
+# Start n8n with tunnel for public URL
+n8n start --tunnel
+
+# Create webhook workflow in UI
+# Workflow receives data from external service
+# Process and send to another service
+```
+
+### Scheduled Tasks
+
+Run tasks on a schedule:
+
+```javascript
+// In workflow editor, use Schedule Trigger
+// Set cron expression: "0 9 * * *" (daily at 9 AM)
+// Connect to nodes that perform tasks
+```
+
+### Data Sync Between Services
+
+Keep data synchronized:
+
+```bash
+# Create workflow with:
+# 1. Webhook trigger (service A)
+# 2. Data transformation node
+# 3. HTTP request node (service B)
+# 4. Response back to service A
+```
+
+### Automated Reporting
+
+Generate and send reports:
+
+```javascript
+// Workflow steps:
+// 1. Schedule trigger (daily/weekly)
+// 2. Database query node
+// 3. Data formatting
+// 4. Email or Slack notification
+```
+
+## Integration Examples
+
+### Slack Integration
+
+```javascript
+// Create Slack notification workflow
+// 1. Trigger (webhook or schedule)
+// 2. Process data
+// 3. Send message to Slack channel
+```
+
+### GitHub Integration
+
+```javascript
+// GitHub repository automation
+// 1. GitHub webhook trigger (push, PR, issue)
+// 2. Conditional logic
+// 3. Actions (create issue, comment, etc.)
+```
+
+### Email Automation
+
+```javascript
+// Email processing workflow
+// 1. Email trigger (IMAP)
+// 2. Parse email content
+// 3. Process data
+// 4. Send response or forward
+```
+
+## Performance Optimization
+
+### Production Tips
+
+- Use PostgreSQL or MySQL instead of SQLite
+- Enable queue mode with Redis
+- Use worker nodes for scaling
+- Configure proper resource limits
+- Set up load balancing for web UI
+
+### Queue Mode
+
+```bash
+# Start main n8n process
+export QUEUE_BULL_REDIS_HOST=redis-server
+export QUEUE_BULL_REDIS_PORT=6379
+n8n start
+
+# Start worker processes
+n8n worker
+```
+
+## Build Information
+
+- **Version**: 2.4.1
+- **Language**: TypeScript/JavaScript (Node.js)
+- **Package Manager**: pnpm
+- **License**: Sustainable Use (Fair-Code)
+- **Source**: [GitHub](https://github.com/n8n-io/n8n)
+
+## Dependencies
+
+- `nodejs` - JavaScript runtime
+- `pnpm` - Package manager (build-time)
+- `python3` - Required for SQLite bindings
+- `node-gyp` - Node.js native addon build tool
+- `libkrb5` - Kerberos authentication
+- `libmongocrypt` - MongoDB encryption
+- `libpq` - PostgreSQL client library
+
+## Platform Support
+
+- Linux
+- macOS
+
+## Notes
+
+- Package has ~80,000 files, so stripping and ELF patching are disabled for performance
+- SQLite3 bindings are rebuilt during build phase
+- TypeScript files and source maps are removed in preInstall phase
+- Non-deterministic files (.turbo, .modules.yaml, types) are removed
+- Node modules are pruned to production dependencies only
+
+## Related
+
+- [Adding Packages](../guides/adding-packages.md) - How to add new packages
+- [Quick Start](../QUICKSTART.md) - Getting started guide
+- [n8n Documentation](https://docs.n8n.io) - Official documentation
+- [n8n Community](https://community.n8n.io) - Community forum
diff --git a/docs/packages/opencode.md b/docs/packages/opencode.md
new file mode 100644
index 0000000..5ad3ab5
--- /dev/null
+++ b/docs/packages/opencode.md
@@ -0,0 +1,346 @@
+# opencode
+
+AI coding agent built for the terminal that can build anything. Combines a TypeScript/JavaScript core with a Go-based TUI for an interactive AI coding experience.
+
+## Description
+
+OpenCode is a terminal-based AI coding agent designed for power users. It provides a comprehensive development environment with AI assistance, code generation, refactoring, and project management capabilities. The tool features a sophisticated TUI (Terminal User Interface) built with Go, while the core functionality is implemented in TypeScript/JavaScript.
+
+## Features
+
+- 🤖 **AI-Powered Coding**: Generate, refactor, and optimize code with AI assistance
+- 🖥️ **Modern TUI**: Beautiful terminal interface built with Go
+- 🔍 **Code Understanding**: Parse and understand existing codebases
+- 🌳 **Tree-Sitter Integration**: Accurate syntax highlighting and code structure analysis
+- 📁 **Project Management**: Navigate and manage projects efficiently
+- 🧠 **Multi-LLM Support**: Works with various language models (OpenAI, Anthropic, etc.)
+- 📝 **Code Generation**: Create new files and features from natural language
+- 🔄 **Refactoring**: Intelligent code refactoring with AI
+- 🐛 **Bug Detection**: Find and fix bugs automatically
+- 📚 **Context Awareness**: Maintains context across editing sessions
+- 🎯 **Task Orchestration**: Break down and execute complex tasks
+- 💾 **Local Development**: Runs entirely on your machine
+
+## Installation
+
+### Via Overlay
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    opencode
+  ];
+}
+```
+
+### Direct Reference
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    inputs.m3ta-nixpkgs.packages.${pkgs.system}.opencode
+  ];
+}
+```
+
+### Run Directly
+
+```bash
+nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#opencode
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Start OpenCode in current directory
+opencode
+
+# Open specific project
+opencode /path/to/project
+
+# Start with specific task description
+opencode "Fix the login bug"
+
+# Show help
+opencode --help
+
+# Show version
+opencode --version
+```
+
+### Interactive Commands
+
+OpenCode provides an interactive TUI with various commands:
+
+- **Navigation**: Arrow keys to move, Enter to select
+- **Search**: `/` to search files, `?` for help
+- **Edit**: `e` to edit selected file
+- **Command Palette**: `Ctrl+p` to access commands
+- **AI Chat**: `Ctrl+c` to open AI chat
+- **Exit**: `q` or `Ctrl+d` to quit
+
+### AI Chat Mode
+
+```bash
+# Start OpenCode
+opencode
+
+# Enter AI chat mode (Ctrl+c)
+# Ask questions, request code changes, etc.
+# Examples:
+# - "Generate a REST API endpoint for user management"
+# - "Refactor this function to use async/await"
+# - "Find and fix potential memory leaks"
+# - "Add unit tests for this module"
+```
+
+### Task Management
+
+```bash
+# Ask OpenCode to work on a specific task
+opencode "Implement authentication with JWT tokens"
+
+# The agent will:
+# 1. Understand the codebase
+# 2. Plan the implementation
+# 3. Generate necessary code
+# 4. Make the changes
+# 5. Verify the implementation
+```
+
+## Configuration
+
+### Environment Variables
+
+- `OPENCODE_API_KEY`: API key for LLM provider
+- `OPENCODE_MODEL`: Default model to use (e.g., gpt-4, claude-3-opus)
+- `OPENCODE_PROVIDER`: LLM provider (openai, anthropic, etc.)
+- `OPENCODE_MAX_TOKENS`: Maximum tokens for responses
+- `OPENCODE_TEMPERATURE`: Sampling temperature (0-1)
+- `OPENCODE_CONFIG`: Path to configuration file
+
+### Configuration File
+
+Create `~/.opencode/config.json`:
+
+```json
+{
+  "model": "gpt-4",
+  "provider": "openai",
+  "maxTokens": 4096,
+  "temperature": 0.7,
+  "systemPrompt": "You are a helpful coding assistant"
+}
+```
+
+### Project-Specific Config
+
+Create `.opencode.json` in your project:
+
+```json
+{
+  "include": ["src/**/*.ts", "tests/**/*.ts"],
+  "exclude": ["node_modules", "dist", "*.test.ts"],
+  "systemPrompt": "You are a TypeScript expert"
+}
+```
+
+## Advanced Usage
+
+### Code Refactoring
+
+```bash
+# Ask for refactoring suggestions
+opencode "Review and refactor src/utils.ts for better performance"
+
+# Apply refactoring automatically
+opencode "Optimize the database queries in src/db/*.ts"
+```
+
+### Bug Fixing
+
+```bash
+# Describe the bug
+opencode "Fix the race condition in the payment processing module"
+
+# OpenCode will:
+# 1. Analyze the code
+# 2. Identify the issue
+# 3. Propose and implement fixes
+# 4. Verify the solution
+```
+
+### Feature Implementation
+
+```bash
+# Request new features
+opencode "Add support for OAuth2 authentication"
+
+# Be specific about requirements
+opencode "Create a REST API with these endpoints: GET /users, POST /users, PUT /users/:id, DELETE /users/:id"
+```
+
+### Code Review
+
+```bash
+# Get code review
+opencode "Review src/api/*.ts for security vulnerabilities"
+
+# Check for best practices
+opencode "Review the entire codebase and suggest improvements following SOLID principles"
+```
+
+### Documentation Generation
+
+```bash
+# Generate documentation
+opencode "Add JSDoc comments to all functions in src/utils.ts"
+
+# Create README
+opencode "Generate a comprehensive README.md for this project"
+```
+
+## Integration with Editors
+
+### VS Code
+
+OpenCode can work alongside your editor:
+
+```bash
+# Keep VS Code running for editing
+code .
+
+# Use OpenCode for AI assistance in another terminal
+opencode
+
+# Switch between them as needed
+```
+
+### Vim/Neovim
+
+```bash
+# Use Vim/Neovim as your editor
+vim src/main.ts
+
+# Use OpenCode for complex tasks
+opencode "Refactor the authentication module"
+```
+
+## Use Cases
+
+### Learning New Codebases
+
+```bash
+# OpenCode will:
+# 1. Analyze the code structure
+# 2. Explain how components work
+# 3. Answer questions about the code
+opencode "Explain how this project handles user authentication"
+```
+
+### Porting Code
+
+```bash
+# Port from one language to another
+opencode "Port this Python function to TypeScript"
+```
+
+### Writing Tests
+
+```bash
+# Generate unit tests
+opencode "Add comprehensive unit tests for src/utils.ts with 100% coverage"
+```
+
+### Debugging
+
+```bash
+# Get help with debugging
+opencode "I'm getting a null pointer exception in src/api/users.ts. Help me debug it"
+```
+
+## Keyboard Shortcuts
+
+### Global
+
+- `Ctrl+p` - Open command palette
+- `Ctrl+c` - Open AI chat
+- `Ctrl+s` - Save current file
+- `Ctrl+q` - Quit
+- `?` - Show help
+
+### Navigation
+
+- `j` / `k` - Down / Up
+- `h` / `l` - Left / Right
+- `gg` - Go to top
+- `G` - Go to bottom
+- `/` - Search
+- `n` - Next search result
+- `N` - Previous search result
+
+### File Operations
+
+- `e` - Edit file
+- `o` - Open in external editor
+- `d` - Delete file (with confirmation)
+- `y` - Yank (copy)
+- `p` - Paste
+
+## Build Information
+
+- **Version**: 1.1.18
+- **Language**: TypeScript/JavaScript (core), Go (TUI)
+- **Runtime**: Bun
+- **License**: MIT
+- **Source**: [GitHub](https://github.com/anomalyco/opencode)
+
+## Dependencies
+
+- `bun` - JavaScript runtime and package manager
+- `fzf` - Fuzzy finder for file selection
+- `ripgrep` - Fast text search
+- `models-dev` - Model definitions and schemas
+
+## Platform Support
+
+- Linux (aarch64, x86_64)
+- macOS (aarch64, x86_64)
+
+## Notes
+
+- Includes a patch to relax Bun version check (changed to warning instead of error)
+- Shell completions are installed for supported platforms (excludes x86_64-darwin)
+- Tree-sitter WASM files are patched to use absolute store paths
+- JSON schema is generated and installed to `$out/share/opencode/schema.json`
+
+## Tips and Best Practices
+
+### Getting Started
+
+1. **Start Small**: Begin with simple tasks to get familiar with the interface
+2. **Provide Context**: Give clear, detailed descriptions of what you want
+3. **Iterate**: Work with OpenCode iteratively, refining requests as needed
+4. **Review Changes**: Always review AI-generated code before committing
+
+### Effective Prompts
+
+- Be specific about requirements
+- Provide examples of expected behavior
+- Mention constraints or preferences
+- Break complex tasks into smaller steps
+
+### Project Structure
+
+- Keep your project well-organized
+- Use consistent naming conventions
+- Add clear comments to complex logic
+- Maintain a clean git history
+
+## Related
+
+- [Adding Packages](../guides/adding-packages.md) - How to add new packages
+- [Quick Start](../QUICKSTART.md) - Getting started guide
+- [OpenCode Documentation](https://github.com/anomalyco/opencode) - Official repository and documentation