@plures/runebook 0.4.0

package/QUICKSTART.md

@@ -0,0 +1,157 @@
+# Quick Start Guide
+
+## Installation
+
+1. **Install prerequisites:**
+   - Node.js 20.x or higher
+   - Rust 1.70 or higher
+   - Platform-specific dependencies (see main README)
+
+2. **Clone and install:**
+   ```bash
+   git clone https://github.com/plures/runebook.git
+   cd runebook
+   npm install
+   ```
+
+3. **Run in development mode:**
+   ```bash
+   npm run tauri dev
+   ```
+
+## Your First Canvas
+
+When RuneBook starts, you'll see:
+- A **dark canvas** (the main workspace)
+- A **toolbar** on the left with buttons to add nodes
+- An empty workspace ready for nodes
+
+### Creating a Simple Workflow
+
+1. **Add a Terminal Node:**
+   - Click "⚡ Terminal" in the toolbar
+   - A terminal node appears on the canvas
+   - The default command is `echo Hello, RuneBook!`
+
+2. **Add a Display Node:**
+   - Click "📊 Display" in the toolbar
+   - A display node appears on the canvas
+   - This will show the output from the terminal
+
+3. **Run the Terminal:**
+   - Click the "▶ Run" button on the terminal node
+   - You'll see the output appear in the terminal node's output area
+
+4. **Try an Input Node:**
+   - Click "📝 Input" in the toolbar
+   - An input node appears with a text field
+   - Type something and see it update in real-time
+
+### Moving Nodes
+
+- Click and drag any node to reposition it on the canvas
+- Nodes can be placed anywhere on the infinite canvas
+
+### Loading Examples
+
+1. Click "📂 Load Example" in the toolbar
+2. The hello-world example will load with:
+   - A terminal that runs `echo`
+   - An input widget
+   - Two display panels showing outputs
+
+### Saving Your Work
+
+1. Create your canvas layout
+2. Click "💾 Save" in the toolbar
+3. A YAML file downloads with your canvas definition
+
+## Common Terminal Commands
+
+Here are some useful commands to try in terminal nodes:
+
+```bash
+# Show current date
+date
+
+# List files
+ls -la
+
+# Show current directory
+pwd
+
+# Echo with variables
+echo "Current user: $USER"
+
+# Count files
+ls | wc -l
+
+# Show system info
+uname -a
+```
+
+## Input Node Types
+
+RuneBook supports several input types:
+
+- **Text**: Free-form text input
+- **Number**: Numeric values with optional min/max/step
+- **Checkbox**: Boolean true/false toggle
+- **Slider**: Visual range selector
+
+## Display Types
+
+Display nodes can show data in different formats:
+
+- **Text**: Plain text display
+- **JSON**: Formatted JSON with syntax highlighting
+- **Table**: Tabular data (for arrays of objects)
+
+## Next Steps
+
+- Explore the example canvases in `/static/examples/`
+- Read the full documentation in README.md
+- Check INTEGRATIONS.md for upcoming features
+- Experiment with different terminal commands
+- Create custom workflows for your tasks
+
+## Tips
+
+- Use the terminal's "Clear" button to reset output
+- Drag nodes to organize your workspace
+- Save frequently to preserve your work
+- Terminal nodes can use environment variables
+- Multiple display nodes can show the same data
+
+## Troubleshooting
+
+**Terminal commands don't execute:**
+- Check that the command is in your system PATH
+- Verify command syntax is correct
+- Check terminal output for error messages
+
+**Can't see node output:**
+- Ensure the terminal node has run successfully
+- Check for errors in the terminal node
+- Try the "Clear" button and run again
+
+**Load Example doesn't work:**
+- Ensure the examples directory exists: `/static/examples/`
+- Check browser console for error messages
+- Verify YAML files are properly formatted
+
+## keyboard Shortcuts (Coming Soon)
+
+Future versions will include:
+- Ctrl/Cmd + S: Save canvas
+- Ctrl/Cmd + O: Load canvas
+- Delete: Remove selected node
+- Ctrl/Cmd + Z: Undo
+- Ctrl/Cmd + Y: Redo
+
+## Learn More
+
+- [Full README](README.md) - Complete documentation
+- [Integration Plans](INTEGRATIONS.md) - Future features
+- [Tauri Documentation](https://tauri.app/) - Desktop app framework
+- [Svelte 5 Guide](https://svelte.dev/) - UI framework

package/README.md

@@ -0,0 +1,295 @@
+# RuneBook
+
+RuneBook is a reactive, canvas-native computing environment that merges terminals, notebooks, and web components. Built on Svelte 5, PluresDB, Tauri, and Sudolang, RuneBook lets you wire terminals, inputs, and UI components on a visual canvas to create programmable, AI-enhanced workflows that behave like reactive web apps.
+
+## Features
+
+- **Visual Canvas Interface**: Drag-and-drop nodes on an infinite canvas
+- **Terminal Nodes**: Execute shell commands with reactive output
+- **Input Widgets**: Text inputs, sliders, checkboxes, and number inputs
+- **Transform Nodes**: Process data with map, filter, and reduce operations
+- **Display Components**: Visualize data as text, JSON, or tables
+- **Reactive Data Flow**: Node outputs automatically flow to connected inputs
+- **YAML Canvas Definitions**: Save and load canvas configurations
+- **Ambient Agent Mode**: Intelligent command analysis and suggestions (opt-in)
+- **Headless CLI**: SSH-friendly interface for agent management
+- **Cross-Platform**: Windows, macOS, and Linux support
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.
+
+## Installation
+
+### Download Pre-built Binaries
+
+Download the latest release for your platform from [GitHub Releases](https://github.com/plures/runebook/releases):
+
+- **macOS**: `.dmg` file (Intel and Apple Silicon)
+- **Linux**: `.AppImage` or `.deb` file
+- **Windows**: `.msi` or `.exe` installer
+
+### Package Managers
+
+**npm**:
+```bash
+npm install -g @plures/runebook
+```
+
+**NixOS / Nix Flakes**:
+```bash
+# Run directly from flake
+nix run github:plures/runebook
+
+# Build packages
+nix build github:plures/runebook#runebook
+nix build github:plures/runebook#runebook-agent
+```
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 20.x or higher
+- Rust 1.70 or higher
+- Platform-specific dependencies:
+  - **Linux**: webkit2gtk, rsvg2 (see [Tauri prerequisites](https://tauri.app/guides/prerequisites/#linux))
+  - **macOS**: Xcode Command Line Tools
+  - **Windows**: Microsoft C++ Build Tools
+  - **NixOS**: Use `nix develop` (includes all dependencies)
+
+### Build from Source
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/plures/runebook.git
+   cd runebook
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Run in development mode:
+   ```bash
+   npm run tauri dev
+   ```
+
+4. Build for production:
+   ```bash
+   npm run tauri build
+   ```
+
+### NixOS Support
+
+**Development:**
+```bash
+nix develop  # Enter development shell
+npm install
+npm run dev
+```
+
+**Building:**
+```bash
+nix build .#runebook        # Build Tauri app
+nix build .#runebook-agent  # Build headless agent CLI
+```
+
+**Running:**
+```bash
+nix run .#runebook                    # Run Tauri app
+nix run .#runebook-agent -- agent status  # Run agent CLI
+```
+
+The flake includes a NixOS module for running `runebook-agent` as a systemd service. See [NIXOS.md](./NIXOS.md) for configuration details.
+
+## Usage
+
+### Creating Nodes
+
+Use the toolbar to add nodes to the canvas:
+
+- **⚡ Terminal**: Execute shell commands
+- **📝 Input**: Create user input widgets
+- **🔄 Transform**: Process and transform data
+- **📊 Display**: Show data and outputs
+
+### Connecting Nodes
+
+1. Click and drag from an output port (right side of a node)
+2. Drop on an input port (left side of another node)
+3. Data flows automatically from output to input
+
+### Saving and Loading
+
+**Save Options:**
+- **Browser Storage**: Save to localStorage (click "💾 Save to Storage")
+- **PluresDB Storage**: P2P-enabled persistent storage (requires PluresDB server)
+- **Export YAML**: Download canvas as a file (click "📥 Export YAML")
+
+**Load Options:**
+- **Saved Canvases**: Click "📚 Saved Canvases" to view your saved work
+- **Load Example**: Click "📂 Load Example" to try pre-built demos
+
+### Ambient Agent Mode
+
+The Ambient Agent analyzes your terminal commands and provides intelligent suggestions. This feature runs in the background and operates entirely locally—no data leaves your machine.
+
+**Features:**
+- Captures terminal commands and outcomes automatically
+- Analyzes patterns in command usage (frequency, success rates, performance)
+- Suggests optimizations, shortcuts, and warnings
+- Provides context-aware remediation suggestions for failures
+- Uses multi-layer analysis (heuristics, local search, optional LLM)
+
+**Enable via CLI:**
+```bash
+# Enable the agent
+npm run agent enable
+
+# Check status
+npm run agent status
+
+# View suggestions
+npm run agent suggestions
+
+# View recent events
+npm run agent events 20
+
+# Analyze last failure
+npm run analyze last
+```
+
+**Enable via Observer:**
+```bash
+# Enable terminal observer (captures all shell commands)
+npm run observer enable
+
+# View events in real-time
+npm run observer events tail
+
+# View recent events
+npm run observer events 20
+```
+
+**What Data is Stored:**
+
+All data is stored locally:
+- Command names, arguments, and outputs
+- Working directory
+- Environment variables (secrets automatically redacted)
+- Exit codes and execution duration
+- Command patterns and error classifications
+- Generated suggestions with confidence scores
+
+**Storage locations:**
+- Observer events: `~/.runebook/observer/events.json`
+- Agent config: `~/.runebook/agent-config.json`
+- PluresDB data: `./pluresdb-data` (if PluresDB enabled)
+
+**Privacy & Security:**
+- All data stored locally—never sent to external services
+- Secrets automatically redacted (API keys, tokens, passwords)
+- Opt-in by default (disabled until explicitly enabled)
+- Configurable retention period (default: 30 days)
+
+**CLI Commands:**
+
+Agent:
+- `npm run agent enable|disable|status`
+- `npm run agent suggestions [priority]`
+- `npm run agent events [limit]`
+- `npm run agent clear [days]`
+
+Observer:
+- `npm run observer enable|disable|status`
+- `npm run observer events [limit]`
+- `npm run observer events tail`
+
+Analysis:
+- `npm run analyze last`
+
+Memory:
+- `npm run memory inspect`
+
+For detailed documentation, see:
+- [ARCHITECTURE.md](./ARCHITECTURE.md) - Technical architecture
+- [ANALYSIS_LADDER.md](./ANALYSIS_LADDER.md) - Analysis system
+- [MEMORY.md](./MEMORY.md) - Memory storage schema
+
+## Architecture
+
+**Stack:**
+- **Frontend**: Svelte 5 with SvelteKit
+- **State Management**: Praxis reactive logic engine
+- **Backend**: Tauri (Rust) for native system access
+- **Storage**: PluresDB for P2P-enabled persistent storage
+- **Serialization**: YAML for canvas definitions
+
+**Project Structure:**
+```
+runebook/
+├── src/
+│   ├── lib/
+│   │   ├── components/     # Svelte components
+│   │   ├── agent/          # Agent system
+│   │   ├── core/           # Core utilities
+│   │   └── types/          # TypeScript types
+│   ├── cli/                # CLI commands
+│   └── routes/             # SvelteKit routes
+├── src-tauri/
+│   ├── src/                # Rust backend
+│   │   ├── agents/         # Agent implementations
+│   │   ├── orchestrator/   # Orchestration logic
+│   │   ├── execution/      # Command execution
+│   │   └── memory/         # Memory/storage
+│   └── Cargo.toml          # Rust dependencies
+├── static/
+│   └── examples/           # Example canvas files
+└── flake.nix               # Nix build configuration
+```
+
+## Security
+
+### Command Execution
+
+- **Direct Execution**: Commands use Rust's `std::process::Command` (no shell interpretation)
+- **No Shell Injection**: Command strings like `ls | grep` won't work as pipelines
+- **User Permissions**: Commands run with your user account permissions
+- **Environment Validation**: Variable names validated to prevent injection
+
+### Transform Nodes
+
+Transform nodes execute user-provided JavaScript:
+
+- **Local Execution**: Runs in browser/app context only
+- **No Sandboxing**: Has same permissions as the application
+- **User Responsibility**: Only use code you trust
+- **Strict Mode**: JavaScript strict mode enforced
+
+### Best Practices
+
+- Only run commands you trust
+- Review canvas files before loading from unknown sources
+- Avoid storing secrets in canvas definitions
+- Use environment variables for sensitive data
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before submitting PRs.
+
+### For Maintainers
+
+- **Releases**: See [RELEASE.md](./RELEASE.md) for release process
+- **Workflows**: See [.github/WORKFLOWS.md](./.github/WORKFLOWS.md) for CI/CD documentation
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Recommended IDE Setup
+
+[VS Code](https://code.visualstudio.com/) + [Svelte](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer).
+
+## Acknowledgments
+
+Built with [Tauri](https://tauri.app/) and [Svelte 5](https://svelte.dev/). Inspired by node-based editors like Blender's Shader Editor and Unreal Engine's Blueprints.

package/RELEASE.md

@@ -0,0 +1,190 @@
+# Quick Start Guide for CI/CD Workflows
+
+This guide provides a quick overview of the automated CI/CD workflows for RuneBook maintainers.
+
+## Quick Links
+
+- **Full Documentation**: [.github/WORKFLOWS.md](./.github/WORKFLOWS.md)
+- **Contributing Guide**: [CONTRIBUTING.md](./CONTRIBUTING.md)
+- **Release Checklist**: [.github/ISSUE_TEMPLATE/release-checklist.md](./.github/ISSUE_TEMPLATE/release-checklist.md)
+
+## Making a Release
+
+### 1. Prepare for Release
+
+```bash
+# Ensure all changes are merged to main
+git checkout main
+git pull origin main
+
+# Verify versions are synchronized
+npm run version:check
+```
+
+### 2. Bump Version
+
+1. Go to [GitHub Actions](https://github.com/plures/runebook/actions)
+2. Select "Version Bump" workflow
+3. Click "Run workflow"
+4. Choose version type:
+   - **patch**: Bug fixes (0.2.0 → 0.2.1)
+   - **minor**: New features (0.2.0 → 0.3.0)
+   - **major**: Breaking changes (0.2.0 → 1.0.0)
+5. Click "Run workflow" button
+
+The workflow will:
+- Update version in all files
+- Commit changes
+- Create git tag
+- Create draft GitHub Release
+
+### 3. Finalize Release
+
+1. Go to [Releases](https://github.com/plures/runebook/releases)
+2. Find the draft release
+3. Edit the release notes
+4. Update CHANGELOG.md if needed
+5. Click "Publish release"
+
+This will trigger the Build and Publish workflow that:
+- Builds for all platforms (macOS Intel/Apple Silicon, Linux, Windows)
+- Uploads binaries to GitHub Release automatically
+- Publishes to npm registry
+- Publishes to GitHub Packages
+- Submits to winget (if configured)
+- Builds Nix packages for NixOS distribution
+
+### 4. Verify Release
+
+```bash
+# Check npm package
+npm view @plures/runebook
+
+# Check GitHub Packages
+# Visit: https://github.com/plures/runebook/packages
+
+# Check GitHub Release (verify binaries are uploaded)
+# Visit: https://github.com/plures/runebook/releases
+
+# Verify Nix packages (if nixos-publish job ran)
+# Check workflow artifacts for nix-packages
+```
+
+## Setup (First Time Only)
+
+### Configure Repository Secrets
+
+1. Go to Settings → Secrets and variables → Actions
+2. Add these secrets:
+   - **NPM_TOKEN**: Create at npmjs.com → Access Tokens
+   - **WINGET_GITHUB_TOKEN**: GitHub PAT with `public_repo` scope (optional)
+
+### Enable Workflow Permissions
+
+1. Go to Settings → Actions → General
+2. Under "Workflow permissions":
+   - Select "Read and write permissions"
+   - Check "Allow GitHub Actions to create and approve pull requests"
+3. Click "Save"
+
+## Common Tasks
+
+### Check Version Synchronization
+
+```bash
+npm run version:check
+```
+
+### Manual Build Test
+
+```bash
+# Frontend
+npm run build
+
+# Full Tauri build
+npm run tauri build
+```
+
+### View Workflow Runs
+
+```bash
+# Using GitHub CLI
+gh run list --workflow=version-bump.yml
+gh run list --workflow=publish-release.yml
+
+# View details
+gh run view <run-id>
+```
+
+## Troubleshooting
+
+### Workflow Fails
+
+1. Check workflow logs in Actions tab
+2. Look for error messages in red
+3. Common issues:
+   - Missing secrets (NPM_TOKEN)
+   - Permission issues (workflow permissions)
+   - Build errors (check build logs)
+
+### Version Mismatch
+
+If versions get out of sync:
+
+```bash
+# Fix manually
+# 1. Update package.json version
+# 2. Run: npm install
+# 3. Update src-tauri/Cargo.toml version
+# 4. Run: cd src-tauri && cargo update -p runebook
+# 5. Update src-tauri/tauri.conf.json version
+# 6. Verify: npm run version:check
+```
+
+Or use the Version Bump workflow to re-sync.
+
+### npm Publish Fails
+
+1. Verify NPM_TOKEN is configured
+2. Check token hasn't expired
+3. Ensure package name `@plures/runebook` is available
+4. Verify you have permissions to publish to `@plures` scope
+
+## Package Distribution
+
+After release, users can install RuneBook via:
+
+**npm**:
+```bash
+npm install -g @plures/runebook
+```
+
+**GitHub Packages**:
+```bash
+npm config set @plures:registry https://npm.pkg.github.com
+npm install -g @plures/runebook
+```
+
+**winget** (Windows):
+```powershell
+winget install Plures.RuneBook
+```
+
+**NixOS / Nix Flakes**:
+```bash
+# Direct flake usage
+nix run github:plures/runebook
+
+# Or add to your flake inputs
+# runebook.url = "github:plures/runebook";
+```
+
+**Direct Download**: 
+- Visit [GitHub Releases](https://github.com/plures/runebook/releases)
+- Download platform-specific installers (.dmg, .AppImage, .msi, .exe)
+
+## Need Help?
+
+- Read the [full documentation](./.github/WORKFLOWS.md)
+- Check the [troubleshooting guide](./.github/WORKFLOWS.md#troubleshooting)
+- Open an issue if you need assistance