rosett-ai 1.3.3

data/INSTALL.md

@@ -0,0 +1,154 @@
+# Installing Rosett-AI
+
+## From .deb Package (Recommended)
+
+Download the latest `.deb` package from the
+[releases page](https://gitlab.neatnerds.be/neatnerds/NeatNerds-AI/rosett-ai/-/releases).
+
+```bash
+# Install the package
+sudo dpkg -i nncc_1.0.0-1_amd64.deb
+
+# Install any missing dependencies
+sudo apt-get install -f
+
+# Verify installation
+raictl version
+```
+
+## APT Repository
+
+The APT repository provides signed packages with automated updates.
+
+```bash
+# Download and install the repository GPG key
+curl -fsSL https://repo.neatnerds.be/gpg.key \
+  | sudo gpg --dearmor -o /etc/apt/keyrings/neatnerds.gpg
+
+# Add the stable repository
+echo "deb [signed-by=/etc/apt/keyrings/neatnerds.gpg arch=amd64] https://repo.neatnerds.be/stable bookworm main" \
+  | sudo tee /etc/apt/sources.list.d/neatnerds.list
+
+# Install rosett-ai
+sudo apt-get update
+sudo apt-get install rosett-ai
+```
+
+For ARM64 systems, replace `arch=amd64` with `arch=arm64`.
+
+For the unstable channel (latest development builds from main):
+
+```bash
+echo "deb [signed-by=/etc/apt/keyrings/neatnerds.gpg arch=amd64] https://repo.neatnerds.be/unstable bookworm main" \
+  | sudo tee /etc/apt/sources.list.d/neatnerds-unstable.list
+```
+
+### Verifying Package Signatures
+
+All packages are GPG-signed. To verify a downloaded `.deb`:
+
+```bash
+dpkg-sig --verify nncc_*.deb
+```
+
+## Post-Install Verification
+
+After installation, verify that rosett-ai is working correctly:
+
+```bash
+# Check version
+raictl version
+
+# Initialize global configuration
+rai init --global
+
+# Validate configuration files
+rai validate
+
+# View man page
+man raictl
+```
+
+## Package Contents
+
+The `.deb` package installs:
+
+| Path | Description |
+|------|-------------|
+| `/opt/rosett-ai/` | Application directory (embedded Ruby + app) |
+| `/opt/rosett-ai/bin/raictl` | Wrapper script |
+| `/usr/local/bin/raictl` | Symlink (created by postinst) |
+| `/etc/rosett-ai/settings.json` | Default configuration (conffile) |
+| `/usr/share/man/man1/rai.1.gz` | Man page |
+
+## Uninstalling
+
+```bash
+# Remove the package (keeps configuration)
+sudo apt-get remove rosett-ai
+
+# Remove the package and its configuration
+sudo apt-get purge rosett-ai
+```
+
+## Troubleshooting
+
+### "command not found" after install
+
+The postinst script creates a symlink at `/usr/local/bin/raictl`. If it is
+missing, recreate it manually:
+
+```bash
+sudo ln -sf /opt/rosett-ai/bin/raictl /usr/local/bin/raictl
+```
+
+### "Engine not found" when compiling
+
+Install the engine plugin gem for your target tool:
+
+```bash
+gem install rosett-ai-engine-claude    # Claude Code
+gem install rosett-ai-engine-cursor    # Cursor
+gem install rosett-ai-engine-agents_md # AGENTS.md
+```
+
+Run `rai engines list` to see all available engines and
+`rai engines detect` to check which are installed.
+
+### Dependency errors during install
+
+```bash
+sudo apt-get install -f
+```
+
+This resolves any missing system library dependencies (libffi, libyaml,
+libssl, etc.) required by the embedded Ruby runtime.
+
+### "Permission denied" errors
+
+The `.deb` package installs to `/opt/rosett-ai/` which is owned by root.
+User data lives in `~/.claude/` and `~/.config/rosett-ai/` which must be owned
+by your user:
+
+```bash
+ls -la ~/.claude/
+ls -la ~/.config/rosett-ai/
+```
+
+If permissions are wrong, fix them:
+
+```bash
+sudo chown -R "$USER:$USER" ~/.claude/ ~/.config/rosett-ai/
+```
+
+## Building from Source
+
+See [SETUP.md](doc/SETUP.md) for development setup instructions.
+
+```bash
+# Build the .deb package
+bin/raictl build package --verbose
+
+# Output will be in pkg/
+ls pkg/*.deb
+```