first commit

QUICKSTART.md

@@ -0,0 +1,190 @@
+# 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! 🚀