# OSIRIS Quick Start Guide

Get up and running with OSIRIS in 5 minutes!

## Prerequisites

- Rust toolchain (1.70+)
- HeroDB running on localhost:6379

## Step 1: Start HeroDB

```bash
cd /path/to/herodb
cargo run --release -- --dir ./data --admin-secret mysecret --port 6379
```

Keep this terminal open.

## Step 2: Build OSIRIS

Open a new terminal:

```bash
cd /path/to/osiris
cargo build --release
```

## Step 3: Initialize OSIRIS

```bash
./target/release/osiris init --herodb redis://localhost:6379
```

Output:
```
✓ OSIRIS initialized
  Config: /Users/you/.config/osiris/config.toml
```

## Step 4: Create Your First Namespace

```bash
./target/release/osiris ns create notes
```

Output:
```
✓ Created namespace 'notes' (DB 1)
```

## Step 5: Add Your First Object

```bash
echo "OSIRIS is awesome!" | \
  ./target/release/osiris put notes/first-note - \
  --title "My First Note" \
  --tags topic=osiris,mood=excited
```

Output:
```
✓ Stored notes/first-note
```

## Step 6: Search for Your Object

```bash
./target/release/osiris find "awesome" --ns notes
```

Output:
```
Found 1 result(s):

1. first-note (score: 0.50)
   OSIRIS is awesome!
```

## Step 7: Retrieve Your Object

```bash
./target/release/osiris get notes/first-note
```

Output (JSON):
```json
{
  "id": "first-note",
  "ns": "notes",
  "meta": {
    "title": "My First Note",
    "tags": {
      "mood": "excited",
      "topic": "osiris"
    },
    "created": "2025-10-20T10:30:00Z",
    "updated": "2025-10-20T10:30:00Z",
    "size": 18
  },
  "text": "OSIRIS is awesome!"
}
```

## Step 8: Try More Features

### Add a note from a file
```bash
echo "This is a longer note about OSIRIS features" > /tmp/note.txt
./target/release/osiris put notes/features /tmp/note.txt \
  --title "OSIRIS Features" \
  --tags topic=osiris,type=documentation
```

### Search with filters
```bash
./target/release/osiris find --ns notes --filter topic=osiris
```

### Get raw content
```bash
./target/release/osiris get notes/first-note --raw
```

### View statistics
```bash
./target/release/osiris stats --ns notes
```

### List all namespaces
```bash
./target/release/osiris ns list
```

## Common Commands Cheat Sheet

```bash
# Initialize
osiris init --herodb redis://localhost:6379

# Namespace management
osiris ns create <name>
osiris ns list
osiris ns delete <name>

# Object operations
osiris put <ns>/<name> <file> [--tags k=v,...] [--title "..."] [--mime "..."]
osiris get <ns>/<name> [--raw] [--output file]
osiris del <ns>/<name>

# Search
osiris find "<query>" --ns <ns> [--filter k=v,...] [--topk N] [--json]

# Statistics
osiris stats [--ns <ns>]
```

## What's Next?

- **Read the [Examples](EXAMPLES.md)** for more use cases
- **Check the [README](README.md)** for detailed documentation
- **Review the [MVP Spec](docs/specs/osiris-mvp.md)** to understand the architecture
- **Explore the [source code](src/)** to see how it works

## Troubleshooting

### "Connection refused"
Make sure HeroDB is running on port 6379:
```bash
redis-cli -p 6379 PING
```

### "Namespace not found"
Create the namespace first:
```bash
osiris ns create <namespace>
```

### "Config file not found"
Run `osiris init` first:
```bash
osiris init --herodb redis://localhost:6379
```

## Need Help?

- Check the [EXAMPLES.md](EXAMPLES.md) for detailed usage patterns
- Review the [README.md](README.md) for architecture details
- Look at the [docs/specs/osiris-mvp.md](docs/specs/osiris-mvp.md) for the full specification

Happy organizing! 🚀