From ba5047db02cca61339829ad0ae2aa2256e687085 Mon Sep 17 00:00:00 2001
From: Your Name <j@842.be>
Date: Sun, 22 Jun 2025 11:09:59 +1200
Subject: [PATCH] 'Generic Commit'

---
 README.md | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 179 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 0404537..a25f67e 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,192 @@
-# Dropshell Tools
+# getpkg - Package Manager for Dropshell Tools
 
-Tools to support dropshell development and (behind the scenes) use.
+getpkg is a command-line package manager that simplifies tool installation, management, and publishing for the dropshell ecosystem. Tools are installed to `~/.local/bin/getpkg/` and automatically added to your PATH with bash completion.
 
-Tools are installed to ~/.local/bin/getpkg, and the tool name is added to the bash PATH, with autocomplete.
+## Installation
 
-## Use
+Install getpkg with a single command:
 
-Just use getpkg. You can install with:
-
-```
+```bash
 curl https://getbin.xyz/getpkg-install | bash
 ```
 
+After installation, restart your shell or run `source ~/.bashrc` to enable the new PATH and completion settings.
+
+## Basic Usage
+
+### Installing Tools
+
+Install any tool from the getpkg registry:
+
+```bash
+# Install a tool
+getpkg install ripgrep
+
+# Shorthand syntax (same as above)
+getpkg ripgrep
+```
+
+### Managing Installed Tools
+
+```bash
+# List all available commands
+getpkg help
+
+# Update all installed tools
+getpkg update
+
+# Uninstall a tool
+getpkg uninstall ripgrep
+
+# Check getpkg version
+getpkg version
+```
+
+## Available Commands
+
+### Core Package Management
+
+- **`getpkg <tool_name>`** - Install or update a tool (shorthand)
+- **`getpkg install <tool_name>`** - Install or update a tool (explicit)
+- **`getpkg uninstall <tool_name>`** - Remove an installed tool
+- **`getpkg update`** - Update getpkg and all installed tools
+
+### Publishing (Requires SOS_WRITE_TOKEN)
+
+- **`getpkg publish <tool_name[:ARCH]> <folder>`** - Upload a tool to getpkg.xyz
+- **`getpkg unpublish <tool_name[:ARCH]>`** - Remove a published tool
+- **`getpkg unpublish <hash>`** - Remove a published tool by hash
+
+### Development Tools
+
+- **`getpkg create <tool_name> <directory>`** - Create a new tool project
+- **`getpkg hash <file_or_directory>`** - Calculate hash of files/directories
+
+### Information
+
+- **`getpkg version`** - Show getpkg version
+- **`getpkg help`** - Show detailed help
+- **`getpkg autocomplete`** - Show available commands for completion
+
+## How It Works
+
+### Installation Process
+
+When you install a tool, getpkg:
+
+1. **Downloads** the tool archive from getpkg.xyz
+2. **Extracts** it to `~/.local/bin/getpkg/<tool_name>/`
+3. **Updates PATH** by modifying `~/.bashrc_getpkg`
+4. **Enables completion** for the tool
+5. **Runs setup** if a `setup_script.sh` exists
+6. **Stores metadata** in `~/.config/getpkg/<tool_name>.json`
+
+### Architecture Support
+
+getpkg supports multiple architectures:
+- `x86_64` (Intel/AMD 64-bit)
+- `aarch64` (ARM 64-bit)  
+- `universal` (cross-platform tools)
+
+Tools are automatically downloaded for your architecture, with fallback to universal versions.
+
+### File Locations
+
+- **Installed tools**: `~/.local/bin/getpkg/<tool_name>/`
+- **Configuration**: `~/.config/getpkg/`
+- **PATH setup**: `~/.bashrc_getpkg` (sourced by `~/.bashrc`)
+
+## Examples
+
+### Installing Popular Tools
+
+```bash
+# Install development tools
+getpkg ripgrep        # Fast grep alternative
+getpkg fd             # Fast find alternative
+getpkg bat            # Cat with syntax highlighting
+
+# Install system utilities
+getpkg whatsdirty     # Check git repo status
+getpkg sos            # Simple object storage client
+```
+
+### Publishing Your Own Tools
+
+```bash
+# Set your publishing token
+export SOS_WRITE_TOKEN="your-token-here"
+
+# Create a new tool project
+getpkg create mytool ./mytool-project
+
+# Publish architecture-specific build
+getpkg publish mytool:x86_64 ./build/
+
+# Publish universal tool
+getpkg publish mytool ./build/
+
+# Remove published tool
+getpkg unpublish mytool:x86_64
+```
+
+### Development Workflow
+
+```bash
+# Create tool structure
+getpkg create awesome-tool ./awesome-tool
+cd awesome-tool
+
+# Build your tool...
+# Add executable to the directory
+
+# Test locally
+./awesome-tool --version
+
+# Publish when ready
+getpkg publish awesome-tool:x86_64 .
+```
+
+## Environment Variables
+
+- **`SOS_WRITE_TOKEN`** - Authentication token for publishing tools
+
+## Troubleshooting
+
+### Tool Not Found
+If a tool isn't found after installation, ensure your shell has loaded the new PATH:
+```bash
+source ~/.bashrc
+```
+
+### Permission Issues
+getpkg installs to your home directory and doesn't require root access. If you encounter permission issues, check that `~/.local/bin/` is writable.
+
+### Network Issues
+All tools are downloaded from `getpkg.xyz`. Ensure you have internet connectivity and the domain is accessible.
 
 ## Development
 
+### Building getpkg
 
+```bash
+# Build debug version
+cd getpkg && ./build.sh
 
+# Run tests  
+cd getpkg && ./test.sh
 
+# Publish (requires SOS_WRITE_TOKEN)
+cd getpkg && ./publish.sh
+```
+
+### Tool Development
+
+When creating tools for getpkg:
+
+1. Create a directory with your tool binary
+2. Optionally include a `setup_script.sh` for post-install setup
+3. The tool should support `version` and `autocomplete` subcommands
+4. Use `getpkg publish` to upload to the registry
+
+For more details, see the development documentation in each tool's directory.